Commits

Robert Brewer committed f640570

Doc work on cherrypy.process.

Comments (0)

Files changed (10)

cherrypy/process/plugins.py

     """Register bus channels (and listeners) for system signals.
     
     By default, instantiating this object subscribes the following signals
-    and listeners:
+    and listeners::
     
         TERM: bus.exit
         HUP : bus.restart
         self._previous_handlers = {}
     
     def subscribe(self):
+        """Subscribe self.handlers to signals."""
         for sig, func in self.handlers.items():
             try:
                 self.set_handler(sig, func)
                 pass
     
     def unsubscribe(self):
+        """Unsubscribe self.handlers from signals."""
         for signum, handler in self._previous_handlers.items():
             signame = self.signals[signum]
             
     """WSPBus listener to periodically run a callback in its own thread.
     
     bus: a Web Site Process Bus object.
+    
     callback: the function to call at intervals.
+    
     frequency: the time in seconds between callback runs.
     """
     

cherrypy/process/wspbus.py

 Ideally, a Bus object will be flexible enough to be useful in a variety
 of invocation scenarios:
 
- 1. The deployer starts a site from the command line via a framework-
-     neutral deployment script; applications from multiple frameworks
-     are mixed in a single site. Command-line arguments and configuration
-     files are used to define site-wide components such as the HTTP server,
-     WSGI component graph, autoreload behavior, signal handling, etc.
+ 1. The deployer starts a site from the command line via a
+    framework-neutral deployment script; applications from multiple frameworks
+    are mixed in a single site. Command-line arguments and configuration
+    files are used to define site-wide components such as the HTTP server,
+    WSGI component graph, autoreload behavior, signal handling, etc.
  2. The deployer starts a site via some other process, such as Apache;
-     applications from multiple frameworks are mixed in a single site.
-     Autoreload and signal handling (from Python at least) are disabled.
+    applications from multiple frameworks are mixed in a single site.
+    Autoreload and signal handling (from Python at least) are disabled.
  3. The deployer starts a site via a framework-specific mechanism;
-     for example, when running tests, exploring tutorials, or deploying
-     single applications from a single framework. The framework controls
-     which site-wide components are enabled as it sees fit.
+    for example, when running tests, exploring tutorials, or deploying
+    single applications from a single framework. The framework controls
+    which site-wide components are enabled as it sees fit.
 
 The Bus object in this package uses topic-based publish-subscribe
 messaging to accomplish all this. A few topic channels are built in
 The Bus object works as a finite state machine which models the current
 state of the process. Bus methods move it from one state to another;
 those methods then publish to subscribed listeners on the channel for
-the new state.
+the new state.::
 
                         O
                         |
 _startup_cwd = os.getcwd()
 
 class ChannelFailures(Exception):
+    """Exception raised when errors occur in a listener during Bus.publish()."""
     delimiter = '\n'
     
     def __init__(self, *args, **kwargs):
         self._exceptions = list()
     
     def handle_exception(self):
+        """Append the current exception to self."""
         self._exceptions.append(sys.exc_info())
     
     def get_instances(self):
+        """Return a list of seen exception instances."""
         return [instance for cls, instance, traceback in self._exceptions]
     
     def __str__(self):
             self._do_execv()
     
     def wait(self, state, interval=0.1, channel=None):
-        """Wait for the given state(s)."""
+        """Poll for the given state(s) at intervals; publish to channel."""
         if isinstance(state, (tuple, list)):
             states = state
         else:

sphinx/source/intro/concepts/basics.rst

    named ``index``, which will get called when the root URL for the site is
    requested (for example, ``http://localhost/``). This method returns the
    **contents** of the Web page; in this case, the ``'Hello World!'`` string.
+   Note that you don't have to subclass any framework-provided classes; in fact,
+   you don't even have to use classes at all! But let's start with them for now.
  * The ``index.exposed = True`` is a necessary step to tell CherryPy that the
    ``index()`` method will be **exposed**. Only exposed methods can be called
    to answer a request. This feature allows the user to select which methods
 
 When the application is executed, the CherryPy server is started with the
 default configuration. It will listen on ``localhost`` at port ``8080``. These
-defaults can be overridden by using a configuration file (more on this later).
+defaults can be overridden by using a configuration file or dictionary
+(more on this later).
 
 Finally, the web server receives the request for the URL
 ``http://localhost:8080``. It searches for the best method to handle the
 to the ``index.html`` that is the standard page for conventional Web servers).
 The HelloWorld class defines an ``index()`` method and exposes it. CherryPy
 calls ``HelloWorld().index()``, and the result of the call is sent back to
-the browser as the contents of the index page for the website. All work is
+the browser as the contents of the index page for the website. All the
+dispatching and HTTP-processing work is
 done automatically; the application programmer only needs to provide the
 desired content as the return value of the ``index`` method.
 
 CherryPy structure
-==================
+------------------
 
 Most of the features of CherryPy are available through the :mod:`cherrypy`
 module. It contains several members:
 
- * :class:`cherrypy.engine <cherrypy._cpengine.Engine>` contains the API to
-   control the CherryPy engine.
+ * cherrypy.engine (a :class:`Bus <cherrypy.process.wspbus.Bus>` instance)
+   controls process startup, shutdown, and other events, including your own
+   Plugins. See :doc:`/intro/concepts/engine`.
  * :class:`cherrypy.server <cherrypy._cpserver.Server>` contains the API to
    control the HTTP server.
  * :class:`cherrypy.request <cherrypy._cprequest.Request>` contains the all

sphinx/source/intro/index.rst

    or any other solution, or none at all if you're not using HTML ;)
  * CherryPy is not a database or ORM. Rather than dictate or bless a persistence
    layer to you, CherryPy allows you to choose your own.
-   See :doc:`/progguide/databases`.
 
 
 Contents

sphinx/source/intro/install.rst

 -----------
 
 * The repository is open for anonymous read-only access. CherryPy developers
-  have write permissions. To obtain write permission, please contact fumanchu via
-  email or IRC.
+  have write permissions. To obtain write permission, please contact us via
+  email or IRC (see http://www.cherrypy.org/wiki/CherryPyInvolved).
 * The repository follows the standard trunk/branches/tags structure that is
   recommended in the Subversion documentation:
 

sphinx/source/intro/whycherrypy.rst

 1. Simplicity
 -------------
 
-Developing with CherryPy is a simple task. "Hello, world" is only a few lines long, and does not require the developer to learn the entire (albeit very manageable) framework all at once. The framework is very pythonic; that is, it follows Python's conventions very nicely (code is sparse and clean).
+Developing with CherryPy is a simple task. "Hello, world" is only a few lines
+long, and does not require the developer to learn the entire (albeit very
+manageable) framework all at once. The framework is very pythonic; that is,
+it follows Python's conventions very nicely (code is sparse and clean).
 
-Contrast this with J2EE and Python's most popular and visible web frameworks: Django, Zope, Pylons, and Turbogears. In all of them, the learning curve is massive. In these frameworks, "Hello, world" requires the programmer to set up a large scaffold which spans multiple files and to type a lot of boilerplate code. CherryPy succeeds because it does not include the bloat of other frameworks, allowing the programmer to write their web application quickly while still maintaining a high level of organization and scalability.
+Contrast this with J2EE and Python's most popular and visible web frameworks:
+Django, Zope, Pylons, and Turbogears. In all of them, the learning curve is
+massive. In these frameworks, "Hello, world" requires the programmer to set
+up a large scaffold which spans multiple files and to type a lot of boilerplate
+code. CherryPy succeeds because it does not include the bloat of other
+frameworks, allowing the programmer to write their web application quickly
+while still maintaining a high level of organization and scalability.
 
-CherryPy is also very modular. The core is fast and clean, and extension features are easy to write and plug in using code or the elegant config system. The primary components (server, engine, request, response, etc.) are all extendable (even replaceable) and well-managed.
+CherryPy is also very modular. The core is fast and clean, and extension
+features are easy to write and plug in using code or the elegant config
+system. The primary components (server, engine, request, response, etc.)
+are all extendable (even replaceable) and well-managed.
 
-In short, CherryPy empowers the developer to work with the framework, not against or around it.
+In short, CherryPy empowers the developer to work with the framework,
+not against or around it.
 
 2. Power
 --------
 
-CherryPy leverages all of the power of Python. Python is a dynamic langauge which allows for rapid development of applications. Python also has an extensive built-in API which simplifies web app development. Even more extensive, however, are the third-party libraries available for Python. These range from object-relational mappers to form libraries, to an automatic Python optimizer, a Windows exe generator, imaging libraries, email support, HTML templating engines, etc. CherryPy applications are just like regular Python applications. CherryPy does not stand in your way if you want to use these brilliant tools.
+CherryPy leverages all of the power of Python. Python is a dynamic language
+which allows for rapid development of applications. Python also has an
+extensive built-in API which simplifies web app development. Even more
+extensive, however, are the third-party libraries available for Python. These
+range from object-relational mappers to form libraries, to an automatic Python
+optimizer, a Windows exe generator, imaging libraries, email support, HTML
+templating engines, etc. CherryPy applications are just like regular Python
+applications. CherryPy does not stand in your way if you want to use these
+brilliant tools.
 
 CherryPy also provides Tools and Plugins, which are powerful extension points
 needed to develop world-class web applications.
 3. Maturity
 -----------
 
-Maturity is extremely important when developing a real-world application. Unlike many other web frameworks, CherryPy has a final, stable release. It is fully bugtested, optimized, and proven reliable for real-world use. The API will not suddenly change and break backwards compatibility, so your applications are assured to continue working even through subsequent updates in the current version series.
+Maturity is extremely important when developing a real-world application.
+Unlike many other web frameworks, CherryPy has had many final, stable releases.
+It is fully bugtested, optimized, and proven reliable for real-world use.
+The API will not suddenly change and break backwards compatibility, so your
+applications are assured to continue working even through subsequent updates
+in the current version series.
 
-CherryPy is also a "3.0" project: the first edition of CherryPy set the tone, the second edition made it work, and the third edition makes it beautiful. Each version built on lessons learned from the previous, bringing the developer a superior tool for the job.
+CherryPy is also a "3.0" project: the first edition of CherryPy set the tone,
+the second edition made it work, and the third edition makes it beautiful.
+Each version built on lessons learned from the previous, bringing the developer
+a superior tool for the job.
 
 4. Community
 ------------
 
-CherryPy has an active community that develops deployed CherryPy applications and are willing and ready to assist you on the CherryPy mailing list or IRC. The developers also frequent the list and often answer questions and implement features requested by the end-users.
+CherryPy has an active community that develops deployed CherryPy applications
+and are willing and ready to assist you on the CherryPy mailing list or IRC.
+The developers also frequent the list and often answer questions and implement
+features requested by the end-users.
 
 5. Deployability
 ----------------
 
-Unlike many other Python web frameworks, there are cost-effective ways to deploy your CherryPy application.
+Unlike many other Python web frameworks, there are cost-effective ways to
+deploy your CherryPy application.
 
-Out of the box, CherryPy includes its own production-ready application server to host your application. If the application needs to be deployed on Apache, there is copious documentation discussing how to connect the two. CherryPy can also be deployed on any WSGI-compliant gateway (a technology for interfacing numerous types of web servers): mod_wsgi, FastCGI, SCGI, IIS, etc.
+Out of the box, CherryPy includes its own production-ready HTTP server
+to host your application. If the application needs to be deployed on Apache,
+there is copious documentation discussing how to connect the two. CherryPy can
+also be deployed on any WSGI-compliant gateway (a technology for interfacing
+numerous types of web servers): mod_wsgi, FastCGI, SCGI, IIS, etc.
 
-In addition, CherryPy is pure-python and is compatible with Python 2.3. This means that CherryPy will run on all major platforms that Python will run on (Windows, MacOSX, Linux, BSD, etc).
+In addition, CherryPy is pure-python and is compatible with Python 2.3. This
+means that CherryPy will run on all major platforms that Python will run on
+(Windows, MacOSX, Linux, BSD, etc).
 
-`Webfaction.com <http://www.webfaction.com>`_, run by the inventor of CherryPy, is a commercial web host that offers CherryPy hosting packages (in addition to several others).
+`Webfaction.com <http://www.webfaction.com>`_, run by the inventor of CherryPy,
+is a commercial web host that offers CherryPy hosting packages (in addition to
+several others).
 
 6. It's free!
 -------------
 
-All of CherryPy is licensed under the open-source BSD license, which means **CherryPy can be used commercially for ZERO cost**.
+All of CherryPy is licensed under the open-source BSD license, which means
+**CherryPy can be used commercially for ZERO cost**.
 
 7. Where to go from here?
 -------------------------
 
-Check out the :doc:`/intro/concepts/index` and :doc:`/progguide/index` for more complete documentation.
-
+Check out the :doc:`/intro/concepts/index` and :doc:`/progguide/index` for
+more complete documentation.
+la

sphinx/source/refman/index.rst

 
    *
    lib/index
+   process/index
 
 

sphinx/source/refman/process/index.rst

+****************
+cherrypy.process
+****************
+
+.. toctree::
+   :glob:
+
+   *
+
+

sphinx/source/refman/process/plugins.rst

+*************************************************
+:mod:`cherrypy.process.plugins` -- Engine Plugins
+*************************************************
+
+.. automodule:: cherrypy.process.plugins
+
+Classes
+=======
+
+.. autoclass:: SimplePlugin
+   :members:
+
+.. autoclass:: SignalHandler
+   :members:
+
+.. autoclass:: DropPrivileges
+   :members:
+
+.. autoclass:: Daemonizer
+   :members:
+
+.. autoclass:: PIDFile
+   :members:
+
+.. autoclass:: PerpetualTimer
+   :members:
+
+.. autoclass:: Monitor
+   :members:
+
+.. autoclass:: Autoreloader
+   :members:
+
+.. autoclass:: ThreadManager
+   :members:
+

sphinx/source/refman/process/wspbus.rst

+**********************************************************
+:mod:`cherrypy.process.wspbus` -- The Web Site Process Bus
+**********************************************************
+
+.. automodule:: cherrypy.process.wspbus
+
+Classes
+=======
+
+.. autoclass:: ChannelFailures
+   :members:
+
+.. autoclass:: Bus
+   :members:
+