Commits

Anonymous committed 4278a49

Docs.

Comments (0)

Files changed (5)

webhelpers/media.py

 
     Returns ``(width, height)`` as two integers, or ``default`` if the size
     could not be ascertained.  Failure usually means the file does not exist
-    or is not in a recognized format.  Only JPG/PNG/GIF/BMP are supported at
+    or is not in a recognized format.  Only JPG, PNG, GIF, BMP are supported at
     this time.
 
     The algorithms are based on a `PyCode recipe

webhelpers/number.py

-"""Number formatting and numeric helpers"""
+"""Number formatting, numeric helpers, and numeric statistics"""
 
 import re
 
     return float(part * 100) / whole
 
 def mean(r):
-    """Return the mean of a sequence of numbers.
-    
-    The mean is the average of all the numbers.
+    """Return the mean (i.e., average) of a sequence of numbers.
 
     >>> mean([5, 10])
     7.5
 
     The median here is somewhat close to the majority of incomes, while the
     mean is far from anybody's income.
-
-        [20 000,
-        40 000,
-        60 000,
-        9 999 999]
-    
-    The median would be around 50 000, which is close to what the majority of
-    respondents make.  The average would be in the millions, which is far from
-    what any of the respondents make.
     
     This implementation makes a temporary list of all numbers in memory.
     """
     return mean([low, high])
 
 def standard_deviation(r, sample=True):
-    """Standard deviation, `from the Python Cookbook
-    <http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/442412>`_
+    """Standard deviation. 
+    
+    `from the Python Cookbook
+    <http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/442412>`_.
     Population mode contributed by Lorenzo Catucci.
 
     Standard deviation shows the variability within a sequence of numbers.
-    A small standard deviation shows the numbers are close to the same.  A
+    A small standard deviation means the numbers are close to each other.  A
     large standard deviation shows they are widely different.  In fact it
     shows how far the numbers tend to deviate from the average.  This can be
     used to detect whether the average has been skewed by a few extremely high
     or extremely low values.
 
+    Most natural and random phenomena follow the normal distribution (aka the
+    bell curve), which says that most values are close to average but a few are
+    extreme.  E.g., most people are close to 5'9" tall but a few are very tall
+    or very short.  If the data does follow the bell curve, 68% of the values
+    will be within 1 standard deviation (stdev) of the average, and 95% will be
+    within 2 standard deviations.  So a university professor grading exams on a
+    curve might give a "C" (mediocre) grade to students within 1 stdev of the
+    average score, "B" (better than average) to those within 2 stdevs above,
+    and "A" (perfect) to the 0.25% higher than 2 stdevs.  Those between 1 and 2
+    stdevs below get a "D" (poor), and those below 2 stdevs... we won't talk
+    about them.
+
     By default the helper computes the unbiased estimate
     for the population standard deviation, by applying an unbiasing
     factor of sqrt(N/(N-1)).
         45.1378360405574...
         >>> standard_deviation([-32, -10, 20, 30, 60, 90, 100, 80, 60, 30, 10, -32], sample=False) # doctest: +ELLIPSIS
         43.2161878106906...
-
-    Most natural and random phenomena follow the normal distribution (aka the
-    bell curve), which says that most values are close to average but a few are
-    extreme.  E.g., most people are close to 5'9" tall but a few are very tall
-    or very short.  If the data does follow the bell curve, 68% of the values
-    will be within 1 standard deviation (stdev) of the average, and 95% will be
-    within 2 standard deviations.  So a university professor grading exams on a
-    curve might give a "C" (mediocre) grade to students within 1 stdev of the
-    average score, "B" (better than average) to those within 2 stdevs above,
-    and "A" (perfect) to the 0.25% higher than 2 stdevs.  Those between 1 and 2
-    stdevs below get a "D" (poor), and those below 2 stdevs... we won't talk
-    about them.
     """
     avg = average(r)
     sdsq = sum([(i - avg) ** 2 for i in r])
     return (sdsq / normal_denom) ** 0.5
 
 class SimpleStats(object):
-    """Calculate a few simple stats on data.
+    """Calculate a few simple statistics on data.
     
     This class calculates the minimum, maximum, and count of all the values
     given to it.  The values are not saved in the object.  Usage::
     ``.finish()`` and then call ``.finish()`` again.  This recalculates the
     stats over the entire data set.
 
-    The ``SimpleStats`` hook methods are available for subclasses, and 
-    additionally the ``._finish_stats`` method.
+    In addition to the hook methods provided by ``SimpleStats``, subclasses
+    can override ``._finish-stats`` to provide additional statistics.
     """
     __version__ = 1
 

webhelpers/paginate.py

 A simple example (ipython session)::
 
     # Set up the routes context (only if you are not using a Pylons application)
-    >>> from routes import Mapper; mapper=Mapper(); mapper.connect(':controller')
+    >>> import routes
+    >>> mapper=routes.Mapper()
+    >>> mapper.connect(None, '/{controller}')
 
     # Create a sample collection of 1000 items
     >>> my_collection = range(1000)
 on a page also has number 1. So if you want to use the page's items by
 their index number please note that you have to substract 1.
 
-This module is the successor to the deprecated ``webhelpers.pagination``
+This module is the successor to the obsolete ``webhelpers.pagination``
 module.  It is **NOT** API compatible.
 
 This version of paginate is based on the code from

webhelpers/text.py

 
 def lchop(s, sub):
     """Chop ``sub`` off the front of ``s`` if present.
-    
+
     >>> lchop("##This is a comment.##", "##")
     'This is a comment.##'
+
+    The difference between ``lchop`` and ``s.lstrip`` is that ``lchop`` strips
+    only the exact prefix, while ``s.lstrip`` treats the argument as a set of
+    leading characters to delete regardless of order.
     """
     if s.startswith(sub):
         s = s[len(sub):]
     
     >>> rchop("##This is a comment.##", "##")
     '##This is a comment.'
+
+    The difference between ``rchop`` and ``s.rstrip`` is that ``rchop`` strips
+    only the exact suffix, while ``s.rstrip`` treats the argument as a set of
+    trailing characters to delete regardless of order.
     """
     if s.endswith(sub):
         s = s[:-len(sub)]
     return "".join(result)
 
 def series(items, conjunction="and", strict_commas=True):
-    """Format a series for use in English text.
+    """Join strings using commas and a conjunction such as "and" or "or".
 
     Examples:
 

webhelpers/util.py

 """Utility functions used by various web helpers
 
-This module is such a mess that no new helpers should be added to it.
+This module contains support functions used by other helpers, and functions for
+URL manipulation. Most of these helpers predate the 0.6 reorganization; they
+would have been put in other subpackages if they have been created later.
 """
 import cgi
 import copy
     'http://example.com/foo?new1=NEW1#myfrag'
     >>> update_params("http://example.com/foo?new1=OLD1#myfrag", new1="NEW1", _debug=True)
     ('http://example.com/foo', {'new1': 'NEW1'}, 'myfrag')
+
     """
     debug = params.pop("_debug", False)
     orig_url = url
     This is a slightly more efficient version of the cgi.escape by
     using 'in' membership to test if the replace is needed.
 
+    This function returns a plain string. Programs using the HTML builder
+    should call ``webhelpers.html.builder.escape()`` instead of this to prevent
+    double-escaping.
+
     """
+    # Called by webhelpers.html.builder
     if '&' in s:
         s = s.replace("&", "&amp;") # Must be done first!
     if '<' in s:
     
     None is treated specially, and returns the empty string.
     
+    This function returns a plain string. Programs using the HTML builder
+    should wrap the result in ``literal()`` to prevent double-escaping.
+
     """
     if s is None:
         return ''
     simplify things a little from the full method.
 
     Returns an ASCII string containing the encoded result.
-    
+
     """
+    # Called by webhelpers.feedgenerator
+    #
     # The list of safe characters here is constructed from the printable ASCII
     # characters that are not explicitly excluded by the list at the end of
     # section 3.1 of RFC 3987.
         return self.fn(*(self.args + args), **d)
 
 class SimplerXMLGenerator(XMLGenerator):
+    # Used by webhelpers.feedgenerator
+
     def addQuickElement(self, name, contents=None, attrs=None):
         """Add an element with no children."""
         if attrs is None:
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.