# Commits

committed 4278a49

Docs.

• Participants
• Parent commits e2e234d
• Branches trunk

# File 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`

# File 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`
` `

# File 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`

# File 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:`
` `

# File 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:`