Robert Brewer avatar Robert Brewer committed d26d4c9

Docstrings, plus Application now copies its cls.namespaces into self.namespaces.

Comments (0)

Files changed (3)

cherrypy/_cpconfig.py

         index.exposed = True
         index._cp_config = {'request.show_tracebacks': False}
 
+Note, however, that this behavior is only guaranteed for the default
+dispatcher. Other dispatchers may have different restrictions on where
+you can attach _cp_config attributes.
+
 
 Namespaces
 ----------
     server:     Controls the default HTTP server via cherrypy.server.
                 These can only be declared in the global config.
     tools:      Runs and configures additional request-processing packages.
+    wsgi:       Adds WSGI middleware to an Application's "pipeline".
+                These can only be declared in the app's root config ("/").
     checker:    Controls the 'checker', which looks for common errors in
                 app state (including config) when the engine starts.
                 Global config only.
 You can define your own namespaces to be called at the Global, Application,
 or Request level, by adding a named handler to cherrypy.config.namespaces,
 app.namespaces, or cherrypy.engine.request_class.namespaces. The name can
-be any string, and the handler must be either a callable or a context
-manager.
+be any string, and the handler must be either a callable or a (Python 2.5
+style) context manager.
 """
 
 import ConfigParser

cherrypy/_cpdispatch.py

 
 
 class Dispatcher(object):
+    """CherryPy Dispatcher which walks a tree of objects to find a handler.
+    
+    The tree is rooted at cherrypy.request.app.root, and each hierarchical
+    component in the path_info argument is matched to a corresponding nested
+    attribute of the root object. Matching handlers must have an 'exposed'
+    attribute which evaluates to True. The special method name "index"
+    matches a URI which ends in a slash ("/"). The special method name
+    "default" may match a portion of the path_info (but only when no longer
+    substring of the path_info matches some other object).
+    
+    This is the default, built-in dispatcher for CherryPy.
+    """
     
     def __call__(self, path_info):
         """Set handler and config for the current request."""

cherrypy/_cptree.py

     
     An instance of this class may also be used as a WSGI callable
     (WSGI application object) for itself.
+    """
     
-    root: the top-most container of page handlers for this app.
-    script_name: the URL "mount point" for this app; for example,
-        if script_name is "/my/cool/app", then the URL
-        "http://my.domain.tld/my/cool/app/page1" might be handled
-        by a "page1" method on the root object. If script_name is
-        explicitly set to None, then CherryPy will attempt to provide
-        it each time from request.wsgi_environ['SCRIPT_NAME'].
-    config: a dict of {path: pathconf} pairs, where 'pathconf' is itself
-        a dict of {key: value} pairs.
+    __metaclass__ = cherrypy._AttributeDocstrings
+    
+    root = None
+    root__doc = """
+    The top-most container of page handlers for this app. Handlers should
+    be arranged in a hierarchy of attributes, matching the expected URI
+    hierarchy; the default dispatcher then searches this hierarchy for a
+    matching handler. When using a dispatcher other than the default,
+    this value may be None."""
+    
+    config = {}
+    config__doc = """
+    A dict of {path: pathconf} pairs, where 'pathconf' is itself a dict
+    of {key: value} pairs."""
+    
+    namespaces = {}
+    namespaces__doc = """
+    A dict of config namespace names and handlers. Each config entry should
+    begin with a namespace name; the corresponding namespace handler will
+    be called once for each config entry in that namespace, and will be
+    passed two arguments: the config key (with the namespace removed)
+    and the config value.
+    
+    Namespace handlers may be any Python callable; they may also be
+    Python 2.5-style 'context managers', in which case their __enter__
+    method should return a callable to be used as the handler.
+    See cherrypy.tools (the Toolbox class) for an example.
     """
     
+    log = None
+    log__doc = """A LogManager instance. See _cplogging."""
+    
+    wsgiapp = None
+    wsgiapp__doc = """A CPWSGIApp instance. See _cpwsgi."""
+    
     def __init__(self, root, script_name=""):
         self.log = _cplogging.LogManager(id(self), cherrypy.log.logger_root)
         self.root = root
         self.script_name = script_name
         self.wsgiapp = _cpwsgi.CPWSGIApp(self)
-        self.namespaces = {"log": lambda k, v: setattr(self.log, k, v),
-                           "wsgi": self.wsgiapp.namespace_handler,
-                           }
+        
+        self.namespaces = self.namespaces.copy()
+        self.namespaces["log"] = lambda k, v: setattr(self.log, k, v)
+        self.namespaces["wsgi"] = self.wsgiapp.namespace_handler
+        
         self.config = {}
     
+    script_name__doc = """
+    The URI "mount point" for this app; for example, if script_name is
+    "/my/cool/app", then the URL "http://my.domain.tld/my/cool/app/page1"
+    might be handled by a "page1" method on the root object. If script_name
+    is explicitly set to None, then the script_name will be provided
+    for each call from request.wsgi_environ['SCRIPT_NAME']."""
     def _get_script_name(self):
         if self._script_name is None:
             # None signals that the script name should be pulled from WSGI environ.
         return self._script_name
     def _set_script_name(self, value):
         self._script_name = value
-    script_name = property(fget=_get_script_name, fset=_set_script_name)
+    script_name = property(fget=_get_script_name, fset=_set_script_name,
+                           doc=script_name__doc)
     
     def merge(self, config):
         """Merge the given config into self.config."""
     An instance of this class may also be used as a WSGI callable
     (WSGI application object), in which case it dispatches to all
     mounted apps.
+    """
     
-    apps: a dict of the form {script name: application}, where "script name"
-        is a string declaring the URL mount point (no trailing slash),
-        and "application" is an instance of cherrypy.Application (or an
-        arbitrary WSGI callable if you happen to be using a WSGI server).
-    """
+    apps = {}
+    apps__doc = """
+    A dict of the form {script name: application}, where "script name"
+    is a string declaring the URI mount point (no trailing slash), and
+    "application" is an instance of cherrypy.Application (or an arbitrary
+    WSGI callable if you happen to be using a WSGI server)."""
     
     def __init__(self):
         self.apps = {}
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.