Mike Orr avatar Mike Orr committed deea83a

Documentation updates.

Comments (0)

Files changed (7)

 lists and from a dict. Some arguments will be changing also.
 
 Run tests on Python 2.4 to see if any 2.5isms have crept in.
+
+What is the purpose of webhelpers.mimehelper? It has a hidden Pylons
+dependency, although it's optional. Under what circumstances would you use it, 
+and how much of an advantage is it to pass a short alias like
+m.mimetype("html")? Need better documentation.`
+
+Document MIMETypes.__init__().
+
+webhelpers.number: document __call__ methods.
+
+

docs/modules/number.rst

 
 .. currentmodule:: webhelpers.number
 
+Functions
+---------
+
 .. autofunction:: percent_of
 .. autofunction:: mean
 .. function:: average(r)
 
 .. autofunction:: median
 .. autofunction:: standard_deviation
+.. autofunction:: format_number
+
+Classes
+-------
 
 .. autoclass:: SimpleStats
     :members:
     :members:
     :undoc-members:
 
-.. autofunction:: format_number
 # Pip requirements to build WebHelpers documentation and run tests.
-#
+
 # Required for tests
 Nose
 Routes
 # Required for generating HTML documentation
 Sphinx
 
-# Optional for certain helpers
+# Optional enhancement for certain helpers
 Unidecode
+
+# Required by pylons.media.get_dimensions_pil()
+# (To avoid installing this, use pylons.media.get_dimensions() instead.)
+#Imaging

webhelpers/media.py

     return int(new_width * proportion)
 
 def get_dimensions_pil(path, default=(None, None)):
-    """Get an image's size using the Python Imaging Library (PIL)
+    """Get an image's size using the Python Imaging Library (PIL).
 
-    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 format recognized by PIL.
+    ``path`` is the path of the image file.
+
+    ``default`` is returned if the size could not be ascertained. This
+    usually means the file does not exist or is not in a format recognized by
+    PIL.
+
+    The normal return value is a tuple: ``(width, height)``.
 
     Depends on the `Python Imaging Library
     <http://pypi.python.org/pypi/PIL>`_. If your application is not
     return im.size
 
 def get_dimensions(path, default=(None, None)):
-    """Get an image's size using only the Python standard library
+    """Get an image's size using only the Python standard library.
 
-    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, and BMP are
-    supported at this time.
+    ``path`` is the path of the image file.
+
+    ``default`` is returned if the size could not be ascertained. This
+    usually means the file does not exist or is not in a recognized format.
+    PIL. Only JPG, PNG, GIF, and BMP are supported at this time.
+
+    The normal return value is a tuple: ``(width, height)``.
 
     The algorithms are based on a `PyCode recipe
     <http://www.pycode.com/modules/?id=32&tab=download>`_ by
 
     This helper recognizes fewer image formats and is potentially less
     accurate than ``get_dimensions_pil()``.
+
+    Running this module as a script tests this helper. It will print the
+    size of each image file specified on the command line.
     """
     apath = os.path.abspath(path)
     try:
             print "%s x %s" % (width, height)
             
         
-
 if __name__ == "__main__":  test_get_dimensions()

webhelpers/mimehelper.py

     
     The MIMETypes object class provides a single point to hold onto all
     the registered mimetypes, and their association extensions. It's
-    used by the mimetypes function to determine the appropriate content
+    used by the mimetypes method to determine the appropriate content
     type to return to a client.
     
     """
     def __init__(self, environ):
         self.env = environ
     
-    def _set_responce_conetent_type(self, mimetype):
+    def _set_response_content_type(self, mimetype):
         if 'pylons.pylons' in self.env:
             self.env['pylons.pylons'].response.content_type = mimetype
         return mimetype
         
     def mimetype(self, content_type):
-        """Check the PATH_INFO of the current request and clients HTTP Accept 
-        to attempt to use the appropriate mime-type
-    
-        If a content-type is matched, the appropriate response content
-        type is set as well.
+        """Check the PATH_INFO of the current request and client's HTTP Accept 
+        to attempt to use the appropriate mime-type.
+
+        If a content-type is matched, return the appropriate response
+        content type, and if running under Pylons, set the response content
+        type directly. If a content-type is not matched, return ``False``.
                 
         This works best with URLs that end in extensions that differentiate
         content-type. Examples: ``http://example.com/example``, 
             MIMETypes.add_alias('xml', 'application/xml')
             MIMETypes.add_alias('csv', 'text/csv')
             
-            # code in a controller
+            # code in a Pylons controller
             def somaction(self):
                 # prepare a bunch of data
                 # ......
                     return csvfile
                 else:
                     abort(404)
-        
+
+            # Code in a non-Pylons controller.
+            m = MIMETypes(environ)
+            response_type = m.mimetype('html')
+            # ``response_type`` is a MIME type or ``False``.
         """
         import webob
 
                 self.env['HTTP_ACCEPT'])
         if has_extension == False:
             if possible_from_accept_header is None:
-                return self._set_responce_conetent_type(content_type)
+                return self._set_response_content_type(content_type)
             elif content_type in possible_from_accept_header:
-                return self._set_responce_conetent_type(content_type)
+                return self._set_response_content_type(content_type)
             else:
                 return False
         if content_type == guess_from_url:
             # Guessed same mimetype
-            return self._set_responce_conetent_type(content_type)
+            return self._set_response_content_type(content_type)
         elif guess_from_url is None and content_type in possible_from_accept_header:
-            return self._set_responce_conetent_type(content_type)
+            return self._set_response_content_type(content_type)
         else:
             return False

webhelpers/misc.py

 class DeclarativeException(Exception):
     """A simpler way to define an exception with a fixed message.
 
-    Example:
+    Subclasses have a class attribute ``.message``, which is used if no
+    message is passed to the constructor. The default message is the empty
+    string.
 
-    >>> class MyException(DeclarativeException):
-    ...     message="can't frob the bar when foo is enabled"
-    ...
-    >>> try:
-    ...     raise MyException()
-    ... except Exception, e:
-    ...      print e
-    ...
-    can't frob the bar when foo is enabled
+    Example::
+
+        >>> class MyException(DeclarativeException):
+        ...     message="can't frob the bar when foo is enabled"
+        ...
+        >>> try:
+        ...     raise MyException()
+        ... except Exception, e:
+        ...      print e
+        ...
+        can't frob the bar when foo is enabled
     """
-    message=""
+    message = ""
 
     def __init__(self, message=None):
         Exception.__init__(self, message or self.message)

webhelpers/number.py

 def standard_deviation(r, sample=True):
     """Standard deviation. 
     
-    `from the Python Cookbook
+    `From the Python Cookbook
     <http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/442412>`_.
     Population mode contributed by Lorenzo Catucci.
 
     >>> stats2.max
     'foo'
 
-    If the ``numeric`` constructor arg is true, only ``int``, ``long``, and 
-    ``float`` values will be accepted.  This flag is intended to enable
-    additional numeric statistics, although none are currently implemented.
-
     ``.min`` and ``.max`` are ``None`` until the first data value is
     registered.
 
     Subclasses can override ``._init_stats`` and ``._update_stats`` to add
-    additional statistics.
+    additional statistics. 
+    
+    The constructor accepts one optional argument, ``numeric``. If true, the
+    instance accepts only values that are ``int``, ``long``, or ``float``.
+    The default is false, which accepts any value. This is meant for instances
+    or subclasses that don't want non-numeric values.
     """
     __version__ = 1
 
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.