CherryPy's Package Design

As code is developed or refactored, a consistent package architecture should be followed.

Goals

1. Flat is better than nested. Start worrying if you're more than one folder deep from cherrypy/__init__.py.
2. Some modules should be considered "private": for CherryPy's internal use only. If they wish to expose functionality to the application developer, a public module should import that functionality.

Strategy

The "root" folder should have an __init__.py module which exposes all the core functionality an application developer would need to build a basic application. That "core functionality" can be broken out into other modules in the same folder, from which __init__ then imports. "Private" modules' names should start with "_cp".

Functionality which application developers may optionally import into their applications should be kept in a separate subfolder (currently, "lib"). Good candidates for that folder are profiling and coverage tools, optional form handlers, authentication tools, etc. Note that the core may also make use of these modules! But if it's designed to be used directly, but optionally, by app devs, it should go in "lib".

In general, if a feature can be provided without being dependent upon other parts of cherrypy, it gets put into lib/http. If it is specific to CherryPy (e.g. tools), then it is placed in lib/cptools. Sometimes, the feature is split into both modules, with a generic interface in http and a CP-specific interface in cptools.

Modules

• __init__.py: The package base. You should be able to build a basic CherryPy application by importing only this module.
• _cperror.py: Exception classes. Internal, but __init__.py calls from _cperror import *.
• _cprequest.py: The "core" HTTP request-to-response handling process. Internal.
• _cpwsgi.py: The WSGI interface. Internal. May be used with any WSGI server (not just the built-in one).
• wsgiserver.py: The WSGI HTTP server. Although built for CherryPy, it should remain isolated and public so that other frameworks or projects may use it with no modifications.
• _cpconfig.py: The CherryPy configuration system, including config getters and setters, and a file parser. Internal.
• _cpengine.py: The interface between the CherryPy core _cprequest and the HTTP servers (_cpserver. Contains top-level controls for the CherryPy service, including start(), stop(), and request() functions. Custom HTTP servers should call these to communicate with the core.
• /lib: Optional functionality for CherryPy applications.
  • __init__.py: Package root. Miscellaneous code goes here.
  • covercp.py: The coverage tool. This is both used by the core, and exposes functions to developers, and runs as a script, as well. The name might have been a bad choice, but it should not be "coverage.py", which would conflict with the tools it wraps.
  • cptools.py: Seems to be CherryPy's version of "miscellaneous developer functions/classes". Other modules may provide components that the core _cprequest uses; in general, /lib and cptools in particular contains those components which developers might also use in their own code.
  • http.py: Low-level (cherrypy-agnostic) HTTP-handling tools.
  • profiler.py: The profiling tool. This is both used by the core, and exposes functions to developers, and runs as a script, as well.
• /test: The CherryPy test suite.
• /tutorial: The CherryPy tutorials.