From e4a1d6a4a169a5fc4f56fd30b26c704d87c42a9c Mon Sep 17 00:00:00 2001 From: Remy Date: Fri, 20 May 2011 19:26:53 -0700 Subject: [PATCH] first full commit --- cherrypy/LICENSE.txt | 25 + cherrypy/__init__.py | 620 ++++ cherrypy/_cpchecker.py | 327 +++ cherrypy/_cpcompat.py | 283 ++ cherrypy/_cpconfig.py | 295 ++ cherrypy/_cpdispatch.py | 622 +++++ cherrypy/_cperror.py | 553 ++++ cherrypy/_cplogging.py | 393 +++ cherrypy/_cpmodpy.py | 333 +++ cherrypy/_cpnative_server.py | 149 + cherrypy/_cpreqbody.py | 941 +++++++ cherrypy/_cprequest.py | 926 ++++++ cherrypy/_cpserver.py | 195 ++ cherrypy/_cpthreadinglocal.py | 239 ++ cherrypy/_cptools.py | 510 ++++ cherrypy/_cptree.py | 279 ++ cherrypy/_cpwsgi.py | 347 +++ cherrypy/_cpwsgi_server.py | 54 + cherrypy/cherryd | 109 + cherrypy/favicon.ico | Bin 0 -> 1406 bytes cherrypy/lib/__init__.py | 45 + cherrypy/lib/auth.py | 87 + cherrypy/lib/auth_basic.py | 87 + cherrypy/lib/auth_digest.py | 365 +++ cherrypy/lib/caching.py | 465 +++ cherrypy/lib/covercp.py | 365 +++ cherrypy/lib/cpstats.py | 661 +++++ cherrypy/lib/cptools.py | 611 ++++ cherrypy/lib/encoding.py | 388 +++ cherrypy/lib/http.py | 7 + cherrypy/lib/httpauth.py | 354 +++ cherrypy/lib/httputil.py | 469 ++++ cherrypy/lib/jsontools.py | 87 + cherrypy/lib/profiler.py | 208 ++ cherrypy/lib/reprconf.py | 351 +++ cherrypy/lib/sessions.py | 832 ++++++ cherrypy/lib/static.py | 352 +++ cherrypy/lib/xmlrpc.py | 49 + cherrypy/process/__init__.py | 14 + cherrypy/process/plugins.py | 681 +++++ cherrypy/process/servers.py | 418 +++ cherrypy/process/win32.py | 174 ++ cherrypy/process/wspbus.py | 393 +++ cherrypy/scaffold/__init__.py | 61 + cherrypy/scaffold/apache-fcgi.conf | 22 + cherrypy/scaffold/example.conf | 3 + cherrypy/scaffold/site.conf | 14 + .../static/made_with_cherrypy_small.png | Bin 0 -> 7455 bytes cherrypy/test/__init__.py | 25 + cherrypy/test/_test_decorators.py | 41 + cherrypy/test/_test_states_demo.py | 66 + cherrypy/test/benchmark.py | 409 +++ cherrypy/test/checkerdemo.py | 47 + cherrypy/test/fastcgi.conf | 18 + cherrypy/test/fcgi.conf | 14 + cherrypy/test/helper.py | 476 ++++ cherrypy/test/logtest.py | 181 ++ cherrypy/test/modfastcgi.py | 135 + cherrypy/test/modfcgid.py | 125 + cherrypy/test/modpy.py | 163 ++ cherrypy/test/modwsgi.py | 148 + cherrypy/test/native-server.ini | 9 + cherrypy/test/sessiondemo.py | 153 + cherrypy/test/static/dirback.jpg | Bin 0 -> 18238 bytes cherrypy/test/static/index.html | 1 + cherrypy/test/style.css | 1 + cherrypy/test/test.pem | 38 + cherrypy/test/test_auth_basic.py | 79 + cherrypy/test/test_auth_digest.py | 115 + cherrypy/test/test_bus.py | 263 ++ cherrypy/test/test_caching.py | 329 +++ cherrypy/test/test_config.py | 249 ++ cherrypy/test/test_config_server.py | 121 + cherrypy/test/test_conn.py | 734 +++++ cherrypy/test/test_core.py | 617 ++++ cherrypy/test/test_dynamicobjectmapping.py | 403 +++ cherrypy/test/test_encoding.py | 363 +++ cherrypy/test/test_etags.py | 81 + cherrypy/test/test_http.py | 168 ++ cherrypy/test/test_httpauth.py | 151 + cherrypy/test/test_httplib.py | 29 + cherrypy/test/test_json.py | 79 + cherrypy/test/test_logging.py | 149 + cherrypy/test/test_mime.py | 128 + cherrypy/test/test_misc_tools.py | 202 ++ cherrypy/test/test_objectmapping.py | 403 +++ cherrypy/test/test_proxy.py | 129 + cherrypy/test/test_refleaks.py | 119 + cherrypy/test/test_request_obj.py | 722 +++++ cherrypy/test/test_routes.py | 69 + cherrypy/test/test_session.py | 464 +++ cherrypy/test/test_sessionauthenticate.py | 62 + cherrypy/test/test_states.py | 436 +++ cherrypy/test/test_static.py | 300 ++ cherrypy/test/test_tools.py | 393 +++ cherrypy/test/test_tutorials.py | 201 ++ cherrypy/test/test_virtualhost.py | 107 + cherrypy/test/test_wsgi_ns.py | 80 + cherrypy/test/test_wsgi_vhost.py | 36 + cherrypy/test/test_wsgiapps.py | 111 + cherrypy/test/test_xmlrpc.py | 172 ++ cherrypy/test/webtest.py | 535 ++++ cherrypy/tutorial/README.txt | 16 + cherrypy/tutorial/__init__.py | 3 + cherrypy/tutorial/bonus-sqlobject.py | 168 ++ cherrypy/tutorial/custom_error.html | 14 + cherrypy/tutorial/pdf_file.pdf | Bin 0 -> 85698 bytes cherrypy/tutorial/tut01_helloworld.py | 35 + cherrypy/tutorial/tut02_expose_methods.py | 32 + cherrypy/tutorial/tut03_get_and_post.py | 53 + cherrypy/tutorial/tut04_complex_site.py | 98 + cherrypy/tutorial/tut05_derived_objects.py | 83 + cherrypy/tutorial/tut06_default_method.py | 64 + cherrypy/tutorial/tut07_sessions.py | 44 + .../tutorial/tut08_generators_and_yield.py | 47 + cherrypy/tutorial/tut09_files.py | 107 + cherrypy/tutorial/tut10_http_errors.py | 81 + cherrypy/tutorial/tutorial.conf | 4 + cherrypy/wsgiserver/__init__.py | 2219 +++++++++++++++ cherrypy/wsgiserver/ssl_builtin.py | 72 + cherrypy/wsgiserver/ssl_pyopenssl.py | 256 ++ config.ini | 25 + config.py | 91 + configobj.py | 2468 ++++++++++++++++ data/css/style.css | 114 + data/css/view.css | 827 ++++++ data/images/blank.gif | Bin 0 -> 49 bytes data/images/bottom.png | Bin 0 -> 431 bytes data/images/headphoneslogo.png | Bin 0 -> 8304 bytes data/images/shadow.gif | Bin 0 -> 46 bytes data/images/top.png | Bin 0 -> 417 bytes data/js/view.js | 1 + findArtist.py | 30 + headphones.py | 13 + musicbrainz2/__init__.py | 26 + musicbrainz2/data/__init__.py | 10 + musicbrainz2/data/countrynames.py | 253 ++ musicbrainz2/data/languagenames.py | 400 +++ musicbrainz2/data/releasetypenames.py | 24 + musicbrainz2/data/scriptnames.py | 59 + musicbrainz2/disc.py | 221 ++ musicbrainz2/model.py | 2488 +++++++++++++++++ musicbrainz2/utils.py | 204 ++ musicbrainz2/webservice.py | 1519 ++++++++++ musicbrainz2/wsxml.py | 1675 +++++++++++ search.py | 29 + server.conf | 19 + templates.py | 30 + webServer.py | 350 +++ 149 files changed, 39684 insertions(+) create mode 100644 cherrypy/LICENSE.txt create mode 100644 cherrypy/__init__.py create mode 100644 cherrypy/_cpchecker.py create mode 100644 cherrypy/_cpcompat.py create mode 100644 cherrypy/_cpconfig.py create mode 100644 cherrypy/_cpdispatch.py create mode 100644 cherrypy/_cperror.py create mode 100644 cherrypy/_cplogging.py create mode 100644 cherrypy/_cpmodpy.py create mode 100644 cherrypy/_cpnative_server.py create mode 100644 cherrypy/_cpreqbody.py create mode 100644 cherrypy/_cprequest.py create mode 100644 cherrypy/_cpserver.py create mode 100644 cherrypy/_cpthreadinglocal.py create mode 100644 cherrypy/_cptools.py create mode 100644 cherrypy/_cptree.py create mode 100644 cherrypy/_cpwsgi.py create mode 100644 cherrypy/_cpwsgi_server.py create mode 100755 cherrypy/cherryd create mode 100644 cherrypy/favicon.ico create mode 100644 cherrypy/lib/__init__.py create mode 100644 cherrypy/lib/auth.py create mode 100644 cherrypy/lib/auth_basic.py create mode 100644 cherrypy/lib/auth_digest.py create mode 100644 cherrypy/lib/caching.py create mode 100644 cherrypy/lib/covercp.py create mode 100644 cherrypy/lib/cpstats.py create mode 100644 cherrypy/lib/cptools.py create mode 100644 cherrypy/lib/encoding.py create mode 100644 cherrypy/lib/http.py create mode 100644 cherrypy/lib/httpauth.py create mode 100644 cherrypy/lib/httputil.py create mode 100644 cherrypy/lib/jsontools.py create mode 100644 cherrypy/lib/profiler.py create mode 100644 cherrypy/lib/reprconf.py create mode 100644 cherrypy/lib/sessions.py create mode 100644 cherrypy/lib/static.py create mode 100644 cherrypy/lib/xmlrpc.py create mode 100644 cherrypy/process/__init__.py create mode 100644 cherrypy/process/plugins.py create mode 100644 cherrypy/process/servers.py create mode 100644 cherrypy/process/win32.py create mode 100644 cherrypy/process/wspbus.py create mode 100644 cherrypy/scaffold/__init__.py create mode 100644 cherrypy/scaffold/apache-fcgi.conf create mode 100644 cherrypy/scaffold/example.conf create mode 100644 cherrypy/scaffold/site.conf create mode 100644 cherrypy/scaffold/static/made_with_cherrypy_small.png create mode 100644 cherrypy/test/__init__.py create mode 100644 cherrypy/test/_test_decorators.py create mode 100644 cherrypy/test/_test_states_demo.py create mode 100644 cherrypy/test/benchmark.py create mode 100644 cherrypy/test/checkerdemo.py create mode 100644 cherrypy/test/fastcgi.conf create mode 100644 cherrypy/test/fcgi.conf create mode 100644 cherrypy/test/helper.py create mode 100644 cherrypy/test/logtest.py create mode 100644 cherrypy/test/modfastcgi.py create mode 100644 cherrypy/test/modfcgid.py create mode 100644 cherrypy/test/modpy.py create mode 100644 cherrypy/test/modwsgi.py create mode 100644 cherrypy/test/native-server.ini create mode 100755 cherrypy/test/sessiondemo.py create mode 100644 cherrypy/test/static/dirback.jpg create mode 100644 cherrypy/test/static/index.html create mode 100644 cherrypy/test/style.css create mode 100644 cherrypy/test/test.pem create mode 100644 cherrypy/test/test_auth_basic.py create mode 100644 cherrypy/test/test_auth_digest.py create mode 100644 cherrypy/test/test_bus.py create mode 100644 cherrypy/test/test_caching.py create mode 100644 cherrypy/test/test_config.py create mode 100644 cherrypy/test/test_config_server.py create mode 100644 cherrypy/test/test_conn.py create mode 100644 cherrypy/test/test_core.py create mode 100644 cherrypy/test/test_dynamicobjectmapping.py create mode 100644 cherrypy/test/test_encoding.py create mode 100644 cherrypy/test/test_etags.py create mode 100644 cherrypy/test/test_http.py create mode 100644 cherrypy/test/test_httpauth.py create mode 100644 cherrypy/test/test_httplib.py create mode 100644 cherrypy/test/test_json.py create mode 100644 cherrypy/test/test_logging.py create mode 100644 cherrypy/test/test_mime.py create mode 100644 cherrypy/test/test_misc_tools.py create mode 100644 cherrypy/test/test_objectmapping.py create mode 100644 cherrypy/test/test_proxy.py create mode 100644 cherrypy/test/test_refleaks.py create mode 100644 cherrypy/test/test_request_obj.py create mode 100644 cherrypy/test/test_routes.py create mode 100755 cherrypy/test/test_session.py create mode 100644 cherrypy/test/test_sessionauthenticate.py create mode 100644 cherrypy/test/test_states.py create mode 100644 cherrypy/test/test_static.py create mode 100644 cherrypy/test/test_tools.py create mode 100644 cherrypy/test/test_tutorials.py create mode 100644 cherrypy/test/test_virtualhost.py create mode 100644 cherrypy/test/test_wsgi_ns.py create mode 100644 cherrypy/test/test_wsgi_vhost.py create mode 100644 cherrypy/test/test_wsgiapps.py create mode 100644 cherrypy/test/test_xmlrpc.py create mode 100644 cherrypy/test/webtest.py create mode 100644 cherrypy/tutorial/README.txt create mode 100644 cherrypy/tutorial/__init__.py create mode 100644 cherrypy/tutorial/bonus-sqlobject.py create mode 100644 cherrypy/tutorial/custom_error.html create mode 100644 cherrypy/tutorial/pdf_file.pdf create mode 100644 cherrypy/tutorial/tut01_helloworld.py create mode 100644 cherrypy/tutorial/tut02_expose_methods.py create mode 100644 cherrypy/tutorial/tut03_get_and_post.py create mode 100644 cherrypy/tutorial/tut04_complex_site.py create mode 100644 cherrypy/tutorial/tut05_derived_objects.py create mode 100644 cherrypy/tutorial/tut06_default_method.py create mode 100644 cherrypy/tutorial/tut07_sessions.py create mode 100644 cherrypy/tutorial/tut08_generators_and_yield.py create mode 100644 cherrypy/tutorial/tut09_files.py create mode 100644 cherrypy/tutorial/tut10_http_errors.py create mode 100644 cherrypy/tutorial/tutorial.conf create mode 100644 cherrypy/wsgiserver/__init__.py create mode 100644 cherrypy/wsgiserver/ssl_builtin.py create mode 100644 cherrypy/wsgiserver/ssl_pyopenssl.py create mode 100644 config.ini create mode 100644 config.py create mode 100644 configobj.py create mode 100644 data/css/style.css create mode 100755 data/css/view.css create mode 100755 data/images/blank.gif create mode 100755 data/images/bottom.png create mode 100644 data/images/headphoneslogo.png create mode 100755 data/images/shadow.gif create mode 100755 data/images/top.png create mode 100755 data/js/view.js create mode 100644 findArtist.py create mode 100755 headphones.py create mode 100644 musicbrainz2/__init__.py create mode 100644 musicbrainz2/data/__init__.py create mode 100644 musicbrainz2/data/countrynames.py create mode 100644 musicbrainz2/data/languagenames.py create mode 100644 musicbrainz2/data/releasetypenames.py create mode 100644 musicbrainz2/data/scriptnames.py create mode 100644 musicbrainz2/disc.py create mode 100644 musicbrainz2/model.py create mode 100644 musicbrainz2/utils.py create mode 100644 musicbrainz2/webservice.py create mode 100644 musicbrainz2/wsxml.py create mode 100644 search.py create mode 100644 server.conf create mode 100644 templates.py create mode 100644 webServer.py diff --git a/cherrypy/LICENSE.txt b/cherrypy/LICENSE.txt new file mode 100644 index 00000000..8db13fb2 --- /dev/null +++ b/cherrypy/LICENSE.txt @@ -0,0 +1,25 @@ +Copyright (c) 2004-2011, CherryPy Team (team@cherrypy.org) +All rights reserved. + +Redistribution and use in source and binary forms, with or without modification, +are permitted provided that the following conditions are met: + + * Redistributions of source code must retain the above copyright notice, + this list of conditions and the following disclaimer. + * Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. + * Neither the name of the CherryPy Team nor the names of its contributors + may be used to endorse or promote products derived from this software + without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND +ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE +FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/cherrypy/__init__.py b/cherrypy/__init__.py new file mode 100644 index 00000000..eb7cabf6 --- /dev/null +++ b/cherrypy/__init__.py @@ -0,0 +1,620 @@ +"""CherryPy is a pythonic, object-oriented HTTP framework. + + +CherryPy consists of not one, but four separate API layers. + +The APPLICATION LAYER is the simplest. CherryPy applications are written as +a tree of classes and methods, where each branch in the tree corresponds to +a branch in the URL path. Each method is a 'page handler', which receives +GET and POST params as keyword arguments, and returns or yields the (HTML) +body of the response. The special method name 'index' is used for paths +that end in a slash, and the special method name 'default' is used to +handle multiple paths via a single handler. This layer also includes: + + * the 'exposed' attribute (and cherrypy.expose) + * cherrypy.quickstart() + * _cp_config attributes + * cherrypy.tools (including cherrypy.session) + * cherrypy.url() + +The ENVIRONMENT LAYER is used by developers at all levels. It provides +information about the current request and response, plus the application +and server environment, via a (default) set of top-level objects: + + * cherrypy.request + * cherrypy.response + * cherrypy.engine + * cherrypy.server + * cherrypy.tree + * cherrypy.config + * cherrypy.thread_data + * cherrypy.log + * cherrypy.HTTPError, NotFound, and HTTPRedirect + * cherrypy.lib + +The EXTENSION LAYER allows advanced users to construct and share their own +plugins. It consists of: + + * Hook API + * Tool API + * Toolbox API + * Dispatch API + * Config Namespace API + +Finally, there is the CORE LAYER, which uses the core API's to construct +the default components which are available at higher layers. You can think +of the default components as the 'reference implementation' for CherryPy. +Megaframeworks (and advanced users) may replace the default components +with customized or extended components. The core API's are: + + * Application API + * Engine API + * Request API + * Server API + * WSGI API + +These API's are described in the CherryPy specification: +http://www.cherrypy.org/wiki/CherryPySpec +""" + +__version__ = "3.2.0" + +from cherrypy._cpcompat import urljoin as _urljoin, urlencode as _urlencode +from cherrypy._cpcompat import basestring, unicodestr + +from cherrypy._cperror import HTTPError, HTTPRedirect, InternalRedirect +from cherrypy._cperror import NotFound, CherryPyException, TimeoutError + +from cherrypy import _cpdispatch as dispatch + +from cherrypy import _cptools +tools = _cptools.default_toolbox +Tool = _cptools.Tool + +from cherrypy import _cprequest +from cherrypy.lib import httputil as _httputil + +from cherrypy import _cptree +tree = _cptree.Tree() +from cherrypy._cptree import Application +from cherrypy import _cpwsgi as wsgi + +from cherrypy import process +try: + from cherrypy.process import win32 + engine = win32.Win32Bus() + engine.console_control_handler = win32.ConsoleCtrlHandler(engine) + del win32 +except ImportError: + engine = process.bus + + +# Timeout monitor +class _TimeoutMonitor(process.plugins.Monitor): + + def __init__(self, bus): + self.servings = [] + process.plugins.Monitor.__init__(self, bus, self.run) + + def acquire(self): + self.servings.append((serving.request, serving.response)) + + def release(self): + try: + self.servings.remove((serving.request, serving.response)) + except ValueError: + pass + + def run(self): + """Check timeout on all responses. (Internal)""" + for req, resp in self.servings: + resp.check_timeout() +engine.timeout_monitor = _TimeoutMonitor(engine) +engine.timeout_monitor.subscribe() + +engine.autoreload = process.plugins.Autoreloader(engine) +engine.autoreload.subscribe() + +engine.thread_manager = process.plugins.ThreadManager(engine) +engine.thread_manager.subscribe() + +engine.signal_handler = process.plugins.SignalHandler(engine) + + +from cherrypy import _cpserver +server = _cpserver.Server() +server.subscribe() + + +def quickstart(root=None, script_name="", config=None): + """Mount the given root, start the builtin server (and engine), then block. + + root: an instance of a "controller class" (a collection of page handler + methods) which represents the root of the application. + script_name: a string containing the "mount point" of the application. + This should start with a slash, and be the path portion of the URL + at which to mount the given root. For example, if root.index() will + handle requests to "http://www.example.com:8080/dept/app1/", then + the script_name argument would be "/dept/app1". + + It MUST NOT end in a slash. If the script_name refers to the root + of the URI, it MUST be an empty string (not "/"). + config: a file or dict containing application config. If this contains + a [global] section, those entries will be used in the global + (site-wide) config. + """ + if config: + _global_conf_alias.update(config) + + tree.mount(root, script_name, config) + + if hasattr(engine, "signal_handler"): + engine.signal_handler.subscribe() + if hasattr(engine, "console_control_handler"): + engine.console_control_handler.subscribe() + + engine.start() + engine.block() + + +from cherrypy._cpcompat import threadlocal as _local + +class _Serving(_local): + """An interface for registering request and response objects. + + Rather than have a separate "thread local" object for the request and + the response, this class works as a single threadlocal container for + both objects (and any others which developers wish to define). In this + way, we can easily dump those objects when we stop/start a new HTTP + conversation, yet still refer to them as module-level globals in a + thread-safe way. + """ + + request = _cprequest.Request(_httputil.Host("127.0.0.1", 80), + _httputil.Host("127.0.0.1", 1111)) + """ + The request object for the current thread. In the main thread, + and any threads which are not receiving HTTP requests, this is None.""" + + response = _cprequest.Response() + """ + The response object for the current thread. In the main thread, + and any threads which are not receiving HTTP requests, this is None.""" + + def load(self, request, response): + self.request = request + self.response = response + + def clear(self): + """Remove all attributes of self.""" + self.__dict__.clear() + +serving = _Serving() + + +class _ThreadLocalProxy(object): + + __slots__ = ['__attrname__', '__dict__'] + + def __init__(self, attrname): + self.__attrname__ = attrname + + def __getattr__(self, name): + child = getattr(serving, self.__attrname__) + return getattr(child, name) + + def __setattr__(self, name, value): + if name in ("__attrname__", ): + object.__setattr__(self, name, value) + else: + child = getattr(serving, self.__attrname__) + setattr(child, name, value) + + def __delattr__(self, name): + child = getattr(serving, self.__attrname__) + delattr(child, name) + + def _get_dict(self): + child = getattr(serving, self.__attrname__) + d = child.__class__.__dict__.copy() + d.update(child.__dict__) + return d + __dict__ = property(_get_dict) + + def __getitem__(self, key): + child = getattr(serving, self.__attrname__) + return child[key] + + def __setitem__(self, key, value): + child = getattr(serving, self.__attrname__) + child[key] = value + + def __delitem__(self, key): + child = getattr(serving, self.__attrname__) + del child[key] + + def __contains__(self, key): + child = getattr(serving, self.__attrname__) + return key in child + + def __len__(self): + child = getattr(serving, self.__attrname__) + return len(child) + + def __nonzero__(self): + child = getattr(serving, self.__attrname__) + return bool(child) + # Python 3 + __bool__ = __nonzero__ + +# Create request and response object (the same objects will be used +# throughout the entire life of the webserver, but will redirect +# to the "serving" object) +request = _ThreadLocalProxy('request') +response = _ThreadLocalProxy('response') + +# Create thread_data object as a thread-specific all-purpose storage +class _ThreadData(_local): + """A container for thread-specific data.""" +thread_data = _ThreadData() + + +# Monkeypatch pydoc to allow help() to go through the threadlocal proxy. +# Jan 2007: no Googleable examples of anyone else replacing pydoc.resolve. +# The only other way would be to change what is returned from type(request) +# and that's not possible in pure Python (you'd have to fake ob_type). +def _cherrypy_pydoc_resolve(thing, forceload=0): + """Given an object or a path to an object, get the object and its name.""" + if isinstance(thing, _ThreadLocalProxy): + thing = getattr(serving, thing.__attrname__) + return _pydoc._builtin_resolve(thing, forceload) + +try: + import pydoc as _pydoc + _pydoc._builtin_resolve = _pydoc.resolve + _pydoc.resolve = _cherrypy_pydoc_resolve +except ImportError: + pass + + +from cherrypy import _cplogging + +class _GlobalLogManager(_cplogging.LogManager): + """A site-wide LogManager; routes to app.log or global log as appropriate. + + This :class:`LogManager` implements + cherrypy.log() and cherrypy.log.access(). If either + function is called during a request, the message will be sent to the + logger for the current Application. If they are called outside of a + request, the message will be sent to the site-wide logger. + """ + + def __call__(self, *args, **kwargs): + """Log the given message to the app.log or global log as appropriate.""" + # Do NOT use try/except here. See http://www.cherrypy.org/ticket/945 + if hasattr(request, 'app') and hasattr(request.app, 'log'): + log = request.app.log + else: + log = self + return log.error(*args, **kwargs) + + def access(self): + """Log an access message to the app.log or global log as appropriate.""" + try: + return request.app.log.access() + except AttributeError: + return _cplogging.LogManager.access(self) + + +log = _GlobalLogManager() +# Set a default screen handler on the global log. +log.screen = True +log.error_file = '' +# Using an access file makes CP about 10% slower. Leave off by default. +log.access_file = '' + +def _buslog(msg, level): + log.error(msg, 'ENGINE', severity=level) +engine.subscribe('log', _buslog) + +# Helper functions for CP apps # + + +def expose(func=None, alias=None): + """Expose the function, optionally providing an alias or set of aliases.""" + def expose_(func): + func.exposed = True + if alias is not None: + if isinstance(alias, basestring): + parents[alias.replace(".", "_")] = func + else: + for a in alias: + parents[a.replace(".", "_")] = func + return func + + import sys, types + if isinstance(func, (types.FunctionType, types.MethodType)): + if alias is None: + # @expose + func.exposed = True + return func + else: + # func = expose(func, alias) + parents = sys._getframe(1).f_locals + return expose_(func) + elif func is None: + if alias is None: + # @expose() + parents = sys._getframe(1).f_locals + return expose_ + else: + # @expose(alias="alias") or + # @expose(alias=["alias1", "alias2"]) + parents = sys._getframe(1).f_locals + return expose_ + else: + # @expose("alias") or + # @expose(["alias1", "alias2"]) + parents = sys._getframe(1).f_locals + alias = func + return expose_ + +def popargs(*args, **kwargs): + """A decorator for _cp_dispatch + (cherrypy.dispatch.Dispatcher.dispatch_method_name). + + Optional keyword argument: handler=(Object or Function) + + Provides a _cp_dispatch function that pops off path segments into + cherrypy.request.params under the names specified. The dispatch + is then forwarded on to the next vpath element. + + Note that any existing (and exposed) member function of the class that + popargs is applied to will override that value of the argument. For + instance, if you have a method named "list" on the class decorated with + popargs, then accessing "/list" will call that function instead of popping + it off as the requested parameter. This restriction applies to all + _cp_dispatch functions. The only way around this restriction is to create + a "blank class" whose only function is to provide _cp_dispatch. + + If there are path elements after the arguments, or more arguments + are requested than are available in the vpath, then the 'handler' + keyword argument specifies the next object to handle the parameterized + request. If handler is not specified or is None, then self is used. + If handler is a function rather than an instance, then that function + will be called with the args specified and the return value from that + function used as the next object INSTEAD of adding the parameters to + cherrypy.request.args. + + This decorator may be used in one of two ways: + + As a class decorator: + @cherrypy.popargs('year', 'month', 'day') + class Blog: + def index(self, year=None, month=None, day=None): + #Process the parameters here; any url like + #/, /2009, /2009/12, or /2009/12/31 + #will fill in the appropriate parameters. + + def create(self): + #This link will still be available at /create. Defined functions + #take precedence over arguments. + + Or as a member of a class: + class Blog: + _cp_dispatch = cherrypy.popargs('year', 'month', 'day') + #... + + The handler argument may be used to mix arguments with built in functions. + For instance, the following setup allows different activities at the + day, month, and year level: + + class DayHandler: + def index(self, year, month, day): + #Do something with this day; probably list entries + + def delete(self, year, month, day): + #Delete all entries for this day + + @cherrypy.popargs('day', handler=DayHandler()) + class MonthHandler: + def index(self, year, month): + #Do something with this month; probably list entries + + def delete(self, year, month): + #Delete all entries for this month + + @cherrypy.popargs('month', handler=MonthHandler()) + class YearHandler: + def index(self, year): + #Do something with this year + + #... + + @cherrypy.popargs('year', handler=YearHandler()) + class Root: + def index(self): + #... + + """ + + #Since keyword arg comes after *args, we have to process it ourselves + #for lower versions of python. + + handler = None + handler_call = False + for k,v in kwargs.items(): + if k == 'handler': + handler = v + else: + raise TypeError( + "cherrypy.popargs() got an unexpected keyword argument '{0}'" \ + .format(k) + ) + + import inspect + + if handler is not None \ + and (hasattr(handler, '__call__') or inspect.isclass(handler)): + handler_call = True + + def decorated(cls_or_self=None, vpath=None): + if inspect.isclass(cls_or_self): + #cherrypy.popargs is a class decorator + cls = cls_or_self + setattr(cls, dispatch.Dispatcher.dispatch_method_name, decorated) + return cls + + #We're in the actual function + self = cls_or_self + parms = {} + for arg in args: + if not vpath: + break + parms[arg] = vpath.pop(0) + + if handler is not None: + if handler_call: + return handler(**parms) + else: + request.params.update(parms) + return handler + + request.params.update(parms) + + #If we are the ultimate handler, then to prevent our _cp_dispatch + #from being called again, we will resolve remaining elements through + #getattr() directly. + if vpath: + return getattr(self, vpath.pop(0), None) + else: + return self + + return decorated + +def url(path="", qs="", script_name=None, base=None, relative=None): + """Create an absolute URL for the given path. + + If 'path' starts with a slash ('/'), this will return + (base + script_name + path + qs). + If it does not start with a slash, this returns + (base + script_name [+ request.path_info] + path + qs). + + If script_name is None, cherrypy.request will be used + to find a script_name, if available. + + If base is None, cherrypy.request.base will be used (if available). + Note that you can use cherrypy.tools.proxy to change this. + + Finally, note that this function can be used to obtain an absolute URL + for the current request path (minus the querystring) by passing no args. + If you call url(qs=cherrypy.request.query_string), you should get the + original browser URL (assuming no internal redirections). + + If relative is None or not provided, request.app.relative_urls will + be used (if available, else False). If False, the output will be an + absolute URL (including the scheme, host, vhost, and script_name). + If True, the output will instead be a URL that is relative to the + current request path, perhaps including '..' atoms. If relative is + the string 'server', the output will instead be a URL that is + relative to the server root; i.e., it will start with a slash. + """ + if isinstance(qs, (tuple, list, dict)): + qs = _urlencode(qs) + if qs: + qs = '?' + qs + + if request.app: + if not path.startswith("/"): + # Append/remove trailing slash from path_info as needed + # (this is to support mistyped URL's without redirecting; + # if you want to redirect, use tools.trailing_slash). + pi = request.path_info + if request.is_index is True: + if not pi.endswith('/'): + pi = pi + '/' + elif request.is_index is False: + if pi.endswith('/') and pi != '/': + pi = pi[:-1] + + if path == "": + path = pi + else: + path = _urljoin(pi, path) + + if script_name is None: + script_name = request.script_name + if base is None: + base = request.base + + newurl = base + script_name + path + qs + else: + # No request.app (we're being called outside a request). + # We'll have to guess the base from server.* attributes. + # This will produce very different results from the above + # if you're using vhosts or tools.proxy. + if base is None: + base = server.base() + + path = (script_name or "") + path + newurl = base + path + qs + + if './' in newurl: + # Normalize the URL by removing ./ and ../ + atoms = [] + for atom in newurl.split('/'): + if atom == '.': + pass + elif atom == '..': + atoms.pop() + else: + atoms.append(atom) + newurl = '/'.join(atoms) + + # At this point, we should have a fully-qualified absolute URL. + + if relative is None: + relative = getattr(request.app, "relative_urls", False) + + # See http://www.ietf.org/rfc/rfc2396.txt + if relative == 'server': + # "A relative reference beginning with a single slash character is + # termed an absolute-path reference, as defined by ..." + # This is also sometimes called "server-relative". + newurl = '/' + '/'.join(newurl.split('/', 3)[3:]) + elif relative: + # "A relative reference that does not begin with a scheme name + # or a slash character is termed a relative-path reference." + old = url().split('/')[:-1] + new = newurl.split('/') + while old and new: + a, b = old[0], new[0] + if a != b: + break + old.pop(0) + new.pop(0) + new = (['..'] * len(old)) + new + newurl = '/'.join(new) + + return newurl + + +# import _cpconfig last so it can reference other top-level objects +from cherrypy import _cpconfig +# Use _global_conf_alias so quickstart can use 'config' as an arg +# without shadowing cherrypy.config. +config = _global_conf_alias = _cpconfig.Config() +config.defaults = { + 'tools.log_tracebacks.on': True, + 'tools.log_headers.on': True, + 'tools.trailing_slash.on': True, + 'tools.encode.on': True + } +config.namespaces["log"] = lambda k, v: setattr(log, k, v) +config.namespaces["checker"] = lambda k, v: setattr(checker, k, v) +# Must reset to get our defaults applied. +config.reset() + +from cherrypy import _cpchecker +checker = _cpchecker.Checker() +engine.subscribe('start', checker) diff --git a/cherrypy/_cpchecker.py b/cherrypy/_cpchecker.py new file mode 100644 index 00000000..7ccfd89d --- /dev/null +++ b/cherrypy/_cpchecker.py @@ -0,0 +1,327 @@ +import os +import warnings + +import cherrypy +from cherrypy._cpcompat import iteritems, copykeys, builtins + + +class Checker(object): + """A checker for CherryPy sites and their mounted applications. + + When this object is called at engine startup, it executes each + of its own methods whose names start with ``check_``. If you wish + to disable selected checks, simply add a line in your global + config which sets the appropriate method to False:: + + [global] + checker.check_skipped_app_config = False + + You may also dynamically add or replace ``check_*`` methods in this way. + """ + + on = True + """If True (the default), run all checks; if False, turn off all checks.""" + + + def __init__(self): + self._populate_known_types() + + def __call__(self): + """Run all check_* methods.""" + if self.on: + oldformatwarning = warnings.formatwarning + warnings.formatwarning = self.formatwarning + try: + for name in dir(self): + if name.startswith("check_"): + method = getattr(self, name) + if method and hasattr(method, '__call__'): + method() + finally: + warnings.formatwarning = oldformatwarning + + def formatwarning(self, message, category, filename, lineno, line=None): + """Function to format a warning.""" + return "CherryPy Checker:\n%s\n\n" % message + + # This value should be set inside _cpconfig. + global_config_contained_paths = False + + def check_app_config_entries_dont_start_with_script_name(self): + """Check for Application config with sections that repeat script_name.""" + for sn, app in cherrypy.tree.apps.items(): + if not isinstance(app, cherrypy.Application): + continue + if not app.config: + continue + if sn == '': + continue + sn_atoms = sn.strip("/").split("/") + for key in app.config.keys(): + key_atoms = key.strip("/").split("/") + if key_atoms[:len(sn_atoms)] == sn_atoms: + warnings.warn( + "The application mounted at %r has config " \ + "entries that start with its script name: %r" % (sn, key)) + + def check_site_config_entries_in_app_config(self): + """Check for mounted Applications that have site-scoped config.""" + for sn, app in iteritems(cherrypy.tree.apps): + if not isinstance(app, cherrypy.Application): + continue + + msg = [] + for section, entries in iteritems(app.config): + if section.startswith('/'): + for key, value in iteritems(entries): + for n in ("engine.", "server.", "tree.", "checker."): + if key.startswith(n): + msg.append("[%s] %s = %s" % (section, key, value)) + if msg: + msg.insert(0, + "The application mounted at %r contains the following " + "config entries, which are only allowed in site-wide " + "config. Move them to a [global] section and pass them " + "to cherrypy.config.update() instead of tree.mount()." % sn) + warnings.warn(os.linesep.join(msg)) + + def check_skipped_app_config(self): + """Check for mounted Applications that have no config.""" + for sn, app in cherrypy.tree.apps.items(): + if not isinstance(app, cherrypy.Application): + continue + if not app.config: + msg = "The Application mounted at %r has an empty config." % sn + if self.global_config_contained_paths: + msg += (" It looks like the config you passed to " + "cherrypy.config.update() contains application-" + "specific sections. You must explicitly pass " + "application config via " + "cherrypy.tree.mount(..., config=app_config)") + warnings.warn(msg) + return + + def check_app_config_brackets(self): + """Check for Application config with extraneous brackets in section names.""" + for sn, app in cherrypy.tree.apps.items(): + if not isinstance(app, cherrypy.Application): + continue + if not app.config: + continue + for key in app.config.keys(): + if key.startswith("[") or key.endswith("]"): + warnings.warn( + "The application mounted at %r has config " \ + "section names with extraneous brackets: %r. " + "Config *files* need brackets; config *dicts* " + "(e.g. passed to tree.mount) do not." % (sn, key)) + + def check_static_paths(self): + """Check Application config for incorrect static paths.""" + # Use the dummy Request object in the main thread. + request = cherrypy.request + for sn, app in cherrypy.tree.apps.items(): + if not isinstance(app, cherrypy.Application): + continue + request.app = app + for section in app.config: + # get_resource will populate request.config + request.get_resource(section + "/dummy.html") + conf = request.config.get + + if conf("tools.staticdir.on", False): + msg = "" + root = conf("tools.staticdir.root") + dir = conf("tools.staticdir.dir") + if dir is None: + msg = "tools.staticdir.dir is not set." + else: + fulldir = "" + if os.path.isabs(dir): + fulldir = dir + if root: + msg = ("dir is an absolute path, even " + "though a root is provided.") + testdir = os.path.join(root, dir[1:]) + if os.path.exists(testdir): + msg += ("\nIf you meant to serve the " + "filesystem folder at %r, remove " + "the leading slash from dir." % testdir) + else: + if not root: + msg = "dir is a relative path and no root provided." + else: + fulldir = os.path.join(root, dir) + if not os.path.isabs(fulldir): + msg = "%r is not an absolute path." % fulldir + + if fulldir and not os.path.exists(fulldir): + if msg: + msg += "\n" + msg += ("%r (root + dir) is not an existing " + "filesystem path." % fulldir) + + if msg: + warnings.warn("%s\nsection: [%s]\nroot: %r\ndir: %r" + % (msg, section, root, dir)) + + + # -------------------------- Compatibility -------------------------- # + + obsolete = { + 'server.default_content_type': 'tools.response_headers.headers', + 'log_access_file': 'log.access_file', + 'log_config_options': None, + 'log_file': 'log.error_file', + 'log_file_not_found': None, + 'log_request_headers': 'tools.log_headers.on', + 'log_to_screen': 'log.screen', + 'show_tracebacks': 'request.show_tracebacks', + 'throw_errors': 'request.throw_errors', + 'profiler.on': ('cherrypy.tree.mount(profiler.make_app(' + 'cherrypy.Application(Root())))'), + } + + deprecated = {} + + def _compat(self, config): + """Process config and warn on each obsolete or deprecated entry.""" + for section, conf in config.items(): + if isinstance(conf, dict): + for k, v in conf.items(): + if k in self.obsolete: + warnings.warn("%r is obsolete. Use %r instead.\n" + "section: [%s]" % + (k, self.obsolete[k], section)) + elif k in self.deprecated: + warnings.warn("%r is deprecated. Use %r instead.\n" + "section: [%s]" % + (k, self.deprecated[k], section)) + else: + if section in self.obsolete: + warnings.warn("%r is obsolete. Use %r instead." + % (section, self.obsolete[section])) + elif section in self.deprecated: + warnings.warn("%r is deprecated. Use %r instead." + % (section, self.deprecated[section])) + + def check_compatibility(self): + """Process config and warn on each obsolete or deprecated entry.""" + self._compat(cherrypy.config) + for sn, app in cherrypy.tree.apps.items(): + if not isinstance(app, cherrypy.Application): + continue + self._compat(app.config) + + + # ------------------------ Known Namespaces ------------------------ # + + extra_config_namespaces = [] + + def _known_ns(self, app): + ns = ["wsgi"] + ns.extend(copykeys(app.toolboxes)) + ns.extend(copykeys(app.namespaces)) + ns.extend(copykeys(app.request_class.namespaces)) + ns.extend(copykeys(cherrypy.config.namespaces)) + ns += self.extra_config_namespaces + + for section, conf in app.config.items(): + is_path_section = section.startswith("/") + if is_path_section and isinstance(conf, dict): + for k, v in conf.items(): + atoms = k.split(".") + if len(atoms) > 1: + if atoms[0] not in ns: + # Spit out a special warning if a known + # namespace is preceded by "cherrypy." + if (atoms[0] == "cherrypy" and atoms[1] in ns): + msg = ("The config entry %r is invalid; " + "try %r instead.\nsection: [%s]" + % (k, ".".join(atoms[1:]), section)) + else: + msg = ("The config entry %r is invalid, because " + "the %r config namespace is unknown.\n" + "section: [%s]" % (k, atoms[0], section)) + warnings.warn(msg) + elif atoms[0] == "tools": + if atoms[1] not in dir(cherrypy.tools): + msg = ("The config entry %r may be invalid, " + "because the %r tool was not found.\n" + "section: [%s]" % (k, atoms[1], section)) + warnings.warn(msg) + + def check_config_namespaces(self): + """Process config and warn on each unknown config namespace.""" + for sn, app in cherrypy.tree.apps.items(): + if not isinstance(app, cherrypy.Application): + continue + self._known_ns(app) + + + + + # -------------------------- Config Types -------------------------- # + + known_config_types = {} + + def _populate_known_types(self): + b = [x for x in vars(builtins).values() + if type(x) is type(str)] + + def traverse(obj, namespace): + for name in dir(obj): + # Hack for 3.2's warning about body_params + if name == 'body_params': + continue + vtype = type(getattr(obj, name, None)) + if vtype in b: + self.known_config_types[namespace + "." + name] = vtype + + traverse(cherrypy.request, "request") + traverse(cherrypy.response, "response") + traverse(cherrypy.server, "server") + traverse(cherrypy.engine, "engine") + traverse(cherrypy.log, "log") + + def _known_types(self, config): + msg = ("The config entry %r in section %r is of type %r, " + "which does not match the expected type %r.") + + for section, conf in config.items(): + if isinstance(conf, dict): + for k, v in conf.items(): + if v is not None: + expected_type = self.known_config_types.get(k, None) + vtype = type(v) + if expected_type and vtype != expected_type: + warnings.warn(msg % (k, section, vtype.__name__, + expected_type.__name__)) + else: + k, v = section, conf + if v is not None: + expected_type = self.known_config_types.get(k, None) + vtype = type(v) + if expected_type and vtype != expected_type: + warnings.warn(msg % (k, section, vtype.__name__, + expected_type.__name__)) + + def check_config_types(self): + """Assert that config values are of the same type as default values.""" + self._known_types(cherrypy.config) + for sn, app in cherrypy.tree.apps.items(): + if not isinstance(app, cherrypy.Application): + continue + self._known_types(app.config) + + + # -------------------- Specific config warnings -------------------- # + + def check_localhost(self): + """Warn if any socket_host is 'localhost'. See #711.""" + for k, v in cherrypy.config.items(): + if k == 'server.socket_host' and v == 'localhost': + warnings.warn("The use of 'localhost' as a socket host can " + "cause problems on newer systems, since 'localhost' can " + "map to either an IPv4 or an IPv6 address. You should " + "use '127.0.0.1' or '[::1]' instead.") diff --git a/cherrypy/_cpcompat.py b/cherrypy/_cpcompat.py new file mode 100644 index 00000000..216ddddc --- /dev/null +++ b/cherrypy/_cpcompat.py @@ -0,0 +1,283 @@ +"""Compatibility code for using CherryPy with various versions of Python. + +CherryPy 3.2 is compatible with Python versions 2.3+. This module provides a +useful abstraction over the differences between Python versions, sometimes by +preferring a newer idiom, sometimes an older one, and sometimes a custom one. + +In particular, Python 2 uses str and '' for byte strings, while Python 3 +uses str and '' for unicode strings. We will call each of these the 'native +string' type for each version. Because of this major difference, this module +provides new 'bytestr', 'unicodestr', and 'nativestr' attributes, as well as +two functions: 'ntob', which translates native strings (of type 'str') into +byte strings regardless of Python version, and 'ntou', which translates native +strings to unicode strings. This also provides a 'BytesIO' name for dealing +specifically with bytes, and a 'StringIO' name for dealing with native strings. +It also provides a 'base64_decode' function with native strings as input and +output. +""" +import os +import sys + +if sys.version_info >= (3, 0): + bytestr = bytes + unicodestr = str + nativestr = unicodestr + basestring = (bytes, str) + def ntob(n, encoding='ISO-8859-1'): + """Return the given native string as a byte string in the given encoding.""" + # In Python 3, the native string type is unicode + return n.encode(encoding) + def ntou(n, encoding='ISO-8859-1'): + """Return the given native string as a unicode string with the given encoding.""" + # In Python 3, the native string type is unicode + return n + # type("") + from io import StringIO + # bytes: + from io import BytesIO as BytesIO +else: + # Python 2 + bytestr = str + unicodestr = unicode + nativestr = bytestr + basestring = basestring + def ntob(n, encoding='ISO-8859-1'): + """Return the given native string as a byte string in the given encoding.""" + # In Python 2, the native string type is bytes. Assume it's already + # in the given encoding, which for ISO-8859-1 is almost always what + # was intended. + return n + def ntou(n, encoding='ISO-8859-1'): + """Return the given native string as a unicode string with the given encoding.""" + # In Python 2, the native string type is bytes. Assume it's already + # in the given encoding, which for ISO-8859-1 is almost always what + # was intended. + return n.decode(encoding) + try: + # type("") + from cStringIO import StringIO + except ImportError: + # type("") + from StringIO import StringIO + # bytes: + BytesIO = StringIO + +try: + set = set +except NameError: + from sets import Set as set + +try: + # Python 3.1+ + from base64 import decodebytes as _base64_decodebytes +except ImportError: + # Python 3.0- + # since CherryPy claims compability with Python 2.3, we must use + # the legacy API of base64 + from base64 import decodestring as _base64_decodebytes + +def base64_decode(n, encoding='ISO-8859-1'): + """Return the native string base64-decoded (as a native string).""" + if isinstance(n, unicodestr): + b = n.encode(encoding) + else: + b = n + b = _base64_decodebytes(b) + if nativestr is unicodestr: + return b.decode(encoding) + else: + return b + +try: + # Python 2.5+ + from hashlib import md5 +except ImportError: + from md5 import new as md5 + +try: + # Python 2.5+ + from hashlib import sha1 as sha +except ImportError: + from sha import new as sha + +try: + sorted = sorted +except NameError: + def sorted(i): + i = i[:] + i.sort() + return i + +try: + reversed = reversed +except NameError: + def reversed(x): + i = len(x) + while i > 0: + i -= 1 + yield x[i] + +try: + # Python 3 + from urllib.parse import urljoin, urlencode + from urllib.parse import quote, quote_plus + from urllib.request import unquote, urlopen + from urllib.request import parse_http_list, parse_keqv_list +except ImportError: + # Python 2 + from urlparse import urljoin + from urllib import urlencode, urlopen + from urllib import quote, quote_plus + from urllib import unquote + from urllib2 import parse_http_list, parse_keqv_list + +try: + from threading import local as threadlocal +except ImportError: + from cherrypy._cpthreadinglocal import local as threadlocal + +try: + dict.iteritems + # Python 2 + iteritems = lambda d: d.iteritems() + copyitems = lambda d: d.items() +except AttributeError: + # Python 3 + iteritems = lambda d: d.items() + copyitems = lambda d: list(d.items()) + +try: + dict.iterkeys + # Python 2 + iterkeys = lambda d: d.iterkeys() + copykeys = lambda d: d.keys() +except AttributeError: + # Python 3 + iterkeys = lambda d: d.keys() + copykeys = lambda d: list(d.keys()) + +try: + dict.itervalues + # Python 2 + itervalues = lambda d: d.itervalues() + copyvalues = lambda d: d.values() +except AttributeError: + # Python 3 + itervalues = lambda d: d.values() + copyvalues = lambda d: list(d.values()) + +try: + # Python 3 + import builtins +except ImportError: + # Python 2 + import __builtin__ as builtins + +try: + # Python 2. We have to do it in this order so Python 2 builds + # don't try to import the 'http' module from cherrypy.lib + from Cookie import SimpleCookie, CookieError + from httplib import BadStatusLine, HTTPConnection, HTTPSConnection, IncompleteRead, NotConnected + from BaseHTTPServer import BaseHTTPRequestHandler +except ImportError: + # Python 3 + from http.cookies import SimpleCookie, CookieError + from http.client import BadStatusLine, HTTPConnection, HTTPSConnection, IncompleteRead, NotConnected + from http.server import BaseHTTPRequestHandler + +try: + # Python 2 + xrange = xrange +except NameError: + # Python 3 + xrange = range + +import threading +if hasattr(threading.Thread, "daemon"): + # Python 2.6+ + def get_daemon(t): + return t.daemon + def set_daemon(t, val): + t.daemon = val +else: + def get_daemon(t): + return t.isDaemon() + def set_daemon(t, val): + t.setDaemon(val) + +try: + from email.utils import formatdate + def HTTPDate(timeval=None): + return formatdate(timeval, usegmt=True) +except ImportError: + from rfc822 import formatdate as HTTPDate + +try: + # Python 3 + from urllib.parse import unquote as parse_unquote + def unquote_qs(atom, encoding, errors='strict'): + return parse_unquote(atom.replace('+', ' '), encoding=encoding, errors=errors) +except ImportError: + # Python 2 + from urllib import unquote as parse_unquote + def unquote_qs(atom, encoding, errors='strict'): + return parse_unquote(atom.replace('+', ' ')).decode(encoding, errors) + +try: + # Prefer simplejson, which is usually more advanced than the builtin module. + import simplejson as json + json_decode = json.JSONDecoder().decode + json_encode = json.JSONEncoder().iterencode +except ImportError: + if sys.version_info >= (3, 0): + # Python 3.0: json is part of the standard library, + # but outputs unicode. We need bytes. + import json + json_decode = json.JSONDecoder().decode + _json_encode = json.JSONEncoder().iterencode + def json_encode(value): + for chunk in _json_encode(value): + yield chunk.encode('utf8') + elif sys.version_info >= (2, 6): + # Python 2.6: json is part of the standard library + import json + json_decode = json.JSONDecoder().decode + json_encode = json.JSONEncoder().iterencode + else: + json = None + def json_decode(s): + raise ValueError('No JSON library is available') + def json_encode(s): + raise ValueError('No JSON library is available') + +try: + import cPickle as pickle +except ImportError: + # In Python 2, pickle is a Python version. + # In Python 3, pickle is the sped-up C version. + import pickle + +try: + os.urandom(20) + import binascii + def random20(): + return binascii.hexlify(os.urandom(20)).decode('ascii') +except (AttributeError, NotImplementedError): + import random + # os.urandom not available until Python 2.4. Fall back to random.random. + def random20(): + return sha('%s' % random.random()).hexdigest() + +try: + from _thread import get_ident as get_thread_ident +except ImportError: + from thread import get_ident as get_thread_ident + +try: + # Python 3 + next = next +except NameError: + # Python 2 + def next(i): + return i.next() + diff --git a/cherrypy/_cpconfig.py b/cherrypy/_cpconfig.py new file mode 100644 index 00000000..7b4c6a46 --- /dev/null +++ b/cherrypy/_cpconfig.py @@ -0,0 +1,295 @@ +""" +Configuration system for CherryPy. + +Configuration in CherryPy is implemented via dictionaries. Keys are strings +which name the mapped value, which may be of any type. + + +Architecture +------------ + +CherryPy Requests are part of an Application, which runs in a global context, +and configuration data may apply to any of those three scopes: + +Global + Configuration entries which apply everywhere are stored in + cherrypy.config. + +Application + Entries which apply to each mounted application are stored + on the Application object itself, as 'app.config'. This is a two-level + dict where each key is a path, or "relative URL" (for example, "/" or + "/path/to/my/page"), and each value is a config dict. Usually, this + data is provided in the call to tree.mount(root(), config=conf), + although you may also use app.merge(conf). + +Request + Each Request object possesses a single 'Request.config' dict. + Early in the request process, this dict is populated by merging global + config entries, Application entries (whose path equals or is a parent + of Request.path_info), and any config acquired while looking up the + page handler (see next). + + +Declaration +----------- + +Configuration data may be supplied as a Python dictionary, as a filename, +or as an open file object. When you supply a filename or file, CherryPy +uses Python's builtin ConfigParser; you declare Application config by +writing each path as a section header:: + + [/path/to/my/page] + request.stream = True + +To declare global configuration entries, place them in a [global] section. + +You may also declare config entries directly on the classes and methods +(page handlers) that make up your CherryPy application via the ``_cp_config`` +attribute. For example:: + + class Demo: + _cp_config = {'tools.gzip.on': True} + + def index(self): + return "Hello world" + index.exposed = True + index._cp_config = {'request.show_tracebacks': False} + +.. note:: + + This behavior is only guaranteed for the default dispatcher. + Other dispatchers may have different restrictions on where + you can attach _cp_config attributes. + + +Namespaces +---------- + +Configuration keys are separated into namespaces by the first "." in the key. +Current namespaces: + +engine + Controls the 'application engine', including autoreload. + These can only be declared in the global config. + +tree + Grafts cherrypy.Application objects onto cherrypy.tree. + These can only be declared in the global config. + +hooks + Declares additional request-processing functions. + +log + Configures the logging for each application. + These can only be declared in the global or / config. + +request + Adds attributes to each Request. + +response + Adds attributes to each Response. + +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. + +The only key that does not exist in a namespace is the "environment" entry. +This special entry 'imports' other config entries from a template stored in +cherrypy._cpconfig.environments[environment]. It only applies to the global +config, and only when you use cherrypy.config.update. + +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 app.request_class.namespaces. The name can +be any string, and the handler must be either a callable or a (Python 2.5 +style) context manager. +""" + +import cherrypy +from cherrypy._cpcompat import set, basestring +from cherrypy.lib import reprconf + +# Deprecated in CherryPy 3.2--remove in 3.3 +NamespaceSet = reprconf.NamespaceSet + +def merge(base, other): + """Merge one app config (from a dict, file, or filename) into another. + + If the given config is a filename, it will be appended to + the list of files to monitor for "autoreload" changes. + """ + if isinstance(other, basestring): + cherrypy.engine.autoreload.files.add(other) + + # Load other into base + for section, value_map in reprconf.as_dict(other).items(): + if not isinstance(value_map, dict): + raise ValueError( + "Application config must include section headers, but the " + "config you tried to merge doesn't have any sections. " + "Wrap your config in another dict with paths as section " + "headers, for example: {'/': config}.") + base.setdefault(section, {}).update(value_map) + + +class Config(reprconf.Config): + """The 'global' configuration data for the entire CherryPy process.""" + + def update(self, config): + """Update self from a dict, file or filename.""" + if isinstance(config, basestring): + # Filename + cherrypy.engine.autoreload.files.add(config) + reprconf.Config.update(self, config) + + def _apply(self, config): + """Update self from a dict.""" + if isinstance(config.get("global", None), dict): + if len(config) > 1: + cherrypy.checker.global_config_contained_paths = True + config = config["global"] + if 'tools.staticdir.dir' in config: + config['tools.staticdir.section'] = "global" + reprconf.Config._apply(self, config) + + def __call__(self, *args, **kwargs): + """Decorator for page handlers to set _cp_config.""" + if args: + raise TypeError( + "The cherrypy.config decorator does not accept positional " + "arguments; you must use keyword arguments.") + def tool_decorator(f): + if not hasattr(f, "_cp_config"): + f._cp_config = {} + for k, v in kwargs.items(): + f._cp_config[k] = v + return f + return tool_decorator + + +Config.environments = environments = { + "staging": { + 'engine.autoreload_on': False, + 'checker.on': False, + 'tools.log_headers.on': False, + 'request.show_tracebacks': False, + 'request.show_mismatched_params': False, + }, + "production": { + 'engine.autoreload_on': False, + 'checker.on': False, + 'tools.log_headers.on': False, + 'request.show_tracebacks': False, + 'request.show_mismatched_params': False, + 'log.screen': False, + }, + "embedded": { + # For use with CherryPy embedded in another deployment stack. + 'engine.autoreload_on': False, + 'checker.on': False, + 'tools.log_headers.on': False, + 'request.show_tracebacks': False, + 'request.show_mismatched_params': False, + 'log.screen': False, + 'engine.SIGHUP': None, + 'engine.SIGTERM': None, + }, + "test_suite": { + 'engine.autoreload_on': False, + 'checker.on': False, + 'tools.log_headers.on': False, + 'request.show_tracebacks': True, + 'request.show_mismatched_params': True, + 'log.screen': False, + }, + } + + +def _server_namespace_handler(k, v): + """Config handler for the "server" namespace.""" + atoms = k.split(".", 1) + if len(atoms) > 1: + # Special-case config keys of the form 'server.servername.socket_port' + # to configure additional HTTP servers. + if not hasattr(cherrypy, "servers"): + cherrypy.servers = {} + + servername, k = atoms + if servername not in cherrypy.servers: + from cherrypy import _cpserver + cherrypy.servers[servername] = _cpserver.Server() + # On by default, but 'on = False' can unsubscribe it (see below). + cherrypy.servers[servername].subscribe() + + if k == 'on': + if v: + cherrypy.servers[servername].subscribe() + else: + cherrypy.servers[servername].unsubscribe() + else: + setattr(cherrypy.servers[servername], k, v) + else: + setattr(cherrypy.server, k, v) +Config.namespaces["server"] = _server_namespace_handler + +def _engine_namespace_handler(k, v): + """Backward compatibility handler for the "engine" namespace.""" + engine = cherrypy.engine + if k == 'autoreload_on': + if v: + engine.autoreload.subscribe() + else: + engine.autoreload.unsubscribe() + elif k == 'autoreload_frequency': + engine.autoreload.frequency = v + elif k == 'autoreload_match': + engine.autoreload.match = v + elif k == 'reload_files': + engine.autoreload.files = set(v) + elif k == 'deadlock_poll_freq': + engine.timeout_monitor.frequency = v + elif k == 'SIGHUP': + engine.listeners['SIGHUP'] = set([v]) + elif k == 'SIGTERM': + engine.listeners['SIGTERM'] = set([v]) + elif "." in k: + plugin, attrname = k.split(".", 1) + plugin = getattr(engine, plugin) + if attrname == 'on': + if v and hasattr(getattr(plugin, 'subscribe', None), '__call__'): + plugin.subscribe() + return + elif (not v) and hasattr(getattr(plugin, 'unsubscribe', None), '__call__'): + plugin.unsubscribe() + return + setattr(plugin, attrname, v) + else: + setattr(engine, k, v) +Config.namespaces["engine"] = _engine_namespace_handler + + +def _tree_namespace_handler(k, v): + """Namespace handler for the 'tree' config namespace.""" + if isinstance(v, dict): + for script_name, app in v.items(): + cherrypy.tree.graft(app, script_name) + cherrypy.engine.log("Mounted: %s on %s" % (app, script_name or "/")) + else: + cherrypy.tree.graft(v, v.script_name) + cherrypy.engine.log("Mounted: %s on %s" % (v, v.script_name or "/")) +Config.namespaces["tree"] = _tree_namespace_handler + + diff --git a/cherrypy/_cpdispatch.py b/cherrypy/_cpdispatch.py new file mode 100644 index 00000000..7250ac92 --- /dev/null +++ b/cherrypy/_cpdispatch.py @@ -0,0 +1,622 @@ +"""CherryPy dispatchers. + +A 'dispatcher' is the object which looks up the 'page handler' callable +and collects config for the current request based on the path_info, other +request attributes, and the application architecture. The core calls the +dispatcher as early as possible, passing it a 'path_info' argument. + +The default dispatcher discovers the page handler by matching path_info +to a hierarchical arrangement of objects, starting at request.app.root. +""" + +import string +import sys +import types + +import cherrypy + + +class PageHandler(object): + """Callable which sets response.body.""" + + def __init__(self, callable, *args, **kwargs): + self.callable = callable + self.args = args + self.kwargs = kwargs + + def __call__(self): + try: + return self.callable(*self.args, **self.kwargs) + except TypeError: + x = sys.exc_info()[1] + try: + test_callable_spec(self.callable, self.args, self.kwargs) + except cherrypy.HTTPError: + raise sys.exc_info()[1] + except: + raise x + raise + + +def test_callable_spec(callable, callable_args, callable_kwargs): + """ + Inspect callable and test to see if the given args are suitable for it. + + When an error occurs during the handler's invoking stage there are 2 + erroneous cases: + 1. Too many parameters passed to a function which doesn't define + one of *args or **kwargs. + 2. Too little parameters are passed to the function. + + There are 3 sources of parameters to a cherrypy handler. + 1. query string parameters are passed as keyword parameters to the handler. + 2. body parameters are also passed as keyword parameters. + 3. when partial matching occurs, the final path atoms are passed as + positional args. + Both the query string and path atoms are part of the URI. If they are + incorrect, then a 404 Not Found should be raised. Conversely the body + parameters are part of the request; if they are invalid a 400 Bad Request. + """ + show_mismatched_params = getattr( + cherrypy.serving.request, 'show_mismatched_params', False) + try: + (args, varargs, varkw, defaults) = inspect.getargspec(callable) + except TypeError: + if isinstance(callable, object) and hasattr(callable, '__call__'): + (args, varargs, varkw, defaults) = inspect.getargspec(callable.__call__) + else: + # If it wasn't one of our own types, re-raise + # the original error + raise + + if args and args[0] == 'self': + args = args[1:] + + arg_usage = dict([(arg, 0,) for arg in args]) + vararg_usage = 0 + varkw_usage = 0 + extra_kwargs = set() + + for i, value in enumerate(callable_args): + try: + arg_usage[args[i]] += 1 + except IndexError: + vararg_usage += 1 + + for key in callable_kwargs.keys(): + try: + arg_usage[key] += 1 + except KeyError: + varkw_usage += 1 + extra_kwargs.add(key) + + # figure out which args have defaults. + args_with_defaults = args[-len(defaults or []):] + for i, val in enumerate(defaults or []): + # Defaults take effect only when the arg hasn't been used yet. + if arg_usage[args_with_defaults[i]] == 0: + arg_usage[args_with_defaults[i]] += 1 + + missing_args = [] + multiple_args = [] + for key, usage in arg_usage.items(): + if usage == 0: + missing_args.append(key) + elif usage > 1: + multiple_args.append(key) + + if missing_args: + # In the case where the method allows body arguments + # there are 3 potential errors: + # 1. not enough query string parameters -> 404 + # 2. not enough body parameters -> 400 + # 3. not enough path parts (partial matches) -> 404 + # + # We can't actually tell which case it is, + # so I'm raising a 404 because that covers 2/3 of the + # possibilities + # + # In the case where the method does not allow body + # arguments it's definitely a 404. + message = None + if show_mismatched_params: + message="Missing parameters: %s" % ",".join(missing_args) + raise cherrypy.HTTPError(404, message=message) + + # the extra positional arguments come from the path - 404 Not Found + if not varargs and vararg_usage > 0: + raise cherrypy.HTTPError(404) + + body_params = cherrypy.serving.request.body.params or {} + body_params = set(body_params.keys()) + qs_params = set(callable_kwargs.keys()) - body_params + + if multiple_args: + if qs_params.intersection(set(multiple_args)): + # If any of the multiple parameters came from the query string then + # it's a 404 Not Found + error = 404 + else: + # Otherwise it's a 400 Bad Request + error = 400 + + message = None + if show_mismatched_params: + message="Multiple values for parameters: "\ + "%s" % ",".join(multiple_args) + raise cherrypy.HTTPError(error, message=message) + + if not varkw and varkw_usage > 0: + + # If there were extra query string parameters, it's a 404 Not Found + extra_qs_params = set(qs_params).intersection(extra_kwargs) + if extra_qs_params: + message = None + if show_mismatched_params: + message="Unexpected query string "\ + "parameters: %s" % ", ".join(extra_qs_params) + raise cherrypy.HTTPError(404, message=message) + + # If there were any extra body parameters, it's a 400 Not Found + extra_body_params = set(body_params).intersection(extra_kwargs) + if extra_body_params: + message = None + if show_mismatched_params: + message="Unexpected body parameters: "\ + "%s" % ", ".join(extra_body_params) + raise cherrypy.HTTPError(400, message=message) + + +try: + import inspect +except ImportError: + test_callable_spec = lambda callable, args, kwargs: None + + + +class LateParamPageHandler(PageHandler): + """When passing cherrypy.request.params to the page handler, we do not + want to capture that dict too early; we want to give tools like the + decoding tool a chance to modify the params dict in-between the lookup + of the handler and the actual calling of the handler. This subclass + takes that into account, and allows request.params to be 'bound late' + (it's more complicated than that, but that's the effect). + """ + + def _get_kwargs(self): + kwargs = cherrypy.serving.request.params.copy() + if self._kwargs: + kwargs.update(self._kwargs) + return kwargs + + def _set_kwargs(self, kwargs): + self._kwargs = kwargs + + kwargs = property(_get_kwargs, _set_kwargs, + doc='page handler kwargs (with ' + 'cherrypy.request.params copied in)') + + +punctuation_to_underscores = string.maketrans( + string.punctuation, '_' * len(string.punctuation)) + +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. + """ + + dispatch_method_name = '_cp_dispatch' + """ + The name of the dispatch method that nodes may optionally implement + to provide their own dynamic dispatch algorithm. + """ + + def __init__(self, dispatch_method_name=None, + translate=punctuation_to_underscores): + if not isinstance(translate, str) or len(translate) != 256: + raise ValueError("The translate argument must be a str of len 256.") + self.translate = translate + if dispatch_method_name: + self.dispatch_method_name = dispatch_method_name + + def __call__(self, path_info): + """Set handler and config for the current request.""" + request = cherrypy.serving.request + func, vpath = self.find_handler(path_info) + + if func: + # Decode any leftover %2F in the virtual_path atoms. + vpath = [x.replace("%2F", "/") for x in vpath] + request.handler = LateParamPageHandler(func, *vpath) + else: + request.handler = cherrypy.NotFound() + + def find_handler(self, path): + """Return the appropriate page handler, plus any virtual path. + + This will return two objects. The first will be a callable, + which can be used to generate page output. Any parameters from + the query string or request body will be sent to that callable + as keyword arguments. + + The callable is found by traversing the application's tree, + starting from cherrypy.request.app.root, and matching path + components to successive objects in the tree. For example, the + URL "/path/to/handler" might return root.path.to.handler. + + The second object returned will be a list of names which are + 'virtual path' components: parts of the URL which are dynamic, + and were not used when looking up the handler. + These virtual path components are passed to the handler as + positional arguments. + """ + request = cherrypy.serving.request + app = request.app + root = app.root + dispatch_name = self.dispatch_method_name + + # Get config for the root object/path. + fullpath = [x for x in path.strip('/').split('/') if x] + ['index'] + fullpath_len = len(fullpath) + segleft = fullpath_len + nodeconf = {} + if hasattr(root, "_cp_config"): + nodeconf.update(root._cp_config) + if "/" in app.config: + nodeconf.update(app.config["/"]) + object_trail = [['root', root, nodeconf, segleft]] + + node = root + iternames = fullpath[:] + while iternames: + name = iternames[0] + # map to legal Python identifiers (e.g. replace '.' with '_') + objname = name.translate(self.translate) + + nodeconf = {} + subnode = getattr(node, objname, None) + pre_len = len(iternames) + if subnode is None: + dispatch = getattr(node, dispatch_name, None) + if dispatch and hasattr(dispatch, '__call__') and not \ + getattr(dispatch, 'exposed', False) and \ + pre_len > 1: + #Don't expose the hidden 'index' token to _cp_dispatch + #We skip this if pre_len == 1 since it makes no sense + #to call a dispatcher when we have no tokens left. + index_name = iternames.pop() + subnode = dispatch(vpath=iternames) + iternames.append(index_name) + else: + #We didn't find a path, but keep processing in case there + #is a default() handler. + iternames.pop(0) + else: + #We found the path, remove the vpath entry + iternames.pop(0) + segleft = len(iternames) + if segleft > pre_len: + #No path segment was removed. Raise an error. + raise cherrypy.CherryPyException( + "A vpath segment was added. Custom dispatchers may only " + + "remove elements. While trying to process " + + "{0} in {1}".format(name, fullpath) + ) + elif segleft == pre_len: + #Assume that the handler used the current path segment, but + #did not pop it. This allows things like + #return getattr(self, vpath[0], None) + iternames.pop(0) + segleft -= 1 + node = subnode + + if node is not None: + # Get _cp_config attached to this node. + if hasattr(node, "_cp_config"): + nodeconf.update(node._cp_config) + + # Mix in values from app.config for this path. + existing_len = fullpath_len - pre_len + if existing_len != 0: + curpath = '/' + '/'.join(fullpath[0:existing_len]) + else: + curpath = '' + new_segs = fullpath[fullpath_len - pre_len:fullpath_len - segleft] + for seg in new_segs: + curpath += '/' + seg + if curpath in app.config: + nodeconf.update(app.config[curpath]) + + object_trail.append([name, node, nodeconf, segleft]) + + def set_conf(): + """Collapse all object_trail config into cherrypy.request.config.""" + base = cherrypy.config.copy() + # Note that we merge the config from each node + # even if that node was None. + for name, obj, conf, segleft in object_trail: + base.update(conf) + if 'tools.staticdir.dir' in conf: + base['tools.staticdir.section'] = '/' + '/'.join(fullpath[0:fullpath_len - segleft]) + return base + + # Try successive objects (reverse order) + num_candidates = len(object_trail) - 1 + for i in range(num_candidates, -1, -1): + + name, candidate, nodeconf, segleft = object_trail[i] + if candidate is None: + continue + + # Try a "default" method on the current leaf. + if hasattr(candidate, "default"): + defhandler = candidate.default + if getattr(defhandler, 'exposed', False): + # Insert any extra _cp_config from the default handler. + conf = getattr(defhandler, "_cp_config", {}) + object_trail.insert(i+1, ["default", defhandler, conf, segleft]) + request.config = set_conf() + # See http://www.cherrypy.org/ticket/613 + request.is_index = path.endswith("/") + return defhandler, fullpath[fullpath_len - segleft:-1] + + # Uncomment the next line to restrict positional params to "default". + # if i < num_candidates - 2: continue + + # Try the current leaf. + if getattr(candidate, 'exposed', False): + request.config = set_conf() + if i == num_candidates: + # We found the extra ".index". Mark request so tools + # can redirect if path_info has no trailing slash. + request.is_index = True + else: + # We're not at an 'index' handler. Mark request so tools + # can redirect if path_info has NO trailing slash. + # Note that this also includes handlers which take + # positional parameters (virtual paths). + request.is_index = False + return candidate, fullpath[fullpath_len - segleft:-1] + + # We didn't find anything + request.config = set_conf() + return None, [] + + +class MethodDispatcher(Dispatcher): + """Additional dispatch based on cherrypy.request.method.upper(). + + Methods named GET, POST, etc will be called on an exposed class. + The method names must be all caps; the appropriate Allow header + will be output showing all capitalized method names as allowable + HTTP verbs. + + Note that the containing class must be exposed, not the methods. + """ + + def __call__(self, path_info): + """Set handler and config for the current request.""" + request = cherrypy.serving.request + resource, vpath = self.find_handler(path_info) + + if resource: + # Set Allow header + avail = [m for m in dir(resource) if m.isupper()] + if "GET" in avail and "HEAD" not in avail: + avail.append("HEAD") + avail.sort() + cherrypy.serving.response.headers['Allow'] = ", ".join(avail) + + # Find the subhandler + meth = request.method.upper() + func = getattr(resource, meth, None) + if func is None and meth == "HEAD": + func = getattr(resource, "GET", None) + if func: + # Grab any _cp_config on the subhandler. + if hasattr(func, "_cp_config"): + request.config.update(func._cp_config) + + # Decode any leftover %2F in the virtual_path atoms. + vpath = [x.replace("%2F", "/") for x in vpath] + request.handler = LateParamPageHandler(func, *vpath) + else: + request.handler = cherrypy.HTTPError(405) + else: + request.handler = cherrypy.NotFound() + + +class RoutesDispatcher(object): + """A Routes based dispatcher for CherryPy.""" + + def __init__(self, full_result=False): + """ + Routes dispatcher + + Set full_result to True if you wish the controller + and the action to be passed on to the page handler + parameters. By default they won't be. + """ + import routes + self.full_result = full_result + self.controllers = {} + self.mapper = routes.Mapper() + self.mapper.controller_scan = self.controllers.keys + + def connect(self, name, route, controller, **kwargs): + self.controllers[name] = controller + self.mapper.connect(name, route, controller=name, **kwargs) + + def redirect(self, url): + raise cherrypy.HTTPRedirect(url) + + def __call__(self, path_info): + """Set handler and config for the current request.""" + func = self.find_handler(path_info) + if func: + cherrypy.serving.request.handler = LateParamPageHandler(func) + else: + cherrypy.serving.request.handler = cherrypy.NotFound() + + def find_handler(self, path_info): + """Find the right page handler, and set request.config.""" + import routes + + request = cherrypy.serving.request + + config = routes.request_config() + config.mapper = self.mapper + if hasattr(request, 'wsgi_environ'): + config.environ = request.wsgi_environ + config.host = request.headers.get('Host', None) + config.protocol = request.scheme + config.redirect = self.redirect + + result = self.mapper.match(path_info) + + config.mapper_dict = result + params = {} + if result: + params = result.copy() + if not self.full_result: + params.pop('controller', None) + params.pop('action', None) + request.params.update(params) + + # Get config for the root object/path. + request.config = base = cherrypy.config.copy() + curpath = "" + + def merge(nodeconf): + if 'tools.staticdir.dir' in nodeconf: + nodeconf['tools.staticdir.section'] = curpath or "/" + base.update(nodeconf) + + app = request.app + root = app.root + if hasattr(root, "_cp_config"): + merge(root._cp_config) + if "/" in app.config: + merge(app.config["/"]) + + # Mix in values from app.config. + atoms = [x for x in path_info.split("/") if x] + if atoms: + last = atoms.pop() + else: + last = None + for atom in atoms: + curpath = "/".join((curpath, atom)) + if curpath in app.config: + merge(app.config[curpath]) + + handler = None + if result: + controller = result.get('controller') + controller = self.controllers.get(controller, controller) + if controller: + if isinstance(controller, (type, types.ClassType)): + controller = controller() + # Get config from the controller. + if hasattr(controller, "_cp_config"): + merge(controller._cp_config) + + action = result.get('action') + if action is not None: + handler = getattr(controller, action, None) + # Get config from the handler + if hasattr(handler, "_cp_config"): + merge(handler._cp_config) + else: + handler = controller + + # Do the last path atom here so it can + # override the controller's _cp_config. + if last: + curpath = "/".join((curpath, last)) + if curpath in app.config: + merge(app.config[curpath]) + + return handler + + +def XMLRPCDispatcher(next_dispatcher=Dispatcher()): + from cherrypy.lib import xmlrpc + def xmlrpc_dispatch(path_info): + path_info = xmlrpc.patched_path(path_info) + return next_dispatcher(path_info) + return xmlrpc_dispatch + + +def VirtualHost(next_dispatcher=Dispatcher(), use_x_forwarded_host=True, **domains): + """ + Select a different handler based on the Host header. + + This can be useful when running multiple sites within one CP server. + It allows several domains to point to different parts of a single + website structure. For example:: + + http://www.domain.example -> root + http://www.domain2.example -> root/domain2/ + http://www.domain2.example:443 -> root/secure + + can be accomplished via the following config:: + + [/] + request.dispatch = cherrypy.dispatch.VirtualHost( + **{'www.domain2.example': '/domain2', + 'www.domain2.example:443': '/secure', + }) + + next_dispatcher + The next dispatcher object in the dispatch chain. + The VirtualHost dispatcher adds a prefix to the URL and calls + another dispatcher. Defaults to cherrypy.dispatch.Dispatcher(). + + use_x_forwarded_host + If True (the default), any "X-Forwarded-Host" + request header will be used instead of the "Host" header. This + is commonly added by HTTP servers (such as Apache) when proxying. + + ``**domains`` + A dict of {host header value: virtual prefix} pairs. + The incoming "Host" request header is looked up in this dict, + and, if a match is found, the corresponding "virtual prefix" + value will be prepended to the URL path before calling the + next dispatcher. Note that you often need separate entries + for "example.com" and "www.example.com". In addition, "Host" + headers may contain the port number. + """ + from cherrypy.lib import httputil + def vhost_dispatch(path_info): + request = cherrypy.serving.request + header = request.headers.get + + domain = header('Host', '') + if use_x_forwarded_host: + domain = header("X-Forwarded-Host", domain) + + prefix = domains.get(domain, "") + if prefix: + path_info = httputil.urljoin(prefix, path_info) + + result = next_dispatcher(path_info) + + # Touch up staticdir config. See http://www.cherrypy.org/ticket/614. + section = request.config.get('tools.staticdir.section') + if section: + section = section[len(prefix):] + request.config['tools.staticdir.section'] = section + + return result + return vhost_dispatch + diff --git a/cherrypy/_cperror.py b/cherrypy/_cperror.py new file mode 100644 index 00000000..00e5b532 --- /dev/null +++ b/cherrypy/_cperror.py @@ -0,0 +1,553 @@ +"""Exception classes for CherryPy. + +CherryPy provides (and uses) exceptions for declaring that the HTTP response +should be a status other than the default "200 OK". You can ``raise`` them like +normal Python exceptions. You can also call them and they will raise themselves; +this means you can set an :class:`HTTPError` +or :class:`HTTPRedirect` as the +:attr:`request.handler`. + +.. _redirectingpost: + +Redirecting POST +================ + +When you GET a resource and are redirected by the server to another Location, +there's generally no problem since GET is both a "safe method" (there should +be no side-effects) and an "idempotent method" (multiple calls are no different +than a single call). + +POST, however, is neither safe nor idempotent--if you +charge a credit card, you don't want to be charged twice by a redirect! + +For this reason, *none* of the 3xx responses permit a user-agent (browser) to +resubmit a POST on redirection without first confirming the action with the user: + +===== ================================= =========== +300 Multiple Choices Confirm with the user +301 Moved Permanently Confirm with the user +302 Found (Object moved temporarily) Confirm with the user +303 See Other GET the new URI--no confirmation +304 Not modified (for conditional GET only--POST should not raise this error) +305 Use Proxy Confirm with the user +307 Temporary Redirect Confirm with the user +===== ================================= =========== + +However, browsers have historically implemented these restrictions poorly; +in particular, many browsers do not force the user to confirm 301, 302 +or 307 when redirecting POST. For this reason, CherryPy defaults to 303, +which most user-agents appear to have implemented correctly. Therefore, if +you raise HTTPRedirect for a POST request, the user-agent will most likely +attempt to GET the new URI (without asking for confirmation from the user). +We realize this is confusing for developers, but it's the safest thing we +could do. You are of course free to raise ``HTTPRedirect(uri, status=302)`` +or any other 3xx status if you know what you're doing, but given the +environment, we couldn't let any of those be the default. + +Custom Error Handling +===================== + +.. image:: /refman/cperrors.gif + +Anticipated HTTP responses +-------------------------- + +The 'error_page' config namespace can be used to provide custom HTML output for +expected responses (like 404 Not Found). Supply a filename from which the output +will be read. The contents will be interpolated with the values %(status)s, +%(message)s, %(traceback)s, and %(version)s using plain old Python +`string formatting `_. + +:: + + _cp_config = {'error_page.404': os.path.join(localDir, "static/index.html")} + + +Beginning in version 3.1, you may also provide a function or other callable as +an error_page entry. It will be passed the same status, message, traceback and +version arguments that are interpolated into templates:: + + def error_page_402(status, message, traceback, version): + return "Error %s - Well, I'm very sorry but you haven't paid!" % status + cherrypy.config.update({'error_page.402': error_page_402}) + +Also in 3.1, in addition to the numbered error codes, you may also supply +"error_page.default" to handle all codes which do not have their own error_page entry. + + + +Unanticipated errors +-------------------- + +CherryPy also has a generic error handling mechanism: whenever an unanticipated +error occurs in your code, it will call +:func:`Request.error_response` to set +the response status, headers, and body. By default, this is the same output as +:class:`HTTPError(500) `. If you want to provide +some other behavior, you generally replace "request.error_response". + +Here is some sample code that shows how to display a custom error message and +send an e-mail containing the error:: + + from cherrypy import _cperror + + def handle_error(): + cherrypy.response.status = 500 + cherrypy.response.body = ["Sorry, an error occured"] + sendMail('error@domain.com', 'Error in your web app', _cperror.format_exc()) + + class Root: + _cp_config = {'request.error_response': handle_error} + + +Note that you have to explicitly set :attr:`response.body ` +and not simply return an error message as a result. +""" + +from cgi import escape as _escape +from sys import exc_info as _exc_info +from traceback import format_exception as _format_exception +from cherrypy._cpcompat import basestring, iteritems, urljoin as _urljoin +from cherrypy.lib import httputil as _httputil + + +class CherryPyException(Exception): + """A base class for CherryPy exceptions.""" + pass + + +class TimeoutError(CherryPyException): + """Exception raised when Response.timed_out is detected.""" + pass + + +class InternalRedirect(CherryPyException): + """Exception raised to switch to the handler for a different URL. + + This exception will redirect processing to another path within the site + (without informing the client). Provide the new path as an argument when + raising the exception. Provide any params in the querystring for the new URL. + """ + + def __init__(self, path, query_string=""): + import cherrypy + self.request = cherrypy.serving.request + + self.query_string = query_string + if "?" in path: + # Separate any params included in the path + path, self.query_string = path.split("?", 1) + + # Note that urljoin will "do the right thing" whether url is: + # 1. a URL relative to root (e.g. "/dummy") + # 2. a URL relative to the current path + # Note that any query string will be discarded. + path = _urljoin(self.request.path_info, path) + + # Set a 'path' member attribute so that code which traps this + # error can have access to it. + self.path = path + + CherryPyException.__init__(self, path, self.query_string) + + +class HTTPRedirect(CherryPyException): + """Exception raised when the request should be redirected. + + This exception will force a HTTP redirect to the URL or URL's you give it. + The new URL must be passed as the first argument to the Exception, + e.g., HTTPRedirect(newUrl). Multiple URLs are allowed in a list. + If a URL is absolute, it will be used as-is. If it is relative, it is + assumed to be relative to the current cherrypy.request.path_info. + + If one of the provided URL is a unicode object, it will be encoded + using the default encoding or the one passed in parameter. + + There are multiple types of redirect, from which you can select via the + ``status`` argument. If you do not provide a ``status`` arg, it defaults to + 303 (or 302 if responding with HTTP/1.0). + + Examples:: + + raise cherrypy.HTTPRedirect("") + raise cherrypy.HTTPRedirect("/abs/path", 307) + raise cherrypy.HTTPRedirect(["path1", "path2?a=1&b=2"], 301) + + See :ref:`redirectingpost` for additional caveats. + """ + + status = None + """The integer HTTP status code to emit.""" + + urls = None + """The list of URL's to emit.""" + + encoding = 'utf-8' + """The encoding when passed urls are unicode objects""" + + def __init__(self, urls, status=None, encoding=None): + import cherrypy + request = cherrypy.serving.request + + if isinstance(urls, basestring): + urls = [urls] + + abs_urls = [] + for url in urls: + if isinstance(url, unicode): + url = url.encode(encoding or self.encoding) + + # Note that urljoin will "do the right thing" whether url is: + # 1. a complete URL with host (e.g. "http://www.example.com/test") + # 2. a URL relative to root (e.g. "/dummy") + # 3. a URL relative to the current path + # Note that any query string in cherrypy.request is discarded. + url = _urljoin(cherrypy.url(), url) + abs_urls.append(url) + self.urls = abs_urls + + # RFC 2616 indicates a 301 response code fits our goal; however, + # browser support for 301 is quite messy. Do 302/303 instead. See + # http://www.alanflavell.org.uk/www/post-redirect.html + if status is None: + if request.protocol >= (1, 1): + status = 303 + else: + status = 302 + else: + status = int(status) + if status < 300 or status > 399: + raise ValueError("status must be between 300 and 399.") + + self.status = status + CherryPyException.__init__(self, abs_urls, status) + + def set_response(self): + """Modify cherrypy.response status, headers, and body to represent self. + + CherryPy uses this internally, but you can also use it to create an + HTTPRedirect object and set its output without *raising* the exception. + """ + import cherrypy + response = cherrypy.serving.response + response.status = status = self.status + + if status in (300, 301, 302, 303, 307): + response.headers['Content-Type'] = "text/html;charset=utf-8" + # "The ... URI SHOULD be given by the Location field + # in the response." + response.headers['Location'] = self.urls[0] + + # "Unless the request method was HEAD, the entity of the response + # SHOULD contain a short hypertext note with a hyperlink to the + # new URI(s)." + msg = {300: "This resource can be found at %s.", + 301: "This resource has permanently moved to %s.", + 302: "This resource resides temporarily at %s.", + 303: "This resource can be found at %s.", + 307: "This resource has moved temporarily to %s.", + }[status] + msgs = [msg % (u, u) for u in self.urls] + response.body = "
\n".join(msgs) + # Previous code may have set C-L, so we have to reset it + # (allow finalize to set it). + response.headers.pop('Content-Length', None) + elif status == 304: + # Not Modified. + # "The response MUST include the following header fields: + # Date, unless its omission is required by section 14.18.1" + # The "Date" header should have been set in Response.__init__ + + # "...the response SHOULD NOT include other entity-headers." + for key in ('Allow', 'Content-Encoding', 'Content-Language', + 'Content-Length', 'Content-Location', 'Content-MD5', + 'Content-Range', 'Content-Type', 'Expires', + 'Last-Modified'): + if key in response.headers: + del response.headers[key] + + # "The 304 response MUST NOT contain a message-body." + response.body = None + # Previous code may have set C-L, so we have to reset it. + response.headers.pop('Content-Length', None) + elif status == 305: + # Use Proxy. + # self.urls[0] should be the URI of the proxy. + response.headers['Location'] = self.urls[0] + response.body = None + # Previous code may have set C-L, so we have to reset it. + response.headers.pop('Content-Length', None) + else: + raise ValueError("The %s status code is unknown." % status) + + def __call__(self): + """Use this exception as a request.handler (raise self).""" + raise self + + +def clean_headers(status): + """Remove any headers which should not apply to an error response.""" + import cherrypy + + response = cherrypy.serving.response + + # Remove headers which applied to the original content, + # but do not apply to the error page. + respheaders = response.headers + for key in ["Accept-Ranges", "Age", "ETag", "Location", "Retry-After", + "Vary", "Content-Encoding", "Content-Length", "Expires", + "Content-Location", "Content-MD5", "Last-Modified"]: + if key in respheaders: + del respheaders[key] + + if status != 416: + # A server sending a response with status code 416 (Requested + # range not satisfiable) SHOULD include a Content-Range field + # with a byte-range-resp-spec of "*". The instance-length + # specifies the current length of the selected resource. + # A response with status code 206 (Partial Content) MUST NOT + # include a Content-Range field with a byte-range- resp-spec of "*". + if "Content-Range" in respheaders: + del respheaders["Content-Range"] + + +class HTTPError(CherryPyException): + """Exception used to return an HTTP error code (4xx-5xx) to the client. + + This exception can be used to automatically send a response using a http status + code, with an appropriate error page. It takes an optional + ``status`` argument (which must be between 400 and 599); it defaults to 500 + ("Internal Server Error"). It also takes an optional ``message`` argument, + which will be returned in the response body. See + `RFC 2616 `_ + for a complete list of available error codes and when to use them. + + Examples:: + + raise cherrypy.HTTPError(403) + raise cherrypy.HTTPError("403 Forbidden", "You are not allowed to access this resource.") + """ + + status = None + """The HTTP status code. May be of type int or str (with a Reason-Phrase).""" + + code = None + """The integer HTTP status code.""" + + reason = None + """The HTTP Reason-Phrase string.""" + + def __init__(self, status=500, message=None): + self.status = status + try: + self.code, self.reason, defaultmsg = _httputil.valid_status(status) + except ValueError, x: + raise self.__class__(500, x.args[0]) + + if self.code < 400 or self.code > 599: + raise ValueError("status must be between 400 and 599.") + + # See http://www.python.org/dev/peps/pep-0352/ + # self.message = message + self._message = message or defaultmsg + CherryPyException.__init__(self, status, message) + + def set_response(self): + """Modify cherrypy.response status, headers, and body to represent self. + + CherryPy uses this internally, but you can also use it to create an + HTTPError object and set its output without *raising* the exception. + """ + import cherrypy + + response = cherrypy.serving.response + + clean_headers(self.code) + + # In all cases, finalize will be called after this method, + # so don't bother cleaning up response values here. + response.status = self.status + tb = None + if cherrypy.serving.request.show_tracebacks: + tb = format_exc() + response.headers['Content-Type'] = "text/html;charset=utf-8" + response.headers.pop('Content-Length', None) + + content = self.get_error_page(self.status, traceback=tb, + message=self._message) + response.body = content + + _be_ie_unfriendly(self.code) + + def get_error_page(self, *args, **kwargs): + return get_error_page(*args, **kwargs) + + def __call__(self): + """Use this exception as a request.handler (raise self).""" + raise self + + +class NotFound(HTTPError): + """Exception raised when a URL could not be mapped to any handler (404). + + This is equivalent to raising + :class:`HTTPError("404 Not Found") `. + """ + + def __init__(self, path=None): + if path is None: + import cherrypy + request = cherrypy.serving.request + path = request.script_name + request.path_info + self.args = (path,) + HTTPError.__init__(self, 404, "The path '%s' was not found." % path) + + +_HTTPErrorTemplate = ''' + + + + %(status)s + + + +

%(status)s

+

%(message)s

+ 
%(traceback)s
+
+ Powered by CherryPy %(version)s +
+ + +''' + +def get_error_page(status, **kwargs): + """Return an HTML page, containing a pretty error response. + + status should be an int or a str. + kwargs will be interpolated into the page template. + """ + import cherrypy + + try: + code, reason, message = _httputil.valid_status(status) + except ValueError, x: + raise cherrypy.HTTPError(500, x.args[0]) + + # We can't use setdefault here, because some + # callers send None for kwarg values. + if kwargs.get('status') is None: + kwargs['status'] = "%s %s" % (code, reason) + if kwargs.get('message') is None: + kwargs['message'] = message + if kwargs.get('traceback') is None: + kwargs['traceback'] = '' + if kwargs.get('version') is None: + kwargs['version'] = cherrypy.__version__ + + for k, v in iteritems(kwargs): + if v is None: + kwargs[k] = "" + else: + kwargs[k] = _escape(kwargs[k]) + + # Use a custom template or callable for the error page? + pages = cherrypy.serving.request.error_page + error_page = pages.get(code) or pages.get('default') + if error_page: + try: + if hasattr(error_page, '__call__'): + return error_page(**kwargs) + else: + return open(error_page, 'rb').read() % kwargs + except: + e = _format_exception(*_exc_info())[-1] + m = kwargs['message'] + if m: + m += "
" + m += "In addition, the custom error page failed:\n
%s" % e + kwargs['message'] = m + + return _HTTPErrorTemplate % kwargs + + +_ie_friendly_error_sizes = { + 400: 512, 403: 256, 404: 512, 405: 256, + 406: 512, 408: 512, 409: 512, 410: 256, + 500: 512, 501: 512, 505: 512, + } + + +def _be_ie_unfriendly(status): + import cherrypy + response = cherrypy.serving.response + + # For some statuses, Internet Explorer 5+ shows "friendly error + # messages" instead of our response.body if the body is smaller + # than a given size. Fix this by returning a body over that size + # (by adding whitespace). + # See http://support.microsoft.com/kb/q218155/ + s = _ie_friendly_error_sizes.get(status, 0) + if s: + s += 1 + # Since we are issuing an HTTP error status, we assume that + # the entity is short, and we should just collapse it. + content = response.collapse_body() + l = len(content) + if l and l < s: + # IN ADDITION: the response must be written to IE + # in one chunk or it will still get replaced! Bah. + content = content + (" " * (s - l)) + response.body = content + response.headers['Content-Length'] = str(len(content)) + + +def format_exc(exc=None): + """Return exc (or sys.exc_info if None), formatted.""" + if exc is None: + exc = _exc_info() + if exc == (None, None, None): + return "" + import traceback + return "".join(traceback.format_exception(*exc)) + +def bare_error(extrabody=None): + """Produce status, headers, body for a critical error. + + Returns a triple without calling any other questionable functions, + so it should be as error-free as possible. Call it from an HTTP server + if you get errors outside of the request. + + If extrabody is None, a friendly but rather unhelpful error message + is set in the body. If extrabody is a string, it will be appended + as-is to the body. + """ + + # The whole point of this function is to be a last line-of-defense + # in handling errors. That is, it must not raise any errors itself; + # it cannot be allowed to fail. Therefore, don't add to it! + # In particular, don't call any other CP functions. + + body = "Unrecoverable error in the server." + if extrabody is not None: + if not isinstance(extrabody, str): + extrabody = extrabody.encode('utf-8') + body += "\n" + extrabody + + return ("500 Internal Server Error", + [('Content-Type', 'text/plain'), + ('Content-Length', str(len(body)))], + [body]) + + diff --git a/cherrypy/_cplogging.py b/cherrypy/_cplogging.py new file mode 100644 index 00000000..d6ca979e --- /dev/null +++ b/cherrypy/_cplogging.py @@ -0,0 +1,393 @@ +""" +Simple config +============= + +Although CherryPy uses the :mod:`Python logging module `, it does so +behind the scenes so that simple logging is simple, but complicated logging +is still possible. "Simple" logging means that you can log to the screen +(i.e. console/stdout) or to a file, and that you can easily have separate +error and access log files. + +Here are the simplified logging settings. You use these by adding lines to +your config file or dict. You should set these at either the global level or +per application (see next), but generally not both. + + * ``log.screen``: Set this to True to have both "error" and "access" messages + printed to stdout. + * ``log.access_file``: Set this to an absolute filename where you want + "access" messages written. + * ``log.error_file``: Set this to an absolute filename where you want "error" + messages written. + +Many events are automatically logged; to log your own application events, call +:func:`cherrypy.log`. + +Architecture +============ + +Separate scopes +--------------- + +CherryPy provides log managers at both the global and application layers. +This means you can have one set of logging rules for your entire site, +and another set of rules specific to each application. The global log +manager is found at :func:`cherrypy.log`, and the log manager for each +application is found at :attr:`app.log`. +If you're inside a request, the latter is reachable from +``cherrypy.request.app.log``; if you're outside a request, you'll have to obtain +a reference to the ``app``: either the return value of +:func:`tree.mount()` or, if you used +:func:`quickstart()` instead, via ``cherrypy.tree.apps['/']``. + +By default, the global logs are named "cherrypy.error" and "cherrypy.access", +and the application logs are named "cherrypy.error.2378745" and +"cherrypy.access.2378745" (the number is the id of the Application object). +This means that the application logs "bubble up" to the site logs, so if your +application has no log handlers, the site-level handlers will still log the +messages. + +Errors vs. Access +----------------- + +Each log manager handles both "access" messages (one per HTTP request) and +"error" messages (everything else). Note that the "error" log is not just for +errors! The format of access messages is highly formalized, but the error log +isn't--it receives messages from a variety of sources (including full error +tracebacks, if enabled). + + +Custom Handlers +=============== + +The simple settings above work by manipulating Python's standard :mod:`logging` +module. So when you need something more complex, the full power of the standard +module is yours to exploit. You can borrow or create custom handlers, formats, +filters, and much more. Here's an example that skips the standard FileHandler +and uses a RotatingFileHandler instead: + +:: + + #python + log = app.log + + # Remove the default FileHandlers if present. + log.error_file = "" + log.access_file = "" + + maxBytes = getattr(log, "rot_maxBytes", 10000000) + backupCount = getattr(log, "rot_backupCount", 1000) + + # Make a new RotatingFileHandler for the error log. + fname = getattr(log, "rot_error_file", "error.log") + h = handlers.RotatingFileHandler(fname, 'a', maxBytes, backupCount) + h.setLevel(DEBUG) + h.setFormatter(_cplogging.logfmt) + log.error_log.addHandler(h) + + # Make a new RotatingFileHandler for the access log. + fname = getattr(log, "rot_access_file", "access.log") + h = handlers.RotatingFileHandler(fname, 'a', maxBytes, backupCount) + h.setLevel(DEBUG) + h.setFormatter(_cplogging.logfmt) + log.access_log.addHandler(h) + + +The ``rot_*`` attributes are pulled straight from the application log object. +Since "log.*" config entries simply set attributes on the log object, you can +add custom attributes to your heart's content. Note that these handlers are +used ''instead'' of the default, simple handlers outlined above (so don't set +the "log.error_file" config entry, for example). +""" + +import datetime +import logging +# Silence the no-handlers "warning" (stderr write!) in stdlib logging +logging.Logger.manager.emittedNoHandlerWarning = 1 +logfmt = logging.Formatter("%(message)s") +import os +import sys + +import cherrypy +from cherrypy import _cperror + + +class LogManager(object): + """An object to assist both simple and advanced logging. + + ``cherrypy.log`` is an instance of this class. + """ + + appid = None + """The id() of the Application object which owns this log manager. If this + is a global log manager, appid is None.""" + + error_log = None + """The actual :class:`logging.Logger` instance for error messages.""" + + access_log = None + """The actual :class:`logging.Logger` instance for access messages.""" + + access_log_format = \ + '%(h)s %(l)s %(u)s %(t)s "%(r)s" %(s)s %(b)s "%(f)s" "%(a)s"' + + logger_root = None + """The "top-level" logger name. + + This string will be used as the first segment in the Logger names. + The default is "cherrypy", for example, in which case the Logger names + will be of the form:: + + cherrypy.error. + cherrypy.access. + """ + + def __init__(self, appid=None, logger_root="cherrypy"): + self.logger_root = logger_root + self.appid = appid + if appid is None: + self.error_log = logging.getLogger("%s.error" % logger_root) + self.access_log = logging.getLogger("%s.access" % logger_root) + else: + self.error_log = logging.getLogger("%s.error.%s" % (logger_root, appid)) + self.access_log = logging.getLogger("%s.access.%s" % (logger_root, appid)) + self.error_log.setLevel(logging.INFO) + self.access_log.setLevel(logging.INFO) + cherrypy.engine.subscribe('graceful', self.reopen_files) + + def reopen_files(self): + """Close and reopen all file handlers.""" + for log in (self.error_log, self.access_log): + for h in log.handlers: + if isinstance(h, logging.FileHandler): + h.acquire() + h.stream.close() + h.stream = open(h.baseFilename, h.mode) + h.release() + + def error(self, msg='', context='', severity=logging.INFO, traceback=False): + """Write the given ``msg`` to the error log. + + This is not just for errors! Applications may call this at any time + to log application-specific information. + + If ``traceback`` is True, the traceback of the current exception + (if any) will be appended to ``msg``. + """ + if traceback: + msg += _cperror.format_exc() + self.error_log.log(severity, ' '.join((self.time(), context, msg))) + + def __call__(self, *args, **kwargs): + """An alias for ``error``.""" + return self.error(*args, **kwargs) + + def access(self): + """Write to the access log (in Apache/NCSA Combined Log format). + + See http://httpd.apache.org/docs/2.0/logs.html#combined for format + details. + + CherryPy calls this automatically for you. Note there are no arguments; + it collects the data itself from + :class:`cherrypy.request`. + + Like Apache started doing in 2.0.46, non-printable and other special + characters in %r (and we expand that to all parts) are escaped using + \\xhh sequences, where hh stands for the hexadecimal representation + of the raw byte. Exceptions from this rule are " and \\, which are + escaped by prepending a backslash, and all whitespace characters, + which are written in their C-style notation (\\n, \\t, etc). + """ + request = cherrypy.serving.request + remote = request.remote + response = cherrypy.serving.response + outheaders = response.headers + inheaders = request.headers + if response.output_status is None: + status = "-" + else: + status = response.output_status.split(" ", 1)[0] + + atoms = {'h': remote.name or remote.ip, + 'l': '-', + 'u': getattr(request, "login", None) or "-", + 't': self.time(), + 'r': request.request_line, + 's': status, + 'b': dict.get(outheaders, 'Content-Length', '') or "-", + 'f': dict.get(inheaders, 'Referer', ''), + 'a': dict.get(inheaders, 'User-Agent', ''), + } + for k, v in atoms.items(): + if isinstance(v, unicode): + v = v.encode('utf8') + elif not isinstance(v, str): + v = str(v) + # Fortunately, repr(str) escapes unprintable chars, \n, \t, etc + # and backslash for us. All we have to do is strip the quotes. + v = repr(v)[1:-1] + # Escape double-quote. + atoms[k] = v.replace('"', '\\"') + + try: + self.access_log.log(logging.INFO, self.access_log_format % atoms) + except: + self(traceback=True) + + def time(self): + """Return now() in Apache Common Log Format (no timezone).""" + now = datetime.datetime.now() + monthnames = ['jan', 'feb', 'mar', 'apr', 'may', 'jun', + 'jul', 'aug', 'sep', 'oct', 'nov', 'dec'] + month = monthnames[now.month - 1].capitalize() + return ('[%02d/%s/%04d:%02d:%02d:%02d]' % + (now.day, month, now.year, now.hour, now.minute, now.second)) + + def _get_builtin_handler(self, log, key): + for h in log.handlers: + if getattr(h, "_cpbuiltin", None) == key: + return h + + + # ------------------------- Screen handlers ------------------------- # + + def _set_screen_handler(self, log, enable, stream=None): + h = self._get_builtin_handler(log, "screen") + if enable: + if not h: + if stream is None: + stream=sys.stderr + h = logging.StreamHandler(stream) + h.setFormatter(logfmt) + h._cpbuiltin = "screen" + log.addHandler(h) + elif h: + log.handlers.remove(h) + + def _get_screen(self): + h = self._get_builtin_handler + has_h = h(self.error_log, "screen") or h(self.access_log, "screen") + return bool(has_h) + + def _set_screen(self, newvalue): + self._set_screen_handler(self.error_log, newvalue, stream=sys.stderr) + self._set_screen_handler(self.access_log, newvalue, stream=sys.stdout) + screen = property(_get_screen, _set_screen, + doc="""Turn stderr/stdout logging on or off. + + If you set this to True, it'll add the appropriate StreamHandler for + you. If you set it to False, it will remove the handler. + """) + + # -------------------------- File handlers -------------------------- # + + def _add_builtin_file_handler(self, log, fname): + h = logging.FileHandler(fname) + h.setFormatter(logfmt) + h._cpbuiltin = "file" + log.addHandler(h) + + def _set_file_handler(self, log, filename): + h = self._get_builtin_handler(log, "file") + if filename: + if h: + if h.baseFilename != os.path.abspath(filename): + h.close() + log.handlers.remove(h) + self._add_builtin_file_handler(log, filename) + else: + self._add_builtin_file_handler(log, filename) + else: + if h: + h.close() + log.handlers.remove(h) + + def _get_error_file(self): + h = self._get_builtin_handler(self.error_log, "file") + if h: + return h.baseFilename + return '' + def _set_error_file(self, newvalue): + self._set_file_handler(self.error_log, newvalue) + error_file = property(_get_error_file, _set_error_file, + doc="""The filename for self.error_log. + + If you set this to a string, it'll add the appropriate FileHandler for + you. If you set it to ``None`` or ``''``, it will remove the handler. + """) + + def _get_access_file(self): + h = self._get_builtin_handler(self.access_log, "file") + if h: + return h.baseFilename + return '' + def _set_access_file(self, newvalue): + self._set_file_handler(self.access_log, newvalue) + access_file = property(_get_access_file, _set_access_file, + doc="""The filename for self.access_log. + + If you set this to a string, it'll add the appropriate FileHandler for + you. If you set it to ``None`` or ``''``, it will remove the handler. + """) + + # ------------------------- WSGI handlers ------------------------- # + + def _set_wsgi_handler(self, log, enable): + h = self._get_builtin_handler(log, "wsgi") + if enable: + if not h: + h = WSGIErrorHandler() + h.setFormatter(logfmt) + h._cpbuiltin = "wsgi" + log.addHandler(h) + elif h: + log.handlers.remove(h) + + def _get_wsgi(self): + return bool(self._get_builtin_handler(self.error_log, "wsgi")) + + def _set_wsgi(self, newvalue): + self._set_wsgi_handler(self.error_log, newvalue) + wsgi = property(_get_wsgi, _set_wsgi, + doc="""Write errors to wsgi.errors. + + If you set this to True, it'll add the appropriate + :class:`WSGIErrorHandler` for you + (which writes errors to ``wsgi.errors``). + If you set it to False, it will remove the handler. + """) + + +class WSGIErrorHandler(logging.Handler): + "A handler class which writes logging records to environ['wsgi.errors']." + + def flush(self): + """Flushes the stream.""" + try: + stream = cherrypy.serving.request.wsgi_environ.get('wsgi.errors') + except (AttributeError, KeyError): + pass + else: + stream.flush() + + def emit(self, record): + """Emit a record.""" + try: + stream = cherrypy.serving.request.wsgi_environ.get('wsgi.errors') + except (AttributeError, KeyError): + pass + else: + try: + msg = self.format(record) + fs = "%s\n" + import types + if not hasattr(types, "UnicodeType"): #if no unicode support... + stream.write(fs % msg) + else: + try: + stream.write(fs % msg) + except UnicodeError: + stream.write(fs % msg.encode("UTF-8")) + self.flush() + except: + self.handleError(record) diff --git a/cherrypy/_cpmodpy.py b/cherrypy/_cpmodpy.py new file mode 100644 index 00000000..ba2ab22f --- /dev/null +++ b/cherrypy/_cpmodpy.py @@ -0,0 +1,333 @@ +"""Native adapter for serving CherryPy via mod_python + +Basic usage: + +########################################## +# Application in a module called myapp.py +########################################## + +import cherrypy + +class Root: + @cherrypy.expose + def index(self): + return 'Hi there, Ho there, Hey there' + + +# We will use this method from the mod_python configuration +# as the entry point to our application +def setup_server(): + cherrypy.tree.mount(Root()) + cherrypy.config.update({'environment': 'production', + 'log.screen': False, + 'show_tracebacks': False}) + +########################################## +# mod_python settings for apache2 +# This should reside in your httpd.conf +# or a file that will be loaded at +# apache startup +########################################## + +# Start +DocumentRoot "/" +Listen 8080 +LoadModule python_module /usr/lib/apache2/modules/mod_python.so + + + PythonPath "sys.path+['/path/to/my/application']" + SetHandler python-program + PythonHandler cherrypy._cpmodpy::handler + PythonOption cherrypy.setup myapp::setup_server + PythonDebug On + +# End + +The actual path to your mod_python.so is dependent on your +environment. In this case we suppose a global mod_python +installation on a Linux distribution such as Ubuntu. + +We do set the PythonPath configuration setting so that +your application can be found by from the user running +the apache2 instance. Of course if your application +resides in the global site-package this won't be needed. + +Then restart apache2 and access http://127.0.0.1:8080 +""" + +import logging +import sys + +import cherrypy +from cherrypy._cpcompat import BytesIO, copyitems, ntob +from cherrypy._cperror import format_exc, bare_error +from cherrypy.lib import httputil + + +# ------------------------------ Request-handling + + + +def setup(req): + from mod_python import apache + + # Run any setup functions defined by a "PythonOption cherrypy.setup" directive. + options = req.get_options() + if 'cherrypy.setup' in options: + for function in options['cherrypy.setup'].split(): + atoms = function.split('::', 1) + if len(atoms) == 1: + mod = __import__(atoms[0], globals(), locals()) + else: + modname, fname = atoms + mod = __import__(modname, globals(), locals(), [fname]) + func = getattr(mod, fname) + func() + + cherrypy.config.update({'log.screen': False, + "tools.ignore_headers.on": True, + "tools.ignore_headers.headers": ['Range'], + }) + + engine = cherrypy.engine + if hasattr(engine, "signal_handler"): + engine.signal_handler.unsubscribe() + if hasattr(engine, "console_control_handler"): + engine.console_control_handler.unsubscribe() + engine.autoreload.unsubscribe() + cherrypy.server.unsubscribe() + + def _log(msg, level): + newlevel = apache.APLOG_ERR + if logging.DEBUG >= level: + newlevel = apache.APLOG_DEBUG + elif logging.INFO >= level: + newlevel = apache.APLOG_INFO + elif logging.WARNING >= level: + newlevel = apache.APLOG_WARNING + # On Windows, req.server is required or the msg will vanish. See + # http://www.modpython.org/pipermail/mod_python/2003-October/014291.html. + # Also, "When server is not specified...LogLevel does not apply..." + apache.log_error(msg, newlevel, req.server) + engine.subscribe('log', _log) + + engine.start() + + def cherrypy_cleanup(data): + engine.exit() + try: + # apache.register_cleanup wasn't available until 3.1.4. + apache.register_cleanup(cherrypy_cleanup) + except AttributeError: + req.server.register_cleanup(req, cherrypy_cleanup) + + +class _ReadOnlyRequest: + expose = ('read', 'readline', 'readlines') + def __init__(self, req): + for method in self.expose: + self.__dict__[method] = getattr(req, method) + + +recursive = False + +_isSetUp = False +def handler(req): + from mod_python import apache + try: + global _isSetUp + if not _isSetUp: + setup(req) + _isSetUp = True + + # Obtain a Request object from CherryPy + local = req.connection.local_addr + local = httputil.Host(local[0], local[1], req.connection.local_host or "") + remote = req.connection.remote_addr + remote = httputil.Host(remote[0], remote[1], req.connection.remote_host or "") + + scheme = req.parsed_uri[0] or 'http' + req.get_basic_auth_pw() + + try: + # apache.mpm_query only became available in mod_python 3.1 + q = apache.mpm_query + threaded = q(apache.AP_MPMQ_IS_THREADED) + forked = q(apache.AP_MPMQ_IS_FORKED) + except AttributeError: + bad_value = ("You must provide a PythonOption '%s', " + "either 'on' or 'off', when running a version " + "of mod_python < 3.1") + + threaded = options.get('multithread', '').lower() + if threaded == 'on': + threaded = True + elif threaded == 'off': + threaded = False + else: + raise ValueError(bad_value % "multithread") + + forked = options.get('multiprocess', '').lower() + if forked == 'on': + forked = True + elif forked == 'off': + forked = False + else: + raise ValueError(bad_value % "multiprocess") + + sn = cherrypy.tree.script_name(req.uri or "/") + if sn is None: + send_response(req, '404 Not Found', [], '') + else: + app = cherrypy.tree.apps[sn] + method = req.method + path = req.uri + qs = req.args or "" + reqproto = req.protocol + headers = copyitems(req.headers_in) + rfile = _ReadOnlyRequest(req) + prev = None + + try: + redirections = [] + while True: + request, response = app.get_serving(local, remote, scheme, + "HTTP/1.1") + request.login = req.user + request.multithread = bool(threaded) + request.multiprocess = bool(forked) + request.app = app + request.prev = prev + + # Run the CherryPy Request object and obtain the response + try: + request.run(method, path, qs, reqproto, headers, rfile) + break + except cherrypy.InternalRedirect: + ir = sys.exc_info()[1] + app.release_serving() + prev = request + + if not recursive: + if ir.path in redirections: + raise RuntimeError("InternalRedirector visited the " + "same URL twice: %r" % ir.path) + else: + # Add the *previous* path_info + qs to redirections. + if qs: + qs = "?" + qs + redirections.append(sn + path + qs) + + # Munge environment and try again. + method = "GET" + path = ir.path + qs = ir.query_string + rfile = BytesIO() + + send_response(req, response.status, response.header_list, + response.body, response.stream) + finally: + app.release_serving() + except: + tb = format_exc() + cherrypy.log(tb, 'MOD_PYTHON', severity=logging.ERROR) + s, h, b = bare_error() + send_response(req, s, h, b) + return apache.OK + + +def send_response(req, status, headers, body, stream=False): + # Set response status + req.status = int(status[:3]) + + # Set response headers + req.content_type = "text/plain" + for header, value in headers: + if header.lower() == 'content-type': + req.content_type = value + continue + req.headers_out.add(header, value) + + if stream: + # Flush now so the status and headers are sent immediately. + req.flush() + + # Set response body + if isinstance(body, basestring): + req.write(body) + else: + for seg in body: + req.write(seg) + + + +# --------------- Startup tools for CherryPy + mod_python --------------- # + + +import os +import re + + +def read_process(cmd, args=""): + fullcmd = "%s %s" % (cmd, args) + pipein, pipeout = os.popen4(fullcmd) + try: + firstline = pipeout.readline() + if (re.search(ntob("(not recognized|No such file|not found)"), firstline, + re.IGNORECASE)): + raise IOError('%s must be on your system path.' % cmd) + output = firstline + pipeout.read() + finally: + pipeout.close() + return output + + +class ModPythonServer(object): + + template = """ +# Apache2 server configuration file for running CherryPy with mod_python. + +DocumentRoot "/" +Listen %(port)s +LoadModule python_module modules/mod_python.so + + + SetHandler python-program + PythonHandler %(handler)s + PythonDebug On +%(opts)s + +""" + + def __init__(self, loc="/", port=80, opts=None, apache_path="apache", + handler="cherrypy._cpmodpy::handler"): + self.loc = loc + self.port = port + self.opts = opts + self.apache_path = apache_path + self.handler = handler + + def start(self): + opts = "".join([" PythonOption %s %s\n" % (k, v) + for k, v in self.opts]) + conf_data = self.template % {"port": self.port, + "loc": self.loc, + "opts": opts, + "handler": self.handler, + } + + mpconf = os.path.join(os.path.dirname(__file__), "cpmodpy.conf") + f = open(mpconf, 'wb') + try: + f.write(conf_data) + finally: + f.close() + + response = read_process(self.apache_path, "-k start -f %s" % mpconf) + self.ready = True + return response + + def stop(self): + os.popen("apache -k stop") + self.ready = False + diff --git a/cherrypy/_cpnative_server.py b/cherrypy/_cpnative_server.py new file mode 100644 index 00000000..57f715a9 --- /dev/null +++ b/cherrypy/_cpnative_server.py @@ -0,0 +1,149 @@ +"""Native adapter for serving CherryPy via its builtin server.""" + +import logging +import sys + +import cherrypy +from cherrypy._cpcompat import BytesIO +from cherrypy._cperror import format_exc, bare_error +from cherrypy.lib import httputil +from cherrypy import wsgiserver + + +class NativeGateway(wsgiserver.Gateway): + + recursive = False + + def respond(self): + req = self.req + try: + # Obtain a Request object from CherryPy + local = req.server.bind_addr + local = httputil.Host(local[0], local[1], "") + remote = req.conn.remote_addr, req.conn.remote_port + remote = httputil.Host(remote[0], remote[1], "") + + scheme = req.scheme + sn = cherrypy.tree.script_name(req.uri or "/") + if sn is None: + self.send_response('404 Not Found', [], ['']) + else: + app = cherrypy.tree.apps[sn] + method = req.method + path = req.path + qs = req.qs or "" + headers = req.inheaders.items() + rfile = req.rfile + prev = None + + try: + redirections = [] + while True: + request, response = app.get_serving( + local, remote, scheme, "HTTP/1.1") + request.multithread = True + request.multiprocess = False + request.app = app + request.prev = prev + + # Run the CherryPy Request object and obtain the response + try: + request.run(method, path, qs, req.request_protocol, headers, rfile) + break + except cherrypy.InternalRedirect: + ir = sys.exc_info()[1] + app.release_serving() + prev = request + + if not self.recursive: + if ir.path in redirections: + raise RuntimeError("InternalRedirector visited the " + "same URL twice: %r" % ir.path) + else: + # Add the *previous* path_info + qs to redirections. + if qs: + qs = "?" + qs + redirections.append(sn + path + qs) + + # Munge environment and try again. + method = "GET" + path = ir.path + qs = ir.query_string + rfile = BytesIO() + + self.send_response( + response.output_status, response.header_list, + response.body) + finally: + app.release_serving() + except: + tb = format_exc() + #print tb + cherrypy.log(tb, 'NATIVE_ADAPTER', severity=logging.ERROR) + s, h, b = bare_error() + self.send_response(s, h, b) + + def send_response(self, status, headers, body): + req = self.req + + # Set response status + req.status = str(status or "500 Server Error") + + # Set response headers + for header, value in headers: + req.outheaders.append((header, value)) + if (req.ready and not req.sent_headers): + req.sent_headers = True + req.send_headers() + + # Set response body + for seg in body: + req.write(seg) + + +class CPHTTPServer(wsgiserver.HTTPServer): + """Wrapper for wsgiserver.HTTPServer. + + wsgiserver has been designed to not reference CherryPy in any way, + so that it can be used in other frameworks and applications. + Therefore, we wrap it here, so we can apply some attributes + from config -> cherrypy.server -> HTTPServer. + """ + + def __init__(self, server_adapter=cherrypy.server): + self.server_adapter = server_adapter + + server_name = (self.server_adapter.socket_host or + self.server_adapter.socket_file or + None) + + wsgiserver.HTTPServer.__init__( + self, server_adapter.bind_addr, NativeGateway, + minthreads=server_adapter.thread_pool, + maxthreads=server_adapter.thread_pool_max, + server_name=server_name) + + self.max_request_header_size = self.server_adapter.max_request_header_size or 0 + self.max_request_body_size = self.server_adapter.max_request_body_size or 0 + self.request_queue_size = self.server_adapter.socket_queue_size + self.timeout = self.server_adapter.socket_timeout + self.shutdown_timeout = self.server_adapter.shutdown_timeout + self.protocol = self.server_adapter.protocol_version + self.nodelay = self.server_adapter.nodelay + + ssl_module = self.server_adapter.ssl_module or 'pyopenssl' + if self.server_adapter.ssl_context: + adapter_class = wsgiserver.get_ssl_adapter_class(ssl_module) + self.ssl_adapter = adapter_class( + self.server_adapter.ssl_certificate, + self.server_adapter.ssl_private_key, + self.server_adapter.ssl_certificate_chain) + self.ssl_adapter.context = self.server_adapter.ssl_context + elif self.server_adapter.ssl_certificate: + adapter_class = wsgiserver.get_ssl_adapter_class(ssl_module) + self.ssl_adapter = adapter_class( + self.server_adapter.ssl_certificate, + self.server_adapter.ssl_private_key, + self.server_adapter.ssl_certificate_chain) + + diff --git a/cherrypy/_cpreqbody.py b/cherrypy/_cpreqbody.py new file mode 100644 index 00000000..1b0496e3 --- /dev/null +++ b/cherrypy/_cpreqbody.py @@ -0,0 +1,941 @@ +"""Request body processing for CherryPy. + +.. versionadded:: 3.2 + +Application authors have complete control over the parsing of HTTP request +entities. In short, :attr:`cherrypy.request.body` +is now always set to an instance of :class:`RequestBody`, +and *that* class is a subclass of :class:`Entity`. + +When an HTTP request includes an entity body, it is often desirable to +provide that information to applications in a form other than the raw bytes. +Different content types demand different approaches. Examples: + + * For a GIF file, we want the raw bytes in a stream. + * An HTML form is better parsed into its component fields, and each text field + decoded from bytes to unicode. + * A JSON body should be deserialized into a Python dict or list. + +When the request contains a Content-Type header, the media type is used as a +key to look up a value in the +:attr:`request.body.processors` dict. +If the full media +type is not found, then the major type is tried; for example, if no processor +is found for the 'image/jpeg' type, then we look for a processor for the 'image' +types altogether. If neither the full type nor the major type has a matching +processor, then a default processor is used +(:func:`default_proc`). For most +types, this means no processing is done, and the body is left unread as a +raw byte stream. Processors are configurable in an 'on_start_resource' hook. + +Some processors, especially those for the 'text' types, attempt to decode bytes +to unicode. If the Content-Type request header includes a 'charset' parameter, +this is used to decode the entity. Otherwise, one or more default charsets may +be attempted, although this decision is up to each processor. If a processor +successfully decodes an Entity or Part, it should set the +:attr:`charset` attribute +on the Entity or Part to the name of the successful charset, so that +applications can easily re-encode or transcode the value if they wish. + +If the Content-Type of the request entity is of major type 'multipart', then +the above parsing process, and possibly a decoding process, is performed for +each part. + +For both the full entity and multipart parts, a Content-Disposition header may +be used to fill :attr:`name` and +:attr:`filename` attributes on the +request.body or the Part. + +.. _custombodyprocessors: + +Custom Processors +================= + +You can add your own processors for any specific or major MIME type. Simply add +it to the :attr:`processors` dict in a +hook/tool that runs at ``on_start_resource`` or ``before_request_body``. +Here's the built-in JSON tool for an example:: + + def json_in(force=True, debug=False): + request = cherrypy.serving.request + def json_processor(entity): + \"""Read application/json data into request.json.\""" + if not entity.headers.get("Content-Length", ""): + raise cherrypy.HTTPError(411) + + body = entity.fp.read() + try: + request.json = json_decode(body) + except ValueError: + raise cherrypy.HTTPError(400, 'Invalid JSON document') + if force: + request.body.processors.clear() + request.body.default_proc = cherrypy.HTTPError( + 415, 'Expected an application/json content type') + request.body.processors['application/json'] = json_processor + +We begin by defining a new ``json_processor`` function to stick in the ``processors`` +dictionary. All processor functions take a single argument, the ``Entity`` instance +they are to process. It will be called whenever a request is received (for those +URI's where the tool is turned on) which has a ``Content-Type`` of +"application/json". + +First, it checks for a valid ``Content-Length`` (raising 411 if not valid), then +reads the remaining bytes on the socket. The ``fp`` object knows its own length, so +it won't hang waiting for data that never arrives. It will return when all data +has been read. Then, we decode those bytes using Python's built-in ``json`` module, +and stick the decoded result onto ``request.json`` . If it cannot be decoded, we +raise 400. + +If the "force" argument is True (the default), the ``Tool`` clears the ``processors`` +dict so that request entities of other ``Content-Types`` aren't parsed at all. Since +there's no entry for those invalid MIME types, the ``default_proc`` method of ``cherrypy.request.body`` +is called. But this does nothing by default (usually to provide the page handler an opportunity to handle it.) +But in our case, we want to raise 415, so we replace ``request.body.default_proc`` +with the error (``HTTPError`` instances, when called, raise themselves). + +If we were defining a custom processor, we can do so without making a ``Tool``. Just add the config entry:: + + request.body.processors = {'application/json': json_processor} + +Note that you can only replace the ``processors`` dict wholesale this way, not update the existing one. +""" + +import re +import sys +import tempfile +from urllib import unquote_plus + +import cherrypy +from cherrypy._cpcompat import basestring, ntob, ntou +from cherrypy.lib import httputil + + +# -------------------------------- Processors -------------------------------- # + +def process_urlencoded(entity): + """Read application/x-www-form-urlencoded data into entity.params.""" + qs = entity.fp.read() + for charset in entity.attempt_charsets: + try: + params = {} + for aparam in qs.split(ntob('&')): + for pair in aparam.split(ntob(';')): + if not pair: + continue + + atoms = pair.split(ntob('='), 1) + if len(atoms) == 1: + atoms.append(ntob('')) + + key = unquote_plus(atoms[0]).decode(charset) + value = unquote_plus(atoms[1]).decode(charset) + + if key in params: + if not isinstance(params[key], list): + params[key] = [params[key]] + params[key].append(value) + else: + params[key] = value + except UnicodeDecodeError: + pass + else: + entity.charset = charset + break + else: + raise cherrypy.HTTPError( + 400, "The request entity could not be decoded. The following " + "charsets were attempted: %s" % repr(entity.attempt_charsets)) + + # Now that all values have been successfully parsed and decoded, + # apply them to the entity.params dict. + for key, value in params.items(): + if key in entity.params: + if not isinstance(entity.params[key], list): + entity.params[key] = [entity.params[key]] + entity.params[key].append(value) + else: + entity.params[key] = value + + +def process_multipart(entity): + """Read all multipart parts into entity.parts.""" + ib = "" + if 'boundary' in entity.content_type.params: + # http://tools.ietf.org/html/rfc2046#section-5.1.1 + # "The grammar for parameters on the Content-type field is such that it + # is often necessary to enclose the boundary parameter values in quotes + # on the Content-type line" + ib = entity.content_type.params['boundary'].strip('"') + + if not re.match("^[ -~]{0,200}[!-~]$", ib): + raise ValueError('Invalid boundary in multipart form: %r' % (ib,)) + + ib = ('--' + ib).encode('ascii') + + # Find the first marker + while True: + b = entity.readline() + if not b: + return + + b = b.strip() + if b == ib: + break + + # Read all parts + while True: + part = entity.part_class.from_fp(entity.fp, ib) + entity.parts.append(part) + part.process() + if part.fp.done: + break + +def process_multipart_form_data(entity): + """Read all multipart/form-data parts into entity.parts or entity.params.""" + process_multipart(entity) + + kept_parts = [] + for part in entity.parts: + if part.name is None: + kept_parts.append(part) + else: + if part.filename is None: + # It's a regular field + value = part.fullvalue() + else: + # It's a file upload. Retain the whole part so consumer code + # has access to its .file and .filename attributes. + value = part + + if part.name in entity.params: + if not isinstance(entity.params[part.name], list): + entity.params[part.name] = [entity.params[part.name]] + entity.params[part.name].append(value) + else: + entity.params[part.name] = value + + entity.parts = kept_parts + +def _old_process_multipart(entity): + """The behavior of 3.2 and lower. Deprecated and will be changed in 3.3.""" + process_multipart(entity) + + params = entity.params + + for part in entity.parts: + if part.name is None: + key = ntou('parts') + else: + key = part.name + + if part.filename is None: + # It's a regular field + value = part.fullvalue() + else: + # It's a file upload. Retain the whole part so consumer code + # has access to its .file and .filename attributes. + value = part + + if key in params: + if not isinstance(params[key], list): + params[key] = [params[key]] + params[key].append(value) + else: + params[key] = value + + + +# --------------------------------- Entities --------------------------------- # + + +class Entity(object): + """An HTTP request body, or MIME multipart body. + + This class collects information about the HTTP request entity. When a + given entity is of MIME type "multipart", each part is parsed into its own + Entity instance, and the set of parts stored in + :attr:`entity.parts`. + + Between the ``before_request_body`` and ``before_handler`` tools, CherryPy + tries to process the request body (if any) by calling + :func:`request.body.process`, a dict. + If a matching processor cannot be found for the complete Content-Type, + it tries again using the major type. For example, if a request with an + entity of type "image/jpeg" arrives, but no processor can be found for + that complete type, then one is sought for the major type "image". If a + processor is still not found, then the + :func:`default_proc` method of the + Entity is called (which does nothing by default; you can override this too). + + CherryPy includes processors for the "application/x-www-form-urlencoded" + type, the "multipart/form-data" type, and the "multipart" major type. + CherryPy 3.2 processes these types almost exactly as older versions. + Parts are passed as arguments to the page handler using their + ``Content-Disposition.name`` if given, otherwise in a generic "parts" + argument. Each such part is either a string, or the + :class:`Part` itself if it's a file. (In this + case it will have ``file`` and ``filename`` attributes, or possibly a + ``value`` attribute). Each Part is itself a subclass of + Entity, and has its own ``process`` method and ``processors`` dict. + + There is a separate processor for the "multipart" major type which is more + flexible, and simply stores all multipart parts in + :attr:`request.body.parts`. You can + enable it with:: + + cherrypy.request.body.processors['multipart'] = _cpreqbody.process_multipart + + in an ``on_start_resource`` tool. + """ + + # http://tools.ietf.org/html/rfc2046#section-4.1.2: + # "The default character set, which must be assumed in the + # absence of a charset parameter, is US-ASCII." + # However, many browsers send data in utf-8 with no charset. + attempt_charsets = ['utf-8'] + """A list of strings, each of which should be a known encoding. + + When the Content-Type of the request body warrants it, each of the given + encodings will be tried in order. The first one to successfully decode the + entity without raising an error is stored as + :attr:`entity.charset`. This defaults + to ``['utf-8']`` (plus 'ISO-8859-1' for "text/\*" types, as required by + `HTTP/1.1 `_), + but ``['us-ascii', 'utf-8']`` for multipart parts. + """ + + charset = None + """The successful decoding; see "attempt_charsets" above.""" + + content_type = None + """The value of the Content-Type request header. + + If the Entity is part of a multipart payload, this will be the Content-Type + given in the MIME headers for this part. + """ + + default_content_type = 'application/x-www-form-urlencoded' + """This defines a default ``Content-Type`` to use if no Content-Type header + is given. The empty string is used for RequestBody, which results in the + request body not being read or parsed at all. This is by design; a missing + ``Content-Type`` header in the HTTP request entity is an error at best, + and a security hole at worst. For multipart parts, however, the MIME spec + declares that a part with no Content-Type defaults to "text/plain" + (see :class:`Part`). + """ + + filename = None + """The ``Content-Disposition.filename`` header, if available.""" + + fp = None + """The readable socket file object.""" + + headers = None + """A dict of request/multipart header names and values. + + This is a copy of the ``request.headers`` for the ``request.body``; + for multipart parts, it is the set of headers for that part. + """ + + length = None + """The value of the ``Content-Length`` header, if provided.""" + + name = None + """The "name" parameter of the ``Content-Disposition`` header, if any.""" + + params = None + """ + If the request Content-Type is 'application/x-www-form-urlencoded' or + multipart, this will be a dict of the params pulled from the entity + body; that is, it will be the portion of request.params that come + from the message body (sometimes called "POST params", although they + can be sent with various HTTP method verbs). This value is set between + the 'before_request_body' and 'before_handler' hooks (assuming that + process_request_body is True).""" + + processors = {'application/x-www-form-urlencoded': process_urlencoded, + 'multipart/form-data': process_multipart_form_data, + 'multipart': process_multipart, + } + """A dict of Content-Type names to processor methods.""" + + parts = None + """A list of Part instances if ``Content-Type`` is of major type "multipart".""" + + part_class = None + """The class used for multipart parts. + + You can replace this with custom subclasses to alter the processing of + multipart parts. + """ + + def __init__(self, fp, headers, params=None, parts=None): + # Make an instance-specific copy of the class processors + # so Tools, etc. can replace them per-request. + self.processors = self.processors.copy() + + self.fp = fp + self.headers = headers + + if params is None: + params = {} + self.params = params + + if parts is None: + parts = [] + self.parts = parts + + # Content-Type + self.content_type = headers.elements('Content-Type') + if self.content_type: + self.content_type = self.content_type[0] + else: + self.content_type = httputil.HeaderElement.from_str( + self.default_content_type) + + # Copy the class 'attempt_charsets', prepending any Content-Type charset + dec = self.content_type.params.get("charset", None) + if dec: + #dec = dec.decode('ISO-8859-1') + self.attempt_charsets = [dec] + [c for c in self.attempt_charsets + if c != dec] + else: + self.attempt_charsets = self.attempt_charsets[:] + + # Length + self.length = None + clen = headers.get('Content-Length', None) + # If Transfer-Encoding is 'chunked', ignore any Content-Length. + if clen is not None and 'chunked' not in headers.get('Transfer-Encoding', ''): + try: + self.length = int(clen) + except ValueError: + pass + + # Content-Disposition + self.name = None + self.filename = None + disp = headers.elements('Content-Disposition') + if disp: + disp = disp[0] + if 'name' in disp.params: + self.name = disp.params['name'] + if self.name.startswith('"') and self.name.endswith('"'): + self.name = self.name[1:-1] + if 'filename' in disp.params: + self.filename = disp.params['filename'] + if self.filename.startswith('"') and self.filename.endswith('"'): + self.filename = self.filename[1:-1] + + # The 'type' attribute is deprecated in 3.2; remove it in 3.3. + type = property(lambda self: self.content_type, + doc="""A deprecated alias for :attr:`content_type`.""") + + def read(self, size=None, fp_out=None): + return self.fp.read(size, fp_out) + + def readline(self, size=None): + return self.fp.readline(size) + + def readlines(self, sizehint=None): + return self.fp.readlines(sizehint) + + def __iter__(self): + return self + + def next(self): + line = self.readline() + if not line: + raise StopIteration + return line + + def read_into_file(self, fp_out=None): + """Read the request body into fp_out (or make_file() if None). Return fp_out.""" + if fp_out is None: + fp_out = self.make_file() + self.read(fp_out=fp_out) + return fp_out + + def make_file(self): + """Return a file-like object into which the request body will be read. + + By default, this will return a TemporaryFile. Override as needed. + See also :attr:`cherrypy._cpreqbody.Part.maxrambytes`.""" + return tempfile.TemporaryFile() + + def fullvalue(self): + """Return this entity as a string, whether stored in a file or not.""" + if self.file: + # It was stored in a tempfile. Read it. + self.file.seek(0) + value = self.file.read() + self.file.seek(0) + else: + value = self.value + return value + + def process(self): + """Execute the best-match processor for the given media type.""" + proc = None + ct = self.content_type.value + try: + proc = self.processors[ct] + except KeyError: + toptype = ct.split('/', 1)[0] + try: + proc = self.processors[toptype] + except KeyError: + pass + if proc is None: + self.default_proc() + else: + proc(self) + + def default_proc(self): + """Called if a more-specific processor is not found for the ``Content-Type``.""" + # Leave the fp alone for someone else to read. This works fine + # for request.body, but the Part subclasses need to override this + # so they can move on to the next part. + pass + + +class Part(Entity): + """A MIME part entity, part of a multipart entity.""" + + # "The default character set, which must be assumed in the absence of a + # charset parameter, is US-ASCII." + attempt_charsets = ['us-ascii', 'utf-8'] + """A list of strings, each of which should be a known encoding. + + When the Content-Type of the request body warrants it, each of the given + encodings will be tried in order. The first one to successfully decode the + entity without raising an error is stored as + :attr:`entity.charset`. This defaults + to ``['utf-8']`` (plus 'ISO-8859-1' for "text/\*" types, as required by + `HTTP/1.1 `_), + but ``['us-ascii', 'utf-8']`` for multipart parts. + """ + + boundary = None + """The MIME multipart boundary.""" + + default_content_type = 'text/plain' + """This defines a default ``Content-Type`` to use if no Content-Type header + is given. The empty string is used for RequestBody, which results in the + request body not being read or parsed at all. This is by design; a missing + ``Content-Type`` header in the HTTP request entity is an error at best, + and a security hole at worst. For multipart parts, however (this class), + the MIME spec declares that a part with no Content-Type defaults to + "text/plain". + """ + + # This is the default in stdlib cgi. We may want to increase it. + maxrambytes = 1000 + """The threshold of bytes after which point the ``Part`` will store its data + in a file (generated by :func:`make_file`) + instead of a string. Defaults to 1000, just like the :mod:`cgi` module in + Python's standard library. + """ + + def __init__(self, fp, headers, boundary): + Entity.__init__(self, fp, headers) + self.boundary = boundary + self.file = None + self.value = None + + def from_fp(cls, fp, boundary): + headers = cls.read_headers(fp) + return cls(fp, headers, boundary) + from_fp = classmethod(from_fp) + + def read_headers(cls, fp): + headers = httputil.HeaderMap() + while True: + line = fp.readline() + if not line: + # No more data--illegal end of headers + raise EOFError("Illegal end of headers.") + + if line == ntob('\r\n'): + # Normal end of headers + break + if not line.endswith(ntob('\r\n')): + raise ValueError("MIME requires CRLF terminators: %r" % line) + + if line[0] in ntob(' \t'): + # It's a continuation line. + v = line.strip().decode('ISO-8859-1') + else: + k, v = line.split(ntob(":"), 1) + k = k.strip().decode('ISO-8859-1') + v = v.strip().decode('ISO-8859-1') + + existing = headers.get(k) + if existing: + v = ", ".join((existing, v)) + headers[k] = v + + return headers + read_headers = classmethod(read_headers) + + def read_lines_to_boundary(self, fp_out=None): + """Read bytes from self.fp and return or write them to a file. + + If the 'fp_out' argument is None (the default), all bytes read are + returned in a single byte string. + + If the 'fp_out' argument is not None, it must be a file-like object that + supports the 'write' method; all bytes read will be written to the fp, + and that fp is returned. + """ + endmarker = self.boundary + ntob("--") + delim = ntob("") + prev_lf = True + lines = [] + seen = 0 + while True: + line = self.fp.readline(1<<16) + if not line: + raise EOFError("Illegal end of multipart body.") + if line.startswith(ntob("--")) and prev_lf: + strippedline = line.strip() + if strippedline == self.boundary: + break + if strippedline == endmarker: + self.fp.finish() + break + + line = delim + line + + if line.endswith(ntob("\r\n")): + delim = ntob("\r\n") + line = line[:-2] + prev_lf = True + elif line.endswith(ntob("\n")): + delim = ntob("\n") + line = line[:-1] + prev_lf = True + else: + delim = ntob("") + prev_lf = False + + if fp_out is None: + lines.append(line) + seen += len(line) + if seen > self.maxrambytes: + fp_out = self.make_file() + for line in lines: + fp_out.write(line) + else: + fp_out.write(line) + + if fp_out is None: + result = ntob('').join(lines) + for charset in self.attempt_charsets: + try: + result = result.decode(charset) + except UnicodeDecodeError: + pass + else: + self.charset = charset + return result + else: + raise cherrypy.HTTPError( + 400, "The request entity could not be decoded. The following " + "charsets were attempted: %s" % repr(self.attempt_charsets)) + else: + fp_out.seek(0) + return fp_out + + def default_proc(self): + """Called if a more-specific processor is not found for the ``Content-Type``.""" + if self.filename: + # Always read into a file if a .filename was given. + self.file = self.read_into_file() + else: + result = self.read_lines_to_boundary() + if isinstance(result, basestring): + self.value = result + else: + self.file = result + + def read_into_file(self, fp_out=None): + """Read the request body into fp_out (or make_file() if None). Return fp_out.""" + if fp_out is None: + fp_out = self.make_file() + self.read_lines_to_boundary(fp_out=fp_out) + return fp_out + +Entity.part_class = Part + + +class Infinity(object): + def __cmp__(self, other): + return 1 + def __sub__(self, other): + return self +inf = Infinity() + + +comma_separated_headers = ['Accept', 'Accept-Charset', 'Accept-Encoding', + 'Accept-Language', 'Accept-Ranges', 'Allow', 'Cache-Control', 'Connection', + 'Content-Encoding', 'Content-Language', 'Expect', 'If-Match', + 'If-None-Match', 'Pragma', 'Proxy-Authenticate', 'Te', 'Trailer', + 'Transfer-Encoding', 'Upgrade', 'Vary', 'Via', 'Warning', 'Www-Authenticate'] + + +class SizedReader: + + def __init__(self, fp, length, maxbytes, bufsize=8192, has_trailers=False): + # Wrap our fp in a buffer so peek() works + self.fp = fp + self.length = length + self.maxbytes = maxbytes + self.buffer = ntob('') + self.bufsize = bufsize + self.bytes_read = 0 + self.done = False + self.has_trailers = has_trailers + + def read(self, size=None, fp_out=None): + """Read bytes from the request body and return or write them to a file. + + A number of bytes less than or equal to the 'size' argument are read + off the socket. The actual number of bytes read are tracked in + self.bytes_read. The number may be smaller than 'size' when 1) the + client sends fewer bytes, 2) the 'Content-Length' request header + specifies fewer bytes than requested, or 3) the number of bytes read + exceeds self.maxbytes (in which case, 413 is raised). + + If the 'fp_out' argument is None (the default), all bytes read are + returned in a single byte string. + + If the 'fp_out' argument is not None, it must be a file-like object that + supports the 'write' method; all bytes read will be written to the fp, + and None is returned. + """ + + if self.length is None: + if size is None: + remaining = inf + else: + remaining = size + else: + remaining = self.length - self.bytes_read + if size and size < remaining: + remaining = size + if remaining == 0: + self.finish() + if fp_out is None: + return ntob('') + else: + return None + + chunks = [] + + # Read bytes from the buffer. + if self.buffer: + if remaining is inf: + data = self.buffer + self.buffer = ntob('') + else: + data = self.buffer[:remaining] + self.buffer = self.buffer[remaining:] + datalen = len(data) + remaining -= datalen + + # Check lengths. + self.bytes_read += datalen + if self.maxbytes and self.bytes_read > self.maxbytes: + raise cherrypy.HTTPError(413) + + # Store the data. + if fp_out is None: + chunks.append(data) + else: + fp_out.write(data) + + # Read bytes from the socket. + while remaining > 0: + chunksize = min(remaining, self.bufsize) + try: + data = self.fp.read(chunksize) + except Exception: + e = sys.exc_info()[1] + if e.__class__.__name__ == 'MaxSizeExceeded': + # Post data is too big + raise cherrypy.HTTPError( + 413, "Maximum request length: %r" % e.args[1]) + else: + raise + if not data: + self.finish() + break + datalen = len(data) + remaining -= datalen + + # Check lengths. + self.bytes_read += datalen + if self.maxbytes and self.bytes_read > self.maxbytes: + raise cherrypy.HTTPError(413) + + # Store the data. + if fp_out is None: + chunks.append(data) + else: + fp_out.write(data) + + if fp_out is None: + return ntob('').join(chunks) + + def readline(self, size=None): + """Read a line from the request body and return it.""" + chunks = [] + while size is None or size > 0: + chunksize = self.bufsize + if size is not None and size < self.bufsize: + chunksize = size + data = self.read(chunksize) + if not data: + break + pos = data.find(ntob('\n')) + 1 + if pos: + chunks.append(data[:pos]) + remainder = data[pos:] + self.buffer += remainder + self.bytes_read -= len(remainder) + break + else: + chunks.append(data) + return ntob('').join(chunks) + + def readlines(self, sizehint=None): + """Read lines from the request body and return them.""" + if self.length is not None: + if sizehint is None: + sizehint = self.length - self.bytes_read + else: + sizehint = min(sizehint, self.length - self.bytes_read) + + lines = [] + seen = 0 + while True: + line = self.readline() + if not line: + break + lines.append(line) + seen += len(line) + if seen >= sizehint: + break + return lines + + def finish(self): + self.done = True + if self.has_trailers and hasattr(self.fp, 'read_trailer_lines'): + self.trailers = {} + + try: + for line in self.fp.read_trailer_lines(): + if line[0] in ntob(' \t'): + # It's a continuation line. + v = line.strip() + else: + try: + k, v = line.split(ntob(":"), 1) + except ValueError: + raise ValueError("Illegal header line.") + k = k.strip().title() + v = v.strip() + + if k in comma_separated_headers: + existing = self.trailers.get(envname) + if existing: + v = ntob(", ").join((existing, v)) + self.trailers[k] = v + except Exception: + e = sys.exc_info()[1] + if e.__class__.__name__ == 'MaxSizeExceeded': + # Post data is too big + raise cherrypy.HTTPError( + 413, "Maximum request length: %r" % e.args[1]) + else: + raise + + +class RequestBody(Entity): + """The entity of the HTTP request.""" + + bufsize = 8 * 1024 + """The buffer size used when reading the socket.""" + + # Don't parse the request body at all if the client didn't provide + # a Content-Type header. See http://www.cherrypy.org/ticket/790 + default_content_type = '' + """This defines a default ``Content-Type`` to use if no Content-Type header + is given. The empty string is used for RequestBody, which results in the + request body not being read or parsed at all. This is by design; a missing + ``Content-Type`` header in the HTTP request entity is an error at best, + and a security hole at worst. For multipart parts, however, the MIME spec + declares that a part with no Content-Type defaults to "text/plain" + (see :class:`Part`). + """ + + maxbytes = None + """Raise ``MaxSizeExceeded`` if more bytes than this are read from the socket.""" + + def __init__(self, fp, headers, params=None, request_params=None): + Entity.__init__(self, fp, headers, params) + + # http://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.7.1 + # When no explicit charset parameter is provided by the + # sender, media subtypes of the "text" type are defined + # to have a default charset value of "ISO-8859-1" when + # received via HTTP. + if self.content_type.value.startswith('text/'): + for c in ('ISO-8859-1', 'iso-8859-1', 'Latin-1', 'latin-1'): + if c in self.attempt_charsets: + break + else: + self.attempt_charsets.append('ISO-8859-1') + + # Temporary fix while deprecating passing .parts as .params. + self.processors['multipart'] = _old_process_multipart + + if request_params is None: + request_params = {} + self.request_params = request_params + + def process(self): + """Process the request entity based on its Content-Type.""" + # "The presence of a message-body in a request is signaled by the + # inclusion of a Content-Length or Transfer-Encoding header field in + # the request's message-headers." + # It is possible to send a POST request with no body, for example; + # however, app developers are responsible in that case to set + # cherrypy.request.process_body to False so this method isn't called. + h = cherrypy.serving.request.headers + if 'Content-Length' not in h and 'Transfer-Encoding' not in h: + raise cherrypy.HTTPError(411) + + self.fp = SizedReader(self.fp, self.length, + self.maxbytes, bufsize=self.bufsize, + has_trailers='Trailer' in h) + super(RequestBody, self).process() + + # Body params should also be a part of the request_params + # add them in here. + request_params = self.request_params + for key, value in self.params.items(): + # Python 2 only: keyword arguments must be byte strings (type 'str'). + if isinstance(key, unicode): + key = key.encode('ISO-8859-1') + + if key in request_params: + if not isinstance(request_params[key], list): + request_params[key] = [request_params[key]] + request_params[key].append(value) + else: + request_params[key] = value diff --git a/cherrypy/_cprequest.py b/cherrypy/_cprequest.py new file mode 100644 index 00000000..ae5e8971 --- /dev/null +++ b/cherrypy/_cprequest.py @@ -0,0 +1,926 @@ + +import os +import sys +import time +import warnings + +import cherrypy +from cherrypy._cpcompat import basestring, copykeys, ntob, unicodestr +from cherrypy._cpcompat import SimpleCookie, CookieError +from cherrypy import _cpreqbody, _cpconfig +from cherrypy._cperror import format_exc, bare_error +from cherrypy.lib import httputil, file_generator + + +class Hook(object): + """A callback and its metadata: failsafe, priority, and kwargs.""" + + callback = None + """ + The bare callable that this Hook object is wrapping, which will + be called when the Hook is called.""" + + failsafe = False + """ + If True, the callback is guaranteed to run even if other callbacks + from the same call point raise exceptions.""" + + priority = 50 + """ + Defines the order of execution for a list of Hooks. Priority numbers + should be limited to the closed interval [0, 100], but values outside + this range are acceptable, as are fractional values.""" + + kwargs = {} + """ + A set of keyword arguments that will be passed to the + callable on each call.""" + + def __init__(self, callback, failsafe=None, priority=None, **kwargs): + self.callback = callback + + if failsafe is None: + failsafe = getattr(callback, "failsafe", False) + self.failsafe = failsafe + + if priority is None: + priority = getattr(callback, "priority", 50) + self.priority = priority + + self.kwargs = kwargs + + def __cmp__(self, other): + return cmp(self.priority, other.priority) + + def __call__(self): + """Run self.callback(**self.kwargs).""" + return self.callback(**self.kwargs) + + def __repr__(self): + cls = self.__class__ + return ("%s.%s(callback=%r, failsafe=%r, priority=%r, %s)" + % (cls.__module__, cls.__name__, self.callback, + self.failsafe, self.priority, + ", ".join(['%s=%r' % (k, v) + for k, v in self.kwargs.items()]))) + + +class HookMap(dict): + """A map of call points to lists of callbacks (Hook objects).""" + + def __new__(cls, points=None): + d = dict.__new__(cls) + for p in points or []: + d[p] = [] + return d + + def __init__(self, *a, **kw): + pass + + def attach(self, point, callback, failsafe=None, priority=None, **kwargs): + """Append a new Hook made from the supplied arguments.""" + self[point].append(Hook(callback, failsafe, priority, **kwargs)) + + def run(self, point): + """Execute all registered Hooks (callbacks) for the given point.""" + exc = None + hooks = self[point] + hooks.sort() + for hook in hooks: + # Some hooks are guaranteed to run even if others at + # the same hookpoint fail. We will still log the failure, + # but proceed on to the next hook. The only way + # to stop all processing from one of these hooks is + # to raise SystemExit and stop the whole server. + if exc is None or hook.failsafe: + try: + hook() + except (KeyboardInterrupt, SystemExit): + raise + except (cherrypy.HTTPError, cherrypy.HTTPRedirect, + cherrypy.InternalRedirect): + exc = sys.exc_info()[1] + except: + exc = sys.exc_info()[1] + cherrypy.log(traceback=True, severity=40) + if exc: + raise + + def __copy__(self): + newmap = self.__class__() + # We can't just use 'update' because we want copies of the + # mutable values (each is a list) as well. + for k, v in self.items(): + newmap[k] = v[:] + return newmap + copy = __copy__ + + def __repr__(self): + cls = self.__class__ + return "%s.%s(points=%r)" % (cls.__module__, cls.__name__, copykeys(self)) + + +# Config namespace handlers + +def hooks_namespace(k, v): + """Attach bare hooks declared in config.""" + # Use split again to allow multiple hooks for a single + # hookpoint per path (e.g. "hooks.before_handler.1"). + # Little-known fact you only get from reading source ;) + hookpoint = k.split(".", 1)[0] + if isinstance(v, basestring): + v = cherrypy.lib.attributes(v) + if not isinstance(v, Hook): + v = Hook(v) + cherrypy.serving.request.hooks[hookpoint].append(v) + +def request_namespace(k, v): + """Attach request attributes declared in config.""" + # Provides config entries to set request.body attrs (like attempt_charsets). + if k[:5] == 'body.': + setattr(cherrypy.serving.request.body, k[5:], v) + else: + setattr(cherrypy.serving.request, k, v) + +def response_namespace(k, v): + """Attach response attributes declared in config.""" + # Provides config entries to set default response headers + # http://cherrypy.org/ticket/889 + if k[:8] == 'headers.': + cherrypy.serving.response.headers[k.split('.', 1)[1]] = v + else: + setattr(cherrypy.serving.response, k, v) + +def error_page_namespace(k, v): + """Attach error pages declared in config.""" + if k != 'default': + k = int(k) + cherrypy.serving.request.error_page[k] = v + + +hookpoints = ['on_start_resource', 'before_request_body', + 'before_handler', 'before_finalize', + 'on_end_resource', 'on_end_request', + 'before_error_response', 'after_error_response'] + + +class Request(object): + """An HTTP request. + + This object represents the metadata of an HTTP request message; + that is, it contains attributes which describe the environment + in which the request URL, headers, and body were sent (if you + want tools to interpret the headers and body, those are elsewhere, + mostly in Tools). This 'metadata' consists of socket data, + transport characteristics, and the Request-Line. This object + also contains data regarding the configuration in effect for + the given URL, and the execution plan for generating a response. + """ + + prev = None + """ + The previous Request object (if any). This should be None + unless we are processing an InternalRedirect.""" + + # Conversation/connection attributes + local = httputil.Host("127.0.0.1", 80) + "An httputil.Host(ip, port, hostname) object for the server socket." + + remote = httputil.Host("127.0.0.1", 1111) + "An httputil.Host(ip, port, hostname) object for the client socket." + + scheme = "http" + """ + The protocol used between client and server. In most cases, + this will be either 'http' or 'https'.""" + + server_protocol = "HTTP/1.1" + """ + The HTTP version for which the HTTP server is at least + conditionally compliant.""" + + base = "" + """The (scheme://host) portion of the requested URL. + In some cases (e.g. when proxying via mod_rewrite), this may contain + path segments which cherrypy.url uses when constructing url's, but + which otherwise are ignored by CherryPy. Regardless, this value + MUST NOT end in a slash.""" + + # Request-Line attributes + request_line = "" + """ + The complete Request-Line received from the client. This is a + single string consisting of the request method, URI, and protocol + version (joined by spaces). Any final CRLF is removed.""" + + method = "GET" + """ + Indicates the HTTP method to be performed on the resource identified + by the Request-URI. Common methods include GET, HEAD, POST, PUT, and + DELETE. CherryPy allows any extension method; however, various HTTP + servers and gateways may restrict the set of allowable methods. + CherryPy applications SHOULD restrict the set (on a per-URI basis).""" + + query_string = "" + """ + The query component of the Request-URI, a string of information to be + interpreted by the resource. The query portion of a URI follows the + path component, and is separated by a '?'. For example, the URI + 'http://www.cherrypy.org/wiki?a=3&b=4' has the query component, + 'a=3&b=4'.""" + + query_string_encoding = 'utf8' + """ + The encoding expected for query string arguments after % HEX HEX decoding). + If a query string is provided that cannot be decoded with this encoding, + 404 is raised (since technically it's a different URI). If you want + arbitrary encodings to not error, set this to 'Latin-1'; you can then + encode back to bytes and re-decode to whatever encoding you like later. + """ + + protocol = (1, 1) + """The HTTP protocol version corresponding to the set + of features which should be allowed in the response. If BOTH + the client's request message AND the server's level of HTTP + compliance is HTTP/1.1, this attribute will be the tuple (1, 1). + If either is 1.0, this attribute will be the tuple (1, 0). + Lower HTTP protocol versions are not explicitly supported.""" + + params = {} + """ + A dict which combines query string (GET) and request entity (POST) + variables. This is populated in two stages: GET params are added + before the 'on_start_resource' hook, and POST params are added + between the 'before_request_body' and 'before_handler' hooks.""" + + # Message attributes + header_list = [] + """ + A list of the HTTP request headers as (name, value) tuples. + In general, you should use request.headers (a dict) instead.""" + + headers = httputil.HeaderMap() + """ + A dict-like object containing the request headers. Keys are header + names (in Title-Case format); however, you may get and set them in + a case-insensitive manner. That is, headers['Content-Type'] and + headers['content-type'] refer to the same value. Values are header + values (decoded according to :rfc:`2047` if necessary). See also: + httputil.HeaderMap, httputil.HeaderElement.""" + + cookie = SimpleCookie() + """See help(Cookie).""" + + rfile = None + """ + If the request included an entity (body), it will be available + as a stream in this attribute. However, the rfile will normally + be read for you between the 'before_request_body' hook and the + 'before_handler' hook, and the resulting string is placed into + either request.params or the request.body attribute. + + You may disable the automatic consumption of the rfile by setting + request.process_request_body to False, either in config for the desired + path, or in an 'on_start_resource' or 'before_request_body' hook. + + WARNING: In almost every case, you should not attempt to read from the + rfile stream after CherryPy's automatic mechanism has read it. If you + turn off the automatic parsing of rfile, you should read exactly the + number of bytes specified in request.headers['Content-Length']. + Ignoring either of these warnings may result in a hung request thread + or in corruption of the next (pipelined) request. + """ + + process_request_body = True + """ + If True, the rfile (if any) is automatically read and parsed, + and the result placed into request.params or request.body.""" + + methods_with_bodies = ("POST", "PUT") + """ + A sequence of HTTP methods for which CherryPy will automatically + attempt to read a body from the rfile.""" + + body = None + """ + If the request Content-Type is 'application/x-www-form-urlencoded' + or multipart, this will be None. Otherwise, this will be an instance + of :class:`RequestBody` (which you + can .read()); this value is set between the 'before_request_body' and + 'before_handler' hooks (assuming that process_request_body is True).""" + + # Dispatch attributes + dispatch = cherrypy.dispatch.Dispatcher() + """ + The object which looks up the 'page handler' callable and collects + config for the current request based on the path_info, other + request attributes, and the application architecture. The core + calls the dispatcher as early as possible, passing it a 'path_info' + argument. + + The default dispatcher discovers the page handler by matching path_info + to a hierarchical arrangement of objects, starting at request.app.root. + See help(cherrypy.dispatch) for more information.""" + + script_name = "" + """ + The 'mount point' of the application which is handling this request. + + This attribute MUST NOT end in a slash. If the script_name refers to + the root of the URI, it MUST be an empty string (not "/"). + """ + + path_info = "/" + """ + The 'relative path' portion of the Request-URI. This is relative + to the script_name ('mount point') of the application which is + handling this request.""" + + login = None + """ + When authentication is used during the request processing this is + set to 'False' if it failed and to the 'username' value if it succeeded. + The default 'None' implies that no authentication happened.""" + + # Note that cherrypy.url uses "if request.app:" to determine whether + # the call is during a real HTTP request or not. So leave this None. + app = None + """The cherrypy.Application object which is handling this request.""" + + handler = None + """ + The function, method, or other callable which CherryPy will call to + produce the response. The discovery of the handler and the arguments + it will receive are determined by the request.dispatch object. + By default, the handler is discovered by walking a tree of objects + starting at request.app.root, and is then passed all HTTP params + (from the query string and POST body) as keyword arguments.""" + + toolmaps = {} + """ + A nested dict of all Toolboxes and Tools in effect for this request, + of the form: {Toolbox.namespace: {Tool.name: config dict}}.""" + + config = None + """ + A flat dict of all configuration entries which apply to the + current request. These entries are collected from global config, + application config (based on request.path_info), and from handler + config (exactly how is governed by the request.dispatch object in + effect for this request; by default, handler config can be attached + anywhere in the tree between request.app.root and the final handler, + and inherits downward).""" + + is_index = None + """ + This will be True if the current request is mapped to an 'index' + resource handler (also, a 'default' handler if path_info ends with + a slash). The value may be used to automatically redirect the + user-agent to a 'more canonical' URL which either adds or removes + the trailing slash. See cherrypy.tools.trailing_slash.""" + + hooks = HookMap(hookpoints) + """ + A HookMap (dict-like object) of the form: {hookpoint: [hook, ...]}. + Each key is a str naming the hook point, and each value is a list + of hooks which will be called at that hook point during this request. + The list of hooks is generally populated as early as possible (mostly + from Tools specified in config), but may be extended at any time. + See also: _cprequest.Hook, _cprequest.HookMap, and cherrypy.tools.""" + + error_response = cherrypy.HTTPError(500).set_response + """ + The no-arg callable which will handle unexpected, untrapped errors + during request processing. This is not used for expected exceptions + (like NotFound, HTTPError, or HTTPRedirect) which are raised in + response to expected conditions (those should be customized either + via request.error_page or by overriding HTTPError.set_response). + By default, error_response uses HTTPError(500) to return a generic + error response to the user-agent.""" + + error_page = {} + """ + A dict of {error code: response filename or callable} pairs. + + The error code must be an int representing a given HTTP error code, + or the string 'default', which will be used if no matching entry + is found for a given numeric code. + + If a filename is provided, the file should contain a Python string- + formatting template, and can expect by default to receive format + values with the mapping keys %(status)s, %(message)s, %(traceback)s, + and %(version)s. The set of format mappings can be extended by + overriding HTTPError.set_response. + + If a callable is provided, it will be called by default with keyword + arguments 'status', 'message', 'traceback', and 'version', as for a + string-formatting template. The callable must return a string or iterable of + strings which will be set to response.body. It may also override headers or + perform any other processing. + + If no entry is given for an error code, and no 'default' entry exists, + a default template will be used. + """ + + show_tracebacks = True + """ + If True, unexpected errors encountered during request processing will + include a traceback in the response body.""" + + show_mismatched_params = True + """ + If True, mismatched parameters encountered during PageHandler invocation + processing will be included in the response body.""" + + throws = (KeyboardInterrupt, SystemExit, cherrypy.InternalRedirect) + """The sequence of exceptions which Request.run does not trap.""" + + throw_errors = False + """ + If True, Request.run will not trap any errors (except HTTPRedirect and + HTTPError, which are more properly called 'exceptions', not errors).""" + + closed = False + """True once the close method has been called, False otherwise.""" + + stage = None + """ + A string containing the stage reached in the request-handling process. + This is useful when debugging a live server with hung requests.""" + + namespaces = _cpconfig.NamespaceSet( + **{"hooks": hooks_namespace, + "request": request_namespace, + "response": response_namespace, + "error_page": error_page_namespace, + "tools": cherrypy.tools, + }) + + def __init__(self, local_host, remote_host, scheme="http", + server_protocol="HTTP/1.1"): + """Populate a new Request object. + + local_host should be an httputil.Host object with the server info. + remote_host should be an httputil.Host object with the client info. + scheme should be a string, either "http" or "https". + """ + self.local = local_host + self.remote = remote_host + self.scheme = scheme + self.server_protocol = server_protocol + + self.closed = False + + # Put a *copy* of the class error_page into self. + self.error_page = self.error_page.copy() + + # Put a *copy* of the class namespaces into self. + self.namespaces = self.namespaces.copy() + + self.stage = None + + def close(self): + """Run cleanup code. (Core)""" + if not self.closed: + self.closed = True + self.stage = 'on_end_request' + self.hooks.run('on_end_request') + self.stage = 'close' + + def run(self, method, path, query_string, req_protocol, headers, rfile): + """Process the Request. (Core) + + method, path, query_string, and req_protocol should be pulled directly + from the Request-Line (e.g. "GET /path?key=val HTTP/1.0"). + + path + This should be %XX-unquoted, but query_string should not be. + They both MUST be byte strings, not unicode strings. + + headers + A list of (name, value) tuples. + + rfile + A file-like object containing the HTTP request entity. + + When run() is done, the returned object should have 3 attributes: + + * status, e.g. "200 OK" + * header_list, a list of (name, value) tuples + * body, an iterable yielding strings + + Consumer code (HTTP servers) should then access these response + attributes to build the outbound stream. + + """ + response = cherrypy.serving.response + self.stage = 'run' + try: + self.error_response = cherrypy.HTTPError(500).set_response + + self.method = method + path = path or "/" + self.query_string = query_string or '' + self.params = {} + + # Compare request and server HTTP protocol versions, in case our + # server does not support the requested protocol. Limit our output + # to min(req, server). We want the following output: + # request server actual written supported response + # protocol protocol response protocol feature set + # a 1.0 1.0 1.0 1.0 + # b 1.0 1.1 1.1 1.0 + # c 1.1 1.0 1.0 1.0 + # d 1.1 1.1 1.1 1.1 + # Notice that, in (b), the response will be "HTTP/1.1" even though + # the client only understands 1.0. RFC 2616 10.5.6 says we should + # only return 505 if the _major_ version is different. + rp = int(req_protocol[5]), int(req_protocol[7]) + sp = int(self.server_protocol[5]), int(self.server_protocol[7]) + self.protocol = min(rp, sp) + response.headers.protocol = self.protocol + + # Rebuild first line of the request (e.g. "GET /path HTTP/1.0"). + url = path + if query_string: + url += '?' + query_string + self.request_line = '%s %s %s' % (method, url, req_protocol) + + self.header_list = list(headers) + self.headers = httputil.HeaderMap() + + self.rfile = rfile + self.body = None + + self.cookie = SimpleCookie() + self.handler = None + + # path_info should be the path from the + # app root (script_name) to the handler. + self.script_name = self.app.script_name + self.path_info = pi = path[len(self.script_name):] + + self.stage = 'respond' + self.respond(pi) + + except self.throws: + raise + except: + if self.throw_errors: + raise + else: + # Failure in setup, error handler or finalize. Bypass them. + # Can't use handle_error because we may not have hooks yet. + cherrypy.log(traceback=True, severity=40) + if self.show_tracebacks: + body = format_exc() + else: + body = "" + r = bare_error(body) + response.output_status, response.header_list, response.body = r + + if self.method == "HEAD": + # HEAD requests MUST NOT return a message-body in the response. + response.body = [] + + try: + cherrypy.log.access() + except: + cherrypy.log.error(traceback=True) + + if response.timed_out: + raise cherrypy.TimeoutError() + + return response + + # Uncomment for stage debugging + # stage = property(lambda self: self._stage, lambda self, v: print(v)) + + def respond(self, path_info): + """Generate a response for the resource at self.path_info. (Core)""" + response = cherrypy.serving.response + try: + try: + try: + if self.app is None: + raise cherrypy.NotFound() + + # Get the 'Host' header, so we can HTTPRedirect properly. + self.stage = 'process_headers' + self.process_headers() + + # Make a copy of the class hooks + self.hooks = self.__class__.hooks.copy() + self.toolmaps = {} + + self.stage = 'get_resource' + self.get_resource(path_info) + + self.body = _cpreqbody.RequestBody( + self.rfile, self.headers, request_params=self.params) + + self.namespaces(self.config) + + self.stage = 'on_start_resource' + self.hooks.run('on_start_resource') + + # Parse the querystring + self.stage = 'process_query_string' + self.process_query_string() + + # Process the body + if self.process_request_body: + if self.method not in self.methods_with_bodies: + self.process_request_body = False + self.stage = 'before_request_body' + self.hooks.run('before_request_body') + if self.process_request_body: + self.body.process() + + # Run the handler + self.stage = 'before_handler' + self.hooks.run('before_handler') + if self.handler: + self.stage = 'handler' + response.body = self.handler() + + # Finalize + self.stage = 'before_finalize' + self.hooks.run('before_finalize') + response.finalize() + except (cherrypy.HTTPRedirect, cherrypy.HTTPError): + inst = sys.exc_info()[1] + inst.set_response() + self.stage = 'before_finalize (HTTPError)' + self.hooks.run('before_finalize') + response.finalize() + finally: + self.stage = 'on_end_resource' + self.hooks.run('on_end_resource') + except self.throws: + raise + except: + if self.throw_errors: + raise + self.handle_error() + + def process_query_string(self): + """Parse the query string into Python structures. (Core)""" + try: + p = httputil.parse_query_string( + self.query_string, encoding=self.query_string_encoding) + except UnicodeDecodeError: + raise cherrypy.HTTPError( + 404, "The given query string could not be processed. Query " + "strings for this resource must be encoded with %r." % + self.query_string_encoding) + + # Python 2 only: keyword arguments must be byte strings (type 'str'). + for key, value in p.items(): + if isinstance(key, unicode): + del p[key] + p[key.encode(self.query_string_encoding)] = value + self.params.update(p) + + def process_headers(self): + """Parse HTTP header data into Python structures. (Core)""" + # Process the headers into self.headers + headers = self.headers + for name, value in self.header_list: + # Call title() now (and use dict.__method__(headers)) + # so title doesn't have to be called twice. + name = name.title() + value = value.strip() + + # Warning: if there is more than one header entry for cookies (AFAIK, + # only Konqueror does that), only the last one will remain in headers + # (but they will be correctly stored in request.cookie). + if "=?" in value: + dict.__setitem__(headers, name, httputil.decode_TEXT(value)) + else: + dict.__setitem__(headers, name, value) + + # Handle cookies differently because on Konqueror, multiple + # cookies come on different lines with the same key + if name == 'Cookie': + try: + self.cookie.load(value) + except CookieError: + msg = "Illegal cookie name %s" % value.split('=')[0] + raise cherrypy.HTTPError(400, msg) + + if not dict.__contains__(headers, 'Host'): + # All Internet-based HTTP/1.1 servers MUST respond with a 400 + # (Bad Request) status code to any HTTP/1.1 request message + # which lacks a Host header field. + if self.protocol >= (1, 1): + msg = "HTTP/1.1 requires a 'Host' request header." + raise cherrypy.HTTPError(400, msg) + host = dict.get(headers, 'Host') + if not host: + host = self.local.name or self.local.ip + self.base = "%s://%s" % (self.scheme, host) + + def get_resource(self, path): + """Call a dispatcher (which sets self.handler and .config). (Core)""" + # First, see if there is a custom dispatch at this URI. Custom + # dispatchers can only be specified in app.config, not in _cp_config + # (since custom dispatchers may not even have an app.root). + dispatch = self.app.find_config(path, "request.dispatch", self.dispatch) + + # dispatch() should set self.handler and self.config + dispatch(path) + + def handle_error(self): + """Handle the last unanticipated exception. (Core)""" + try: + self.hooks.run("before_error_response") + if self.error_response: + self.error_response() + self.hooks.run("after_error_response") + cherrypy.serving.response.finalize() + except cherrypy.HTTPRedirect: + inst = sys.exc_info()[1] + inst.set_response() + cherrypy.serving.response.finalize() + + # ------------------------- Properties ------------------------- # + + def _get_body_params(self): + warnings.warn( + "body_params is deprecated in CherryPy 3.2, will be removed in " + "CherryPy 3.3.", + DeprecationWarning + ) + return self.body.params + body_params = property(_get_body_params, + doc= """ + If the request Content-Type is 'application/x-www-form-urlencoded' or + multipart, this will be a dict of the params pulled from the entity + body; that is, it will be the portion of request.params that come + from the message body (sometimes called "POST params", although they + can be sent with various HTTP method verbs). This value is set between + the 'before_request_body' and 'before_handler' hooks (assuming that + process_request_body is True). + + Deprecated in 3.2, will be removed for 3.3 in favor of + :attr:`request.body.params`.""") + + +class ResponseBody(object): + """The body of the HTTP response (the response entity).""" + + def __get__(self, obj, objclass=None): + if obj is None: + # When calling on the class instead of an instance... + return self + else: + return obj._body + + def __set__(self, obj, value): + # Convert the given value to an iterable object. + if isinstance(value, basestring): + # strings get wrapped in a list because iterating over a single + # item list is much faster than iterating over every character + # in a long string. + if value: + value = [value] + else: + # [''] doesn't evaluate to False, so replace it with []. + value = [] + # Don't use isinstance here; io.IOBase which has an ABC takes + # 1000 times as long as, say, isinstance(value, str) + elif hasattr(value, 'read'): + value = file_generator(value) + elif value is None: + value = [] + obj._body = value + + +class Response(object): + """An HTTP Response, including status, headers, and body.""" + + status = "" + """The HTTP Status-Code and Reason-Phrase.""" + + header_list = [] + """ + A list of the HTTP response headers as (name, value) tuples. + In general, you should use response.headers (a dict) instead. This + attribute is generated from response.headers and is not valid until + after the finalize phase.""" + + headers = httputil.HeaderMap() + """ + A dict-like object containing the response headers. Keys are header + names (in Title-Case format); however, you may get and set them in + a case-insensitive manner. That is, headers['Content-Type'] and + headers['content-type'] refer to the same value. Values are header + values (decoded according to :rfc:`2047` if necessary). + + .. seealso:: classes :class:`HeaderMap`, :class:`HeaderElement` + """ + + cookie = SimpleCookie() + """See help(Cookie).""" + + body = ResponseBody() + """The body (entity) of the HTTP response.""" + + time = None + """The value of time.time() when created. Use in HTTP dates.""" + + timeout = 300 + """Seconds after which the response will be aborted.""" + + timed_out = False + """ + Flag to indicate the response should be aborted, because it has + exceeded its timeout.""" + + stream = False + """If False, buffer the response body.""" + + def __init__(self): + self.status = None + self.header_list = None + self._body = [] + self.time = time.time() + + self.headers = httputil.HeaderMap() + # Since we know all our keys are titled strings, we can + # bypass HeaderMap.update and get a big speed boost. + dict.update(self.headers, { + "Content-Type": 'text/html', + "Server": "CherryPy/" + cherrypy.__version__, + "Date": httputil.HTTPDate(self.time), + }) + self.cookie = SimpleCookie() + + def collapse_body(self): + """Collapse self.body to a single string; replace it and return it.""" + if isinstance(self.body, basestring): + return self.body + + newbody = ''.join([chunk for chunk in self.body]) + + self.body = newbody + return newbody + + def finalize(self): + """Transform headers (and cookies) into self.header_list. (Core)""" + try: + code, reason, _ = httputil.valid_status(self.status) + except ValueError: + raise cherrypy.HTTPError(500, sys.exc_info()[1].args[0]) + + headers = self.headers + + self.output_status = ntob(str(code), 'ascii') + ntob(" ") + headers.encode(reason) + + if self.stream: + # The upshot: wsgiserver will chunk the response if + # you pop Content-Length (or set it explicitly to None). + # Note that lib.static sets C-L to the file's st_size. + if dict.get(headers, 'Content-Length') is None: + dict.pop(headers, 'Content-Length', None) + elif code < 200 or code in (204, 205, 304): + # "All 1xx (informational), 204 (no content), + # and 304 (not modified) responses MUST NOT + # include a message-body." + dict.pop(headers, 'Content-Length', None) + self.body = ntob("") + else: + # Responses which are not streamed should have a Content-Length, + # but allow user code to set Content-Length if desired. + if dict.get(headers, 'Content-Length') is None: + content = self.collapse_body() + dict.__setitem__(headers, 'Content-Length', len(content)) + + # Transform our header dict into a list of tuples. + self.header_list = h = headers.output() + + cookie = self.cookie.output() + if cookie: + for line in cookie.split("\n"): + if line.endswith("\r"): + # Python 2.4 emits cookies joined by LF but 2.5+ by CRLF. + line = line[:-1] + name, value = line.split(": ", 1) + if isinstance(name, unicodestr): + name = name.encode("ISO-8859-1") + if isinstance(value, unicodestr): + value = headers.encode(value) + h.append((name, value)) + + def check_timeout(self): + """If now > self.time + self.timeout, set self.timed_out. + + This purposefully sets a flag, rather than raising an error, + so that a monitor thread can interrupt the Response thread. + """ + if time.time() > self.time + self.timeout: + self.timed_out = True + + + diff --git a/cherrypy/_cpserver.py b/cherrypy/_cpserver.py new file mode 100644 index 00000000..c1695a66 --- /dev/null +++ b/cherrypy/_cpserver.py @@ -0,0 +1,195 @@ +"""Manage HTTP servers with CherryPy.""" + +import warnings + +import cherrypy +from cherrypy.lib import attributes +from cherrypy._cpcompat import basestring + +# We import * because we want to export check_port +# et al as attributes of this module. +from cherrypy.process.servers import * + + +class Server(ServerAdapter): + """An adapter for an HTTP server. + + You can set attributes (like socket_host and socket_port) + on *this* object (which is probably cherrypy.server), and call + quickstart. For example:: + + cherrypy.server.socket_port = 80 + cherrypy.quickstart() + """ + + socket_port = 8080 + """The TCP port on which to listen for connections.""" + + _socket_host = '127.0.0.1' + def _get_socket_host(self): + return self._socket_host + def _set_socket_host(self, value): + if value == '': + raise ValueError("The empty string ('') is not an allowed value. " + "Use '0.0.0.0' instead to listen on all active " + "interfaces (INADDR_ANY).") + self._socket_host = value + socket_host = property(_get_socket_host, _set_socket_host, + doc="""The hostname or IP address on which to listen for connections. + + Host values may be any IPv4 or IPv6 address, or any valid hostname. + The string 'localhost' is a synonym for '127.0.0.1' (or '::1', if + your hosts file prefers IPv6). The string '0.0.0.0' is a special + IPv4 entry meaning "any active interface" (INADDR_ANY), and '::' + is the similar IN6ADDR_ANY for IPv6. The empty string or None are + not allowed.""") + + socket_file = None + """If given, the name of the UNIX socket to use instead of TCP/IP. + + When this option is not None, the `socket_host` and `socket_port` options + are ignored.""" + + socket_queue_size = 5 + """The 'backlog' argument to socket.listen(); specifies the maximum number + of queued connections (default 5).""" + + socket_timeout = 10 + """The timeout in seconds for accepted connections (default 10).""" + + shutdown_timeout = 5 + """The time to wait for HTTP worker threads to clean up.""" + + protocol_version = 'HTTP/1.1' + """The version string to write in the Status-Line of all HTTP responses, + for example, "HTTP/1.1" (the default). Depending on the HTTP server used, + this should also limit the supported features used in the response.""" + + thread_pool = 10 + """The number of worker threads to start up in the pool.""" + + thread_pool_max = -1 + """The maximum size of the worker-thread pool. Use -1 to indicate no limit.""" + + max_request_header_size = 500 * 1024 + """The maximum number of bytes allowable in the request headers. If exceeded, + the HTTP server should return "413 Request Entity Too Large".""" + + max_request_body_size = 100 * 1024 * 1024 + """The maximum number of bytes allowable in the request body. If exceeded, + the HTTP server should return "413 Request Entity Too Large".""" + + instance = None + """If not None, this should be an HTTP server instance (such as + CPWSGIServer) which cherrypy.server will control. Use this when you need + more control over object instantiation than is available in the various + configuration options.""" + + ssl_context = None + """When using PyOpenSSL, an instance of SSL.Context.""" + + ssl_certificate = None + """The filename of the SSL certificate to use.""" + + ssl_certificate_chain = None + """When using PyOpenSSL, the certificate chain to pass to + Context.load_verify_locations.""" + + ssl_private_key = None + """The filename of the private key to use with SSL.""" + + ssl_module = 'pyopenssl' + """The name of a registered SSL adaptation module to use with the builtin + WSGI server. Builtin options are 'builtin' (to use the SSL library built + into recent versions of Python) and 'pyopenssl' (to use the PyOpenSSL + project, which you must install separately). You may also register your + own classes in the wsgiserver.ssl_adapters dict.""" + + nodelay = True + """If True (the default since 3.1), sets the TCP_NODELAY socket option.""" + + wsgi_version = (1, 0) + """The WSGI version tuple to use with the builtin WSGI server. + The provided options are (1, 0) [which includes support for PEP 3333, + which declares it covers WSGI version 1.0.1 but still mandates the + wsgi.version (1, 0)] and ('u', 0), an experimental unicode version. + You may create and register your own experimental versions of the WSGI + protocol by adding custom classes to the wsgiserver.wsgi_gateways dict.""" + + def __init__(self): + self.bus = cherrypy.engine + self.httpserver = None + self.interrupt = None + self.running = False + + def httpserver_from_self(self, httpserver=None): + """Return a (httpserver, bind_addr) pair based on self attributes.""" + if httpserver is None: + httpserver = self.instance + if httpserver is None: + from cherrypy import _cpwsgi_server + httpserver = _cpwsgi_server.CPWSGIServer(self) + if isinstance(httpserver, basestring): + # Is anyone using this? Can I add an arg? + httpserver = attributes(httpserver)(self) + return httpserver, self.bind_addr + + def start(self): + """Start the HTTP server.""" + if not self.httpserver: + self.httpserver, self.bind_addr = self.httpserver_from_self() + ServerAdapter.start(self) + start.priority = 75 + + def _get_bind_addr(self): + if self.socket_file: + return self.socket_file + if self.socket_host is None and self.socket_port is None: + return None + return (self.socket_host, self.socket_port) + def _set_bind_addr(self, value): + if value is None: + self.socket_file = None + self.socket_host = None + self.socket_port = None + elif isinstance(value, basestring): + self.socket_file = value + self.socket_host = None + self.socket_port = None + else: + try: + self.socket_host, self.socket_port = value + self.socket_file = None + except ValueError: + raise ValueError("bind_addr must be a (host, port) tuple " + "(for TCP sockets) or a string (for Unix " + "domain sockets), not %r" % value) + bind_addr = property(_get_bind_addr, _set_bind_addr, + doc='A (host, port) tuple for TCP sockets or a str for Unix domain sockets.') + + def base(self): + """Return the base (scheme://host[:port] or sock file) for this server.""" + if self.socket_file: + return self.socket_file + + host = self.socket_host + if host in ('0.0.0.0', '::'): + # 0.0.0.0 is INADDR_ANY and :: is IN6ADDR_ANY. + # Look up the host name, which should be the + # safest thing to spit out in a URL. + import socket + host = socket.gethostname() + + port = self.socket_port + + if self.ssl_certificate: + scheme = "https" + if port != 443: + host += ":%s" % port + else: + scheme = "http" + if port != 80: + host += ":%s" % port + + return "%s://%s" % (scheme, host) + diff --git a/cherrypy/_cpthreadinglocal.py b/cherrypy/_cpthreadinglocal.py new file mode 100644 index 00000000..34c17ac4 --- /dev/null +++ b/cherrypy/_cpthreadinglocal.py @@ -0,0 +1,239 @@ +# This is a backport of Python-2.4's threading.local() implementation + +"""Thread-local objects + +(Note that this module provides a Python version of thread + threading.local class. Depending on the version of Python you're + using, there may be a faster one available. You should always import + the local class from threading.) + +Thread-local objects support the management of thread-local data. +If you have data that you want to be local to a thread, simply create +a thread-local object and use its attributes: + + >>> mydata = local() + >>> mydata.number = 42 + >>> mydata.number + 42 + +You can also access the local-object's dictionary: + + >>> mydata.__dict__ + {'number': 42} + >>> mydata.__dict__.setdefault('widgets', []) + [] + >>> mydata.widgets + [] + +What's important about thread-local objects is that their data are +local to a thread. If we access the data in a different thread: + + >>> log = [] + >>> def f(): + ... items = mydata.__dict__.items() + ... items.sort() + ... log.append(items) + ... mydata.number = 11 + ... log.append(mydata.number) + + >>> import threading + >>> thread = threading.Thread(target=f) + >>> thread.start() + >>> thread.join() + >>> log + [[], 11] + +we get different data. Furthermore, changes made in the other thread +don't affect data seen in this thread: + + >>> mydata.number + 42 + +Of course, values you get from a local object, including a __dict__ +attribute, are for whatever thread was current at the time the +attribute was read. For that reason, you generally don't want to save +these values across threads, as they apply only to the thread they +came from. + +You can create custom local objects by subclassing the local class: + + >>> class MyLocal(local): + ... number = 2 + ... initialized = False + ... def __init__(self, **kw): + ... if self.initialized: + ... raise SystemError('__init__ called too many times') + ... self.initialized = True + ... self.__dict__.update(kw) + ... def squared(self): + ... return self.number ** 2 + +This can be useful to support default values, methods and +initialization. Note that if you define an __init__ method, it will be +called each time the local object is used in a separate thread. This +is necessary to initialize each thread's dictionary. + +Now if we create a local object: + + >>> mydata = MyLocal(color='red') + +Now we have a default number: + + >>> mydata.number + 2 + +an initial color: + + >>> mydata.color + 'red' + >>> del mydata.color + +And a method that operates on the data: + + >>> mydata.squared() + 4 + +As before, we can access the data in a separate thread: + + >>> log = [] + >>> thread = threading.Thread(target=f) + >>> thread.start() + >>> thread.join() + >>> log + [[('color', 'red'), ('initialized', True)], 11] + +without affecting this thread's data: + + >>> mydata.number + 2 + >>> mydata.color + Traceback (most recent call last): + ... + AttributeError: 'MyLocal' object has no attribute 'color' + +Note that subclasses can define slots, but they are not thread +local. They are shared across threads: + + >>> class MyLocal(local): + ... __slots__ = 'number' + + >>> mydata = MyLocal() + >>> mydata.number = 42 + >>> mydata.color = 'red' + +So, the separate thread: + + >>> thread = threading.Thread(target=f) + >>> thread.start() + >>> thread.join() + +affects what we see: + + >>> mydata.number + 11 + +>>> del mydata +""" + +# Threading import is at end + +class _localbase(object): + __slots__ = '_local__key', '_local__args', '_local__lock' + + def __new__(cls, *args, **kw): + self = object.__new__(cls) + key = 'thread.local.' + str(id(self)) + object.__setattr__(self, '_local__key', key) + object.__setattr__(self, '_local__args', (args, kw)) + object.__setattr__(self, '_local__lock', RLock()) + + if args or kw and (cls.__init__ is object.__init__): + raise TypeError("Initialization arguments are not supported") + + # We need to create the thread dict in anticipation of + # __init__ being called, to make sure we don't call it + # again ourselves. + dict = object.__getattribute__(self, '__dict__') + currentThread().__dict__[key] = dict + + return self + +def _patch(self): + key = object.__getattribute__(self, '_local__key') + d = currentThread().__dict__.get(key) + if d is None: + d = {} + currentThread().__dict__[key] = d + object.__setattr__(self, '__dict__', d) + + # we have a new instance dict, so call out __init__ if we have + # one + cls = type(self) + if cls.__init__ is not object.__init__: + args, kw = object.__getattribute__(self, '_local__args') + cls.__init__(self, *args, **kw) + else: + object.__setattr__(self, '__dict__', d) + +class local(_localbase): + + def __getattribute__(self, name): + lock = object.__getattribute__(self, '_local__lock') + lock.acquire() + try: + _patch(self) + return object.__getattribute__(self, name) + finally: + lock.release() + + def __setattr__(self, name, value): + lock = object.__getattribute__(self, '_local__lock') + lock.acquire() + try: + _patch(self) + return object.__setattr__(self, name, value) + finally: + lock.release() + + def __delattr__(self, name): + lock = object.__getattribute__(self, '_local__lock') + lock.acquire() + try: + _patch(self) + return object.__delattr__(self, name) + finally: + lock.release() + + + def __del__(): + threading_enumerate = enumerate + __getattribute__ = object.__getattribute__ + + def __del__(self): + key = __getattribute__(self, '_local__key') + + try: + threads = list(threading_enumerate()) + except: + # if enumerate fails, as it seems to do during + # shutdown, we'll skip cleanup under the assumption + # that there is nothing to clean up + return + + for thread in threads: + try: + __dict__ = thread.__dict__ + except AttributeError: + # Thread is dying, rest in peace + continue + + if key in __dict__: + try: + del __dict__[key] + except KeyError: + pass # didn't have anything in this thread + + return __del__ + __del__ = __del__() + +from threading import currentThread, enumerate, RLock diff --git a/cherrypy/_cptools.py b/cherrypy/_cptools.py new file mode 100644 index 00000000..d3eab059 --- /dev/null +++ b/cherrypy/_cptools.py @@ -0,0 +1,510 @@ +"""CherryPy tools. A "tool" is any helper, adapted to CP. + +Tools are usually designed to be used in a variety of ways (although some +may only offer one if they choose): + + Library calls + All tools are callables that can be used wherever needed. + The arguments are straightforward and should be detailed within the + docstring. + + Function decorators + All tools, when called, may be used as decorators which configure + individual CherryPy page handlers (methods on the CherryPy tree). + That is, "@tools.anytool()" should "turn on" the tool via the + decorated function's _cp_config attribute. + + CherryPy config + If a tool exposes a "_setup" callable, it will be called + once per Request (if the feature is "turned on" via config). + +Tools may be implemented as any object with a namespace. The builtins +are generally either modules or instances of the tools.Tool class. +""" + +import sys +import warnings + +import cherrypy + + +def _getargs(func): + """Return the names of all static arguments to the given function.""" + # Use this instead of importing inspect for less mem overhead. + import types + if sys.version_info >= (3, 0): + if isinstance(func, types.MethodType): + func = func.__func__ + co = func.__code__ + else: + if isinstance(func, types.MethodType): + func = func.im_func + co = func.func_code + return co.co_varnames[:co.co_argcount] + + +_attr_error = ("CherryPy Tools cannot be turned on directly. Instead, turn them " + "on via config, or use them as decorators on your page handlers.") + +class Tool(object): + """A registered function for use with CherryPy request-processing hooks. + + help(tool.callable) should give you more information about this Tool. + """ + + namespace = "tools" + + def __init__(self, point, callable, name=None, priority=50): + self._point = point + self.callable = callable + self._name = name + self._priority = priority + self.__doc__ = self.callable.__doc__ + self._setargs() + + def _get_on(self): + raise AttributeError(_attr_error) + def _set_on(self, value): + raise AttributeError(_attr_error) + on = property(_get_on, _set_on) + + def _setargs(self): + """Copy func parameter names to obj attributes.""" + try: + for arg in _getargs(self.callable): + setattr(self, arg, None) + except (TypeError, AttributeError): + if hasattr(self.callable, "__call__"): + for arg in _getargs(self.callable.__call__): + setattr(self, arg, None) + # IronPython 1.0 raises NotImplementedError because + # inspect.getargspec tries to access Python bytecode + # in co_code attribute. + except NotImplementedError: + pass + # IronPython 1B1 may raise IndexError in some cases, + # but if we trap it here it doesn't prevent CP from working. + except IndexError: + pass + + def _merged_args(self, d=None): + """Return a dict of configuration entries for this Tool.""" + if d: + conf = d.copy() + else: + conf = {} + + tm = cherrypy.serving.request.toolmaps[self.namespace] + if self._name in tm: + conf.update(tm[self._name]) + + if "on" in conf: + del conf["on"] + + return conf + + def __call__(self, *args, **kwargs): + """Compile-time decorator (turn on the tool in config). + + For example:: + + @tools.proxy() + def whats_my_base(self): + return cherrypy.request.base + whats_my_base.exposed = True + """ + if args: + raise TypeError("The %r Tool does not accept positional " + "arguments; you must use keyword arguments." + % self._name) + def tool_decorator(f): + if not hasattr(f, "_cp_config"): + f._cp_config = {} + subspace = self.namespace + "." + self._name + "." + f._cp_config[subspace + "on"] = True + for k, v in kwargs.items(): + f._cp_config[subspace + k] = v + return f + return tool_decorator + + def _setup(self): + """Hook this tool into cherrypy.request. + + The standard CherryPy request object will automatically call this + method when the tool is "turned on" in config. + """ + conf = self._merged_args() + p = conf.pop("priority", None) + if p is None: + p = getattr(self.callable, "priority", self._priority) + cherrypy.serving.request.hooks.attach(self._point, self.callable, + priority=p, **conf) + + +class HandlerTool(Tool): + """Tool which is called 'before main', that may skip normal handlers. + + If the tool successfully handles the request (by setting response.body), + if should return True. This will cause CherryPy to skip any 'normal' page + handler. If the tool did not handle the request, it should return False + to tell CherryPy to continue on and call the normal page handler. If the + tool is declared AS a page handler (see the 'handler' method), returning + False will raise NotFound. + """ + + def __init__(self, callable, name=None): + Tool.__init__(self, 'before_handler', callable, name) + + def handler(self, *args, **kwargs): + """Use this tool as a CherryPy page handler. + + For example:: + + class Root: + nav = tools.staticdir.handler(section="/nav", dir="nav", + root=absDir) + """ + def handle_func(*a, **kw): + handled = self.callable(*args, **self._merged_args(kwargs)) + if not handled: + raise cherrypy.NotFound() + return cherrypy.serving.response.body + handle_func.exposed = True + return handle_func + + def _wrapper(self, **kwargs): + if self.callable(**kwargs): + cherrypy.serving.request.handler = None + + def _setup(self): + """Hook this tool into cherrypy.request. + + The standard CherryPy request object will automatically call this + method when the tool is "turned on" in config. + """ + conf = self._merged_args() + p = conf.pop("priority", None) + if p is None: + p = getattr(self.callable, "priority", self._priority) + cherrypy.serving.request.hooks.attach(self._point, self._wrapper, + priority=p, **conf) + + +class HandlerWrapperTool(Tool): + """Tool which wraps request.handler in a provided wrapper function. + + The 'newhandler' arg must be a handler wrapper function that takes a + 'next_handler' argument, plus ``*args`` and ``**kwargs``. Like all + page handler + functions, it must return an iterable for use as cherrypy.response.body. + + For example, to allow your 'inner' page handlers to return dicts + which then get interpolated into a template:: + + def interpolator(next_handler, *args, **kwargs): + filename = cherrypy.request.config.get('template') + cherrypy.response.template = env.get_template(filename) + response_dict = next_handler(*args, **kwargs) + return cherrypy.response.template.render(**response_dict) + cherrypy.tools.jinja = HandlerWrapperTool(interpolator) + """ + + def __init__(self, newhandler, point='before_handler', name=None, priority=50): + self.newhandler = newhandler + self._point = point + self._name = name + self._priority = priority + + def callable(self, debug=False): + innerfunc = cherrypy.serving.request.handler + def wrap(*args, **kwargs): + return self.newhandler(innerfunc, *args, **kwargs) + cherrypy.serving.request.handler = wrap + + +class ErrorTool(Tool): + """Tool which is used to replace the default request.error_response.""" + + def __init__(self, callable, name=None): + Tool.__init__(self, None, callable, name) + + def _wrapper(self): + self.callable(**self._merged_args()) + + def _setup(self): + """Hook this tool into cherrypy.request. + + The standard CherryPy request object will automatically call this + method when the tool is "turned on" in config. + """ + cherrypy.serving.request.error_response = self._wrapper + + +# Builtin tools # + +from cherrypy.lib import cptools, encoding, auth, static, jsontools +from cherrypy.lib import sessions as _sessions, xmlrpc as _xmlrpc +from cherrypy.lib import caching as _caching +from cherrypy.lib import auth_basic, auth_digest + + +class SessionTool(Tool): + """Session Tool for CherryPy. + + sessions.locking + When 'implicit' (the default), the session will be locked for you, + just before running the page handler. + + When 'early', the session will be locked before reading the request + body. This is off by default for safety reasons; for example, + a large upload would block the session, denying an AJAX + progress meter (see http://www.cherrypy.org/ticket/630). + + When 'explicit' (or any other value), you need to call + cherrypy.session.acquire_lock() yourself before using + session data. + """ + + def __init__(self): + # _sessions.init must be bound after headers are read + Tool.__init__(self, 'before_request_body', _sessions.init) + + def _lock_session(self): + cherrypy.serving.session.acquire_lock() + + def _setup(self): + """Hook this tool into cherrypy.request. + + The standard CherryPy request object will automatically call this + method when the tool is "turned on" in config. + """ + hooks = cherrypy.serving.request.hooks + + conf = self._merged_args() + + p = conf.pop("priority", None) + if p is None: + p = getattr(self.callable, "priority", self._priority) + + hooks.attach(self._point, self.callable, priority=p, **conf) + + locking = conf.pop('locking', 'implicit') + if locking == 'implicit': + hooks.attach('before_handler', self._lock_session) + elif locking == 'early': + # Lock before the request body (but after _sessions.init runs!) + hooks.attach('before_request_body', self._lock_session, + priority=60) + else: + # Don't lock + pass + + hooks.attach('before_finalize', _sessions.save) + hooks.attach('on_end_request', _sessions.close) + + def regenerate(self): + """Drop the current session and make a new one (with a new id).""" + sess = cherrypy.serving.session + sess.regenerate() + + # Grab cookie-relevant tool args + conf = dict([(k, v) for k, v in self._merged_args().items() + if k in ('path', 'path_header', 'name', 'timeout', + 'domain', 'secure')]) + _sessions.set_response_cookie(**conf) + + + + +class XMLRPCController(object): + """A Controller (page handler collection) for XML-RPC. + + To use it, have your controllers subclass this base class (it will + turn on the tool for you). + + You can also supply the following optional config entries:: + + tools.xmlrpc.encoding: 'utf-8' + tools.xmlrpc.allow_none: 0 + + XML-RPC is a rather discontinuous layer over HTTP; dispatching to the + appropriate handler must first be performed according to the URL, and + then a second dispatch step must take place according to the RPC method + specified in the request body. It also allows a superfluous "/RPC2" + prefix in the URL, supplies its own handler args in the body, and + requires a 200 OK "Fault" response instead of 404 when the desired + method is not found. + + Therefore, XML-RPC cannot be implemented for CherryPy via a Tool alone. + This Controller acts as the dispatch target for the first half (based + on the URL); it then reads the RPC method from the request body and + does its own second dispatch step based on that method. It also reads + body params, and returns a Fault on error. + + The XMLRPCDispatcher strips any /RPC2 prefix; if you aren't using /RPC2 + in your URL's, you can safely skip turning on the XMLRPCDispatcher. + Otherwise, you need to use declare it in config:: + + request.dispatch: cherrypy.dispatch.XMLRPCDispatcher() + """ + + # Note we're hard-coding this into the 'tools' namespace. We could do + # a huge amount of work to make it relocatable, but the only reason why + # would be if someone actually disabled the default_toolbox. Meh. + _cp_config = {'tools.xmlrpc.on': True} + + def default(self, *vpath, **params): + rpcparams, rpcmethod = _xmlrpc.process_body() + + subhandler = self + for attr in str(rpcmethod).split('.'): + subhandler = getattr(subhandler, attr, None) + + if subhandler and getattr(subhandler, "exposed", False): + body = subhandler(*(vpath + rpcparams), **params) + + else: + # http://www.cherrypy.org/ticket/533 + # if a method is not found, an xmlrpclib.Fault should be returned + # raising an exception here will do that; see + # cherrypy.lib.xmlrpc.on_error + raise Exception('method "%s" is not supported' % attr) + + conf = cherrypy.serving.request.toolmaps['tools'].get("xmlrpc", {}) + _xmlrpc.respond(body, + conf.get('encoding', 'utf-8'), + conf.get('allow_none', 0)) + return cherrypy.serving.response.body + default.exposed = True + + +class SessionAuthTool(HandlerTool): + + def _setargs(self): + for name in dir(cptools.SessionAuth): + if not name.startswith("__"): + setattr(self, name, None) + + +class CachingTool(Tool): + """Caching Tool for CherryPy.""" + + def _wrapper(self, **kwargs): + request = cherrypy.serving.request + if _caching.get(**kwargs): + request.handler = None + else: + if request.cacheable: + # Note the devious technique here of adding hooks on the fly + request.hooks.attach('before_finalize', _caching.tee_output, + priority = 90) + _wrapper.priority = 20 + + def _setup(self): + """Hook caching into cherrypy.request.""" + conf = self._merged_args() + + p = conf.pop("priority", None) + cherrypy.serving.request.hooks.attach('before_handler', self._wrapper, + priority=p, **conf) + + + +class Toolbox(object): + """A collection of Tools. + + This object also functions as a config namespace handler for itself. + Custom toolboxes should be added to each Application's toolboxes dict. + """ + + def __init__(self, namespace): + self.namespace = namespace + + def __setattr__(self, name, value): + # If the Tool._name is None, supply it from the attribute name. + if isinstance(value, Tool): + if value._name is None: + value._name = name + value.namespace = self.namespace + object.__setattr__(self, name, value) + + def __enter__(self): + """Populate request.toolmaps from tools specified in config.""" + cherrypy.serving.request.toolmaps[self.namespace] = map = {} + def populate(k, v): + toolname, arg = k.split(".", 1) + bucket = map.setdefault(toolname, {}) + bucket[arg] = v + return populate + + def __exit__(self, exc_type, exc_val, exc_tb): + """Run tool._setup() for each tool in our toolmap.""" + map = cherrypy.serving.request.toolmaps.get(self.namespace) + if map: + for name, settings in map.items(): + if settings.get("on", False): + tool = getattr(self, name) + tool._setup() + + +class DeprecatedTool(Tool): + + _name = None + warnmsg = "This Tool is deprecated." + + def __init__(self, point, warnmsg=None): + self.point = point + if warnmsg is not None: + self.warnmsg = warnmsg + + def __call__(self, *args, **kwargs): + warnings.warn(self.warnmsg) + def tool_decorator(f): + return f + return tool_decorator + + def _setup(self): + warnings.warn(self.warnmsg) + + +default_toolbox = _d = Toolbox("tools") +_d.session_auth = SessionAuthTool(cptools.session_auth) +_d.allow = Tool('on_start_resource', cptools.allow) +_d.proxy = Tool('before_request_body', cptools.proxy, priority=30) +_d.response_headers = Tool('on_start_resource', cptools.response_headers) +_d.log_tracebacks = Tool('before_error_response', cptools.log_traceback) +_d.log_headers = Tool('before_error_response', cptools.log_request_headers) +_d.log_hooks = Tool('on_end_request', cptools.log_hooks, priority=100) +_d.err_redirect = ErrorTool(cptools.redirect) +_d.etags = Tool('before_finalize', cptools.validate_etags, priority=75) +_d.decode = Tool('before_request_body', encoding.decode) +# the order of encoding, gzip, caching is important +_d.encode = Tool('before_handler', encoding.ResponseEncoder, priority=70) +_d.gzip = Tool('before_finalize', encoding.gzip, priority=80) +_d.staticdir = HandlerTool(static.staticdir) +_d.staticfile = HandlerTool(static.staticfile) +_d.sessions = SessionTool() +_d.xmlrpc = ErrorTool(_xmlrpc.on_error) +_d.caching = CachingTool('before_handler', _caching.get, 'caching') +_d.expires = Tool('before_finalize', _caching.expires) +_d.tidy = DeprecatedTool('before_finalize', + "The tidy tool has been removed from the standard distribution of CherryPy. " + "The most recent version can be found at http://tools.cherrypy.org/browser.") +_d.nsgmls = DeprecatedTool('before_finalize', + "The nsgmls tool has been removed from the standard distribution of CherryPy. " + "The most recent version can be found at http://tools.cherrypy.org/browser.") +_d.ignore_headers = Tool('before_request_body', cptools.ignore_headers) +_d.referer = Tool('before_request_body', cptools.referer) +_d.basic_auth = Tool('on_start_resource', auth.basic_auth) +_d.digest_auth = Tool('on_start_resource', auth.digest_auth) +_d.trailing_slash = Tool('before_handler', cptools.trailing_slash, priority=60) +_d.flatten = Tool('before_finalize', cptools.flatten) +_d.accept = Tool('on_start_resource', cptools.accept) +_d.redirect = Tool('on_start_resource', cptools.redirect) +_d.autovary = Tool('on_start_resource', cptools.autovary, priority=0) +_d.json_in = Tool('before_request_body', jsontools.json_in, priority=30) +_d.json_out = Tool('before_handler', jsontools.json_out, priority=30) +_d.auth_basic = Tool('before_handler', auth_basic.basic_auth, priority=1) +_d.auth_digest = Tool('before_handler', auth_digest.digest_auth, priority=1) + +del _d, cptools, encoding, auth, static diff --git a/cherrypy/_cptree.py b/cherrypy/_cptree.py new file mode 100644 index 00000000..67ce5465 --- /dev/null +++ b/cherrypy/_cptree.py @@ -0,0 +1,279 @@ +"""CherryPy Application and Tree objects.""" + +import os +import cherrypy +from cherrypy._cpcompat import ntou +from cherrypy import _cpconfig, _cplogging, _cprequest, _cpwsgi, tools +from cherrypy.lib import httputil + + +class Application(object): + """A CherryPy Application. + + Servers and gateways should not instantiate Request objects directly. + Instead, they should ask an Application object for a request object. + + An instance of this class may also be used as a WSGI callable + (WSGI application object) for itself. + """ + + root = None + """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 = {} + """A dict of {path: pathconf} pairs, where 'pathconf' is itself a dict + of {key: value} pairs.""" + + namespaces = _cpconfig.NamespaceSet() + toolboxes = {'tools': cherrypy.tools} + + log = None + """A LogManager instance. See _cplogging.""" + + wsgiapp = None + """A CPWSGIApp instance. See _cpwsgi.""" + + request_class = _cprequest.Request + response_class = _cprequest.Response + + relative_urls = False + + def __init__(self, root, script_name="", config=None): + 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 = self.namespaces.copy() + self.namespaces["log"] = lambda k, v: setattr(self.log, k, v) + self.namespaces["wsgi"] = self.wsgiapp.namespace_handler + + self.config = self.__class__.config.copy() + if config: + self.merge(config) + + def __repr__(self): + return "%s.%s(%r, %r)" % (self.__module__, self.__class__.__name__, + self.root, self.script_name) + + script_name_doc = """The URI "mount point" for this app. A mount point is that portion of + the URI which is constant for all URIs that are serviced by this + application; it does not include scheme, host, or proxy ("virtual host") + portions of the URI. + + For example, if script_name is "/my/cool/app", then the URL + "http://www.example.com/my/cool/app/page1" might be handled by a + "page1" method on the root object. + + The value of script_name MUST NOT end in a slash. If the script_name + refers to the root of the URI, it MUST be an empty string (not "/"). + + 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 cherrypy.serving.request.wsgi_environ['SCRIPT_NAME'].rstrip("/") + return self._script_name + def _set_script_name(self, value): + if value: + value = value.rstrip("/") + self._script_name = value + 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.""" + _cpconfig.merge(self.config, config) + + # Handle namespaces specified in config. + self.namespaces(self.config.get("/", {})) + + def find_config(self, path, key, default=None): + """Return the most-specific value for key along path, or default.""" + trail = path or "/" + while trail: + nodeconf = self.config.get(trail, {}) + + if key in nodeconf: + return nodeconf[key] + + lastslash = trail.rfind("/") + if lastslash == -1: + break + elif lastslash == 0 and trail != "/": + trail = "/" + else: + trail = trail[:lastslash] + + return default + + def get_serving(self, local, remote, scheme, sproto): + """Create and return a Request and Response object.""" + req = self.request_class(local, remote, scheme, sproto) + req.app = self + + for name, toolbox in self.toolboxes.items(): + req.namespaces[name] = toolbox + + resp = self.response_class() + cherrypy.serving.load(req, resp) + cherrypy.engine.timeout_monitor.acquire() + cherrypy.engine.publish('acquire_thread') + + return req, resp + + def release_serving(self): + """Release the current serving (request and response).""" + req = cherrypy.serving.request + + cherrypy.engine.timeout_monitor.release() + + try: + req.close() + except: + cherrypy.log(traceback=True, severity=40) + + cherrypy.serving.clear() + + def __call__(self, environ, start_response): + return self.wsgiapp(environ, start_response) + + +class Tree(object): + """A registry of CherryPy applications, mounted at diverse points. + + 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 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 = {} + + def mount(self, root, script_name="", config=None): + """Mount a new app from a root object, script_name, and config. + + root + An instance of a "controller class" (a collection of page + handler methods) which represents the root of the application. + This may also be an Application instance, or None if using + a dispatcher other than the default. + + script_name + A string containing the "mount point" of the application. + This should start with a slash, and be the path portion of the + URL at which to mount the given root. For example, if root.index() + will handle requests to "http://www.example.com:8080/dept/app1/", + then the script_name argument would be "/dept/app1". + + It MUST NOT end in a slash. If the script_name refers to the + root of the URI, it MUST be an empty string (not "/"). + + config + A file or dict containing application config. + """ + if script_name is None: + raise TypeError( + "The 'script_name' argument may not be None. Application " + "objects may, however, possess a script_name of None (in " + "order to inpect the WSGI environ for SCRIPT_NAME upon each " + "request). You cannot mount such Applications on this Tree; " + "you must pass them to a WSGI server interface directly.") + + # Next line both 1) strips trailing slash and 2) maps "/" -> "". + script_name = script_name.rstrip("/") + + if isinstance(root, Application): + app = root + if script_name != "" and script_name != app.script_name: + raise ValueError("Cannot specify a different script name and " + "pass an Application instance to cherrypy.mount") + script_name = app.script_name + else: + app = Application(root, script_name) + + # If mounted at "", add favicon.ico + if (script_name == "" and root is not None + and not hasattr(root, "favicon_ico")): + favicon = os.path.join(os.getcwd(), os.path.dirname(__file__), + "favicon.ico") + root.favicon_ico = tools.staticfile.handler(favicon) + + if config: + app.merge(config) + + self.apps[script_name] = app + + return app + + def graft(self, wsgi_callable, script_name=""): + """Mount a wsgi callable at the given script_name.""" + # Next line both 1) strips trailing slash and 2) maps "/" -> "". + script_name = script_name.rstrip("/") + self.apps[script_name] = wsgi_callable + + def script_name(self, path=None): + """The script_name of the app at the given path, or None. + + If path is None, cherrypy.request is used. + """ + if path is None: + try: + request = cherrypy.serving.request + path = httputil.urljoin(request.script_name, + request.path_info) + except AttributeError: + return None + + while True: + if path in self.apps: + return path + + if path == "": + return None + + # Move one node up the tree and try again. + path = path[:path.rfind("/")] + + def __call__(self, environ, start_response): + # If you're calling this, then you're probably setting SCRIPT_NAME + # to '' (some WSGI servers always set SCRIPT_NAME to ''). + # Try to look up the app using the full path. + env1x = environ + if environ.get(ntou('wsgi.version')) == (ntou('u'), 0): + env1x = _cpwsgi.downgrade_wsgi_ux_to_1x(environ) + path = httputil.urljoin(env1x.get('SCRIPT_NAME', ''), + env1x.get('PATH_INFO', '')) + sn = self.script_name(path or "/") + if sn is None: + start_response('404 Not Found', []) + return [] + + app = self.apps[sn] + + # Correct the SCRIPT_NAME and PATH_INFO environ entries. + environ = environ.copy() + if environ.get(u'wsgi.version') == (u'u', 0): + # Python 2/WSGI u.0: all strings MUST be of type unicode + enc = environ[u'wsgi.url_encoding'] + environ[u'SCRIPT_NAME'] = sn.decode(enc) + environ[u'PATH_INFO'] = path[len(sn.rstrip("/")):].decode(enc) + else: + # Python 2/WSGI 1.x: all strings MUST be of type str + environ['SCRIPT_NAME'] = sn + environ['PATH_INFO'] = path[len(sn.rstrip("/")):] + return app(environ, start_response) + diff --git a/cherrypy/_cpwsgi.py b/cherrypy/_cpwsgi.py new file mode 100644 index 00000000..aa4b7631 --- /dev/null +++ b/cherrypy/_cpwsgi.py @@ -0,0 +1,347 @@ +"""WSGI interface (see PEP 333 and 3333). + +Note that WSGI environ keys and values are 'native strings'; that is, +whatever the type of "" is. For Python 2, that's a byte string; for Python 3, +it's a unicode string. But PEP 3333 says: "even if Python's str type is +actually Unicode "under the hood", the content of native strings must +still be translatable to bytes via the Latin-1 encoding!" +""" + +import sys as _sys + +import cherrypy as _cherrypy +from cherrypy._cpcompat import BytesIO +from cherrypy import _cperror +from cherrypy.lib import httputil + + +def downgrade_wsgi_ux_to_1x(environ): + """Return a new environ dict for WSGI 1.x from the given WSGI u.x environ.""" + env1x = {} + + url_encoding = environ[u'wsgi.url_encoding'] + for k, v in environ.items(): + if k in [u'PATH_INFO', u'SCRIPT_NAME', u'QUERY_STRING']: + v = v.encode(url_encoding) + elif isinstance(v, unicode): + v = v.encode('ISO-8859-1') + env1x[k.encode('ISO-8859-1')] = v + + return env1x + + +class VirtualHost(object): + """Select a different WSGI application based on the Host header. + + This can be useful when running multiple sites within one CP server. + It allows several domains to point to different applications. For example:: + + root = Root() + RootApp = cherrypy.Application(root) + Domain2App = cherrypy.Application(root) + SecureApp = cherrypy.Application(Secure()) + + vhost = cherrypy._cpwsgi.VirtualHost(RootApp, + domains={'www.domain2.example': Domain2App, + 'www.domain2.example:443': SecureApp, + }) + + cherrypy.tree.graft(vhost) + """ + default = None + """Required. The default WSGI application.""" + + use_x_forwarded_host = True + """If True (the default), any "X-Forwarded-Host" + request header will be used instead of the "Host" header. This + is commonly added by HTTP servers (such as Apache) when proxying.""" + + domains = {} + """A dict of {host header value: application} pairs. + The incoming "Host" request header is looked up in this dict, + and, if a match is found, the corresponding WSGI application + will be called instead of the default. Note that you often need + separate entries for "example.com" and "www.example.com". + In addition, "Host" headers may contain the port number. + """ + + def __init__(self, default, domains=None, use_x_forwarded_host=True): + self.default = default + self.domains = domains or {} + self.use_x_forwarded_host = use_x_forwarded_host + + def __call__(self, environ, start_response): + domain = environ.get('HTTP_HOST', '') + if self.use_x_forwarded_host: + domain = environ.get("HTTP_X_FORWARDED_HOST", domain) + + nextapp = self.domains.get(domain) + if nextapp is None: + nextapp = self.default + return nextapp(environ, start_response) + + +class InternalRedirector(object): + """WSGI middleware that handles raised cherrypy.InternalRedirect.""" + + def __init__(self, nextapp, recursive=False): + self.nextapp = nextapp + self.recursive = recursive + + def __call__(self, environ, start_response): + redirections = [] + while True: + environ = environ.copy() + try: + return self.nextapp(environ, start_response) + except _cherrypy.InternalRedirect, ir: + sn = environ.get('SCRIPT_NAME', '') + path = environ.get('PATH_INFO', '') + qs = environ.get('QUERY_STRING', '') + + # Add the *previous* path_info + qs to redirections. + old_uri = sn + path + if qs: + old_uri += "?" + qs + redirections.append(old_uri) + + if not self.recursive: + # Check to see if the new URI has been redirected to already + new_uri = sn + ir.path + if ir.query_string: + new_uri += "?" + ir.query_string + if new_uri in redirections: + ir.request.close() + raise RuntimeError("InternalRedirector visited the " + "same URL twice: %r" % new_uri) + + # Munge the environment and try again. + environ['REQUEST_METHOD'] = "GET" + environ['PATH_INFO'] = ir.path + environ['QUERY_STRING'] = ir.query_string + environ['wsgi.input'] = BytesIO() + environ['CONTENT_LENGTH'] = "0" + environ['cherrypy.previous_request'] = ir.request + + +class ExceptionTrapper(object): + """WSGI middleware that traps exceptions.""" + + def __init__(self, nextapp, throws=(KeyboardInterrupt, SystemExit)): + self.nextapp = nextapp + self.throws = throws + + def __call__(self, environ, start_response): + return _TrappedResponse(self.nextapp, environ, start_response, self.throws) + + +class _TrappedResponse(object): + + response = iter([]) + + def __init__(self, nextapp, environ, start_response, throws): + self.nextapp = nextapp + self.environ = environ + self.start_response = start_response + self.throws = throws + self.started_response = False + self.response = self.trap(self.nextapp, self.environ, self.start_response) + self.iter_response = iter(self.response) + + def __iter__(self): + self.started_response = True + return self + + def next(self): + return self.trap(self.iter_response.next) + + def close(self): + if hasattr(self.response, 'close'): + self.response.close() + + def trap(self, func, *args, **kwargs): + try: + return func(*args, **kwargs) + except self.throws: + raise + except StopIteration: + raise + except: + tb = _cperror.format_exc() + #print('trapped (started %s):' % self.started_response, tb) + _cherrypy.log(tb, severity=40) + if not _cherrypy.request.show_tracebacks: + tb = "" + s, h, b = _cperror.bare_error(tb) + if self.started_response: + # Empty our iterable (so future calls raise StopIteration) + self.iter_response = iter([]) + else: + self.iter_response = iter(b) + + try: + self.start_response(s, h, _sys.exc_info()) + except: + # "The application must not trap any exceptions raised by + # start_response, if it called start_response with exc_info. + # Instead, it should allow such exceptions to propagate + # back to the server or gateway." + # But we still log and call close() to clean up ourselves. + _cherrypy.log(traceback=True, severity=40) + raise + + if self.started_response: + return "".join(b) + else: + return b + + +# WSGI-to-CP Adapter # + + +class AppResponse(object): + """WSGI response iterable for CherryPy applications.""" + + def __init__(self, environ, start_response, cpapp): + if environ.get(u'wsgi.version') == (u'u', 0): + environ = downgrade_wsgi_ux_to_1x(environ) + self.environ = environ + self.cpapp = cpapp + try: + self.run() + except: + self.close() + raise + r = _cherrypy.serving.response + self.iter_response = iter(r.body) + self.write = start_response(r.output_status, r.header_list) + + def __iter__(self): + return self + + def next(self): + return self.iter_response.next() + + def close(self): + """Close and de-reference the current request and response. (Core)""" + self.cpapp.release_serving() + + def run(self): + """Create a Request object using environ.""" + env = self.environ.get + + local = httputil.Host('', int(env('SERVER_PORT', 80)), + env('SERVER_NAME', '')) + remote = httputil.Host(env('REMOTE_ADDR', ''), + int(env('REMOTE_PORT', -1) or -1), + env('REMOTE_HOST', '')) + scheme = env('wsgi.url_scheme') + sproto = env('ACTUAL_SERVER_PROTOCOL', "HTTP/1.1") + request, resp = self.cpapp.get_serving(local, remote, scheme, sproto) + + # LOGON_USER is served by IIS, and is the name of the + # user after having been mapped to a local account. + # Both IIS and Apache set REMOTE_USER, when possible. + request.login = env('LOGON_USER') or env('REMOTE_USER') or None + request.multithread = self.environ['wsgi.multithread'] + request.multiprocess = self.environ['wsgi.multiprocess'] + request.wsgi_environ = self.environ + request.prev = env('cherrypy.previous_request', None) + + meth = self.environ['REQUEST_METHOD'] + + path = httputil.urljoin(self.environ.get('SCRIPT_NAME', ''), + self.environ.get('PATH_INFO', '')) + qs = self.environ.get('QUERY_STRING', '') + rproto = self.environ.get('SERVER_PROTOCOL') + headers = self.translate_headers(self.environ) + rfile = self.environ['wsgi.input'] + request.run(meth, path, qs, rproto, headers, rfile) + + headerNames = {'HTTP_CGI_AUTHORIZATION': 'Authorization', + 'CONTENT_LENGTH': 'Content-Length', + 'CONTENT_TYPE': 'Content-Type', + 'REMOTE_HOST': 'Remote-Host', + 'REMOTE_ADDR': 'Remote-Addr', + } + + def translate_headers(self, environ): + """Translate CGI-environ header names to HTTP header names.""" + for cgiName in environ: + # We assume all incoming header keys are uppercase already. + if cgiName in self.headerNames: + yield self.headerNames[cgiName], environ[cgiName] + elif cgiName[:5] == "HTTP_": + # Hackish attempt at recovering original header names. + translatedHeader = cgiName[5:].replace("_", "-") + yield translatedHeader, environ[cgiName] + + +class CPWSGIApp(object): + """A WSGI application object for a CherryPy Application.""" + + pipeline = [('ExceptionTrapper', ExceptionTrapper), + ('InternalRedirector', InternalRedirector), + ] + """A list of (name, wsgiapp) pairs. Each 'wsgiapp' MUST be a + constructor that takes an initial, positional 'nextapp' argument, + plus optional keyword arguments, and returns a WSGI application + (that takes environ and start_response arguments). The 'name' can + be any you choose, and will correspond to keys in self.config.""" + + head = None + """Rather than nest all apps in the pipeline on each call, it's only + done the first time, and the result is memoized into self.head. Set + this to None again if you change self.pipeline after calling self.""" + + config = {} + """A dict whose keys match names listed in the pipeline. Each + value is a further dict which will be passed to the corresponding + named WSGI callable (from the pipeline) as keyword arguments.""" + + response_class = AppResponse + """The class to instantiate and return as the next app in the WSGI chain.""" + + def __init__(self, cpapp, pipeline=None): + self.cpapp = cpapp + self.pipeline = self.pipeline[:] + if pipeline: + self.pipeline.extend(pipeline) + self.config = self.config.copy() + + def tail(self, environ, start_response): + """WSGI application callable for the actual CherryPy application. + + You probably shouldn't call this; call self.__call__ instead, + so that any WSGI middleware in self.pipeline can run first. + """ + return self.response_class(environ, start_response, self.cpapp) + + def __call__(self, environ, start_response): + head = self.head + if head is None: + # Create and nest the WSGI apps in our pipeline (in reverse order). + # Then memoize the result in self.head. + head = self.tail + for name, callable in self.pipeline[::-1]: + conf = self.config.get(name, {}) + head = callable(head, **conf) + self.head = head + return head(environ, start_response) + + def namespace_handler(self, k, v): + """Config handler for the 'wsgi' namespace.""" + if k == "pipeline": + # Note this allows multiple 'wsgi.pipeline' config entries + # (but each entry will be processed in a 'random' order). + # It should also allow developers to set default middleware + # in code (passed to self.__init__) that deployers can add to + # (but not remove) via config. + self.pipeline.extend(v) + elif k == "response_class": + self.response_class = v + else: + name, arg = k.split(".", 1) + bucket = self.config.setdefault(name, {}) + bucket[arg] = v + diff --git a/cherrypy/_cpwsgi_server.py b/cherrypy/_cpwsgi_server.py new file mode 100644 index 00000000..49fd5a19 --- /dev/null +++ b/cherrypy/_cpwsgi_server.py @@ -0,0 +1,54 @@ +"""WSGI server interface (see PEP 333). This adds some CP-specific bits to +the framework-agnostic wsgiserver package. +""" +import sys + +import cherrypy +from cherrypy import wsgiserver + + +class CPWSGIServer(wsgiserver.CherryPyWSGIServer): + """Wrapper for wsgiserver.CherryPyWSGIServer. + + wsgiserver has been designed to not reference CherryPy in any way, + so that it can be used in other frameworks and applications. Therefore, + we wrap it here, so we can set our own mount points from cherrypy.tree + and apply some attributes from config -> cherrypy.server -> wsgiserver. + """ + + def __init__(self, server_adapter=cherrypy.server): + self.server_adapter = server_adapter + self.max_request_header_size = self.server_adapter.max_request_header_size or 0 + self.max_request_body_size = self.server_adapter.max_request_body_size or 0 + + server_name = (self.server_adapter.socket_host or + self.server_adapter.socket_file or + None) + + self.wsgi_version = self.server_adapter.wsgi_version + s = wsgiserver.CherryPyWSGIServer + s.__init__(self, server_adapter.bind_addr, cherrypy.tree, + self.server_adapter.thread_pool, + server_name, + max = self.server_adapter.thread_pool_max, + request_queue_size = self.server_adapter.socket_queue_size, + timeout = self.server_adapter.socket_timeout, + shutdown_timeout = self.server_adapter.shutdown_timeout, + ) + self.protocol = self.server_adapter.protocol_version + self.nodelay = self.server_adapter.nodelay + + ssl_module = self.server_adapter.ssl_module or 'pyopenssl' + if self.server_adapter.ssl_context: + adapter_class = wsgiserver.get_ssl_adapter_class(ssl_module) + self.ssl_adapter = adapter_class( + self.server_adapter.ssl_certificate, + self.server_adapter.ssl_private_key, + self.server_adapter.ssl_certificate_chain) + self.ssl_adapter.context = self.server_adapter.ssl_context + elif self.server_adapter.ssl_certificate: + adapter_class = wsgiserver.get_ssl_adapter_class(ssl_module) + self.ssl_adapter = adapter_class( + self.server_adapter.ssl_certificate, + self.server_adapter.ssl_private_key, + self.server_adapter.ssl_certificate_chain) diff --git a/cherrypy/cherryd b/cherrypy/cherryd new file mode 100755 index 00000000..adb2a02e --- /dev/null +++ b/cherrypy/cherryd @@ -0,0 +1,109 @@ +#! /usr/bin/env python +"""The CherryPy daemon.""" + +import sys + +import cherrypy +from cherrypy.process import plugins, servers +from cherrypy import Application + +def start(configfiles=None, daemonize=False, environment=None, + fastcgi=False, scgi=False, pidfile=None, imports=None, + cgi=False): + """Subscribe all engine plugins and start the engine.""" + sys.path = [''] + sys.path + for i in imports or []: + exec("import %s" % i) + + for c in configfiles or []: + cherrypy.config.update(c) + # If there's only one app mounted, merge config into it. + if len(cherrypy.tree.apps) == 1: + for app in cherrypy.tree.apps.values(): + if isinstance(app, Application): + app.merge(c) + + engine = cherrypy.engine + + if environment is not None: + cherrypy.config.update({'environment': environment}) + + # Only daemonize if asked to. + if daemonize: + # Don't print anything to stdout/sterr. + cherrypy.config.update({'log.screen': False}) + plugins.Daemonizer(engine).subscribe() + + if pidfile: + plugins.PIDFile(engine, pidfile).subscribe() + + if hasattr(engine, "signal_handler"): + engine.signal_handler.subscribe() + if hasattr(engine, "console_control_handler"): + engine.console_control_handler.subscribe() + + if (fastcgi and (scgi or cgi)) or (scgi and cgi): + cherrypy.log.error("You may only specify one of the cgi, fastcgi, and " + "scgi options.", 'ENGINE') + sys.exit(1) + elif fastcgi or scgi or cgi: + # Turn off autoreload when using *cgi. + cherrypy.config.update({'engine.autoreload_on': False}) + # Turn off the default HTTP server (which is subscribed by default). + cherrypy.server.unsubscribe() + + addr = cherrypy.server.bind_addr + if fastcgi: + f = servers.FlupFCGIServer(application=cherrypy.tree, + bindAddress=addr) + elif scgi: + f = servers.FlupSCGIServer(application=cherrypy.tree, + bindAddress=addr) + else: + f = servers.FlupCGIServer(application=cherrypy.tree, + bindAddress=addr) + s = servers.ServerAdapter(engine, httpserver=f, bind_addr=addr) + s.subscribe() + + # Always start the engine; this will start all other services + try: + engine.start() + except: + # Assume the error has been logged already via bus.log. + sys.exit(1) + else: + engine.block() + + +if __name__ == '__main__': + from optparse import OptionParser + + p = OptionParser() + p.add_option('-c', '--config', action="append", dest='config', + help="specify config file(s)") + p.add_option('-d', action="store_true", dest='daemonize', + help="run the server as a daemon") + p.add_option('-e', '--environment', dest='environment', default=None, + help="apply the given config environment") + p.add_option('-f', action="store_true", dest='fastcgi', + help="start a fastcgi server instead of the default HTTP server") + p.add_option('-s', action="store_true", dest='scgi', + help="start a scgi server instead of the default HTTP server") + p.add_option('-x', action="store_true", dest='cgi', + help="start a cgi server instead of the default HTTP server") + p.add_option('-i', '--import', action="append", dest='imports', + help="specify modules to import") + p.add_option('-p', '--pidfile', dest='pidfile', default=None, + help="store the process id in the given file") + p.add_option('-P', '--Path', action="append", dest='Path', + help="add the given paths to sys.path") + options, args = p.parse_args() + + if options.Path: + for p in options.Path: + sys.path.insert(0, p) + + start(options.config, options.daemonize, + options.environment, options.fastcgi, options.scgi, + options.pidfile, options.imports, options.cgi) + diff --git a/cherrypy/favicon.ico b/cherrypy/favicon.ico new file mode 100644 index 0000000000000000000000000000000000000000..f0d7e61badad3f332cf1e663efb97c0b5be80f5e GIT binary patch literal 1406 zcmb`Hd05U_6vscWSJJB#$ugQ@jA;zAXDv%YAxlVP&ytAjTU10ymNpe4LY9=2_SI5K zC3>Y)vZNK!rhR_zJdtfiw$m?BBmX0|pFW;J|@s zYHBiQ&>#j69?Xy-Ll`=AD8q&gWBBmlj2JNjEiElZjvUFTQKJ|=dNgCkjA889v5Xrx z4sC61baZqWKYlzDCQM-B#EDFrGznc@T_#VSjGmqzQ>IK|>eQ)Bn>G!7eSHiJ446KB zIx}X>VCKx37#bQfYt}4g&z{YkIdhmhcP>UoM$DTxkNNZGvtYpjjE#+1xNspRCMGOe zw1~xv7h`H_%915ZSh{p6%a$!;`SRtgSh0eYD_62=)hf))%vim8HEY(aVeQ(rtXsDZ zb8~anuV0Uag#{ZnY+&QYjaXV*vT4&MHgDdHm6a7+wrpYR)~#&YwvFxEx3go%4tDO` z$*x_y*u8rke3QwOtB{embw6rwR)6;qO>=_vu z89aafoEI-%keQi@R4V1=%a>$jW%26OE3&h*$;rv#_3PK<=H`-@mq&hnK5yQT(K__B|98+X@Zp^73MZjvW!HsVT|~sc)O^ZGM)}O{A)-)@n=bmFdz? zRaLc>D=T%Qr>f`&r)>x2Kb1tH)^h|wLs?1GQ@HOR^ik=lq13yT$@Z=qojU#WZ-LIg Kbp8+jKgeIP@z;_7 literal 0 HcmV?d00001 diff --git a/cherrypy/lib/__init__.py b/cherrypy/lib/__init__.py new file mode 100644 index 00000000..611350c9 --- /dev/null +++ b/cherrypy/lib/__init__.py @@ -0,0 +1,45 @@ +"""CherryPy Library""" + +# Deprecated in CherryPy 3.2 -- remove in CherryPy 3.3 +from cherrypy.lib.reprconf import _Builder, unrepr, modules, attributes + +class file_generator(object): + """Yield the given input (a file object) in chunks (default 64k). (Core)""" + + def __init__(self, input, chunkSize=65536): + self.input = input + self.chunkSize = chunkSize + + def __iter__(self): + return self + + def __next__(self): + chunk = self.input.read(self.chunkSize) + if chunk: + return chunk + else: + if hasattr(self.input, 'close'): + self.input.close() + raise StopIteration() + next = __next__ + +def file_generator_limited(fileobj, count, chunk_size=65536): + """Yield the given file object in chunks, stopping after `count` + bytes has been emitted. Default chunk size is 64kB. (Core) + """ + remaining = count + while remaining > 0: + chunk = fileobj.read(min(chunk_size, remaining)) + chunklen = len(chunk) + if chunklen == 0: + return + remaining -= chunklen + yield chunk + +def set_vary_header(response, header_name): + "Add a Vary header to a response" + varies = response.headers.get("Vary", "") + varies = [x.strip() for x in varies.split(",") if x.strip()] + if header_name not in varies: + varies.append(header_name) + response.headers['Vary'] = ", ".join(varies) diff --git a/cherrypy/lib/auth.py b/cherrypy/lib/auth.py new file mode 100644 index 00000000..7d2f6dc2 --- /dev/null +++ b/cherrypy/lib/auth.py @@ -0,0 +1,87 @@ +import cherrypy +from cherrypy.lib import httpauth + + +def check_auth(users, encrypt=None, realm=None): + """If an authorization header contains credentials, return True, else False.""" + request = cherrypy.serving.request + if 'authorization' in request.headers: + # make sure the provided credentials are correctly set + ah = httpauth.parseAuthorization(request.headers['authorization']) + if ah is None: + raise cherrypy.HTTPError(400, 'Bad Request') + + if not encrypt: + encrypt = httpauth.DIGEST_AUTH_ENCODERS[httpauth.MD5] + + if hasattr(users, '__call__'): + try: + # backward compatibility + users = users() # expect it to return a dictionary + + if not isinstance(users, dict): + raise ValueError("Authentication users must be a dictionary") + + # fetch the user password + password = users.get(ah["username"], None) + except TypeError: + # returns a password (encrypted or clear text) + password = users(ah["username"]) + else: + if not isinstance(users, dict): + raise ValueError("Authentication users must be a dictionary") + + # fetch the user password + password = users.get(ah["username"], None) + + # validate the authorization by re-computing it here + # and compare it with what the user-agent provided + if httpauth.checkResponse(ah, password, method=request.method, + encrypt=encrypt, realm=realm): + request.login = ah["username"] + return True + + request.login = False + return False + +def basic_auth(realm, users, encrypt=None, debug=False): + """If auth fails, raise 401 with a basic authentication header. + + realm + A string containing the authentication realm. + + users + A dict of the form: {username: password} or a callable returning a dict. + + encrypt + callable used to encrypt the password returned from the user-agent. + if None it defaults to a md5 encryption. + + """ + if check_auth(users, encrypt): + if debug: + cherrypy.log('Auth successful', 'TOOLS.BASIC_AUTH') + return + + # inform the user-agent this path is protected + cherrypy.serving.response.headers['www-authenticate'] = httpauth.basicAuth(realm) + + raise cherrypy.HTTPError(401, "You are not authorized to access that resource") + +def digest_auth(realm, users, debug=False): + """If auth fails, raise 401 with a digest authentication header. + + realm + A string containing the authentication realm. + users + A dict of the form: {username: password} or a callable returning a dict. + """ + if check_auth(users, realm=realm): + if debug: + cherrypy.log('Auth successful', 'TOOLS.DIGEST_AUTH') + return + + # inform the user-agent this path is protected + cherrypy.serving.response.headers['www-authenticate'] = httpauth.digestAuth(realm) + + raise cherrypy.HTTPError(401, "You are not authorized to access that resource") diff --git a/cherrypy/lib/auth_basic.py b/cherrypy/lib/auth_basic.py new file mode 100644 index 00000000..2c05e013 --- /dev/null +++ b/cherrypy/lib/auth_basic.py @@ -0,0 +1,87 @@ +# This file is part of CherryPy +# -*- coding: utf-8 -*- +# vim:ts=4:sw=4:expandtab:fileencoding=utf-8 + +__doc__ = """This module provides a CherryPy 3.x tool which implements +the server-side of HTTP Basic Access Authentication, as described in :rfc:`2617`. + +Example usage, using the built-in checkpassword_dict function which uses a dict +as the credentials store:: + + userpassdict = {'bird' : 'bebop', 'ornette' : 'wayout'} + checkpassword = cherrypy.lib.auth_basic.checkpassword_dict(userpassdict) + basic_auth = {'tools.auth_basic.on': True, + 'tools.auth_basic.realm': 'earth', + 'tools.auth_basic.checkpassword': checkpassword, + } + app_config = { '/' : basic_auth } + +""" + +__author__ = 'visteya' +__date__ = 'April 2009' + +import binascii +from cherrypy._cpcompat import base64_decode +import cherrypy + + +def checkpassword_dict(user_password_dict): + """Returns a checkpassword function which checks credentials + against a dictionary of the form: {username : password}. + + If you want a simple dictionary-based authentication scheme, use + checkpassword_dict(my_credentials_dict) as the value for the + checkpassword argument to basic_auth(). + """ + def checkpassword(realm, user, password): + p = user_password_dict.get(user) + return p and p == password or False + + return checkpassword + + +def basic_auth(realm, checkpassword, debug=False): + """A CherryPy tool which hooks at before_handler to perform + HTTP Basic Access Authentication, as specified in :rfc:`2617`. + + If the request has an 'authorization' header with a 'Basic' scheme, this + tool attempts to authenticate the credentials supplied in that header. If + the request has no 'authorization' header, or if it does but the scheme is + not 'Basic', or if authentication fails, the tool sends a 401 response with + a 'WWW-Authenticate' Basic header. + + realm + A string containing the authentication realm. + + checkpassword + A callable which checks the authentication credentials. + Its signature is checkpassword(realm, username, password). where + username and password are the values obtained from the request's + 'authorization' header. If authentication succeeds, checkpassword + returns True, else it returns False. + + """ + + if '"' in realm: + raise ValueError('Realm cannot contain the " (quote) character.') + request = cherrypy.serving.request + + auth_header = request.headers.get('authorization') + if auth_header is not None: + try: + scheme, params = auth_header.split(' ', 1) + if scheme.lower() == 'basic': + username, password = base64_decode(params).split(':', 1) + if checkpassword(realm, username, password): + if debug: + cherrypy.log('Auth succeeded', 'TOOLS.AUTH_BASIC') + request.login = username + return # successful authentication + except (ValueError, binascii.Error): # split() error, base64.decodestring() error + raise cherrypy.HTTPError(400, 'Bad Request') + + # Respond with 401 status and a WWW-Authenticate header + cherrypy.serving.response.headers['www-authenticate'] = 'Basic realm="%s"' % realm + raise cherrypy.HTTPError(401, "You are not authorized to access that resource") + diff --git a/cherrypy/lib/auth_digest.py b/cherrypy/lib/auth_digest.py new file mode 100644 index 00000000..67578e00 --- /dev/null +++ b/cherrypy/lib/auth_digest.py @@ -0,0 +1,365 @@ +# This file is part of CherryPy +# -*- coding: utf-8 -*- +# vim:ts=4:sw=4:expandtab:fileencoding=utf-8 + +__doc__ = """An implementation of the server-side of HTTP Digest Access +Authentication, which is described in :rfc:`2617`. + +Example usage, using the built-in get_ha1_dict_plain function which uses a dict +of plaintext passwords as the credentials store:: + + userpassdict = {'alice' : '4x5istwelve'} + get_ha1 = cherrypy.lib.auth_digest.get_ha1_dict_plain(userpassdict) + digest_auth = {'tools.auth_digest.on': True, + 'tools.auth_digest.realm': 'wonderland', + 'tools.auth_digest.get_ha1': get_ha1, + 'tools.auth_digest.key': 'a565c27146791cfb', + } + app_config = { '/' : digest_auth } +""" + +__author__ = 'visteya' +__date__ = 'April 2009' + + +import time +from cherrypy._cpcompat import parse_http_list, parse_keqv_list + +import cherrypy +from cherrypy._cpcompat import md5, ntob +md5_hex = lambda s: md5(ntob(s)).hexdigest() + +qop_auth = 'auth' +qop_auth_int = 'auth-int' +valid_qops = (qop_auth, qop_auth_int) + +valid_algorithms = ('MD5', 'MD5-sess') + + +def TRACE(msg): + cherrypy.log(msg, context='TOOLS.AUTH_DIGEST') + +# Three helper functions for users of the tool, providing three variants +# of get_ha1() functions for three different kinds of credential stores. +def get_ha1_dict_plain(user_password_dict): + """Returns a get_ha1 function which obtains a plaintext password from a + dictionary of the form: {username : password}. + + If you want a simple dictionary-based authentication scheme, with plaintext + passwords, use get_ha1_dict_plain(my_userpass_dict) as the value for the + get_ha1 argument to digest_auth(). + """ + def get_ha1(realm, username): + password = user_password_dict.get(username) + if password: + return md5_hex('%s:%s:%s' % (username, realm, password)) + return None + + return get_ha1 + +def get_ha1_dict(user_ha1_dict): + """Returns a get_ha1 function which obtains a HA1 password hash from a + dictionary of the form: {username : HA1}. + + If you want a dictionary-based authentication scheme, but with + pre-computed HA1 hashes instead of plain-text passwords, use + get_ha1_dict(my_userha1_dict) as the value for the get_ha1 + argument to digest_auth(). + """ + def get_ha1(realm, username): + return user_ha1_dict.get(user) + + return get_ha1 + +def get_ha1_file_htdigest(filename): + """Returns a get_ha1 function which obtains a HA1 password hash from a + flat file with lines of the same format as that produced by the Apache + htdigest utility. For example, for realm 'wonderland', username 'alice', + and password '4x5istwelve', the htdigest line would be:: + + alice:wonderland:3238cdfe91a8b2ed8e39646921a02d4c + + If you want to use an Apache htdigest file as the credentials store, + then use get_ha1_file_htdigest(my_htdigest_file) as the value for the + get_ha1 argument to digest_auth(). It is recommended that the filename + argument be an absolute path, to avoid problems. + """ + def get_ha1(realm, username): + result = None + f = open(filename, 'r') + for line in f: + u, r, ha1 = line.rstrip().split(':') + if u == username and r == realm: + result = ha1 + break + f.close() + return result + + return get_ha1 + + +def synthesize_nonce(s, key, timestamp=None): + """Synthesize a nonce value which resists spoofing and can be checked for staleness. + Returns a string suitable as the value for 'nonce' in the www-authenticate header. + + s + A string related to the resource, such as the hostname of the server. + + key + A secret string known only to the server. + + timestamp + An integer seconds-since-the-epoch timestamp + + """ + if timestamp is None: + timestamp = int(time.time()) + h = md5_hex('%s:%s:%s' % (timestamp, s, key)) + nonce = '%s:%s' % (timestamp, h) + return nonce + + +def H(s): + """The hash function H""" + return md5_hex(s) + + +class HttpDigestAuthorization (object): + """Class to parse a Digest Authorization header and perform re-calculation + of the digest. + """ + + def errmsg(self, s): + return 'Digest Authorization header: %s' % s + + def __init__(self, auth_header, http_method, debug=False): + self.http_method = http_method + self.debug = debug + scheme, params = auth_header.split(" ", 1) + self.scheme = scheme.lower() + if self.scheme != 'digest': + raise ValueError('Authorization scheme is not "Digest"') + + self.auth_header = auth_header + + # make a dict of the params + items = parse_http_list(params) + paramsd = parse_keqv_list(items) + + self.realm = paramsd.get('realm') + self.username = paramsd.get('username') + self.nonce = paramsd.get('nonce') + self.uri = paramsd.get('uri') + self.method = paramsd.get('method') + self.response = paramsd.get('response') # the response digest + self.algorithm = paramsd.get('algorithm', 'MD5') + self.cnonce = paramsd.get('cnonce') + self.opaque = paramsd.get('opaque') + self.qop = paramsd.get('qop') # qop + self.nc = paramsd.get('nc') # nonce count + + # perform some correctness checks + if self.algorithm not in valid_algorithms: + raise ValueError(self.errmsg("Unsupported value for algorithm: '%s'" % self.algorithm)) + + has_reqd = self.username and \ + self.realm and \ + self.nonce and \ + self.uri and \ + self.response + if not has_reqd: + raise ValueError(self.errmsg("Not all required parameters are present.")) + + if self.qop: + if self.qop not in valid_qops: + raise ValueError(self.errmsg("Unsupported value for qop: '%s'" % self.qop)) + if not (self.cnonce and self.nc): + raise ValueError(self.errmsg("If qop is sent then cnonce and nc MUST be present")) + else: + if self.cnonce or self.nc: + raise ValueError(self.errmsg("If qop is not sent, neither cnonce nor nc can be present")) + + + def __str__(self): + return 'authorization : %s' % self.auth_header + + def validate_nonce(self, s, key): + """Validate the nonce. + Returns True if nonce was generated by synthesize_nonce() and the timestamp + is not spoofed, else returns False. + + s + A string related to the resource, such as the hostname of the server. + + key + A secret string known only to the server. + + Both s and key must be the same values which were used to synthesize the nonce + we are trying to validate. + """ + try: + timestamp, hashpart = self.nonce.split(':', 1) + s_timestamp, s_hashpart = synthesize_nonce(s, key, timestamp).split(':', 1) + is_valid = s_hashpart == hashpart + if self.debug: + TRACE('validate_nonce: %s' % is_valid) + return is_valid + except ValueError: # split() error + pass + return False + + + def is_nonce_stale(self, max_age_seconds=600): + """Returns True if a validated nonce is stale. The nonce contains a + timestamp in plaintext and also a secure hash of the timestamp. You should + first validate the nonce to ensure the plaintext timestamp is not spoofed. + """ + try: + timestamp, hashpart = self.nonce.split(':', 1) + if int(timestamp) + max_age_seconds > int(time.time()): + return False + except ValueError: # int() error + pass + if self.debug: + TRACE("nonce is stale") + return True + + + def HA2(self, entity_body=''): + """Returns the H(A2) string. See :rfc:`2617` section 3.2.2.3.""" + # RFC 2617 3.2.2.3 + # If the "qop" directive's value is "auth" or is unspecified, then A2 is: + # A2 = method ":" digest-uri-value + # + # If the "qop" value is "auth-int", then A2 is: + # A2 = method ":" digest-uri-value ":" H(entity-body) + if self.qop is None or self.qop == "auth": + a2 = '%s:%s' % (self.http_method, self.uri) + elif self.qop == "auth-int": + a2 = "%s:%s:%s" % (self.http_method, self.uri, H(entity_body)) + else: + # in theory, this should never happen, since I validate qop in __init__() + raise ValueError(self.errmsg("Unrecognized value for qop!")) + return H(a2) + + + def request_digest(self, ha1, entity_body=''): + """Calculates the Request-Digest. See :rfc:`2617` section 3.2.2.1. + + ha1 + The HA1 string obtained from the credentials store. + + entity_body + If 'qop' is set to 'auth-int', then A2 includes a hash + of the "entity body". The entity body is the part of the + message which follows the HTTP headers. See :rfc:`2617` section + 4.3. This refers to the entity the user agent sent in the request which + has the Authorization header. Typically GET requests don't have an entity, + and POST requests do. + + """ + ha2 = self.HA2(entity_body) + # Request-Digest -- RFC 2617 3.2.2.1 + if self.qop: + req = "%s:%s:%s:%s:%s" % (self.nonce, self.nc, self.cnonce, self.qop, ha2) + else: + req = "%s:%s" % (self.nonce, ha2) + + # RFC 2617 3.2.2.2 + # + # If the "algorithm" directive's value is "MD5" or is unspecified, then A1 is: + # A1 = unq(username-value) ":" unq(realm-value) ":" passwd + # + # If the "algorithm" directive's value is "MD5-sess", then A1 is + # calculated only once - on the first request by the client following + # receipt of a WWW-Authenticate challenge from the server. + # A1 = H( unq(username-value) ":" unq(realm-value) ":" passwd ) + # ":" unq(nonce-value) ":" unq(cnonce-value) + if self.algorithm == 'MD5-sess': + ha1 = H('%s:%s:%s' % (ha1, self.nonce, self.cnonce)) + + digest = H('%s:%s' % (ha1, req)) + return digest + + + +def www_authenticate(realm, key, algorithm='MD5', nonce=None, qop=qop_auth, stale=False): + """Constructs a WWW-Authenticate header for Digest authentication.""" + if qop not in valid_qops: + raise ValueError("Unsupported value for qop: '%s'" % qop) + if algorithm not in valid_algorithms: + raise ValueError("Unsupported value for algorithm: '%s'" % algorithm) + + if nonce is None: + nonce = synthesize_nonce(realm, key) + s = 'Digest realm="%s", nonce="%s", algorithm="%s", qop="%s"' % ( + realm, nonce, algorithm, qop) + if stale: + s += ', stale="true"' + return s + + +def digest_auth(realm, get_ha1, key, debug=False): + """A CherryPy tool which hooks at before_handler to perform + HTTP Digest Access Authentication, as specified in :rfc:`2617`. + + If the request has an 'authorization' header with a 'Digest' scheme, this + tool authenticates the credentials supplied in that header. If + the request has no 'authorization' header, or if it does but the scheme is + not "Digest", or if authentication fails, the tool sends a 401 response with + a 'WWW-Authenticate' Digest header. + + realm + A string containing the authentication realm. + + get_ha1 + A callable which looks up a username in a credentials store + and returns the HA1 string, which is defined in the RFC to be + MD5(username : realm : password). The function's signature is: + ``get_ha1(realm, username)`` + where username is obtained from the request's 'authorization' header. + If username is not found in the credentials store, get_ha1() returns + None. + + key + A secret string known only to the server, used in the synthesis of nonces. + + """ + request = cherrypy.serving.request + + auth_header = request.headers.get('authorization') + nonce_is_stale = False + if auth_header is not None: + try: + auth = HttpDigestAuthorization(auth_header, request.method, debug=debug) + except ValueError: + raise cherrypy.HTTPError(400, "The Authorization header could not be parsed.") + + if debug: + TRACE(str(auth)) + + if auth.validate_nonce(realm, key): + ha1 = get_ha1(realm, auth.username) + if ha1 is not None: + # note that for request.body to be available we need to hook in at + # before_handler, not on_start_resource like 3.1.x digest_auth does. + digest = auth.request_digest(ha1, entity_body=request.body) + if digest == auth.response: # authenticated + if debug: + TRACE("digest matches auth.response") + # Now check if nonce is stale. + # The choice of ten minutes' lifetime for nonce is somewhat arbitrary + nonce_is_stale = auth.is_nonce_stale(max_age_seconds=600) + if not nonce_is_stale: + request.login = auth.username + if debug: + TRACE("authentication of %s successful" % auth.username) + return + + # Respond with 401 status and a WWW-Authenticate header + header = www_authenticate(realm, key, stale=nonce_is_stale) + if debug: + TRACE(header) + cherrypy.serving.response.headers['WWW-Authenticate'] = header + raise cherrypy.HTTPError(401, "You are not authorized to access that resource") + diff --git a/cherrypy/lib/caching.py b/cherrypy/lib/caching.py new file mode 100644 index 00000000..435b9dc1 --- /dev/null +++ b/cherrypy/lib/caching.py @@ -0,0 +1,465 @@ +""" +CherryPy implements a simple caching system as a pluggable Tool. This tool tries +to be an (in-process) HTTP/1.1-compliant cache. It's not quite there yet, but +it's probably good enough for most sites. + +In general, GET responses are cached (along with selecting headers) and, if +another request arrives for the same resource, the caching Tool will return 304 +Not Modified if possible, or serve the cached response otherwise. It also sets +request.cached to True if serving a cached representation, and sets +request.cacheable to False (so it doesn't get cached again). + +If POST, PUT, or DELETE requests are made for a cached resource, they invalidate +(delete) any cached response. + +Usage +===== + +Configuration file example:: + + [/] + tools.caching.on = True + tools.caching.delay = 3600 + +You may use a class other than the default +:class:`MemoryCache` by supplying the config +entry ``cache_class``; supply the full dotted name of the replacement class +as the config value. It must implement the basic methods ``get``, ``put``, +``delete``, and ``clear``. + +You may set any attribute, including overriding methods, on the cache +instance by providing them in config. The above sets the +:attr:`delay` attribute, for example. +""" + +import datetime +import sys +import threading +import time + +import cherrypy +from cherrypy.lib import cptools, httputil +from cherrypy._cpcompat import copyitems, ntob, set_daemon, sorted + + +class Cache(object): + """Base class for Cache implementations.""" + + def get(self): + """Return the current variant if in the cache, else None.""" + raise NotImplemented + + def put(self, obj, size): + """Store the current variant in the cache.""" + raise NotImplemented + + def delete(self): + """Remove ALL cached variants of the current resource.""" + raise NotImplemented + + def clear(self): + """Reset the cache to its initial, empty state.""" + raise NotImplemented + + + +# ------------------------------- Memory Cache ------------------------------- # + + +class AntiStampedeCache(dict): + """A storage system for cached items which reduces stampede collisions.""" + + def wait(self, key, timeout=5, debug=False): + """Return the cached value for the given key, or None. + + If timeout is not None, and the value is already + being calculated by another thread, wait until the given timeout has + elapsed. If the value is available before the timeout expires, it is + returned. If not, None is returned, and a sentinel placed in the cache + to signal other threads to wait. + + If timeout is None, no waiting is performed nor sentinels used. + """ + value = self.get(key) + if isinstance(value, threading._Event): + if timeout is None: + # Ignore the other thread and recalc it ourselves. + if debug: + cherrypy.log('No timeout', 'TOOLS.CACHING') + return None + + # Wait until it's done or times out. + if debug: + cherrypy.log('Waiting up to %s seconds' % timeout, 'TOOLS.CACHING') + value.wait(timeout) + if value.result is not None: + # The other thread finished its calculation. Use it. + if debug: + cherrypy.log('Result!', 'TOOLS.CACHING') + return value.result + # Timed out. Stick an Event in the slot so other threads wait + # on this one to finish calculating the value. + if debug: + cherrypy.log('Timed out', 'TOOLS.CACHING') + e = threading.Event() + e.result = None + dict.__setitem__(self, key, e) + + return None + elif value is None: + # Stick an Event in the slot so other threads wait + # on this one to finish calculating the value. + if debug: + cherrypy.log('Timed out', 'TOOLS.CACHING') + e = threading.Event() + e.result = None + dict.__setitem__(self, key, e) + return value + + def __setitem__(self, key, value): + """Set the cached value for the given key.""" + existing = self.get(key) + dict.__setitem__(self, key, value) + if isinstance(existing, threading._Event): + # Set Event.result so other threads waiting on it have + # immediate access without needing to poll the cache again. + existing.result = value + existing.set() + + +class MemoryCache(Cache): + """An in-memory cache for varying response content. + + Each key in self.store is a URI, and each value is an AntiStampedeCache. + The response for any given URI may vary based on the values of + "selecting request headers"; that is, those named in the Vary + response header. We assume the list of header names to be constant + for each URI throughout the lifetime of the application, and store + that list in ``self.store[uri].selecting_headers``. + + The items contained in ``self.store[uri]`` have keys which are tuples of + request header values (in the same order as the names in its + selecting_headers), and values which are the actual responses. + """ + + maxobjects = 1000 + """The maximum number of cached objects; defaults to 1000.""" + + maxobj_size = 100000 + """The maximum size of each cached object in bytes; defaults to 100 KB.""" + + maxsize = 10000000 + """The maximum size of the entire cache in bytes; defaults to 10 MB.""" + + delay = 600 + """Seconds until the cached content expires; defaults to 600 (10 minutes).""" + + antistampede_timeout = 5 + """Seconds to wait for other threads to release a cache lock.""" + + expire_freq = 0.1 + """Seconds to sleep between cache expiration sweeps.""" + + debug = False + + def __init__(self): + self.clear() + + # Run self.expire_cache in a separate daemon thread. + t = threading.Thread(target=self.expire_cache, name='expire_cache') + self.expiration_thread = t + set_daemon(t, True) + t.start() + + def clear(self): + """Reset the cache to its initial, empty state.""" + self.store = {} + self.expirations = {} + self.tot_puts = 0 + self.tot_gets = 0 + self.tot_hist = 0 + self.tot_expires = 0 + self.tot_non_modified = 0 + self.cursize = 0 + + def expire_cache(self): + """Continuously examine cached objects, expiring stale ones. + + This function is designed to be run in its own daemon thread, + referenced at ``self.expiration_thread``. + """ + # It's possible that "time" will be set to None + # arbitrarily, so we check "while time" to avoid exceptions. + # See tickets #99 and #180 for more information. + while time: + now = time.time() + # Must make a copy of expirations so it doesn't change size + # during iteration + for expiration_time, objects in copyitems(self.expirations): + if expiration_time <= now: + for obj_size, uri, sel_header_values in objects: + try: + del self.store[uri][tuple(sel_header_values)] + self.tot_expires += 1 + self.cursize -= obj_size + except KeyError: + # the key may have been deleted elsewhere + pass + del self.expirations[expiration_time] + time.sleep(self.expire_freq) + + def get(self): + """Return the current variant if in the cache, else None.""" + request = cherrypy.serving.request + self.tot_gets += 1 + + uri = cherrypy.url(qs=request.query_string) + uricache = self.store.get(uri) + if uricache is None: + return None + + header_values = [request.headers.get(h, '') + for h in uricache.selecting_headers] + variant = uricache.wait(key=tuple(sorted(header_values)), + timeout=self.antistampede_timeout, + debug=self.debug) + if variant is not None: + self.tot_hist += 1 + return variant + + def put(self, variant, size): + """Store the current variant in the cache.""" + request = cherrypy.serving.request + response = cherrypy.serving.response + + uri = cherrypy.url(qs=request.query_string) + uricache = self.store.get(uri) + if uricache is None: + uricache = AntiStampedeCache() + uricache.selecting_headers = [ + e.value for e in response.headers.elements('Vary')] + self.store[uri] = uricache + + if len(self.store) < self.maxobjects: + total_size = self.cursize + size + + # checks if there's space for the object + if (size < self.maxobj_size and total_size < self.maxsize): + # add to the expirations list + expiration_time = response.time + self.delay + bucket = self.expirations.setdefault(expiration_time, []) + bucket.append((size, uri, uricache.selecting_headers)) + + # add to the cache + header_values = [request.headers.get(h, '') + for h in uricache.selecting_headers] + uricache[tuple(sorted(header_values))] = variant + self.tot_puts += 1 + self.cursize = total_size + + def delete(self): + """Remove ALL cached variants of the current resource.""" + uri = cherrypy.url(qs=cherrypy.serving.request.query_string) + self.store.pop(uri, None) + + +def get(invalid_methods=("POST", "PUT", "DELETE"), debug=False, **kwargs): + """Try to obtain cached output. If fresh enough, raise HTTPError(304). + + If POST, PUT, or DELETE: + * invalidates (deletes) any cached response for this resource + * sets request.cached = False + * sets request.cacheable = False + + else if a cached copy exists: + * sets request.cached = True + * sets request.cacheable = False + * sets response.headers to the cached values + * checks the cached Last-Modified response header against the + current If-(Un)Modified-Since request headers; raises 304 + if necessary. + * sets response.status and response.body to the cached values + * returns True + + otherwise: + * sets request.cached = False + * sets request.cacheable = True + * returns False + """ + request = cherrypy.serving.request + response = cherrypy.serving.response + + if not hasattr(cherrypy, "_cache"): + # Make a process-wide Cache object. + cherrypy._cache = kwargs.pop("cache_class", MemoryCache)() + + # Take all remaining kwargs and set them on the Cache object. + for k, v in kwargs.items(): + setattr(cherrypy._cache, k, v) + cherrypy._cache.debug = debug + + # POST, PUT, DELETE should invalidate (delete) the cached copy. + # See http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html#sec13.10. + if request.method in invalid_methods: + if debug: + cherrypy.log('request.method %r in invalid_methods %r' % + (request.method, invalid_methods), 'TOOLS.CACHING') + cherrypy._cache.delete() + request.cached = False + request.cacheable = False + return False + + if 'no-cache' in [e.value for e in request.headers.elements('Pragma')]: + request.cached = False + request.cacheable = True + return False + + cache_data = cherrypy._cache.get() + request.cached = bool(cache_data) + request.cacheable = not request.cached + if request.cached: + # Serve the cached copy. + max_age = cherrypy._cache.delay + for v in [e.value for e in request.headers.elements('Cache-Control')]: + atoms = v.split('=', 1) + directive = atoms.pop(0) + if directive == 'max-age': + if len(atoms) != 1 or not atoms[0].isdigit(): + raise cherrypy.HTTPError(400, "Invalid Cache-Control header") + max_age = int(atoms[0]) + break + elif directive == 'no-cache': + if debug: + cherrypy.log('Ignoring cache due to Cache-Control: no-cache', + 'TOOLS.CACHING') + request.cached = False + request.cacheable = True + return False + + if debug: + cherrypy.log('Reading response from cache', 'TOOLS.CACHING') + s, h, b, create_time = cache_data + age = int(response.time - create_time) + if (age > max_age): + if debug: + cherrypy.log('Ignoring cache due to age > %d' % max_age, + 'TOOLS.CACHING') + request.cached = False + request.cacheable = True + return False + + # Copy the response headers. See http://www.cherrypy.org/ticket/721. + response.headers = rh = httputil.HeaderMap() + for k in h: + dict.__setitem__(rh, k, dict.__getitem__(h, k)) + + # Add the required Age header + response.headers["Age"] = str(age) + + try: + # Note that validate_since depends on a Last-Modified header; + # this was put into the cached copy, and should have been + # resurrected just above (response.headers = cache_data[1]). + cptools.validate_since() + except cherrypy.HTTPRedirect: + x = sys.exc_info()[1] + if x.status == 304: + cherrypy._cache.tot_non_modified += 1 + raise + + # serve it & get out from the request + response.status = s + response.body = b + else: + if debug: + cherrypy.log('request is not cached', 'TOOLS.CACHING') + return request.cached + + +def tee_output(): + """Tee response output to cache storage. Internal.""" + # Used by CachingTool by attaching to request.hooks + + request = cherrypy.serving.request + if 'no-store' in request.headers.values('Cache-Control'): + return + + def tee(body): + """Tee response.body into a list.""" + if ('no-cache' in response.headers.values('Pragma') or + 'no-store' in response.headers.values('Cache-Control')): + for chunk in body: + yield chunk + return + + output = [] + for chunk in body: + output.append(chunk) + yield chunk + + # save the cache data + body = ntob('').join(output) + cherrypy._cache.put((response.status, response.headers or {}, + body, response.time), len(body)) + + response = cherrypy.serving.response + response.body = tee(response.body) + + +def expires(secs=0, force=False, debug=False): + """Tool for influencing cache mechanisms using the 'Expires' header. + + secs + Must be either an int or a datetime.timedelta, and indicates the + number of seconds between response.time and when the response should + expire. The 'Expires' header will be set to response.time + secs. + If secs is zero, the 'Expires' header is set one year in the past, and + the following "cache prevention" headers are also set: + + * Pragma: no-cache + * Cache-Control': no-cache, must-revalidate + + force + If False, the following headers are checked: + + * Etag + * Last-Modified + * Age + * Expires + + If any are already present, none of the above response headers are set. + + """ + + response = cherrypy.serving.response + headers = response.headers + + cacheable = False + if not force: + # some header names that indicate that the response can be cached + for indicator in ('Etag', 'Last-Modified', 'Age', 'Expires'): + if indicator in headers: + cacheable = True + break + + if not cacheable and not force: + if debug: + cherrypy.log('request is not cacheable', 'TOOLS.EXPIRES') + else: + if debug: + cherrypy.log('request is cacheable', 'TOOLS.EXPIRES') + if isinstance(secs, datetime.timedelta): + secs = (86400 * secs.days) + secs.seconds + + if secs == 0: + if force or ("Pragma" not in headers): + headers["Pragma"] = "no-cache" + if cherrypy.serving.request.protocol >= (1, 1): + if force or "Cache-Control" not in headers: + headers["Cache-Control"] = "no-cache, must-revalidate" + # Set an explicit Expires date in the past. + expiry = httputil.HTTPDate(1169942400.0) + else: + expiry = httputil.HTTPDate(response.time + secs) + if force or "Expires" not in headers: + headers["Expires"] = expiry diff --git a/cherrypy/lib/covercp.py b/cherrypy/lib/covercp.py new file mode 100644 index 00000000..9b701b56 --- /dev/null +++ b/cherrypy/lib/covercp.py @@ -0,0 +1,365 @@ +"""Code-coverage tools for CherryPy. + +To use this module, or the coverage tools in the test suite, +you need to download 'coverage.py', either Gareth Rees' `original +implementation `_ +or Ned Batchelder's `enhanced version: +`_ + +To turn on coverage tracing, use the following code:: + + cherrypy.engine.subscribe('start', covercp.start) + +DO NOT subscribe anything on the 'start_thread' channel, as previously +recommended. Calling start once in the main thread should be sufficient +to start coverage on all threads. Calling start again in each thread +effectively clears any coverage data gathered up to that point. + +Run your code, then use the ``covercp.serve()`` function to browse the +results in a web browser. If you run this module from the command line, +it will call ``serve()`` for you. +""" + +import re +import sys +import cgi +from cherrypy._cpcompat import quote_plus +import os, os.path +localFile = os.path.join(os.path.dirname(__file__), "coverage.cache") + +the_coverage = None +try: + from coverage import coverage + the_coverage = coverage(data_file=localFile) + def start(): + the_coverage.start() +except ImportError: + # Setting the_coverage to None will raise errors + # that need to be trapped downstream. + the_coverage = None + + import warnings + warnings.warn("No code coverage will be performed; coverage.py could not be imported.") + + def start(): + pass +start.priority = 20 + +TEMPLATE_MENU = """ + + CherryPy Coverage Menu + + + +

CherryPy Coverage

""" + +TEMPLATE_FORM = """ +
+
+ + Show percentages
+ Hide files over %%
+ Exclude files matching
+ +
+ + +
+
""" + +TEMPLATE_FRAMESET = """ +CherryPy coverage data + + + + + +""" + +TEMPLATE_COVERAGE = """ + + Coverage for %(name)s + + + +

%(name)s

+

%(fullpath)s

+

Coverage: %(pc)s%%

""" + +TEMPLATE_LOC_COVERED = """ + %s  + %s +\n""" +TEMPLATE_LOC_NOT_COVERED = """ + %s  + %s +\n""" +TEMPLATE_LOC_EXCLUDED = """ + %s  + %s +\n""" + +TEMPLATE_ITEM = "%s%s%s\n" + +def _percent(statements, missing): + s = len(statements) + e = s - len(missing) + if s > 0: + return int(round(100.0 * e / s)) + return 0 + +def _show_branch(root, base, path, pct=0, showpct=False, exclude="", + coverage=the_coverage): + + # Show the directory name and any of our children + dirs = [k for k, v in root.items() if v] + dirs.sort() + for name in dirs: + newpath = os.path.join(path, name) + + if newpath.lower().startswith(base): + relpath = newpath[len(base):] + yield "| " * relpath.count(os.sep) + yield "%s\n" % \ + (newpath, quote_plus(exclude), name) + + for chunk in _show_branch(root[name], base, newpath, pct, showpct, exclude, coverage=coverage): + yield chunk + + # Now list the files + if path.lower().startswith(base): + relpath = path[len(base):] + files = [k for k, v in root.items() if not v] + files.sort() + for name in files: + newpath = os.path.join(path, name) + + pc_str = "" + if showpct: + try: + _, statements, _, missing, _ = coverage.analysis2(newpath) + except: + # Yes, we really want to pass on all errors. + pass + else: + pc = _percent(statements, missing) + pc_str = ("%3d%% " % pc).replace(' ',' ') + if pc < float(pct) or pc == -1: + pc_str = "%s" % pc_str + else: + pc_str = "%s" % pc_str + + yield TEMPLATE_ITEM % ("| " * (relpath.count(os.sep) + 1), + pc_str, newpath, name) + +def _skip_file(path, exclude): + if exclude: + return bool(re.search(exclude, path)) + +def _graft(path, tree): + d = tree + + p = path + atoms = [] + while True: + p, tail = os.path.split(p) + if not tail: + break + atoms.append(tail) + atoms.append(p) + if p != "/": + atoms.append("/") + + atoms.reverse() + for node in atoms: + if node: + d = d.setdefault(node, {}) + +def get_tree(base, exclude, coverage=the_coverage): + """Return covered module names as a nested dict.""" + tree = {} + runs = coverage.data.executed_files() + for path in runs: + if not _skip_file(path, exclude) and not os.path.isdir(path): + _graft(path, tree) + return tree + +class CoverStats(object): + + def __init__(self, coverage, root=None): + self.coverage = coverage + if root is None: + # Guess initial depth. Files outside this path will not be + # reachable from the web interface. + import cherrypy + root = os.path.dirname(cherrypy.__file__) + self.root = root + + def index(self): + return TEMPLATE_FRAMESET % self.root.lower() + index.exposed = True + + def menu(self, base="/", pct="50", showpct="", + exclude=r'python\d\.\d|test|tut\d|tutorial'): + + # The coverage module uses all-lower-case names. + base = base.lower().rstrip(os.sep) + + yield TEMPLATE_MENU + yield TEMPLATE_FORM % locals() + + # Start by showing links for parent paths + yield "
" + path = "" + atoms = base.split(os.sep) + atoms.pop() + for atom in atoms: + path += atom + os.sep + yield ("%s %s" + % (path, quote_plus(exclude), atom, os.sep)) + yield "
" + + yield "
" + + # Then display the tree + tree = get_tree(base, exclude, self.coverage) + if not tree: + yield "

No modules covered.

" + else: + for chunk in _show_branch(tree, base, "/", pct, + showpct=='checked', exclude, coverage=self.coverage): + yield chunk + + yield "
" + yield "" + menu.exposed = True + + def annotated_file(self, filename, statements, excluded, missing): + source = open(filename, 'r') + buffer = [] + for lineno, line in enumerate(source.readlines()): + lineno += 1 + line = line.strip("\n\r") + empty_the_buffer = True + if lineno in excluded: + template = TEMPLATE_LOC_EXCLUDED + elif lineno in missing: + template = TEMPLATE_LOC_NOT_COVERED + elif lineno in statements: + template = TEMPLATE_LOC_COVERED + else: + empty_the_buffer = False + buffer.append((lineno, line)) + if empty_the_buffer: + for lno, pastline in buffer: + yield template % (lno, cgi.escape(pastline)) + buffer = [] + yield template % (lineno, cgi.escape(line)) + + def report(self, name): + filename, statements, excluded, missing, _ = self.coverage.analysis2(name) + pc = _percent(statements, missing) + yield TEMPLATE_COVERAGE % dict(name=os.path.basename(name), + fullpath=name, + pc=pc) + yield '\n' + for line in self.annotated_file(filename, statements, excluded, + missing): + yield line + yield '
' + yield '' + yield '' + report.exposed = True + + +def serve(path=localFile, port=8080, root=None): + if coverage is None: + raise ImportError("The coverage module could not be imported.") + from coverage import coverage + cov = coverage(data_file = path) + cov.load() + + import cherrypy + cherrypy.config.update({'server.socket_port': int(port), + 'server.thread_pool': 10, + 'environment': "production", + }) + cherrypy.quickstart(CoverStats(cov, root)) + +if __name__ == "__main__": + serve(*tuple(sys.argv[1:])) + diff --git a/cherrypy/lib/cpstats.py b/cherrypy/lib/cpstats.py new file mode 100644 index 00000000..79d5c3a9 --- /dev/null +++ b/cherrypy/lib/cpstats.py @@ -0,0 +1,661 @@ +"""CPStats, a package for collecting and reporting on program statistics. + +Overview +======== + +Statistics about program operation are an invaluable monitoring and debugging +tool. Unfortunately, the gathering and reporting of these critical values is +usually ad-hoc. This package aims to add a centralized place for gathering +statistical performance data, a structure for recording that data which +provides for extrapolation of that data into more useful information, +and a method of serving that data to both human investigators and +monitoring software. Let's examine each of those in more detail. + +Data Gathering +-------------- + +Just as Python's `logging` module provides a common importable for gathering +and sending messages, performance statistics would benefit from a similar +common mechanism, and one that does *not* require each package which wishes +to collect stats to import a third-party module. Therefore, we choose to +re-use the `logging` module by adding a `statistics` object to it. + +That `logging.statistics` object is a nested dict. It is not a custom class, +because that would 1) require libraries and applications to import a third- +party module in order to participate, 2) inhibit innovation in extrapolation +approaches and in reporting tools, and 3) be slow. There are, however, some +specifications regarding the structure of the dict. + + { + +----"SQLAlchemy": { + | "Inserts": 4389745, + | "Inserts per Second": + | lambda s: s["Inserts"] / (time() - s["Start"]), + | C +---"Table Statistics": { + | o | "widgets": {-----------+ + N | l | "Rows": 1.3M, | Record + a | l | "Inserts": 400, | + m | e | },---------------------+ + e | c | "froobles": { + s | t | "Rows": 7845, + p | i | "Inserts": 0, + a | o | }, + c | n +---}, + e | "Slow Queries": + | [{"Query": "SELECT * FROM widgets;", + | "Processing Time": 47.840923343, + | }, + | ], + +----}, + } + +The `logging.statistics` dict has four levels. The topmost level is nothing +more than a set of names to introduce modularity, usually along the lines of +package names. If the SQLAlchemy project wanted to participate, for example, +it might populate the item `logging.statistics['SQLAlchemy']`, whose value +would be a second-layer dict we call a "namespace". Namespaces help multiple +packages to avoid collisions over key names, and make reports easier to read, +to boot. The maintainers of SQLAlchemy should feel free to use more than one +namespace if needed (such as 'SQLAlchemy ORM'). Note that there are no case +or other syntax constraints on the namespace names; they should be chosen +to be maximally readable by humans (neither too short nor too long). + +Each namespace, then, is a dict of named statistical values, such as +'Requests/sec' or 'Uptime'. You should choose names which will look +good on a report: spaces and capitalization are just fine. + +In addition to scalars, values in a namespace MAY be a (third-layer) +dict, or a list, called a "collection". For example, the CherryPy StatsTool +keeps track of what each request is doing (or has most recently done) +in a 'Requests' collection, where each key is a thread ID; each +value in the subdict MUST be a fourth dict (whew!) of statistical data about +each thread. We call each subdict in the collection a "record". Similarly, +the StatsTool also keeps a list of slow queries, where each record contains +data about each slow query, in order. + +Values in a namespace or record may also be functions, which brings us to: + +Extrapolation +------------- + +The collection of statistical data needs to be fast, as close to unnoticeable +as possible to the host program. That requires us to minimize I/O, for example, +but in Python it also means we need to minimize function calls. So when you +are designing your namespace and record values, try to insert the most basic +scalar values you already have on hand. + +When it comes time to report on the gathered data, however, we usually have +much more freedom in what we can calculate. Therefore, whenever reporting +tools (like the provided StatsPage CherryPy class) fetch the contents of +`logging.statistics` for reporting, they first call `extrapolate_statistics` +(passing the whole `statistics` dict as the only argument). This makes a +deep copy of the statistics dict so that the reporting tool can both iterate +over it and even change it without harming the original. But it also expands +any functions in the dict by calling them. For example, you might have a +'Current Time' entry in the namespace with the value "lambda scope: time.time()". +The "scope" parameter is the current namespace dict (or record, if we're +currently expanding one of those instead), allowing you access to existing +static entries. If you're truly evil, you can even modify more than one entry +at a time. + +However, don't try to calculate an entry and then use its value in further +extrapolations; the order in which the functions are called is not guaranteed. +This can lead to a certain amount of duplicated work (or a redesign of your +schema), but that's better than complicating the spec. + +After the whole thing has been extrapolated, it's time for: + +Reporting +--------- + +The StatsPage class grabs the `logging.statistics` dict, extrapolates it all, +and then transforms it to HTML for easy viewing. Each namespace gets its own +header and attribute table, plus an extra table for each collection. This is +NOT part of the statistics specification; other tools can format how they like. + +You can control which columns are output and how they are formatted by updating +StatsPage.formatting, which is a dict that mirrors the keys and nesting of +`logging.statistics`. The difference is that, instead of data values, it has +formatting values. Use None for a given key to indicate to the StatsPage that a +given column should not be output. Use a string with formatting (such as '%.3f') +to interpolate the value(s), or use a callable (such as lambda v: v.isoformat()) +for more advanced formatting. Any entry which is not mentioned in the formatting +dict is output unchanged. + +Monitoring +---------- + +Although the HTML output takes pains to assign unique id's to each with +statistical data, you're probably better off fetching /cpstats/data, which +outputs the whole (extrapolated) `logging.statistics` dict in JSON format. +That is probably easier to parse, and doesn't have any formatting controls, +so you get the "original" data in a consistently-serialized format. +Note: there's no treatment yet for datetime objects. Try time.time() instead +for now if you can. Nagios will probably thank you. + +Turning Collection Off +---------------------- + +It is recommended each namespace have an "Enabled" item which, if False, +stops collection (but not reporting) of statistical data. Applications +SHOULD provide controls to pause and resume collection by setting these +entries to False or True, if present. + + +Usage +===== + +To collect statistics on CherryPy applications: + + from cherrypy.lib import cpstats + appconfig['/']['tools.cpstats.on'] = True + +To collect statistics on your own code: + + import logging + # Initialize the repository + if not hasattr(logging, 'statistics'): logging.statistics = {} + # Initialize my namespace + mystats = logging.statistics.setdefault('My Stuff', {}) + # Initialize my namespace's scalars and collections + mystats.update({ + 'Enabled': True, + 'Start Time': time.time(), + 'Important Events': 0, + 'Events/Second': lambda s: ( + (s['Important Events'] / (time.time() - s['Start Time']))), + }) + ... + for event in events: + ... + # Collect stats + if mystats.get('Enabled', False): + mystats['Important Events'] += 1 + +To report statistics: + + root.cpstats = cpstats.StatsPage() + +To format statistics reports: + + See 'Reporting', above. + +""" + +# -------------------------------- Statistics -------------------------------- # + +import logging +if not hasattr(logging, 'statistics'): logging.statistics = {} + +def extrapolate_statistics(scope): + """Return an extrapolated copy of the given scope.""" + c = {} + for k, v in list(scope.items()): + if isinstance(v, dict): + v = extrapolate_statistics(v) + elif isinstance(v, (list, tuple)): + v = [extrapolate_statistics(record) for record in v] + elif hasattr(v, '__call__'): + v = v(scope) + c[k] = v + return c + + +# --------------------- CherryPy Applications Statistics --------------------- # + +import threading +import time + +import cherrypy + +appstats = logging.statistics.setdefault('CherryPy Applications', {}) +appstats.update({ + 'Enabled': True, + 'Bytes Read/Request': lambda s: (s['Total Requests'] and + (s['Total Bytes Read'] / float(s['Total Requests'])) or 0.0), + 'Bytes Read/Second': lambda s: s['Total Bytes Read'] / s['Uptime'](s), + 'Bytes Written/Request': lambda s: (s['Total Requests'] and + (s['Total Bytes Written'] / float(s['Total Requests'])) or 0.0), + 'Bytes Written/Second': lambda s: s['Total Bytes Written'] / s['Uptime'](s), + 'Current Time': lambda s: time.time(), + 'Current Requests': 0, + 'Requests/Second': lambda s: float(s['Total Requests']) / s['Uptime'](s), + 'Server Version': cherrypy.__version__, + 'Start Time': time.time(), + 'Total Bytes Read': 0, + 'Total Bytes Written': 0, + 'Total Requests': 0, + 'Total Time': 0, + 'Uptime': lambda s: time.time() - s['Start Time'], + 'Requests': {}, + }) + +proc_time = lambda s: time.time() - s['Start Time'] + + +class ByteCountWrapper(object): + """Wraps a file-like object, counting the number of bytes read.""" + + def __init__(self, rfile): + self.rfile = rfile + self.bytes_read = 0 + + def read(self, size=-1): + data = self.rfile.read(size) + self.bytes_read += len(data) + return data + + def readline(self, size=-1): + data = self.rfile.readline(size) + self.bytes_read += len(data) + return data + + def readlines(self, sizehint=0): + # Shamelessly stolen from StringIO + total = 0 + lines = [] + line = self.readline() + while line: + lines.append(line) + total += len(line) + if 0 < sizehint <= total: + break + line = self.readline() + return lines + + def close(self): + self.rfile.close() + + def __iter__(self): + return self + + def next(self): + data = self.rfile.next() + self.bytes_read += len(data) + return data + + +average_uriset_time = lambda s: s['Count'] and (s['Sum'] / s['Count']) or 0 + + +class StatsTool(cherrypy.Tool): + """Record various information about the current request.""" + + def __init__(self): + cherrypy.Tool.__init__(self, 'on_end_request', self.record_stop) + + def _setup(self): + """Hook this tool into cherrypy.request. + + The standard CherryPy request object will automatically call this + method when the tool is "turned on" in config. + """ + if appstats.get('Enabled', False): + cherrypy.Tool._setup(self) + self.record_start() + + def record_start(self): + """Record the beginning of a request.""" + request = cherrypy.serving.request + if not hasattr(request.rfile, 'bytes_read'): + request.rfile = ByteCountWrapper(request.rfile) + request.body.fp = request.rfile + + r = request.remote + + appstats['Current Requests'] += 1 + appstats['Total Requests'] += 1 + appstats['Requests'][threading._get_ident()] = { + 'Bytes Read': None, + 'Bytes Written': None, + # Use a lambda so the ip gets updated by tools.proxy later + 'Client': lambda s: '%s:%s' % (r.ip, r.port), + 'End Time': None, + 'Processing Time': proc_time, + 'Request-Line': request.request_line, + 'Response Status': None, + 'Start Time': time.time(), + } + + def record_stop(self, uriset=None, slow_queries=1.0, slow_queries_count=100, + debug=False, **kwargs): + """Record the end of a request.""" + w = appstats['Requests'][threading._get_ident()] + + r = cherrypy.request.rfile.bytes_read + w['Bytes Read'] = r + appstats['Total Bytes Read'] += r + + if cherrypy.response.stream: + w['Bytes Written'] = 'chunked' + else: + cl = int(cherrypy.response.headers.get('Content-Length', 0)) + w['Bytes Written'] = cl + appstats['Total Bytes Written'] += cl + + w['Response Status'] = cherrypy.response.status + + w['End Time'] = time.time() + p = w['End Time'] - w['Start Time'] + w['Processing Time'] = p + appstats['Total Time'] += p + + appstats['Current Requests'] -= 1 + + if debug: + cherrypy.log('Stats recorded: %s' % repr(w), 'TOOLS.CPSTATS') + + if uriset: + rs = appstats.setdefault('URI Set Tracking', {}) + r = rs.setdefault(uriset, { + 'Min': None, 'Max': None, 'Count': 0, 'Sum': 0, + 'Avg': average_uriset_time}) + if r['Min'] is None or p < r['Min']: + r['Min'] = p + if r['Max'] is None or p > r['Max']: + r['Max'] = p + r['Count'] += 1 + r['Sum'] += p + + if slow_queries and p > slow_queries: + sq = appstats.setdefault('Slow Queries', []) + sq.append(w.copy()) + if len(sq) > slow_queries_count: + sq.pop(0) + + +import cherrypy +cherrypy.tools.cpstats = StatsTool() + + +# ---------------------- CherryPy Statistics Reporting ---------------------- # + +import os +thisdir = os.path.abspath(os.path.dirname(__file__)) + +try: + import json +except ImportError: + try: + import simplejson as json + except ImportError: + json = None + + +missing = object() + +locale_date = lambda v: time.strftime('%c', time.gmtime(v)) +iso_format = lambda v: time.strftime('%Y-%m-%d %H:%M:%S', time.gmtime(v)) + +def pause_resume(ns): + def _pause_resume(enabled): + pause_disabled = '' + resume_disabled = '' + if enabled: + resume_disabled = 'disabled="disabled" ' + else: + pause_disabled = 'disabled="disabled" ' + return """ +
+ + +
+
+ + +
+ """ % (ns, pause_disabled, ns, resume_disabled) + return _pause_resume + + +class StatsPage(object): + + formatting = { + 'CherryPy Applications': { + 'Enabled': pause_resume('CherryPy Applications'), + 'Bytes Read/Request': '%.3f', + 'Bytes Read/Second': '%.3f', + 'Bytes Written/Request': '%.3f', + 'Bytes Written/Second': '%.3f', + 'Current Time': iso_format, + 'Requests/Second': '%.3f', + 'Start Time': iso_format, + 'Total Time': '%.3f', + 'Uptime': '%.3f', + 'Slow Queries': { + 'End Time': None, + 'Processing Time': '%.3f', + 'Start Time': iso_format, + }, + 'URI Set Tracking': { + 'Avg': '%.3f', + 'Max': '%.3f', + 'Min': '%.3f', + 'Sum': '%.3f', + }, + 'Requests': { + 'Bytes Read': '%s', + 'Bytes Written': '%s', + 'End Time': None, + 'Processing Time': '%.3f', + 'Start Time': None, + }, + }, + 'CherryPy WSGIServer': { + 'Enabled': pause_resume('CherryPy WSGIServer'), + 'Connections/second': '%.3f', + 'Start time': iso_format, + }, + } + + + def index(self): + # Transform the raw data into pretty output for HTML + yield """ + + + Statistics + + + +""" + for title, scalars, collections in self.get_namespaces(): + yield """ +

%s

+ + + +""" % title + for i, (key, value) in enumerate(scalars): + colnum = i % 3 + if colnum == 0: yield """ + """ + yield """ + """ % vars() + if colnum == 2: yield """ + """ + + if colnum == 0: yield """ + + + """ + elif colnum == 1: yield """ + + """ + yield """ + +
%(key)s%(value)s
""" + + for subtitle, headers, subrows in collections: + yield """ +

%s

+ + + """ % subtitle + for key in headers: + yield """ + """ % key + yield """ + + + """ + for subrow in subrows: + yield """ + """ + for value in subrow: + yield """ + """ % value + yield """ + """ + yield """ + +
%s
%s
""" + yield """ + + +""" + index.exposed = True + + def get_namespaces(self): + """Yield (title, scalars, collections) for each namespace.""" + s = extrapolate_statistics(logging.statistics) + for title, ns in sorted(s.items()): + scalars = [] + collections = [] + ns_fmt = self.formatting.get(title, {}) + for k, v in sorted(ns.items()): + fmt = ns_fmt.get(k, {}) + if isinstance(v, dict): + headers, subrows = self.get_dict_collection(v, fmt) + collections.append((k, ['ID'] + headers, subrows)) + elif isinstance(v, (list, tuple)): + headers, subrows = self.get_list_collection(v, fmt) + collections.append((k, headers, subrows)) + else: + format = ns_fmt.get(k, missing) + if format is None: + # Don't output this column. + continue + if hasattr(format, '__call__'): + v = format(v) + elif format is not missing: + v = format % v + scalars.append((k, v)) + yield title, scalars, collections + + def get_dict_collection(self, v, formatting): + """Return ([headers], [rows]) for the given collection.""" + # E.g., the 'Requests' dict. + headers = [] + for record in v.itervalues(): + for k3 in record: + format = formatting.get(k3, missing) + if format is None: + # Don't output this column. + continue + if k3 not in headers: + headers.append(k3) + headers.sort() + + subrows = [] + for k2, record in sorted(v.items()): + subrow = [k2] + for k3 in headers: + v3 = record.get(k3, '') + format = formatting.get(k3, missing) + if format is None: + # Don't output this column. + continue + if hasattr(format, '__call__'): + v3 = format(v3) + elif format is not missing: + v3 = format % v3 + subrow.append(v3) + subrows.append(subrow) + + return headers, subrows + + def get_list_collection(self, v, formatting): + """Return ([headers], [subrows]) for the given collection.""" + # E.g., the 'Slow Queries' list. + headers = [] + for record in v: + for k3 in record: + format = formatting.get(k3, missing) + if format is None: + # Don't output this column. + continue + if k3 not in headers: + headers.append(k3) + headers.sort() + + subrows = [] + for record in v: + subrow = [] + for k3 in headers: + v3 = record.get(k3, '') + format = formatting.get(k3, missing) + if format is None: + # Don't output this column. + continue + if hasattr(format, '__call__'): + v3 = format(v3) + elif format is not missing: + v3 = format % v3 + subrow.append(v3) + subrows.append(subrow) + + return headers, subrows + + if json is not None: + def data(self): + s = extrapolate_statistics(logging.statistics) + cherrypy.response.headers['Content-Type'] = 'application/json' + return json.dumps(s, sort_keys=True, indent=4) + data.exposed = True + + def pause(self, namespace): + logging.statistics.get(namespace, {})['Enabled'] = False + raise cherrypy.HTTPRedirect('./') + pause.exposed = True + pause.cp_config = {'tools.allow.on': True, + 'tools.allow.methods': ['POST']} + + def resume(self, namespace): + logging.statistics.get(namespace, {})['Enabled'] = True + raise cherrypy.HTTPRedirect('./') + resume.exposed = True + resume.cp_config = {'tools.allow.on': True, + 'tools.allow.methods': ['POST']} + diff --git a/cherrypy/lib/cptools.py b/cherrypy/lib/cptools.py new file mode 100644 index 00000000..3eedf97a --- /dev/null +++ b/cherrypy/lib/cptools.py @@ -0,0 +1,611 @@ +"""Functions for builtin CherryPy tools.""" + +import logging +import re + +import cherrypy +from cherrypy._cpcompat import basestring, ntob, md5, set +from cherrypy.lib import httputil as _httputil + + +# Conditional HTTP request support # + +def validate_etags(autotags=False, debug=False): + """Validate the current ETag against If-Match, If-None-Match headers. + + If autotags is True, an ETag response-header value will be provided + from an MD5 hash of the response body (unless some other code has + already provided an ETag header). If False (the default), the ETag + will not be automatic. + + WARNING: the autotags feature is not designed for URL's which allow + methods other than GET. For example, if a POST to the same URL returns + no content, the automatic ETag will be incorrect, breaking a fundamental + use for entity tags in a possibly destructive fashion. Likewise, if you + raise 304 Not Modified, the response body will be empty, the ETag hash + will be incorrect, and your application will break. + See :rfc:`2616` Section 14.24. + """ + response = cherrypy.serving.response + + # Guard against being run twice. + if hasattr(response, "ETag"): + return + + status, reason, msg = _httputil.valid_status(response.status) + + etag = response.headers.get('ETag') + + # Automatic ETag generation. See warning in docstring. + if etag: + if debug: + cherrypy.log('ETag already set: %s' % etag, 'TOOLS.ETAGS') + elif not autotags: + if debug: + cherrypy.log('Autotags off', 'TOOLS.ETAGS') + elif status != 200: + if debug: + cherrypy.log('Status not 200', 'TOOLS.ETAGS') + else: + etag = response.collapse_body() + etag = '"%s"' % md5(etag).hexdigest() + if debug: + cherrypy.log('Setting ETag: %s' % etag, 'TOOLS.ETAGS') + response.headers['ETag'] = etag + + response.ETag = etag + + # "If the request would, without the If-Match header field, result in + # anything other than a 2xx or 412 status, then the If-Match header + # MUST be ignored." + if debug: + cherrypy.log('Status: %s' % status, 'TOOLS.ETAGS') + if status >= 200 and status <= 299: + request = cherrypy.serving.request + + conditions = request.headers.elements('If-Match') or [] + conditions = [str(x) for x in conditions] + if debug: + cherrypy.log('If-Match conditions: %s' % repr(conditions), + 'TOOLS.ETAGS') + if conditions and not (conditions == ["*"] or etag in conditions): + raise cherrypy.HTTPError(412, "If-Match failed: ETag %r did " + "not match %r" % (etag, conditions)) + + conditions = request.headers.elements('If-None-Match') or [] + conditions = [str(x) for x in conditions] + if debug: + cherrypy.log('If-None-Match conditions: %s' % repr(conditions), + 'TOOLS.ETAGS') + if conditions == ["*"] or etag in conditions: + if debug: + cherrypy.log('request.method: %s' % request.method, 'TOOLS.ETAGS') + if request.method in ("GET", "HEAD"): + raise cherrypy.HTTPRedirect([], 304) + else: + raise cherrypy.HTTPError(412, "If-None-Match failed: ETag %r " + "matched %r" % (etag, conditions)) + +def validate_since(): + """Validate the current Last-Modified against If-Modified-Since headers. + + If no code has set the Last-Modified response header, then no validation + will be performed. + """ + response = cherrypy.serving.response + lastmod = response.headers.get('Last-Modified') + if lastmod: + status, reason, msg = _httputil.valid_status(response.status) + + request = cherrypy.serving.request + + since = request.headers.get('If-Unmodified-Since') + if since and since != lastmod: + if (status >= 200 and status <= 299) or status == 412: + raise cherrypy.HTTPError(412) + + since = request.headers.get('If-Modified-Since') + if since and since == lastmod: + if (status >= 200 and status <= 299) or status == 304: + if request.method in ("GET", "HEAD"): + raise cherrypy.HTTPRedirect([], 304) + else: + raise cherrypy.HTTPError(412) + + +# Tool code # + +def allow(methods=None, debug=False): + """Raise 405 if request.method not in methods (default GET/HEAD). + + The given methods are case-insensitive, and may be in any order. + If only one method is allowed, you may supply a single string; + if more than one, supply a list of strings. + + Regardless of whether the current method is allowed or not, this + also emits an 'Allow' response header, containing the given methods. + """ + if not isinstance(methods, (tuple, list)): + methods = [methods] + methods = [m.upper() for m in methods if m] + if not methods: + methods = ['GET', 'HEAD'] + elif 'GET' in methods and 'HEAD' not in methods: + methods.append('HEAD') + + cherrypy.response.headers['Allow'] = ', '.join(methods) + if cherrypy.request.method not in methods: + if debug: + cherrypy.log('request.method %r not in methods %r' % + (cherrypy.request.method, methods), 'TOOLS.ALLOW') + raise cherrypy.HTTPError(405) + else: + if debug: + cherrypy.log('request.method %r in methods %r' % + (cherrypy.request.method, methods), 'TOOLS.ALLOW') + + +def proxy(base=None, local='X-Forwarded-Host', remote='X-Forwarded-For', + scheme='X-Forwarded-Proto', debug=False): + """Change the base URL (scheme://host[:port][/path]). + + For running a CP server behind Apache, lighttpd, or other HTTP server. + + If you want the new request.base to include path info (not just the host), + you must explicitly set base to the full base path, and ALSO set 'local' + to '', so that the X-Forwarded-Host request header (which never includes + path info) does not override it. Regardless, the value for 'base' MUST + NOT end in a slash. + + cherrypy.request.remote.ip (the IP address of the client) will be + rewritten if the header specified by the 'remote' arg is valid. + By default, 'remote' is set to 'X-Forwarded-For'. If you do not + want to rewrite remote.ip, set the 'remote' arg to an empty string. + """ + + request = cherrypy.serving.request + + if scheme: + s = request.headers.get(scheme, None) + if debug: + cherrypy.log('Testing scheme %r:%r' % (scheme, s), 'TOOLS.PROXY') + if s == 'on' and 'ssl' in scheme.lower(): + # This handles e.g. webfaction's 'X-Forwarded-Ssl: on' header + scheme = 'https' + else: + # This is for lighttpd/pound/Mongrel's 'X-Forwarded-Proto: https' + scheme = s + if not scheme: + scheme = request.base[:request.base.find("://")] + + if local: + lbase = request.headers.get(local, None) + if debug: + cherrypy.log('Testing local %r:%r' % (local, lbase), 'TOOLS.PROXY') + if lbase is not None: + base = lbase.split(',')[0] + if not base: + port = request.local.port + if port == 80: + base = '127.0.0.1' + else: + base = '127.0.0.1:%s' % port + + if base.find("://") == -1: + # add http:// or https:// if needed + base = scheme + "://" + base + + request.base = base + + if remote: + xff = request.headers.get(remote) + if debug: + cherrypy.log('Testing remote %r:%r' % (remote, xff), 'TOOLS.PROXY') + if xff: + if remote == 'X-Forwarded-For': + # See http://bob.pythonmac.org/archives/2005/09/23/apache-x-forwarded-for-caveat/ + xff = xff.split(',')[-1].strip() + request.remote.ip = xff + + +def ignore_headers(headers=('Range',), debug=False): + """Delete request headers whose field names are included in 'headers'. + + This is a useful tool for working behind certain HTTP servers; + for example, Apache duplicates the work that CP does for 'Range' + headers, and will doubly-truncate the response. + """ + request = cherrypy.serving.request + for name in headers: + if name in request.headers: + if debug: + cherrypy.log('Ignoring request header %r' % name, + 'TOOLS.IGNORE_HEADERS') + del request.headers[name] + + +def response_headers(headers=None, debug=False): + """Set headers on the response.""" + if debug: + cherrypy.log('Setting response headers: %s' % repr(headers), + 'TOOLS.RESPONSE_HEADERS') + for name, value in (headers or []): + cherrypy.serving.response.headers[name] = value +response_headers.failsafe = True + + +def referer(pattern, accept=True, accept_missing=False, error=403, + message='Forbidden Referer header.', debug=False): + """Raise HTTPError if Referer header does/does not match the given pattern. + + pattern + A regular expression pattern to test against the Referer. + + accept + If True, the Referer must match the pattern; if False, + the Referer must NOT match the pattern. + + accept_missing + If True, permit requests with no Referer header. + + error + The HTTP error code to return to the client on failure. + + message + A string to include in the response body on failure. + + """ + try: + ref = cherrypy.serving.request.headers['Referer'] + match = bool(re.match(pattern, ref)) + if debug: + cherrypy.log('Referer %r matches %r' % (ref, pattern), + 'TOOLS.REFERER') + if accept == match: + return + except KeyError: + if debug: + cherrypy.log('No Referer header', 'TOOLS.REFERER') + if accept_missing: + return + + raise cherrypy.HTTPError(error, message) + + +class SessionAuth(object): + """Assert that the user is logged in.""" + + session_key = "username" + debug = False + + def check_username_and_password(self, username, password): + pass + + def anonymous(self): + """Provide a temporary user name for anonymous users.""" + pass + + def on_login(self, username): + pass + + def on_logout(self, username): + pass + + def on_check(self, username): + pass + + def login_screen(self, from_page='..', username='', error_msg='', **kwargs): + return ntob(""" +Message: %(error_msg)s +
+ Login:
+ Password:
+
+ +
+""" % {'from_page': from_page, 'username': username, + 'error_msg': error_msg}, "utf-8") + + def do_login(self, username, password, from_page='..', **kwargs): + """Login. May raise redirect, or return True if request handled.""" + response = cherrypy.serving.response + error_msg = self.check_username_and_password(username, password) + if error_msg: + body = self.login_screen(from_page, username, error_msg) + response.body = body + if "Content-Length" in response.headers: + # Delete Content-Length header so finalize() recalcs it. + del response.headers["Content-Length"] + return True + else: + cherrypy.serving.request.login = username + cherrypy.session[self.session_key] = username + self.on_login(username) + raise cherrypy.HTTPRedirect(from_page or "/") + + def do_logout(self, from_page='..', **kwargs): + """Logout. May raise redirect, or return True if request handled.""" + sess = cherrypy.session + username = sess.get(self.session_key) + sess[self.session_key] = None + if username: + cherrypy.serving.request.login = None + self.on_logout(username) + raise cherrypy.HTTPRedirect(from_page) + + def do_check(self): + """Assert username. May raise redirect, or return True if request handled.""" + sess = cherrypy.session + request = cherrypy.serving.request + response = cherrypy.serving.response + + username = sess.get(self.session_key) + if not username: + sess[self.session_key] = username = self.anonymous() + if self.debug: + cherrypy.log('No session[username], trying anonymous', 'TOOLS.SESSAUTH') + if not username: + url = cherrypy.url(qs=request.query_string) + if self.debug: + cherrypy.log('No username, routing to login_screen with ' + 'from_page %r' % url, 'TOOLS.SESSAUTH') + response.body = self.login_screen(url) + if "Content-Length" in response.headers: + # Delete Content-Length header so finalize() recalcs it. + del response.headers["Content-Length"] + return True + if self.debug: + cherrypy.log('Setting request.login to %r' % username, 'TOOLS.SESSAUTH') + request.login = username + self.on_check(username) + + def run(self): + request = cherrypy.serving.request + response = cherrypy.serving.response + + path = request.path_info + if path.endswith('login_screen'): + if self.debug: + cherrypy.log('routing %r to login_screen' % path, 'TOOLS.SESSAUTH') + return self.login_screen(**request.params) + elif path.endswith('do_login'): + if request.method != 'POST': + response.headers['Allow'] = "POST" + if self.debug: + cherrypy.log('do_login requires POST', 'TOOLS.SESSAUTH') + raise cherrypy.HTTPError(405) + if self.debug: + cherrypy.log('routing %r to do_login' % path, 'TOOLS.SESSAUTH') + return self.do_login(**request.params) + elif path.endswith('do_logout'): + if request.method != 'POST': + response.headers['Allow'] = "POST" + raise cherrypy.HTTPError(405) + if self.debug: + cherrypy.log('routing %r to do_logout' % path, 'TOOLS.SESSAUTH') + return self.do_logout(**request.params) + else: + if self.debug: + cherrypy.log('No special path, running do_check', 'TOOLS.SESSAUTH') + return self.do_check() + + +def session_auth(**kwargs): + sa = SessionAuth() + for k, v in kwargs.items(): + setattr(sa, k, v) + return sa.run() +session_auth.__doc__ = """Session authentication hook. + +Any attribute of the SessionAuth class may be overridden via a keyword arg +to this function: + +""" + "\n".join(["%s: %s" % (k, type(getattr(SessionAuth, k)).__name__) + for k in dir(SessionAuth) if not k.startswith("__")]) + + +def log_traceback(severity=logging.ERROR, debug=False): + """Write the last error's traceback to the cherrypy error log.""" + cherrypy.log("", "HTTP", severity=severity, traceback=True) + +def log_request_headers(debug=False): + """Write request headers to the cherrypy error log.""" + h = [" %s: %s" % (k, v) for k, v in cherrypy.serving.request.header_list] + cherrypy.log('\nRequest Headers:\n' + '\n'.join(h), "HTTP") + +def log_hooks(debug=False): + """Write request.hooks to the cherrypy error log.""" + request = cherrypy.serving.request + + msg = [] + # Sort by the standard points if possible. + from cherrypy import _cprequest + points = _cprequest.hookpoints + for k in request.hooks.keys(): + if k not in points: + points.append(k) + + for k in points: + msg.append(" %s:" % k) + v = request.hooks.get(k, []) + v.sort() + for h in v: + msg.append(" %r" % h) + cherrypy.log('\nRequest Hooks for ' + cherrypy.url() + + ':\n' + '\n'.join(msg), "HTTP") + +def redirect(url='', internal=True, debug=False): + """Raise InternalRedirect or HTTPRedirect to the given url.""" + if debug: + cherrypy.log('Redirecting %sto: %s' % + ({True: 'internal ', False: ''}[internal], url), + 'TOOLS.REDIRECT') + if internal: + raise cherrypy.InternalRedirect(url) + else: + raise cherrypy.HTTPRedirect(url) + +def trailing_slash(missing=True, extra=False, status=None, debug=False): + """Redirect if path_info has (missing|extra) trailing slash.""" + request = cherrypy.serving.request + pi = request.path_info + + if debug: + cherrypy.log('is_index: %r, missing: %r, extra: %r, path_info: %r' % + (request.is_index, missing, extra, pi), + 'TOOLS.TRAILING_SLASH') + if request.is_index is True: + if missing: + if not pi.endswith('/'): + new_url = cherrypy.url(pi + '/', request.query_string) + raise cherrypy.HTTPRedirect(new_url, status=status or 301) + elif request.is_index is False: + if extra: + # If pi == '/', don't redirect to ''! + if pi.endswith('/') and pi != '/': + new_url = cherrypy.url(pi[:-1], request.query_string) + raise cherrypy.HTTPRedirect(new_url, status=status or 301) + +def flatten(debug=False): + """Wrap response.body in a generator that recursively iterates over body. + + This allows cherrypy.response.body to consist of 'nested generators'; + that is, a set of generators that yield generators. + """ + import types + def flattener(input): + numchunks = 0 + for x in input: + if not isinstance(x, types.GeneratorType): + numchunks += 1 + yield x + else: + for y in flattener(x): + numchunks += 1 + yield y + if debug: + cherrypy.log('Flattened %d chunks' % numchunks, 'TOOLS.FLATTEN') + response = cherrypy.serving.response + response.body = flattener(response.body) + + +def accept(media=None, debug=False): + """Return the client's preferred media-type (from the given Content-Types). + + If 'media' is None (the default), no test will be performed. + + If 'media' is provided, it should be the Content-Type value (as a string) + or values (as a list or tuple of strings) which the current resource + can emit. The client's acceptable media ranges (as declared in the + Accept request header) will be matched in order to these Content-Type + values; the first such string is returned. That is, the return value + will always be one of the strings provided in the 'media' arg (or None + if 'media' is None). + + If no match is found, then HTTPError 406 (Not Acceptable) is raised. + Note that most web browsers send */* as a (low-quality) acceptable + media range, which should match any Content-Type. In addition, "...if + no Accept header field is present, then it is assumed that the client + accepts all media types." + + Matching types are checked in order of client preference first, + and then in the order of the given 'media' values. + + Note that this function does not honor accept-params (other than "q"). + """ + if not media: + return + if isinstance(media, basestring): + media = [media] + request = cherrypy.serving.request + + # Parse the Accept request header, and try to match one + # of the requested media-ranges (in order of preference). + ranges = request.headers.elements('Accept') + if not ranges: + # Any media type is acceptable. + if debug: + cherrypy.log('No Accept header elements', 'TOOLS.ACCEPT') + return media[0] + else: + # Note that 'ranges' is sorted in order of preference + for element in ranges: + if element.qvalue > 0: + if element.value == "*/*": + # Matches any type or subtype + if debug: + cherrypy.log('Match due to */*', 'TOOLS.ACCEPT') + return media[0] + elif element.value.endswith("/*"): + # Matches any subtype + mtype = element.value[:-1] # Keep the slash + for m in media: + if m.startswith(mtype): + if debug: + cherrypy.log('Match due to %s' % element.value, + 'TOOLS.ACCEPT') + return m + else: + # Matches exact value + if element.value in media: + if debug: + cherrypy.log('Match due to %s' % element.value, + 'TOOLS.ACCEPT') + return element.value + + # No suitable media-range found. + ah = request.headers.get('Accept') + if ah is None: + msg = "Your client did not send an Accept header." + else: + msg = "Your client sent this Accept header: %s." % ah + msg += (" But this resource only emits these media types: %s." % + ", ".join(media)) + raise cherrypy.HTTPError(406, msg) + + +class MonitoredHeaderMap(_httputil.HeaderMap): + + def __init__(self): + self.accessed_headers = set() + + def __getitem__(self, key): + self.accessed_headers.add(key) + return _httputil.HeaderMap.__getitem__(self, key) + + def __contains__(self, key): + self.accessed_headers.add(key) + return _httputil.HeaderMap.__contains__(self, key) + + def get(self, key, default=None): + self.accessed_headers.add(key) + return _httputil.HeaderMap.get(self, key, default=default) + + def has_key(self, key): + self.accessed_headers.add(key) + return _httputil.HeaderMap.has_key(self, key) + + +def autovary(ignore=None, debug=False): + """Auto-populate the Vary response header based on request.header access.""" + request = cherrypy.serving.request + + req_h = request.headers + request.headers = MonitoredHeaderMap() + request.headers.update(req_h) + if ignore is None: + ignore = set(['Content-Disposition', 'Content-Length', 'Content-Type']) + + def set_response_header(): + resp_h = cherrypy.serving.response.headers + v = set([e.value for e in resp_h.elements('Vary')]) + if debug: + cherrypy.log('Accessed headers: %s' % request.headers.accessed_headers, + 'TOOLS.AUTOVARY') + v = v.union(request.headers.accessed_headers) + v = v.difference(ignore) + v = list(v) + v.sort() + resp_h['Vary'] = ', '.join(v) + request.hooks.attach('before_finalize', set_response_header, 95) + diff --git a/cherrypy/lib/encoding.py b/cherrypy/lib/encoding.py new file mode 100644 index 00000000..64597465 --- /dev/null +++ b/cherrypy/lib/encoding.py @@ -0,0 +1,388 @@ +import struct +import time + +import cherrypy +from cherrypy._cpcompat import basestring, BytesIO, ntob, set, unicodestr +from cherrypy.lib import file_generator +from cherrypy.lib import set_vary_header + + +def decode(encoding=None, default_encoding='utf-8'): + """Replace or extend the list of charsets used to decode a request entity. + + Either argument may be a single string or a list of strings. + + encoding + If not None, restricts the set of charsets attempted while decoding + a request entity to the given set (even if a different charset is given in + the Content-Type request header). + + default_encoding + Only in effect if the 'encoding' argument is not given. + If given, the set of charsets attempted while decoding a request entity is + *extended* with the given value(s). + + """ + body = cherrypy.request.body + if encoding is not None: + if not isinstance(encoding, list): + encoding = [encoding] + body.attempt_charsets = encoding + elif default_encoding: + if not isinstance(default_encoding, list): + default_encoding = [default_encoding] + body.attempt_charsets = body.attempt_charsets + default_encoding + + +class ResponseEncoder: + + default_encoding = 'utf-8' + failmsg = "Response body could not be encoded with %r." + encoding = None + errors = 'strict' + text_only = True + add_charset = True + debug = False + + def __init__(self, **kwargs): + for k, v in kwargs.items(): + setattr(self, k, v) + + self.attempted_charsets = set() + request = cherrypy.serving.request + if request.handler is not None: + # Replace request.handler with self + if self.debug: + cherrypy.log('Replacing request.handler', 'TOOLS.ENCODE') + self.oldhandler = request.handler + request.handler = self + + def encode_stream(self, encoding): + """Encode a streaming response body. + + Use a generator wrapper, and just pray it works as the stream is + being written out. + """ + if encoding in self.attempted_charsets: + return False + self.attempted_charsets.add(encoding) + + def encoder(body): + for chunk in body: + if isinstance(chunk, unicodestr): + chunk = chunk.encode(encoding, self.errors) + yield chunk + self.body = encoder(self.body) + return True + + def encode_string(self, encoding): + """Encode a buffered response body.""" + if encoding in self.attempted_charsets: + return False + self.attempted_charsets.add(encoding) + + try: + body = [] + for chunk in self.body: + if isinstance(chunk, unicodestr): + chunk = chunk.encode(encoding, self.errors) + body.append(chunk) + self.body = body + except (LookupError, UnicodeError): + return False + else: + return True + + def find_acceptable_charset(self): + request = cherrypy.serving.request + response = cherrypy.serving.response + + if self.debug: + cherrypy.log('response.stream %r' % response.stream, 'TOOLS.ENCODE') + if response.stream: + encoder = self.encode_stream + else: + encoder = self.encode_string + if "Content-Length" in response.headers: + # Delete Content-Length header so finalize() recalcs it. + # Encoded strings may be of different lengths from their + # unicode equivalents, and even from each other. For example: + # >>> t = u"\u7007\u3040" + # >>> len(t) + # 2 + # >>> len(t.encode("UTF-8")) + # 6 + # >>> len(t.encode("utf7")) + # 8 + del response.headers["Content-Length"] + + # Parse the Accept-Charset request header, and try to provide one + # of the requested charsets (in order of user preference). + encs = request.headers.elements('Accept-Charset') + charsets = [enc.value.lower() for enc in encs] + if self.debug: + cherrypy.log('charsets %s' % repr(charsets), 'TOOLS.ENCODE') + + if self.encoding is not None: + # If specified, force this encoding to be used, or fail. + encoding = self.encoding.lower() + if self.debug: + cherrypy.log('Specified encoding %r' % encoding, 'TOOLS.ENCODE') + if (not charsets) or "*" in charsets or encoding in charsets: + if self.debug: + cherrypy.log('Attempting encoding %r' % encoding, 'TOOLS.ENCODE') + if encoder(encoding): + return encoding + else: + if not encs: + if self.debug: + cherrypy.log('Attempting default encoding %r' % + self.default_encoding, 'TOOLS.ENCODE') + # Any character-set is acceptable. + if encoder(self.default_encoding): + return self.default_encoding + else: + raise cherrypy.HTTPError(500, self.failmsg % self.default_encoding) + else: + for element in encs: + if element.qvalue > 0: + if element.value == "*": + # Matches any charset. Try our default. + if self.debug: + cherrypy.log('Attempting default encoding due ' + 'to %r' % element, 'TOOLS.ENCODE') + if encoder(self.default_encoding): + return self.default_encoding + else: + encoding = element.value + if self.debug: + cherrypy.log('Attempting encoding %s (qvalue >' + '0)' % element, 'TOOLS.ENCODE') + if encoder(encoding): + return encoding + + if "*" not in charsets: + # If no "*" is present in an Accept-Charset field, then all + # character sets not explicitly mentioned get a quality + # value of 0, except for ISO-8859-1, which gets a quality + # value of 1 if not explicitly mentioned. + iso = 'iso-8859-1' + if iso not in charsets: + if self.debug: + cherrypy.log('Attempting ISO-8859-1 encoding', + 'TOOLS.ENCODE') + if encoder(iso): + return iso + + # No suitable encoding found. + ac = request.headers.get('Accept-Charset') + if ac is None: + msg = "Your client did not send an Accept-Charset header." + else: + msg = "Your client sent this Accept-Charset header: %s." % ac + msg += " We tried these charsets: %s." % ", ".join(self.attempted_charsets) + raise cherrypy.HTTPError(406, msg) + + def __call__(self, *args, **kwargs): + response = cherrypy.serving.response + self.body = self.oldhandler(*args, **kwargs) + + if isinstance(self.body, basestring): + # strings get wrapped in a list because iterating over a single + # item list is much faster than iterating over every character + # in a long string. + if self.body: + self.body = [self.body] + else: + # [''] doesn't evaluate to False, so replace it with []. + self.body = [] + elif hasattr(self.body, 'read'): + self.body = file_generator(self.body) + elif self.body is None: + self.body = [] + + ct = response.headers.elements("Content-Type") + if self.debug: + cherrypy.log('Content-Type: %r' % [str(h) for h in ct], 'TOOLS.ENCODE') + if ct: + ct = ct[0] + if self.text_only: + if ct.value.lower().startswith("text/"): + if self.debug: + cherrypy.log('Content-Type %s starts with "text/"' % ct, + 'TOOLS.ENCODE') + do_find = True + else: + if self.debug: + cherrypy.log('Not finding because Content-Type %s does ' + 'not start with "text/"' % ct, + 'TOOLS.ENCODE') + do_find = False + else: + if self.debug: + cherrypy.log('Finding because not text_only', 'TOOLS.ENCODE') + do_find = True + + if do_find: + # Set "charset=..." param on response Content-Type header + ct.params['charset'] = self.find_acceptable_charset() + if self.add_charset: + if self.debug: + cherrypy.log('Setting Content-Type %s' % ct, + 'TOOLS.ENCODE') + response.headers["Content-Type"] = str(ct) + + return self.body + +# GZIP + +def compress(body, compress_level): + """Compress 'body' at the given compress_level.""" + import zlib + + # See http://www.gzip.org/zlib/rfc-gzip.html + yield ntob('\x1f\x8b') # ID1 and ID2: gzip marker + yield ntob('\x08') # CM: compression method + yield ntob('\x00') # FLG: none set + # MTIME: 4 bytes + yield struct.pack(" 0 is present + * The 'identity' value is given with a qvalue > 0. + + """ + request = cherrypy.serving.request + response = cherrypy.serving.response + + set_vary_header(response, "Accept-Encoding") + + if not response.body: + # Response body is empty (might be a 304 for instance) + if debug: + cherrypy.log('No response body', context='TOOLS.GZIP') + return + + # If returning cached content (which should already have been gzipped), + # don't re-zip. + if getattr(request, "cached", False): + if debug: + cherrypy.log('Not gzipping cached response', context='TOOLS.GZIP') + return + + acceptable = request.headers.elements('Accept-Encoding') + if not acceptable: + # If no Accept-Encoding field is present in a request, + # the server MAY assume that the client will accept any + # content coding. In this case, if "identity" is one of + # the available content-codings, then the server SHOULD use + # the "identity" content-coding, unless it has additional + # information that a different content-coding is meaningful + # to the client. + if debug: + cherrypy.log('No Accept-Encoding', context='TOOLS.GZIP') + return + + ct = response.headers.get('Content-Type', '').split(';')[0] + for coding in acceptable: + if coding.value == 'identity' and coding.qvalue != 0: + if debug: + cherrypy.log('Non-zero identity qvalue: %s' % coding, + context='TOOLS.GZIP') + return + if coding.value in ('gzip', 'x-gzip'): + if coding.qvalue == 0: + if debug: + cherrypy.log('Zero gzip qvalue: %s' % coding, + context='TOOLS.GZIP') + return + + if ct not in mime_types: + # If the list of provided mime-types contains tokens + # such as 'text/*' or 'application/*+xml', + # we go through them and find the most appropriate one + # based on the given content-type. + # The pattern matching is only caring about the most + # common cases, as stated above, and doesn't support + # for extra parameters. + found = False + if '/' in ct: + ct_media_type, ct_sub_type = ct.split('/') + for mime_type in mime_types: + if '/' in mime_type: + media_type, sub_type = mime_type.split('/') + if ct_media_type == media_type: + if sub_type == '*': + found = True + break + elif '+' in sub_type and '+' in ct_sub_type: + ct_left, ct_right = ct_sub_type.split('+') + left, right = sub_type.split('+') + if left == '*' and ct_right == right: + found = True + break + + if not found: + if debug: + cherrypy.log('Content-Type %s not in mime_types %r' % + (ct, mime_types), context='TOOLS.GZIP') + return + + if debug: + cherrypy.log('Gzipping', context='TOOLS.GZIP') + # Return a generator that compresses the page + response.headers['Content-Encoding'] = 'gzip' + response.body = compress(response.body, compress_level) + if "Content-Length" in response.headers: + # Delete Content-Length header so finalize() recalcs it. + del response.headers["Content-Length"] + + return + + if debug: + cherrypy.log('No acceptable encoding found.', context='GZIP') + cherrypy.HTTPError(406, "identity, gzip").set_response() + diff --git a/cherrypy/lib/http.py b/cherrypy/lib/http.py new file mode 100644 index 00000000..4661d69e --- /dev/null +++ b/cherrypy/lib/http.py @@ -0,0 +1,7 @@ +import warnings +warnings.warn('cherrypy.lib.http has been deprecated and will be removed ' + 'in CherryPy 3.3 use cherrypy.lib.httputil instead.', + DeprecationWarning) + +from cherrypy.lib.httputil import * + diff --git a/cherrypy/lib/httpauth.py b/cherrypy/lib/httpauth.py new file mode 100644 index 00000000..ad7c6eba --- /dev/null +++ b/cherrypy/lib/httpauth.py @@ -0,0 +1,354 @@ +""" +This module defines functions to implement HTTP Digest Authentication (:rfc:`2617`). +This has full compliance with 'Digest' and 'Basic' authentication methods. In +'Digest' it supports both MD5 and MD5-sess algorithms. + +Usage: + First use 'doAuth' to request the client authentication for a + certain resource. You should send an httplib.UNAUTHORIZED response to the + client so he knows he has to authenticate itself. + + Then use 'parseAuthorization' to retrieve the 'auth_map' used in + 'checkResponse'. + + To use 'checkResponse' you must have already verified the password associated + with the 'username' key in 'auth_map' dict. Then you use the 'checkResponse' + function to verify if the password matches the one sent by the client. + +SUPPORTED_ALGORITHM - list of supported 'Digest' algorithms +SUPPORTED_QOP - list of supported 'Digest' 'qop'. +""" +__version__ = 1, 0, 1 +__author__ = "Tiago Cogumbreiro " +__credits__ = """ + Peter van Kampen for its recipe which implement most of Digest authentication: + http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/302378 +""" + +__license__ = """ +Copyright (c) 2005, Tiago Cogumbreiro +All rights reserved. + +Redistribution and use in source and binary forms, with or without modification, +are permitted provided that the following conditions are met: + + * Redistributions of source code must retain the above copyright notice, + this list of conditions and the following disclaimer. + * Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. + * Neither the name of Sylvain Hellegouarch nor the names of his contributors + may be used to endorse or promote products derived from this software + without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND +ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE +FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +""" + +__all__ = ("digestAuth", "basicAuth", "doAuth", "checkResponse", + "parseAuthorization", "SUPPORTED_ALGORITHM", "md5SessionKey", + "calculateNonce", "SUPPORTED_QOP") + +################################################################################ +import time +from cherrypy._cpcompat import base64_decode, ntob, md5 +from cherrypy._cpcompat import parse_http_list, parse_keqv_list + +MD5 = "MD5" +MD5_SESS = "MD5-sess" +AUTH = "auth" +AUTH_INT = "auth-int" + +SUPPORTED_ALGORITHM = (MD5, MD5_SESS) +SUPPORTED_QOP = (AUTH, AUTH_INT) + +################################################################################ +# doAuth +# +DIGEST_AUTH_ENCODERS = { + MD5: lambda val: md5(ntob(val)).hexdigest(), + MD5_SESS: lambda val: md5(ntob(val)).hexdigest(), +# SHA: lambda val: sha.new(ntob(val)).hexdigest (), +} + +def calculateNonce (realm, algorithm = MD5): + """This is an auxaliary function that calculates 'nonce' value. It is used + to handle sessions.""" + + global SUPPORTED_ALGORITHM, DIGEST_AUTH_ENCODERS + assert algorithm in SUPPORTED_ALGORITHM + + try: + encoder = DIGEST_AUTH_ENCODERS[algorithm] + except KeyError: + raise NotImplementedError ("The chosen algorithm (%s) does not have "\ + "an implementation yet" % algorithm) + + return encoder ("%d:%s" % (time.time(), realm)) + +def digestAuth (realm, algorithm = MD5, nonce = None, qop = AUTH): + """Challenges the client for a Digest authentication.""" + global SUPPORTED_ALGORITHM, DIGEST_AUTH_ENCODERS, SUPPORTED_QOP + assert algorithm in SUPPORTED_ALGORITHM + assert qop in SUPPORTED_QOP + + if nonce is None: + nonce = calculateNonce (realm, algorithm) + + return 'Digest realm="%s", nonce="%s", algorithm="%s", qop="%s"' % ( + realm, nonce, algorithm, qop + ) + +def basicAuth (realm): + """Challengenes the client for a Basic authentication.""" + assert '"' not in realm, "Realms cannot contain the \" (quote) character." + + return 'Basic realm="%s"' % realm + +def doAuth (realm): + """'doAuth' function returns the challenge string b giving priority over + Digest and fallback to Basic authentication when the browser doesn't + support the first one. + + This should be set in the HTTP header under the key 'WWW-Authenticate'.""" + + return digestAuth (realm) + " " + basicAuth (realm) + + +################################################################################ +# Parse authorization parameters +# +def _parseDigestAuthorization (auth_params): + # Convert the auth params to a dict + items = parse_http_list(auth_params) + params = parse_keqv_list(items) + + # Now validate the params + + # Check for required parameters + required = ["username", "realm", "nonce", "uri", "response"] + for k in required: + if k not in params: + return None + + # If qop is sent then cnonce and nc MUST be present + if "qop" in params and not ("cnonce" in params \ + and "nc" in params): + return None + + # If qop is not sent, neither cnonce nor nc can be present + if ("cnonce" in params or "nc" in params) and \ + "qop" not in params: + return None + + return params + + +def _parseBasicAuthorization (auth_params): + username, password = base64_decode(auth_params).split(":", 1) + return {"username": username, "password": password} + +AUTH_SCHEMES = { + "basic": _parseBasicAuthorization, + "digest": _parseDigestAuthorization, +} + +def parseAuthorization (credentials): + """parseAuthorization will convert the value of the 'Authorization' key in + the HTTP header to a map itself. If the parsing fails 'None' is returned. + """ + + global AUTH_SCHEMES + + auth_scheme, auth_params = credentials.split(" ", 1) + auth_scheme = auth_scheme.lower () + + parser = AUTH_SCHEMES[auth_scheme] + params = parser (auth_params) + + if params is None: + return + + assert "auth_scheme" not in params + params["auth_scheme"] = auth_scheme + return params + + +################################################################################ +# Check provided response for a valid password +# +def md5SessionKey (params, password): + """ + If the "algorithm" directive's value is "MD5-sess", then A1 + [the session key] is calculated only once - on the first request by the + client following receipt of a WWW-Authenticate challenge from the server. + + This creates a 'session key' for the authentication of subsequent + requests and responses which is different for each "authentication + session", thus limiting the amount of material hashed with any one + key. + + Because the server need only use the hash of the user + credentials in order to create the A1 value, this construction could + be used in conjunction with a third party authentication service so + that the web server would not need the actual password value. The + specification of such a protocol is beyond the scope of this + specification. +""" + + keys = ("username", "realm", "nonce", "cnonce") + params_copy = {} + for key in keys: + params_copy[key] = params[key] + + params_copy["algorithm"] = MD5_SESS + return _A1 (params_copy, password) + +def _A1(params, password): + algorithm = params.get ("algorithm", MD5) + H = DIGEST_AUTH_ENCODERS[algorithm] + + if algorithm == MD5: + # If the "algorithm" directive's value is "MD5" or is + # unspecified, then A1 is: + # A1 = unq(username-value) ":" unq(realm-value) ":" passwd + return "%s:%s:%s" % (params["username"], params["realm"], password) + + elif algorithm == MD5_SESS: + + # This is A1 if qop is set + # A1 = H( unq(username-value) ":" unq(realm-value) ":" passwd ) + # ":" unq(nonce-value) ":" unq(cnonce-value) + h_a1 = H ("%s:%s:%s" % (params["username"], params["realm"], password)) + return "%s:%s:%s" % (h_a1, params["nonce"], params["cnonce"]) + + +def _A2(params, method, kwargs): + # If the "qop" directive's value is "auth" or is unspecified, then A2 is: + # A2 = Method ":" digest-uri-value + + qop = params.get ("qop", "auth") + if qop == "auth": + return method + ":" + params["uri"] + elif qop == "auth-int": + # If the "qop" value is "auth-int", then A2 is: + # A2 = Method ":" digest-uri-value ":" H(entity-body) + entity_body = kwargs.get ("entity_body", "") + H = kwargs["H"] + + return "%s:%s:%s" % ( + method, + params["uri"], + H(entity_body) + ) + + else: + raise NotImplementedError ("The 'qop' method is unknown: %s" % qop) + +def _computeDigestResponse(auth_map, password, method = "GET", A1 = None,**kwargs): + """ + Generates a response respecting the algorithm defined in RFC 2617 + """ + params = auth_map + + algorithm = params.get ("algorithm", MD5) + + H = DIGEST_AUTH_ENCODERS[algorithm] + KD = lambda secret, data: H(secret + ":" + data) + + qop = params.get ("qop", None) + + H_A2 = H(_A2(params, method, kwargs)) + + if algorithm == MD5_SESS and A1 is not None: + H_A1 = H(A1) + else: + H_A1 = H(_A1(params, password)) + + if qop in ("auth", "auth-int"): + # If the "qop" value is "auth" or "auth-int": + # request-digest = <"> < KD ( H(A1), unq(nonce-value) + # ":" nc-value + # ":" unq(cnonce-value) + # ":" unq(qop-value) + # ":" H(A2) + # ) <"> + request = "%s:%s:%s:%s:%s" % ( + params["nonce"], + params["nc"], + params["cnonce"], + params["qop"], + H_A2, + ) + elif qop is None: + # If the "qop" directive is not present (this construction is + # for compatibility with RFC 2069): + # request-digest = + # <"> < KD ( H(A1), unq(nonce-value) ":" H(A2) ) > <"> + request = "%s:%s" % (params["nonce"], H_A2) + + return KD(H_A1, request) + +def _checkDigestResponse(auth_map, password, method = "GET", A1 = None, **kwargs): + """This function is used to verify the response given by the client when + he tries to authenticate. + Optional arguments: + entity_body - when 'qop' is set to 'auth-int' you MUST provide the + raw data you are going to send to the client (usually the + HTML page. + request_uri - the uri from the request line compared with the 'uri' + directive of the authorization map. They must represent + the same resource (unused at this time). + """ + + if auth_map['realm'] != kwargs.get('realm', None): + return False + + response = _computeDigestResponse(auth_map, password, method, A1,**kwargs) + + return response == auth_map["response"] + +def _checkBasicResponse (auth_map, password, method='GET', encrypt=None, **kwargs): + # Note that the Basic response doesn't provide the realm value so we cannot + # test it + try: + return encrypt(auth_map["password"], auth_map["username"]) == password + except TypeError: + return encrypt(auth_map["password"]) == password + +AUTH_RESPONSES = { + "basic": _checkBasicResponse, + "digest": _checkDigestResponse, +} + +def checkResponse (auth_map, password, method = "GET", encrypt=None, **kwargs): + """'checkResponse' compares the auth_map with the password and optionally + other arguments that each implementation might need. + + If the response is of type 'Basic' then the function has the following + signature:: + + checkBasicResponse (auth_map, password) -> bool + + If the response is of type 'Digest' then the function has the following + signature:: + + checkDigestResponse (auth_map, password, method = 'GET', A1 = None) -> bool + + The 'A1' argument is only used in MD5_SESS algorithm based responses. + Check md5SessionKey() for more info. + """ + checker = AUTH_RESPONSES[auth_map["auth_scheme"]] + return checker (auth_map, password, method=method, encrypt=encrypt, **kwargs) + + + + diff --git a/cherrypy/lib/httputil.py b/cherrypy/lib/httputil.py new file mode 100644 index 00000000..e0058751 --- /dev/null +++ b/cherrypy/lib/httputil.py @@ -0,0 +1,469 @@ +"""HTTP library functions. + +This module contains functions for building an HTTP application +framework: any one, not just one whose name starts with "Ch". ;) If you +reference any modules from some popular framework inside *this* module, +FuManChu will personally hang you up by your thumbs and submit you +to a public caning. +""" + +from binascii import b2a_base64 +from cherrypy._cpcompat import BaseHTTPRequestHandler, HTTPDate, ntob, ntou, reversed, sorted +from cherrypy._cpcompat import basestring, iteritems, unicodestr, unquote_qs +response_codes = BaseHTTPRequestHandler.responses.copy() + +# From http://www.cherrypy.org/ticket/361 +response_codes[500] = ('Internal Server Error', + 'The server encountered an unexpected condition ' + 'which prevented it from fulfilling the request.') +response_codes[503] = ('Service Unavailable', + 'The server is currently unable to handle the ' + 'request due to a temporary overloading or ' + 'maintenance of the server.') + +import re +import urllib + + + +def urljoin(*atoms): + """Return the given path \*atoms, joined into a single URL. + + This will correctly join a SCRIPT_NAME and PATH_INFO into the + original URL, even if either atom is blank. + """ + url = "/".join([x for x in atoms if x]) + while "//" in url: + url = url.replace("//", "/") + # Special-case the final url of "", and return "/" instead. + return url or "/" + +def protocol_from_http(protocol_str): + """Return a protocol tuple from the given 'HTTP/x.y' string.""" + return int(protocol_str[5]), int(protocol_str[7]) + +def get_ranges(headervalue, content_length): + """Return a list of (start, stop) indices from a Range header, or None. + + Each (start, stop) tuple will be composed of two ints, which are suitable + for use in a slicing operation. That is, the header "Range: bytes=3-6", + if applied against a Python string, is requesting resource[3:7]. This + function will return the list [(3, 7)]. + + If this function returns an empty list, you should return HTTP 416. + """ + + if not headervalue: + return None + + result = [] + bytesunit, byteranges = headervalue.split("=", 1) + for brange in byteranges.split(","): + start, stop = [x.strip() for x in brange.split("-", 1)] + if start: + if not stop: + stop = content_length - 1 + start, stop = int(start), int(stop) + if start >= content_length: + # From rfc 2616 sec 14.16: + # "If the server receives a request (other than one + # including an If-Range request-header field) with an + # unsatisfiable Range request-header field (that is, + # all of whose byte-range-spec values have a first-byte-pos + # value greater than the current length of the selected + # resource), it SHOULD return a response code of 416 + # (Requested range not satisfiable)." + continue + if stop < start: + # From rfc 2616 sec 14.16: + # "If the server ignores a byte-range-spec because it + # is syntactically invalid, the server SHOULD treat + # the request as if the invalid Range header field + # did not exist. (Normally, this means return a 200 + # response containing the full entity)." + return None + result.append((start, stop + 1)) + else: + if not stop: + # See rfc quote above. + return None + # Negative subscript (last N bytes) + result.append((content_length - int(stop), content_length)) + + return result + + +class HeaderElement(object): + """An element (with parameters) from an HTTP header's element list.""" + + def __init__(self, value, params=None): + self.value = value + if params is None: + params = {} + self.params = params + + def __cmp__(self, other): + return cmp(self.value, other.value) + + def __str__(self): + p = [";%s=%s" % (k, v) for k, v in iteritems(self.params)] + return "%s%s" % (self.value, "".join(p)) + + def __unicode__(self): + return ntou(self.__str__()) + + def parse(elementstr): + """Transform 'token;key=val' to ('token', {'key': 'val'}).""" + # Split the element into a value and parameters. The 'value' may + # be of the form, "token=token", but we don't split that here. + atoms = [x.strip() for x in elementstr.split(";") if x.strip()] + if not atoms: + initial_value = '' + else: + initial_value = atoms.pop(0).strip() + params = {} + for atom in atoms: + atom = [x.strip() for x in atom.split("=", 1) if x.strip()] + key = atom.pop(0) + if atom: + val = atom[0] + else: + val = "" + params[key] = val + return initial_value, params + parse = staticmethod(parse) + + def from_str(cls, elementstr): + """Construct an instance from a string of the form 'token;key=val'.""" + ival, params = cls.parse(elementstr) + return cls(ival, params) + from_str = classmethod(from_str) + + +q_separator = re.compile(r'; *q *=') + +class AcceptElement(HeaderElement): + """An element (with parameters) from an Accept* header's element list. + + AcceptElement objects are comparable; the more-preferred object will be + "less than" the less-preferred object. They are also therefore sortable; + if you sort a list of AcceptElement objects, they will be listed in + priority order; the most preferred value will be first. Yes, it should + have been the other way around, but it's too late to fix now. + """ + + def from_str(cls, elementstr): + qvalue = None + # The first "q" parameter (if any) separates the initial + # media-range parameter(s) (if any) from the accept-params. + atoms = q_separator.split(elementstr, 1) + media_range = atoms.pop(0).strip() + if atoms: + # The qvalue for an Accept header can have extensions. The other + # headers cannot, but it's easier to parse them as if they did. + qvalue = HeaderElement.from_str(atoms[0].strip()) + + media_type, params = cls.parse(media_range) + if qvalue is not None: + params["q"] = qvalue + return cls(media_type, params) + from_str = classmethod(from_str) + + def qvalue(self): + val = self.params.get("q", "1") + if isinstance(val, HeaderElement): + val = val.value + return float(val) + qvalue = property(qvalue, doc="The qvalue, or priority, of this value.") + + def __cmp__(self, other): + diff = cmp(self.qvalue, other.qvalue) + if diff == 0: + diff = cmp(str(self), str(other)) + return diff + + +def header_elements(fieldname, fieldvalue): + """Return a sorted HeaderElement list from a comma-separated header string.""" + if not fieldvalue: + return [] + + result = [] + for element in fieldvalue.split(","): + if fieldname.startswith("Accept") or fieldname == 'TE': + hv = AcceptElement.from_str(element) + else: + hv = HeaderElement.from_str(element) + result.append(hv) + + return list(reversed(sorted(result))) + +def decode_TEXT(value): + r"""Decode :rfc:`2047` TEXT (e.g. "=?utf-8?q?f=C3=BCr?=" -> u"f\xfcr").""" + from email.Header import decode_header + atoms = decode_header(value) + decodedvalue = "" + for atom, charset in atoms: + if charset is not None: + atom = atom.decode(charset) + decodedvalue += atom + return decodedvalue + +def valid_status(status): + """Return legal HTTP status Code, Reason-phrase and Message. + + The status arg must be an int, or a str that begins with an int. + + If status is an int, or a str and no reason-phrase is supplied, + a default reason-phrase will be provided. + """ + + if not status: + status = 200 + + status = str(status) + parts = status.split(" ", 1) + if len(parts) == 1: + # No reason supplied. + code, = parts + reason = None + else: + code, reason = parts + reason = reason.strip() + + try: + code = int(code) + except ValueError: + raise ValueError("Illegal response status from server " + "(%s is non-numeric)." % repr(code)) + + if code < 100 or code > 599: + raise ValueError("Illegal response status from server " + "(%s is out of range)." % repr(code)) + + if code not in response_codes: + # code is unknown but not illegal + default_reason, message = "", "" + else: + default_reason, message = response_codes[code] + + if reason is None: + reason = default_reason + + return code, reason, message + + +def _parse_qs(qs, keep_blank_values=0, strict_parsing=0, encoding='utf-8'): + """Parse a query given as a string argument. + + Arguments: + + qs: URL-encoded query string to be parsed + + keep_blank_values: flag indicating whether blank values in + URL encoded queries should be treated as blank strings. A + true value indicates that blanks should be retained as blank + strings. The default false value indicates that blank values + are to be ignored and treated as if they were not included. + + strict_parsing: flag indicating what to do with parsing errors. If + false (the default), errors are silently ignored. If true, + errors raise a ValueError exception. + + Returns a dict, as G-d intended. + """ + pairs = [s2 for s1 in qs.split('&') for s2 in s1.split(';')] + d = {} + for name_value in pairs: + if not name_value and not strict_parsing: + continue + nv = name_value.split('=', 1) + if len(nv) != 2: + if strict_parsing: + raise ValueError("bad query field: %r" % (name_value,)) + # Handle case of a control-name with no equal sign + if keep_blank_values: + nv.append('') + else: + continue + if len(nv[1]) or keep_blank_values: + name = unquote_qs(nv[0], encoding) + value = unquote_qs(nv[1], encoding) + if name in d: + if not isinstance(d[name], list): + d[name] = [d[name]] + d[name].append(value) + else: + d[name] = value + return d + + +image_map_pattern = re.compile(r"[0-9]+,[0-9]+") + +def parse_query_string(query_string, keep_blank_values=True, encoding='utf-8'): + """Build a params dictionary from a query_string. + + Duplicate key/value pairs in the provided query_string will be + returned as {'key': [val1, val2, ...]}. Single key/values will + be returned as strings: {'key': 'value'}. + """ + if image_map_pattern.match(query_string): + # Server-side image map. Map the coords to 'x' and 'y' + # (like CGI::Request does). + pm = query_string.split(",") + pm = {'x': int(pm[0]), 'y': int(pm[1])} + else: + pm = _parse_qs(query_string, keep_blank_values, encoding=encoding) + return pm + + +class CaseInsensitiveDict(dict): + """A case-insensitive dict subclass. + + Each key is changed on entry to str(key).title(). + """ + + def __getitem__(self, key): + return dict.__getitem__(self, str(key).title()) + + def __setitem__(self, key, value): + dict.__setitem__(self, str(key).title(), value) + + def __delitem__(self, key): + dict.__delitem__(self, str(key).title()) + + def __contains__(self, key): + return dict.__contains__(self, str(key).title()) + + def get(self, key, default=None): + return dict.get(self, str(key).title(), default) + + def has_key(self, key): + return dict.has_key(self, str(key).title()) + + def update(self, E): + for k in E.keys(): + self[str(k).title()] = E[k] + + def fromkeys(cls, seq, value=None): + newdict = cls() + for k in seq: + newdict[str(k).title()] = value + return newdict + fromkeys = classmethod(fromkeys) + + def setdefault(self, key, x=None): + key = str(key).title() + try: + return self[key] + except KeyError: + self[key] = x + return x + + def pop(self, key, default): + return dict.pop(self, str(key).title(), default) + + +# TEXT = +# +# A CRLF is allowed in the definition of TEXT only as part of a header +# field continuation. It is expected that the folding LWS will be +# replaced with a single SP before interpretation of the TEXT value." +header_translate_table = ''.join([chr(i) for i in xrange(256)]) +header_translate_deletechars = ''.join([chr(i) for i in xrange(32)]) + chr(127) + + +class HeaderMap(CaseInsensitiveDict): + """A dict subclass for HTTP request and response headers. + + Each key is changed on entry to str(key).title(). This allows headers + to be case-insensitive and avoid duplicates. + + Values are header values (decoded according to :rfc:`2047` if necessary). + """ + + protocol=(1, 1) + encodings = ["ISO-8859-1"] + + # Someday, when http-bis is done, this will probably get dropped + # since few servers, clients, or intermediaries do it. But until then, + # we're going to obey the spec as is. + # "Words of *TEXT MAY contain characters from character sets other than + # ISO-8859-1 only when encoded according to the rules of RFC 2047." + use_rfc_2047 = True + + def elements(self, key): + """Return a sorted list of HeaderElements for the given header.""" + key = str(key).title() + value = self.get(key) + return header_elements(key, value) + + def values(self, key): + """Return a sorted list of HeaderElement.value for the given header.""" + return [e.value for e in self.elements(key)] + + def output(self): + """Transform self into a list of (name, value) tuples.""" + header_list = [] + for k, v in self.items(): + if isinstance(k, unicodestr): + k = self.encode(k) + + if not isinstance(v, basestring): + v = str(v) + + if isinstance(v, unicodestr): + v = self.encode(v) + + # See header_translate_* constants above. + # Replace only if you really know what you're doing. + k = k.translate(header_translate_table, header_translate_deletechars) + v = v.translate(header_translate_table, header_translate_deletechars) + + header_list.append((k, v)) + return header_list + + def encode(self, v): + """Return the given header name or value, encoded for HTTP output.""" + for enc in self.encodings: + try: + return v.encode(enc) + except UnicodeEncodeError: + continue + + if self.protocol == (1, 1) and self.use_rfc_2047: + # Encode RFC-2047 TEXT + # (e.g. u"\u8200" -> "=?utf-8?b?6IiA?="). + # We do our own here instead of using the email module + # because we never want to fold lines--folding has + # been deprecated by the HTTP working group. + v = b2a_base64(v.encode('utf-8')) + return (ntob('=?utf-8?b?') + v.strip(ntob('\n')) + ntob('?=')) + + raise ValueError("Could not encode header part %r using " + "any of the encodings %r." % + (v, self.encodings)) + + +class Host(object): + """An internet address. + + name + Should be the client's host name. If not available (because no DNS + lookup is performed), the IP address should be used instead. + + """ + + ip = "0.0.0.0" + port = 80 + name = "unknown.tld" + + def __init__(self, ip, port, name=None): + self.ip = ip + self.port = port + if name is None: + name = ip + self.name = name + + def __repr__(self): + return "httputil.Host(%r, %r, %r)" % (self.ip, self.port, self.name) diff --git a/cherrypy/lib/jsontools.py b/cherrypy/lib/jsontools.py new file mode 100644 index 00000000..09042e45 --- /dev/null +++ b/cherrypy/lib/jsontools.py @@ -0,0 +1,87 @@ +import sys +import cherrypy +from cherrypy._cpcompat import basestring, ntou, json, json_encode, json_decode + +def json_processor(entity): + """Read application/json data into request.json.""" + if not entity.headers.get(ntou("Content-Length"), ntou("")): + raise cherrypy.HTTPError(411) + + body = entity.fp.read() + try: + cherrypy.serving.request.json = json_decode(body.decode('utf-8')) + except ValueError: + raise cherrypy.HTTPError(400, 'Invalid JSON document') + +def json_in(content_type=[ntou('application/json'), ntou('text/javascript')], + force=True, debug=False, processor = json_processor): + """Add a processor to parse JSON request entities: + The default processor places the parsed data into request.json. + + Incoming request entities which match the given content_type(s) will + be deserialized from JSON to the Python equivalent, and the result + stored at cherrypy.request.json. The 'content_type' argument may + be a Content-Type string or a list of allowable Content-Type strings. + + If the 'force' argument is True (the default), then entities of other + content types will not be allowed; "415 Unsupported Media Type" is + raised instead. + + Supply your own processor to use a custom decoder, or to handle the parsed + data differently. The processor can be configured via + tools.json_in.processor or via the decorator method. + + Note that the deserializer requires the client send a Content-Length + request header, or it will raise "411 Length Required". If for any + other reason the request entity cannot be deserialized from JSON, + it will raise "400 Bad Request: Invalid JSON document". + + You must be using Python 2.6 or greater, or have the 'simplejson' + package importable; otherwise, ValueError is raised during processing. + """ + request = cherrypy.serving.request + if isinstance(content_type, basestring): + content_type = [content_type] + + if force: + if debug: + cherrypy.log('Removing body processors %s' % + repr(request.body.processors.keys()), 'TOOLS.JSON_IN') + request.body.processors.clear() + request.body.default_proc = cherrypy.HTTPError( + 415, 'Expected an entity of content type %s' % + ', '.join(content_type)) + + for ct in content_type: + if debug: + cherrypy.log('Adding body processor for %s' % ct, 'TOOLS.JSON_IN') + request.body.processors[ct] = processor + +def json_handler(*args, **kwargs): + value = cherrypy.serving.request._json_inner_handler(*args, **kwargs) + return json_encode(value) + +def json_out(content_type='application/json', debug=False, handler=json_handler): + """Wrap request.handler to serialize its output to JSON. Sets Content-Type. + + If the given content_type is None, the Content-Type response header + is not set. + + Provide your own handler to use a custom encoder. For example + cherrypy.config['tools.json_out.handler'] = , or + @json_out(handler=function). + + You must be using Python 2.6 or greater, or have the 'simplejson' + package importable; otherwise, ValueError is raised during processing. + """ + request = cherrypy.serving.request + if debug: + cherrypy.log('Replacing %s with JSON handler' % request.handler, + 'TOOLS.JSON_OUT') + request._json_inner_handler = request.handler + request.handler = handler + if content_type is not None: + if debug: + cherrypy.log('Setting Content-Type to %s' % ct, 'TOOLS.JSON_OUT') + cherrypy.serving.response.headers['Content-Type'] = content_type + diff --git a/cherrypy/lib/profiler.py b/cherrypy/lib/profiler.py new file mode 100644 index 00000000..785d58a3 --- /dev/null +++ b/cherrypy/lib/profiler.py @@ -0,0 +1,208 @@ +"""Profiler tools for CherryPy. + +CherryPy users +============== + +You can profile any of your pages as follows:: + + from cherrypy.lib import profiler + + class Root: + p = profile.Profiler("/path/to/profile/dir") + + def index(self): + self.p.run(self._index) + index.exposed = True + + def _index(self): + return "Hello, world!" + + cherrypy.tree.mount(Root()) + +You can also turn on profiling for all requests +using the ``make_app`` function as WSGI middleware. + +CherryPy developers +=================== + +This module can be used whenever you make changes to CherryPy, +to get a quick sanity-check on overall CP performance. Use the +``--profile`` flag when running the test suite. Then, use the ``serve()`` +function to browse the results in a web browser. If you run this +module from the command line, it will call ``serve()`` for you. + +""" + + +def new_func_strip_path(func_name): + """Make profiler output more readable by adding ``__init__`` modules' parents""" + filename, line, name = func_name + if filename.endswith("__init__.py"): + return os.path.basename(filename[:-12]) + filename[-12:], line, name + return os.path.basename(filename), line, name + +try: + import profile + import pstats + pstats.func_strip_path = new_func_strip_path +except ImportError: + profile = None + pstats = None + +import os, os.path +import sys +import warnings + +from cherrypy._cpcompat import BytesIO + +_count = 0 + +class Profiler(object): + + def __init__(self, path=None): + if not path: + path = os.path.join(os.path.dirname(__file__), "profile") + self.path = path + if not os.path.exists(path): + os.makedirs(path) + + def run(self, func, *args, **params): + """Dump profile data into self.path.""" + global _count + c = _count = _count + 1 + path = os.path.join(self.path, "cp_%04d.prof" % c) + prof = profile.Profile() + result = prof.runcall(func, *args, **params) + prof.dump_stats(path) + return result + + def statfiles(self): + """:rtype: list of available profiles. + """ + return [f for f in os.listdir(self.path) + if f.startswith("cp_") and f.endswith(".prof")] + + def stats(self, filename, sortby='cumulative'): + """:rtype stats(index): output of print_stats() for the given profile. + """ + sio = BytesIO() + if sys.version_info >= (2, 5): + s = pstats.Stats(os.path.join(self.path, filename), stream=sio) + s.strip_dirs() + s.sort_stats(sortby) + s.print_stats() + else: + # pstats.Stats before Python 2.5 didn't take a 'stream' arg, + # but just printed to stdout. So re-route stdout. + s = pstats.Stats(os.path.join(self.path, filename)) + s.strip_dirs() + s.sort_stats(sortby) + oldout = sys.stdout + try: + sys.stdout = sio + s.print_stats() + finally: + sys.stdout = oldout + response = sio.getvalue() + sio.close() + return response + + def index(self): + return """ + CherryPy profile data + + + + + + """ + index.exposed = True + + def menu(self): + yield "

Profiling runs

" + yield "

Click on one of the runs below to see profiling data.

" + runs = self.statfiles() + runs.sort() + for i in runs: + yield "%s
" % (i, i) + menu.exposed = True + + def report(self, filename): + import cherrypy + cherrypy.response.headers['Content-Type'] = 'text/plain' + return self.stats(filename) + report.exposed = True + + +class ProfileAggregator(Profiler): + + def __init__(self, path=None): + Profiler.__init__(self, path) + global _count + self.count = _count = _count + 1 + self.profiler = profile.Profile() + + def run(self, func, *args): + path = os.path.join(self.path, "cp_%04d.prof" % self.count) + result = self.profiler.runcall(func, *args) + self.profiler.dump_stats(path) + return result + + +class make_app: + def __init__(self, nextapp, path=None, aggregate=False): + """Make a WSGI middleware app which wraps 'nextapp' with profiling. + + nextapp + the WSGI application to wrap, usually an instance of + cherrypy.Application. + + path + where to dump the profiling output. + + aggregate + if True, profile data for all HTTP requests will go in + a single file. If False (the default), each HTTP request will + dump its profile data into a separate file. + + """ + if profile is None or pstats is None: + msg = ("Your installation of Python does not have a profile module. " + "If you're on Debian, try `sudo apt-get install python-profiler`. " + "See http://www.cherrypy.org/wiki/ProfilingOnDebian for details.") + warnings.warn(msg) + + self.nextapp = nextapp + self.aggregate = aggregate + if aggregate: + self.profiler = ProfileAggregator(path) + else: + self.profiler = Profiler(path) + + def __call__(self, environ, start_response): + def gather(): + result = [] + for line in self.nextapp(environ, start_response): + result.append(line) + return result + return self.profiler.run(gather) + + +def serve(path=None, port=8080): + if profile is None or pstats is None: + msg = ("Your installation of Python does not have a profile module. " + "If you're on Debian, try `sudo apt-get install python-profiler`. " + "See http://www.cherrypy.org/wiki/ProfilingOnDebian for details.") + warnings.warn(msg) + + import cherrypy + cherrypy.config.update({'server.socket_port': int(port), + 'server.thread_pool': 10, + 'environment': "production", + }) + cherrypy.quickstart(Profiler(path)) + + +if __name__ == "__main__": + serve(*tuple(sys.argv[1:])) + diff --git a/cherrypy/lib/reprconf.py b/cherrypy/lib/reprconf.py new file mode 100644 index 00000000..e18949ee --- /dev/null +++ b/cherrypy/lib/reprconf.py @@ -0,0 +1,351 @@ +"""Generic configuration system using unrepr. + +Configuration data may be supplied as a Python dictionary, as a filename, +or as an open file object. When you supply a filename or file, Python's +builtin ConfigParser is used (with some extensions). + +Namespaces +---------- + +Configuration keys are separated into namespaces by the first "." in the key. + +The only key that cannot exist in a namespace is the "environment" entry. +This special entry 'imports' other config entries from a template stored in +the Config.environments dict. + +You can define your own namespaces to be called when new config is merged +by adding a named handler to Config.namespaces. The name can be any string, +and the handler must be either a callable or a context manager. +""" + +try: + # Python 3.0+ + from configparser import ConfigParser +except ImportError: + from ConfigParser import ConfigParser + +try: + set +except NameError: + from sets import Set as set +import sys + +def as_dict(config): + """Return a dict from 'config' whether it is a dict, file, or filename.""" + if isinstance(config, basestring): + config = Parser().dict_from_file(config) + elif hasattr(config, 'read'): + config = Parser().dict_from_file(config) + return config + + +class NamespaceSet(dict): + """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. + """ + + def __call__(self, config): + """Iterate through config and pass it to each namespace handler. + + config + A flat dict, where keys use dots to separate + namespaces, and values are arbitrary. + + The first name in each config key is used to look up the corresponding + namespace handler. For example, a config entry of {'tools.gzip.on': v} + will call the 'tools' namespace handler with the args: ('gzip.on', v) + """ + # Separate the given config into namespaces + ns_confs = {} + for k in config: + if "." in k: + ns, name = k.split(".", 1) + bucket = ns_confs.setdefault(ns, {}) + bucket[name] = config[k] + + # I chose __enter__ and __exit__ so someday this could be + # rewritten using Python 2.5's 'with' statement: + # for ns, handler in self.iteritems(): + # with handler as callable: + # for k, v in ns_confs.get(ns, {}).iteritems(): + # callable(k, v) + for ns, handler in self.items(): + exit = getattr(handler, "__exit__", None) + if exit: + callable = handler.__enter__() + no_exc = True + try: + try: + for k, v in ns_confs.get(ns, {}).items(): + callable(k, v) + except: + # The exceptional case is handled here + no_exc = False + if exit is None: + raise + if not exit(*sys.exc_info()): + raise + # The exception is swallowed if exit() returns true + finally: + # The normal and non-local-goto cases are handled here + if no_exc and exit: + exit(None, None, None) + else: + for k, v in ns_confs.get(ns, {}).items(): + handler(k, v) + + def __repr__(self): + return "%s.%s(%s)" % (self.__module__, self.__class__.__name__, + dict.__repr__(self)) + + def __copy__(self): + newobj = self.__class__() + newobj.update(self) + return newobj + copy = __copy__ + + +class Config(dict): + """A dict-like set of configuration data, with defaults and namespaces. + + May take a file, filename, or dict. + """ + + defaults = {} + environments = {} + namespaces = NamespaceSet() + + def __init__(self, file=None, **kwargs): + self.reset() + if file is not None: + self.update(file) + if kwargs: + self.update(kwargs) + + def reset(self): + """Reset self to default values.""" + self.clear() + dict.update(self, self.defaults) + + def update(self, config): + """Update self from a dict, file or filename.""" + if isinstance(config, basestring): + # Filename + config = Parser().dict_from_file(config) + elif hasattr(config, 'read'): + # Open file object + config = Parser().dict_from_file(config) + else: + config = config.copy() + self._apply(config) + + def _apply(self, config): + """Update self from a dict.""" + which_env = config.get('environment') + if which_env: + env = self.environments[which_env] + for k in env: + if k not in config: + config[k] = env[k] + + dict.update(self, config) + self.namespaces(config) + + def __setitem__(self, k, v): + dict.__setitem__(self, k, v) + self.namespaces({k: v}) + + +class Parser(ConfigParser): + """Sub-class of ConfigParser that keeps the case of options and that + raises an exception if the file cannot be read. + """ + + def optionxform(self, optionstr): + return optionstr + + def read(self, filenames): + if isinstance(filenames, basestring): + filenames = [filenames] + for filename in filenames: + # try: + # fp = open(filename) + # except IOError: + # continue + fp = open(filename) + try: + self._read(fp, filename) + finally: + fp.close() + + def as_dict(self, raw=False, vars=None): + """Convert an INI file to a dictionary""" + # Load INI file into a dict + result = {} + for section in self.sections(): + if section not in result: + result[section] = {} + for option in self.options(section): + value = self.get(section, option, raw, vars) + try: + value = unrepr(value) + except Exception, x: + msg = ("Config error in section: %r, option: %r, " + "value: %r. Config values must be valid Python." % + (section, option, value)) + raise ValueError(msg, x.__class__.__name__, x.args) + result[section][option] = value + return result + + def dict_from_file(self, file): + if hasattr(file, 'read'): + self.readfp(file) + else: + self.read(file) + return self.as_dict() + + +# public domain "unrepr" implementation, found on the web and then improved. + +class _Builder: + + def build(self, o): + m = getattr(self, 'build_' + o.__class__.__name__, None) + if m is None: + raise TypeError("unrepr does not recognize %s" % + repr(o.__class__.__name__)) + return m(o) + + def build_Subscript(self, o): + expr, flags, subs = o.getChildren() + expr = self.build(expr) + subs = self.build(subs) + return expr[subs] + + def build_CallFunc(self, o): + children = map(self.build, o.getChildren()) + callee = children.pop(0) + kwargs = children.pop() or {} + starargs = children.pop() or () + args = tuple(children) + tuple(starargs) + return callee(*args, **kwargs) + + def build_List(self, o): + return map(self.build, o.getChildren()) + + def build_Const(self, o): + return o.value + + def build_Dict(self, o): + d = {} + i = iter(map(self.build, o.getChildren())) + for el in i: + d[el] = i.next() + return d + + def build_Tuple(self, o): + return tuple(self.build_List(o)) + + def build_Name(self, o): + name = o.name + if name == 'None': + return None + if name == 'True': + return True + if name == 'False': + return False + + # See if the Name is a package or module. If it is, import it. + try: + return modules(name) + except ImportError: + pass + + # See if the Name is in builtins. + try: + import __builtin__ + return getattr(__builtin__, name) + except AttributeError: + pass + + raise TypeError("unrepr could not resolve the name %s" % repr(name)) + + def build_Add(self, o): + left, right = map(self.build, o.getChildren()) + return left + right + + def build_Getattr(self, o): + parent = self.build(o.expr) + return getattr(parent, o.attrname) + + def build_NoneType(self, o): + return None + + def build_UnarySub(self, o): + return -self.build(o.getChildren()[0]) + + def build_UnaryAdd(self, o): + return self.build(o.getChildren()[0]) + + +def _astnode(s): + """Return a Python ast Node compiled from a string.""" + try: + import compiler + except ImportError: + # Fallback to eval when compiler package is not available, + # e.g. IronPython 1.0. + return eval(s) + + p = compiler.parse("__tempvalue__ = " + s) + return p.getChildren()[1].getChildren()[0].getChildren()[1] + + +def unrepr(s): + """Return a Python object compiled from a string.""" + if not s: + return s + obj = _astnode(s) + return _Builder().build(obj) + + +def modules(modulePath): + """Load a module and retrieve a reference to that module.""" + try: + mod = sys.modules[modulePath] + if mod is None: + raise KeyError() + except KeyError: + # The last [''] is important. + mod = __import__(modulePath, globals(), locals(), ['']) + return mod + +def attributes(full_attribute_name): + """Load a module and retrieve an attribute of that module.""" + + # Parse out the path, module, and attribute + last_dot = full_attribute_name.rfind(".") + attr_name = full_attribute_name[last_dot + 1:] + mod_path = full_attribute_name[:last_dot] + + mod = modules(mod_path) + # Let an AttributeError propagate outward. + try: + attr = getattr(mod, attr_name) + except AttributeError: + raise AttributeError("'%s' object has no attribute '%s'" + % (mod_path, attr_name)) + + # Return a reference to the attribute. + return attr + + diff --git a/cherrypy/lib/sessions.py b/cherrypy/lib/sessions.py new file mode 100644 index 00000000..42c28009 --- /dev/null +++ b/cherrypy/lib/sessions.py @@ -0,0 +1,832 @@ +"""Session implementation for CherryPy. + +You need to edit your config file to use sessions. Here's an example:: + + [/] + tools.sessions.on = True + tools.sessions.storage_type = "file" + tools.sessions.storage_path = "/home/site/sessions" + tools.sessions.timeout = 60 + +This sets the session to be stored in files in the directory /home/site/sessions, +and the session timeout to 60 minutes. If you omit ``storage_type`` the sessions +will be saved in RAM. ``tools.sessions.on`` is the only required line for +working sessions, the rest are optional. + +By default, the session ID is passed in a cookie, so the client's browser must +have cookies enabled for your site. + +To set data for the current session, use +``cherrypy.session['fieldname'] = 'fieldvalue'``; +to get data use ``cherrypy.session.get('fieldname')``. + +================ +Locking sessions +================ + +By default, the ``'locking'`` mode of sessions is ``'implicit'``, which means +the session is locked early and unlocked late. If you want to control when the +session data is locked and unlocked, set ``tools.sessions.locking = 'explicit'``. +Then call ``cherrypy.session.acquire_lock()`` and ``cherrypy.session.release_lock()``. +Regardless of which mode you use, the session is guaranteed to be unlocked when +the request is complete. + +================= +Expiring Sessions +================= + +You can force a session to expire with :func:`cherrypy.lib.sessions.expire`. +Simply call that function at the point you want the session to expire, and it +will cause the session cookie to expire client-side. + +=========================== +Session Fixation Protection +=========================== + +If CherryPy receives, via a request cookie, a session id that it does not +recognize, it will reject that id and create a new one to return in the +response cookie. This `helps prevent session fixation attacks +`_. +However, CherryPy "recognizes" a session id by looking up the saved session +data for that id. Therefore, if you never save any session data, +**you will get a new session id for every request**. + +================ +Sharing Sessions +================ + +If you run multiple instances of CherryPy (for example via mod_python behind +Apache prefork), you most likely cannot use the RAM session backend, since each +instance of CherryPy will have its own memory space. Use a different backend +instead, and verify that all instances are pointing at the same file or db +location. Alternately, you might try a load balancer which makes sessions +"sticky". Google is your friend, there. + +================ +Expiration Dates +================ + +The response cookie will possess an expiration date to inform the client at +which point to stop sending the cookie back in requests. If the server time +and client time differ, expect sessions to be unreliable. **Make sure the +system time of your server is accurate**. + +CherryPy defaults to a 60-minute session timeout, which also applies to the +cookie which is sent to the client. Unfortunately, some versions of Safari +("4 public beta" on Windows XP at least) appear to have a bug in their parsing +of the GMT expiration date--they appear to interpret the date as one hour in +the past. Sixty minutes minus one hour is pretty close to zero, so you may +experience this bug as a new session id for every request, unless the requests +are less than one second apart. To fix, try increasing the session.timeout. + +On the other extreme, some users report Firefox sending cookies after their +expiration date, although this was on a system with an inaccurate system time. +Maybe FF doesn't trust system time. +""" + +import datetime +import os +import random +import time +import threading +import types +from warnings import warn + +import cherrypy +from cherrypy._cpcompat import copyitems, pickle, random20 +from cherrypy.lib import httputil + + +missing = object() + +class Session(object): + """A CherryPy dict-like Session object (one per request).""" + + _id = None + + id_observers = None + "A list of callbacks to which to pass new id's." + + def _get_id(self): + return self._id + def _set_id(self, value): + self._id = value + for o in self.id_observers: + o(value) + id = property(_get_id, _set_id, doc="The current session ID.") + + timeout = 60 + "Number of minutes after which to delete session data." + + locked = False + """ + If True, this session instance has exclusive read/write access + to session data.""" + + loaded = False + """ + If True, data has been retrieved from storage. This should happen + automatically on the first attempt to access session data.""" + + clean_thread = None + "Class-level Monitor which calls self.clean_up." + + clean_freq = 5 + "The poll rate for expired session cleanup in minutes." + + originalid = None + "The session id passed by the client. May be missing or unsafe." + + missing = False + "True if the session requested by the client did not exist." + + regenerated = False + """ + True if the application called session.regenerate(). This is not set by + internal calls to regenerate the session id.""" + + debug=False + + def __init__(self, id=None, **kwargs): + self.id_observers = [] + self._data = {} + + for k, v in kwargs.items(): + setattr(self, k, v) + + self.originalid = id + self.missing = False + if id is None: + if self.debug: + cherrypy.log('No id given; making a new one', 'TOOLS.SESSIONS') + self._regenerate() + else: + self.id = id + if not self._exists(): + if self.debug: + cherrypy.log('Expired or malicious session %r; ' + 'making a new one' % id, 'TOOLS.SESSIONS') + # Expired or malicious session. Make a new one. + # See http://www.cherrypy.org/ticket/709. + self.id = None + self.missing = True + self._regenerate() + + def regenerate(self): + """Replace the current session (with a new id).""" + self.regenerated = True + self._regenerate() + + def _regenerate(self): + if self.id is not None: + self.delete() + + old_session_was_locked = self.locked + if old_session_was_locked: + self.release_lock() + + self.id = None + while self.id is None: + self.id = self.generate_id() + # Assert that the generated id is not already stored. + if self._exists(): + self.id = None + + if old_session_was_locked: + self.acquire_lock() + + def clean_up(self): + """Clean up expired sessions.""" + pass + + def generate_id(self): + """Return a new session id.""" + return random20() + + def save(self): + """Save session data.""" + try: + # If session data has never been loaded then it's never been + # accessed: no need to save it + if self.loaded: + t = datetime.timedelta(seconds = self.timeout * 60) + expiration_time = datetime.datetime.now() + t + if self.debug: + cherrypy.log('Saving with expiry %s' % expiration_time, + 'TOOLS.SESSIONS') + self._save(expiration_time) + + finally: + if self.locked: + # Always release the lock if the user didn't release it + self.release_lock() + + def load(self): + """Copy stored session data into this session instance.""" + data = self._load() + # data is either None or a tuple (session_data, expiration_time) + if data is None or data[1] < datetime.datetime.now(): + if self.debug: + cherrypy.log('Expired session, flushing data', 'TOOLS.SESSIONS') + self._data = {} + else: + self._data = data[0] + self.loaded = True + + # Stick the clean_thread in the class, not the instance. + # The instances are created and destroyed per-request. + cls = self.__class__ + if self.clean_freq and not cls.clean_thread: + # clean_up is in instancemethod and not a classmethod, + # so that tool config can be accessed inside the method. + t = cherrypy.process.plugins.Monitor( + cherrypy.engine, self.clean_up, self.clean_freq * 60, + name='Session cleanup') + t.subscribe() + cls.clean_thread = t + t.start() + + def delete(self): + """Delete stored session data.""" + self._delete() + + def __getitem__(self, key): + if not self.loaded: self.load() + return self._data[key] + + def __setitem__(self, key, value): + if not self.loaded: self.load() + self._data[key] = value + + def __delitem__(self, key): + if not self.loaded: self.load() + del self._data[key] + + def pop(self, key, default=missing): + """Remove the specified key and return the corresponding value. + If key is not found, default is returned if given, + otherwise KeyError is raised. + """ + if not self.loaded: self.load() + if default is missing: + return self._data.pop(key) + else: + return self._data.pop(key, default) + + def __contains__(self, key): + if not self.loaded: self.load() + return key in self._data + + def has_key(self, key): + """D.has_key(k) -> True if D has a key k, else False.""" + if not self.loaded: self.load() + return key in self._data + + def get(self, key, default=None): + """D.get(k[,d]) -> D[k] if k in D, else d. d defaults to None.""" + if not self.loaded: self.load() + return self._data.get(key, default) + + def update(self, d): + """D.update(E) -> None. Update D from E: for k in E: D[k] = E[k].""" + if not self.loaded: self.load() + self._data.update(d) + + def setdefault(self, key, default=None): + """D.setdefault(k[,d]) -> D.get(k,d), also set D[k]=d if k not in D.""" + if not self.loaded: self.load() + return self._data.setdefault(key, default) + + def clear(self): + """D.clear() -> None. Remove all items from D.""" + if not self.loaded: self.load() + self._data.clear() + + def keys(self): + """D.keys() -> list of D's keys.""" + if not self.loaded: self.load() + return self._data.keys() + + def items(self): + """D.items() -> list of D's (key, value) pairs, as 2-tuples.""" + if not self.loaded: self.load() + return self._data.items() + + def values(self): + """D.values() -> list of D's values.""" + if not self.loaded: self.load() + return self._data.values() + + +class RamSession(Session): + + # Class-level objects. Don't rebind these! + cache = {} + locks = {} + + def clean_up(self): + """Clean up expired sessions.""" + now = datetime.datetime.now() + for id, (data, expiration_time) in copyitems(self.cache): + if expiration_time <= now: + try: + del self.cache[id] + except KeyError: + pass + try: + del self.locks[id] + except KeyError: + pass + + def _exists(self): + return self.id in self.cache + + def _load(self): + return self.cache.get(self.id) + + def _save(self, expiration_time): + self.cache[self.id] = (self._data, expiration_time) + + def _delete(self): + self.cache.pop(self.id, None) + + def acquire_lock(self): + """Acquire an exclusive lock on the currently-loaded session data.""" + self.locked = True + self.locks.setdefault(self.id, threading.RLock()).acquire() + + def release_lock(self): + """Release the lock on the currently-loaded session data.""" + self.locks[self.id].release() + self.locked = False + + def __len__(self): + """Return the number of active sessions.""" + return len(self.cache) + + +class FileSession(Session): + """Implementation of the File backend for sessions + + storage_path + The folder where session data will be saved. Each session + will be saved as pickle.dump(data, expiration_time) in its own file; + the filename will be self.SESSION_PREFIX + self.id. + + """ + + SESSION_PREFIX = 'session-' + LOCK_SUFFIX = '.lock' + pickle_protocol = pickle.HIGHEST_PROTOCOL + + def __init__(self, id=None, **kwargs): + # The 'storage_path' arg is required for file-based sessions. + kwargs['storage_path'] = os.path.abspath(kwargs['storage_path']) + Session.__init__(self, id=id, **kwargs) + + def setup(cls, **kwargs): + """Set up the storage system for file-based sessions. + + This should only be called once per process; this will be done + automatically when using sessions.init (as the built-in Tool does). + """ + # The 'storage_path' arg is required for file-based sessions. + kwargs['storage_path'] = os.path.abspath(kwargs['storage_path']) + + for k, v in kwargs.items(): + setattr(cls, k, v) + + # Warn if any lock files exist at startup. + lockfiles = [fname for fname in os.listdir(cls.storage_path) + if (fname.startswith(cls.SESSION_PREFIX) + and fname.endswith(cls.LOCK_SUFFIX))] + if lockfiles: + plural = ('', 's')[len(lockfiles) > 1] + warn("%s session lockfile%s found at startup. If you are " + "only running one process, then you may need to " + "manually delete the lockfiles found at %r." + % (len(lockfiles), plural, cls.storage_path)) + setup = classmethod(setup) + + def _get_file_path(self): + f = os.path.join(self.storage_path, self.SESSION_PREFIX + self.id) + if not os.path.abspath(f).startswith(self.storage_path): + raise cherrypy.HTTPError(400, "Invalid session id in cookie.") + return f + + def _exists(self): + path = self._get_file_path() + return os.path.exists(path) + + def _load(self, path=None): + if path is None: + path = self._get_file_path() + try: + f = open(path, "rb") + try: + return pickle.load(f) + finally: + f.close() + except (IOError, EOFError): + return None + + def _save(self, expiration_time): + f = open(self._get_file_path(), "wb") + try: + pickle.dump((self._data, expiration_time), f, self.pickle_protocol) + finally: + f.close() + + def _delete(self): + try: + os.unlink(self._get_file_path()) + except OSError: + pass + + def acquire_lock(self, path=None): + """Acquire an exclusive lock on the currently-loaded session data.""" + if path is None: + path = self._get_file_path() + path += self.LOCK_SUFFIX + while True: + try: + lockfd = os.open(path, os.O_CREAT|os.O_WRONLY|os.O_EXCL) + except OSError: + time.sleep(0.1) + else: + os.close(lockfd) + break + self.locked = True + + def release_lock(self, path=None): + """Release the lock on the currently-loaded session data.""" + if path is None: + path = self._get_file_path() + os.unlink(path + self.LOCK_SUFFIX) + self.locked = False + + def clean_up(self): + """Clean up expired sessions.""" + now = datetime.datetime.now() + # Iterate over all session files in self.storage_path + for fname in os.listdir(self.storage_path): + if (fname.startswith(self.SESSION_PREFIX) + and not fname.endswith(self.LOCK_SUFFIX)): + # We have a session file: lock and load it and check + # if it's expired. If it fails, nevermind. + path = os.path.join(self.storage_path, fname) + self.acquire_lock(path) + try: + contents = self._load(path) + # _load returns None on IOError + if contents is not None: + data, expiration_time = contents + if expiration_time < now: + # Session expired: deleting it + os.unlink(path) + finally: + self.release_lock(path) + + def __len__(self): + """Return the number of active sessions.""" + return len([fname for fname in os.listdir(self.storage_path) + if (fname.startswith(self.SESSION_PREFIX) + and not fname.endswith(self.LOCK_SUFFIX))]) + + +class PostgresqlSession(Session): + """ Implementation of the PostgreSQL backend for sessions. It assumes + a table like this:: + + create table session ( + id varchar(40), + data text, + expiration_time timestamp + ) + + You must provide your own get_db function. + """ + + pickle_protocol = pickle.HIGHEST_PROTOCOL + + def __init__(self, id=None, **kwargs): + Session.__init__(self, id, **kwargs) + self.cursor = self.db.cursor() + + def setup(cls, **kwargs): + """Set up the storage system for Postgres-based sessions. + + This should only be called once per process; this will be done + automatically when using sessions.init (as the built-in Tool does). + """ + for k, v in kwargs.items(): + setattr(cls, k, v) + + self.db = self.get_db() + setup = classmethod(setup) + + def __del__(self): + if self.cursor: + self.cursor.close() + self.db.commit() + + def _exists(self): + # Select session data from table + self.cursor.execute('select data, expiration_time from session ' + 'where id=%s', (self.id,)) + rows = self.cursor.fetchall() + return bool(rows) + + def _load(self): + # Select session data from table + self.cursor.execute('select data, expiration_time from session ' + 'where id=%s', (self.id,)) + rows = self.cursor.fetchall() + if not rows: + return None + + pickled_data, expiration_time = rows[0] + data = pickle.loads(pickled_data) + return data, expiration_time + + def _save(self, expiration_time): + pickled_data = pickle.dumps(self._data, self.pickle_protocol) + self.cursor.execute('update session set data = %s, ' + 'expiration_time = %s where id = %s', + (pickled_data, expiration_time, self.id)) + + def _delete(self): + self.cursor.execute('delete from session where id=%s', (self.id,)) + + def acquire_lock(self): + """Acquire an exclusive lock on the currently-loaded session data.""" + # We use the "for update" clause to lock the row + self.locked = True + self.cursor.execute('select id from session where id=%s for update', + (self.id,)) + + def release_lock(self): + """Release the lock on the currently-loaded session data.""" + # We just close the cursor and that will remove the lock + # introduced by the "for update" clause + self.cursor.close() + self.locked = False + + def clean_up(self): + """Clean up expired sessions.""" + self.cursor.execute('delete from session where expiration_time < %s', + (datetime.datetime.now(),)) + + +class MemcachedSession(Session): + + # The most popular memcached client for Python isn't thread-safe. + # Wrap all .get and .set operations in a single lock. + mc_lock = threading.RLock() + + # This is a seperate set of locks per session id. + locks = {} + + servers = ['127.0.0.1:11211'] + + def setup(cls, **kwargs): + """Set up the storage system for memcached-based sessions. + + This should only be called once per process; this will be done + automatically when using sessions.init (as the built-in Tool does). + """ + for k, v in kwargs.items(): + setattr(cls, k, v) + + import memcache + cls.cache = memcache.Client(cls.servers) + setup = classmethod(setup) + + def _exists(self): + self.mc_lock.acquire() + try: + return bool(self.cache.get(self.id)) + finally: + self.mc_lock.release() + + def _load(self): + self.mc_lock.acquire() + try: + return self.cache.get(self.id) + finally: + self.mc_lock.release() + + def _save(self, expiration_time): + # Send the expiration time as "Unix time" (seconds since 1/1/1970) + td = int(time.mktime(expiration_time.timetuple())) + self.mc_lock.acquire() + try: + if not self.cache.set(self.id, (self._data, expiration_time), td): + raise AssertionError("Session data for id %r not set." % self.id) + finally: + self.mc_lock.release() + + def _delete(self): + self.cache.delete(self.id) + + def acquire_lock(self): + """Acquire an exclusive lock on the currently-loaded session data.""" + self.locked = True + self.locks.setdefault(self.id, threading.RLock()).acquire() + + def release_lock(self): + """Release the lock on the currently-loaded session data.""" + self.locks[self.id].release() + self.locked = False + + def __len__(self): + """Return the number of active sessions.""" + raise NotImplementedError + + +# Hook functions (for CherryPy tools) + +def save(): + """Save any changed session data.""" + + if not hasattr(cherrypy.serving, "session"): + return + request = cherrypy.serving.request + response = cherrypy.serving.response + + # Guard against running twice + if hasattr(request, "_sessionsaved"): + return + request._sessionsaved = True + + if response.stream: + # If the body is being streamed, we have to save the data + # *after* the response has been written out + request.hooks.attach('on_end_request', cherrypy.session.save) + else: + # If the body is not being streamed, we save the data now + # (so we can release the lock). + if isinstance(response.body, types.GeneratorType): + response.collapse_body() + cherrypy.session.save() +save.failsafe = True + +def close(): + """Close the session object for this request.""" + sess = getattr(cherrypy.serving, "session", None) + if getattr(sess, "locked", False): + # If the session is still locked we release the lock + sess.release_lock() +close.failsafe = True +close.priority = 90 + + +def init(storage_type='ram', path=None, path_header=None, name='session_id', + timeout=60, domain=None, secure=False, clean_freq=5, + persistent=True, debug=False, **kwargs): + """Initialize session object (using cookies). + + storage_type + One of 'ram', 'file', 'postgresql'. This will be used + to look up the corresponding class in cherrypy.lib.sessions + globals. For example, 'file' will use the FileSession class. + + path + The 'path' value to stick in the response cookie metadata. + + path_header + If 'path' is None (the default), then the response + cookie 'path' will be pulled from request.headers[path_header]. + + name + The name of the cookie. + + timeout + The expiration timeout (in minutes) for the stored session data. + If 'persistent' is True (the default), this is also the timeout + for the cookie. + + domain + The cookie domain. + + secure + If False (the default) the cookie 'secure' value will not + be set. If True, the cookie 'secure' value will be set (to 1). + + clean_freq (minutes) + The poll rate for expired session cleanup. + + persistent + If True (the default), the 'timeout' argument will be used + to expire the cookie. If False, the cookie will not have an expiry, + and the cookie will be a "session cookie" which expires when the + browser is closed. + + Any additional kwargs will be bound to the new Session instance, + and may be specific to the storage type. See the subclass of Session + you're using for more information. + """ + + request = cherrypy.serving.request + + # Guard against running twice + if hasattr(request, "_session_init_flag"): + return + request._session_init_flag = True + + # Check if request came with a session ID + id = None + if name in request.cookie: + id = request.cookie[name].value + if debug: + cherrypy.log('ID obtained from request.cookie: %r' % id, + 'TOOLS.SESSIONS') + + # Find the storage class and call setup (first time only). + storage_class = storage_type.title() + 'Session' + storage_class = globals()[storage_class] + if not hasattr(cherrypy, "session"): + if hasattr(storage_class, "setup"): + storage_class.setup(**kwargs) + + # Create and attach a new Session instance to cherrypy.serving. + # It will possess a reference to (and lock, and lazily load) + # the requested session data. + kwargs['timeout'] = timeout + kwargs['clean_freq'] = clean_freq + cherrypy.serving.session = sess = storage_class(id, **kwargs) + sess.debug = debug + def update_cookie(id): + """Update the cookie every time the session id changes.""" + cherrypy.serving.response.cookie[name] = id + sess.id_observers.append(update_cookie) + + # Create cherrypy.session which will proxy to cherrypy.serving.session + if not hasattr(cherrypy, "session"): + cherrypy.session = cherrypy._ThreadLocalProxy('session') + + if persistent: + cookie_timeout = timeout + else: + # See http://support.microsoft.com/kb/223799/EN-US/ + # and http://support.mozilla.com/en-US/kb/Cookies + cookie_timeout = None + set_response_cookie(path=path, path_header=path_header, name=name, + timeout=cookie_timeout, domain=domain, secure=secure) + + +def set_response_cookie(path=None, path_header=None, name='session_id', + timeout=60, domain=None, secure=False): + """Set a response cookie for the client. + + path + the 'path' value to stick in the response cookie metadata. + + path_header + if 'path' is None (the default), then the response + cookie 'path' will be pulled from request.headers[path_header]. + + name + the name of the cookie. + + timeout + the expiration timeout for the cookie. If 0 or other boolean + False, no 'expires' param will be set, and the cookie will be a + "session cookie" which expires when the browser is closed. + + domain + the cookie domain. + + secure + if False (the default) the cookie 'secure' value will not + be set. If True, the cookie 'secure' value will be set (to 1). + + """ + # Set response cookie + cookie = cherrypy.serving.response.cookie + cookie[name] = cherrypy.serving.session.id + cookie[name]['path'] = (path or cherrypy.serving.request.headers.get(path_header) + or '/') + + # We'd like to use the "max-age" param as indicated in + # http://www.faqs.org/rfcs/rfc2109.html but IE doesn't + # save it to disk and the session is lost if people close + # the browser. So we have to use the old "expires" ... sigh ... +## cookie[name]['max-age'] = timeout * 60 + if timeout: + e = time.time() + (timeout * 60) + cookie[name]['expires'] = httputil.HTTPDate(e) + if domain is not None: + cookie[name]['domain'] = domain + if secure: + cookie[name]['secure'] = 1 + + +def expire(): + """Expire the current session cookie.""" + name = cherrypy.serving.request.config.get('tools.sessions.name', 'session_id') + one_year = 60 * 60 * 24 * 365 + e = time.time() - one_year + cherrypy.serving.response.cookie[name]['expires'] = httputil.HTTPDate(e) + + diff --git a/cherrypy/lib/static.py b/cherrypy/lib/static.py new file mode 100644 index 00000000..cb9a68cb --- /dev/null +++ b/cherrypy/lib/static.py @@ -0,0 +1,352 @@ +import logging +import mimetypes +mimetypes.init() +mimetypes.types_map['.dwg']='image/x-dwg' +mimetypes.types_map['.ico']='image/x-icon' +mimetypes.types_map['.bz2']='application/x-bzip2' +mimetypes.types_map['.gz']='application/x-gzip' + +import os +import re +import stat +import time + +import cherrypy +from cherrypy._cpcompat import ntob, unquote +from cherrypy.lib import cptools, httputil, file_generator_limited + + +def serve_file(path, content_type=None, disposition=None, name=None, debug=False): + """Set status, headers, and body in order to serve the given path. + + The Content-Type header will be set to the content_type arg, if provided. + If not provided, the Content-Type will be guessed by the file extension + of the 'path' argument. + + If disposition is not None, the Content-Disposition header will be set + to "; filename=". If name is None, it will be set + to the basename of path. If disposition is None, no Content-Disposition + header will be written. + """ + + response = cherrypy.serving.response + + # If path is relative, users should fix it by making path absolute. + # That is, CherryPy should not guess where the application root is. + # It certainly should *not* use cwd (since CP may be invoked from a + # variety of paths). If using tools.staticdir, you can make your relative + # paths become absolute by supplying a value for "tools.staticdir.root". + if not os.path.isabs(path): + msg = "'%s' is not an absolute path." % path + if debug: + cherrypy.log(msg, 'TOOLS.STATICFILE') + raise ValueError(msg) + + try: + st = os.stat(path) + except OSError: + if debug: + cherrypy.log('os.stat(%r) failed' % path, 'TOOLS.STATIC') + raise cherrypy.NotFound() + + # Check if path is a directory. + if stat.S_ISDIR(st.st_mode): + # Let the caller deal with it as they like. + if debug: + cherrypy.log('%r is a directory' % path, 'TOOLS.STATIC') + raise cherrypy.NotFound() + + # Set the Last-Modified response header, so that + # modified-since validation code can work. + response.headers['Last-Modified'] = httputil.HTTPDate(st.st_mtime) + cptools.validate_since() + + if content_type is None: + # Set content-type based on filename extension + ext = "" + i = path.rfind('.') + if i != -1: + ext = path[i:].lower() + content_type = mimetypes.types_map.get(ext, None) + if content_type is not None: + response.headers['Content-Type'] = content_type + if debug: + cherrypy.log('Content-Type: %r' % content_type, 'TOOLS.STATIC') + + cd = None + if disposition is not None: + if name is None: + name = os.path.basename(path) + cd = '%s; filename="%s"' % (disposition, name) + response.headers["Content-Disposition"] = cd + if debug: + cherrypy.log('Content-Disposition: %r' % cd, 'TOOLS.STATIC') + + # Set Content-Length and use an iterable (file object) + # this way CP won't load the whole file in memory + content_length = st.st_size + fileobj = open(path, 'rb') + return _serve_fileobj(fileobj, content_type, content_length, debug=debug) + +def serve_fileobj(fileobj, content_type=None, disposition=None, name=None, + debug=False): + """Set status, headers, and body in order to serve the given file object. + + The Content-Type header will be set to the content_type arg, if provided. + + If disposition is not None, the Content-Disposition header will be set + to "; filename=". If name is None, 'filename' will + not be set. If disposition is None, no Content-Disposition header will + be written. + + CAUTION: If the request contains a 'Range' header, one or more seek()s will + be performed on the file object. This may cause undesired behavior if + the file object is not seekable. It could also produce undesired results + if the caller set the read position of the file object prior to calling + serve_fileobj(), expecting that the data would be served starting from that + position. + """ + + response = cherrypy.serving.response + + try: + st = os.fstat(fileobj.fileno()) + except AttributeError: + if debug: + cherrypy.log('os has no fstat attribute', 'TOOLS.STATIC') + content_length = None + else: + # Set the Last-Modified response header, so that + # modified-since validation code can work. + response.headers['Last-Modified'] = httputil.HTTPDate(st.st_mtime) + cptools.validate_since() + content_length = st.st_size + + if content_type is not None: + response.headers['Content-Type'] = content_type + if debug: + cherrypy.log('Content-Type: %r' % content_type, 'TOOLS.STATIC') + + cd = None + if disposition is not None: + if name is None: + cd = disposition + else: + cd = '%s; filename="%s"' % (disposition, name) + response.headers["Content-Disposition"] = cd + if debug: + cherrypy.log('Content-Disposition: %r' % cd, 'TOOLS.STATIC') + + return _serve_fileobj(fileobj, content_type, content_length, debug=debug) + +def _serve_fileobj(fileobj, content_type, content_length, debug=False): + """Internal. Set response.body to the given file object, perhaps ranged.""" + response = cherrypy.serving.response + + # HTTP/1.0 didn't have Range/Accept-Ranges headers, or the 206 code + request = cherrypy.serving.request + if request.protocol >= (1, 1): + response.headers["Accept-Ranges"] = "bytes" + r = httputil.get_ranges(request.headers.get('Range'), content_length) + if r == []: + response.headers['Content-Range'] = "bytes */%s" % content_length + message = "Invalid Range (first-byte-pos greater than Content-Length)" + if debug: + cherrypy.log(message, 'TOOLS.STATIC') + raise cherrypy.HTTPError(416, message) + + if r: + if len(r) == 1: + # Return a single-part response. + start, stop = r[0] + if stop > content_length: + stop = content_length + r_len = stop - start + if debug: + cherrypy.log('Single part; start: %r, stop: %r' % (start, stop), + 'TOOLS.STATIC') + response.status = "206 Partial Content" + response.headers['Content-Range'] = ( + "bytes %s-%s/%s" % (start, stop - 1, content_length)) + response.headers['Content-Length'] = r_len + fileobj.seek(start) + response.body = file_generator_limited(fileobj, r_len) + else: + # Return a multipart/byteranges response. + response.status = "206 Partial Content" + from mimetools import choose_boundary + boundary = choose_boundary() + ct = "multipart/byteranges; boundary=%s" % boundary + response.headers['Content-Type'] = ct + if "Content-Length" in response.headers: + # Delete Content-Length header so finalize() recalcs it. + del response.headers["Content-Length"] + + def file_ranges(): + # Apache compatibility: + yield ntob("\r\n") + + for start, stop in r: + if debug: + cherrypy.log('Multipart; start: %r, stop: %r' % (start, stop), + 'TOOLS.STATIC') + yield ntob("--" + boundary, 'ascii') + yield ntob("\r\nContent-type: %s" % content_type, 'ascii') + yield ntob("\r\nContent-range: bytes %s-%s/%s\r\n\r\n" + % (start, stop - 1, content_length), 'ascii') + fileobj.seek(start) + for chunk in file_generator_limited(fileobj, stop-start): + yield chunk + yield ntob("\r\n") + # Final boundary + yield ntob("--" + boundary + "--", 'ascii') + + # Apache compatibility: + yield ntob("\r\n") + response.body = file_ranges() + return response.body + else: + if debug: + cherrypy.log('No byteranges requested', 'TOOLS.STATIC') + + # Set Content-Length and use an iterable (file object) + # this way CP won't load the whole file in memory + response.headers['Content-Length'] = content_length + response.body = fileobj + return response.body + +def serve_download(path, name=None): + """Serve 'path' as an application/x-download attachment.""" + # This is such a common idiom I felt it deserved its own wrapper. + return serve_file(path, "application/x-download", "attachment", name) + + +def _attempt(filename, content_types, debug=False): + if debug: + cherrypy.log('Attempting %r (content_types %r)' % + (filename, content_types), 'TOOLS.STATICDIR') + try: + # you can set the content types for a + # complete directory per extension + content_type = None + if content_types: + r, ext = os.path.splitext(filename) + content_type = content_types.get(ext[1:], None) + serve_file(filename, content_type=content_type, debug=debug) + return True + except cherrypy.NotFound: + # If we didn't find the static file, continue handling the + # request. We might find a dynamic handler instead. + if debug: + cherrypy.log('NotFound', 'TOOLS.STATICFILE') + return False + +def staticdir(section, dir, root="", match="", content_types=None, index="", + debug=False): + """Serve a static resource from the given (root +) dir. + + match + If given, request.path_info will be searched for the given + regular expression before attempting to serve static content. + + content_types + If given, it should be a Python dictionary of + {file-extension: content-type} pairs, where 'file-extension' is + a string (e.g. "gif") and 'content-type' is the value to write + out in the Content-Type response header (e.g. "image/gif"). + + index + If provided, it should be the (relative) name of a file to + serve for directory requests. For example, if the dir argument is + '/home/me', the Request-URI is 'myapp', and the index arg is + 'index.html', the file '/home/me/myapp/index.html' will be sought. + """ + request = cherrypy.serving.request + if request.method not in ('GET', 'HEAD'): + if debug: + cherrypy.log('request.method not GET or HEAD', 'TOOLS.STATICDIR') + return False + + if match and not re.search(match, request.path_info): + if debug: + cherrypy.log('request.path_info %r does not match pattern %r' % + (request.path_info, match), 'TOOLS.STATICDIR') + return False + + # Allow the use of '~' to refer to a user's home directory. + dir = os.path.expanduser(dir) + + # If dir is relative, make absolute using "root". + if not os.path.isabs(dir): + if not root: + msg = "Static dir requires an absolute dir (or root)." + if debug: + cherrypy.log(msg, 'TOOLS.STATICDIR') + raise ValueError(msg) + dir = os.path.join(root, dir) + + # Determine where we are in the object tree relative to 'section' + # (where the static tool was defined). + if section == 'global': + section = "/" + section = section.rstrip(r"\/") + branch = request.path_info[len(section) + 1:] + branch = unquote(branch.lstrip(r"\/")) + + # If branch is "", filename will end in a slash + filename = os.path.join(dir, branch) + if debug: + cherrypy.log('Checking file %r to fulfill %r' % + (filename, request.path_info), 'TOOLS.STATICDIR') + + # There's a chance that the branch pulled from the URL might + # have ".." or similar uplevel attacks in it. Check that the final + # filename is a child of dir. + if not os.path.normpath(filename).startswith(os.path.normpath(dir)): + raise cherrypy.HTTPError(403) # Forbidden + + handled = _attempt(filename, content_types) + if not handled: + # Check for an index file if a folder was requested. + if index: + handled = _attempt(os.path.join(filename, index), content_types) + if handled: + request.is_index = filename[-1] in (r"\/") + return handled + +def staticfile(filename, root=None, match="", content_types=None, debug=False): + """Serve a static resource from the given (root +) filename. + + match + If given, request.path_info will be searched for the given + regular expression before attempting to serve static content. + + content_types + If given, it should be a Python dictionary of + {file-extension: content-type} pairs, where 'file-extension' is + a string (e.g. "gif") and 'content-type' is the value to write + out in the Content-Type response header (e.g. "image/gif"). + + """ + request = cherrypy.serving.request + if request.method not in ('GET', 'HEAD'): + if debug: + cherrypy.log('request.method not GET or HEAD', 'TOOLS.STATICFILE') + return False + + if match and not re.search(match, request.path_info): + if debug: + cherrypy.log('request.path_info %r does not match pattern %r' % + (request.path_info, match), 'TOOLS.STATICFILE') + return False + + # If filename is relative, make absolute using "root". + if not os.path.isabs(filename): + if not root: + msg = "Static tool requires an absolute filename (got '%s')." % filename + if debug: + cherrypy.log(msg, 'TOOLS.STATICFILE') + raise ValueError(msg) + filename = os.path.join(root, filename) + + return _attempt(filename, content_types, debug=debug) diff --git a/cherrypy/lib/xmlrpc.py b/cherrypy/lib/xmlrpc.py new file mode 100644 index 00000000..8a5ef546 --- /dev/null +++ b/cherrypy/lib/xmlrpc.py @@ -0,0 +1,49 @@ +import sys + +import cherrypy + + +def process_body(): + """Return (params, method) from request body.""" + try: + import xmlrpclib + return xmlrpclib.loads(cherrypy.request.body.read()) + except Exception: + return ('ERROR PARAMS', ), 'ERRORMETHOD' + + +def patched_path(path): + """Return 'path', doctored for RPC.""" + if not path.endswith('/'): + path += '/' + if path.startswith('/RPC2/'): + # strip the first /rpc2 + path = path[5:] + return path + + +def _set_response(body): + # The XML-RPC spec (http://www.xmlrpc.com/spec) says: + # "Unless there's a lower-level error, always return 200 OK." + # Since Python's xmlrpclib interprets a non-200 response + # as a "Protocol Error", we'll just return 200 every time. + response = cherrypy.response + response.status = '200 OK' + response.body = body + response.headers['Content-Type'] = 'text/xml' + response.headers['Content-Length'] = len(body) + + +def respond(body, encoding='utf-8', allow_none=0): + from xmlrpclib import Fault, dumps + if not isinstance(body, Fault): + body = (body,) + _set_response(dumps(body, methodresponse=1, + encoding=encoding, + allow_none=allow_none)) + +def on_error(*args, **kwargs): + body = str(sys.exc_info()[1]) + from xmlrpclib import Fault, dumps + _set_response(dumps(Fault(1, body))) + diff --git a/cherrypy/process/__init__.py b/cherrypy/process/__init__.py new file mode 100644 index 00000000..f15b1237 --- /dev/null +++ b/cherrypy/process/__init__.py @@ -0,0 +1,14 @@ +"""Site container for an HTTP server. + +A Web Site Process Bus object is used to connect applications, servers, +and frameworks with site-wide services such as daemonization, process +reload, signal handling, drop privileges, PID file management, logging +for all of these, and many more. + +The 'plugins' module defines a few abstract and concrete services for +use with the bus. Some use tool-specific channels; see the documentation +for each class. +""" + +from cherrypy.process.wspbus import bus +from cherrypy.process import plugins, servers diff --git a/cherrypy/process/plugins.py b/cherrypy/process/plugins.py new file mode 100644 index 00000000..488958eb --- /dev/null +++ b/cherrypy/process/plugins.py @@ -0,0 +1,681 @@ +"""Site services for use with a Web Site Process Bus.""" + +import os +import re +import signal as _signal +import sys +import time +import threading + +from cherrypy._cpcompat import basestring, get_daemon, get_thread_ident, ntob, set + +# _module__file__base is used by Autoreload to make +# absolute any filenames retrieved from sys.modules which are not +# already absolute paths. This is to work around Python's quirk +# of importing the startup script and using a relative filename +# for it in sys.modules. +# +# Autoreload examines sys.modules afresh every time it runs. If an application +# changes the current directory by executing os.chdir(), then the next time +# Autoreload runs, it will not be able to find any filenames which are +# not absolute paths, because the current directory is not the same as when the +# module was first imported. Autoreload will then wrongly conclude the file has +# "changed", and initiate the shutdown/re-exec sequence. +# See ticket #917. +# For this workaround to have a decent probability of success, this module +# needs to be imported as early as possible, before the app has much chance +# to change the working directory. +_module__file__base = os.getcwd() + + +class SimplePlugin(object): + """Plugin base class which auto-subscribes methods for known channels.""" + + bus = None + """A :class:`Bus `, usually cherrypy.engine.""" + + def __init__(self, bus): + self.bus = bus + + def subscribe(self): + """Register this object as a (multi-channel) listener on the bus.""" + for channel in self.bus.listeners: + # Subscribe self.start, self.exit, etc. if present. + method = getattr(self, channel, None) + if method is not None: + self.bus.subscribe(channel, method) + + def unsubscribe(self): + """Unregister this object as a listener on the bus.""" + for channel in self.bus.listeners: + # Unsubscribe self.start, self.exit, etc. if present. + method = getattr(self, channel, None) + if method is not None: + self.bus.unsubscribe(channel, method) + + + +class SignalHandler(object): + """Register bus channels (and listeners) for system signals. + + You can modify what signals your application listens for, and what it does + when it receives signals, by modifying :attr:`SignalHandler.handlers`, + a dict of {signal name: callback} pairs. The default set is:: + + handlers = {'SIGTERM': self.bus.exit, + 'SIGHUP': self.handle_SIGHUP, + 'SIGUSR1': self.bus.graceful, + } + + The :func:`SignalHandler.handle_SIGHUP`` method calls + :func:`bus.restart()` + if the process is daemonized, but + :func:`bus.exit()` + if the process is attached to a TTY. This is because Unix window + managers tend to send SIGHUP to terminal windows when the user closes them. + + Feel free to add signals which are not available on every platform. The + :class:`SignalHandler` will ignore errors raised from attempting to register + handlers for unknown signals. + """ + + handlers = {} + """A map from signal names (e.g. 'SIGTERM') to handlers (e.g. bus.exit).""" + + signals = {} + """A map from signal numbers to names.""" + + for k, v in vars(_signal).items(): + if k.startswith('SIG') and not k.startswith('SIG_'): + signals[v] = k + del k, v + + def __init__(self, bus): + self.bus = bus + # Set default handlers + self.handlers = {'SIGTERM': self.bus.exit, + 'SIGHUP': self.handle_SIGHUP, + 'SIGUSR1': self.bus.graceful, + } + + if sys.platform[:4] == 'java': + del self.handlers['SIGUSR1'] + self.handlers['SIGUSR2'] = self.bus.graceful + self.bus.log("SIGUSR1 cannot be set on the JVM platform. " + "Using SIGUSR2 instead.") + self.handlers['SIGINT'] = self._jython_SIGINT_handler + + self._previous_handlers = {} + + def _jython_SIGINT_handler(self, signum=None, frame=None): + # See http://bugs.jython.org/issue1313 + self.bus.log('Keyboard Interrupt: shutting down bus') + self.bus.exit() + + def subscribe(self): + """Subscribe self.handlers to signals.""" + for sig, func in self.handlers.items(): + try: + self.set_handler(sig, func) + except ValueError: + pass + + def unsubscribe(self): + """Unsubscribe self.handlers from signals.""" + for signum, handler in self._previous_handlers.items(): + signame = self.signals[signum] + + if handler is None: + self.bus.log("Restoring %s handler to SIG_DFL." % signame) + handler = _signal.SIG_DFL + else: + self.bus.log("Restoring %s handler %r." % (signame, handler)) + + try: + our_handler = _signal.signal(signum, handler) + if our_handler is None: + self.bus.log("Restored old %s handler %r, but our " + "handler was not registered." % + (signame, handler), level=30) + except ValueError: + self.bus.log("Unable to restore %s handler %r." % + (signame, handler), level=40, traceback=True) + + def set_handler(self, signal, listener=None): + """Subscribe a handler for the given signal (number or name). + + If the optional 'listener' argument is provided, it will be + subscribed as a listener for the given signal's channel. + + If the given signal name or number is not available on the current + platform, ValueError is raised. + """ + if isinstance(signal, basestring): + signum = getattr(_signal, signal, None) + if signum is None: + raise ValueError("No such signal: %r" % signal) + signame = signal + else: + try: + signame = self.signals[signal] + except KeyError: + raise ValueError("No such signal: %r" % signal) + signum = signal + + prev = _signal.signal(signum, self._handle_signal) + self._previous_handlers[signum] = prev + + if listener is not None: + self.bus.log("Listening for %s." % signame) + self.bus.subscribe(signame, listener) + + def _handle_signal(self, signum=None, frame=None): + """Python signal handler (self.set_handler subscribes it for you).""" + signame = self.signals[signum] + self.bus.log("Caught signal %s." % signame) + self.bus.publish(signame) + + def handle_SIGHUP(self): + """Restart if daemonized, else exit.""" + if os.isatty(sys.stdin.fileno()): + # not daemonized (may be foreground or background) + self.bus.log("SIGHUP caught but not daemonized. Exiting.") + self.bus.exit() + else: + self.bus.log("SIGHUP caught while daemonized. Restarting.") + self.bus.restart() + + +try: + import pwd, grp +except ImportError: + pwd, grp = None, None + + +class DropPrivileges(SimplePlugin): + """Drop privileges. uid/gid arguments not available on Windows. + + Special thanks to Gavin Baker: http://antonym.org/node/100. + """ + + def __init__(self, bus, umask=None, uid=None, gid=None): + SimplePlugin.__init__(self, bus) + self.finalized = False + self.uid = uid + self.gid = gid + self.umask = umask + + def _get_uid(self): + return self._uid + def _set_uid(self, val): + if val is not None: + if pwd is None: + self.bus.log("pwd module not available; ignoring uid.", + level=30) + val = None + elif isinstance(val, basestring): + val = pwd.getpwnam(val)[2] + self._uid = val + uid = property(_get_uid, _set_uid, + doc="The uid under which to run. Availability: Unix.") + + def _get_gid(self): + return self._gid + def _set_gid(self, val): + if val is not None: + if grp is None: + self.bus.log("grp module not available; ignoring gid.", + level=30) + val = None + elif isinstance(val, basestring): + val = grp.getgrnam(val)[2] + self._gid = val + gid = property(_get_gid, _set_gid, + doc="The gid under which to run. Availability: Unix.") + + def _get_umask(self): + return self._umask + def _set_umask(self, val): + if val is not None: + try: + os.umask + except AttributeError: + self.bus.log("umask function not available; ignoring umask.", + level=30) + val = None + self._umask = val + umask = property(_get_umask, _set_umask, + doc="""The default permission mode for newly created files and directories. + + Usually expressed in octal format, for example, ``0644``. + Availability: Unix, Windows. + """) + + def start(self): + # uid/gid + def current_ids(): + """Return the current (uid, gid) if available.""" + name, group = None, None + if pwd: + name = pwd.getpwuid(os.getuid())[0] + if grp: + group = grp.getgrgid(os.getgid())[0] + return name, group + + if self.finalized: + if not (self.uid is None and self.gid is None): + self.bus.log('Already running as uid: %r gid: %r' % + current_ids()) + else: + if self.uid is None and self.gid is None: + if pwd or grp: + self.bus.log('uid/gid not set', level=30) + else: + self.bus.log('Started as uid: %r gid: %r' % current_ids()) + if self.gid is not None: + os.setgid(self.gid) + os.setgroups([]) + if self.uid is not None: + os.setuid(self.uid) + self.bus.log('Running as uid: %r gid: %r' % current_ids()) + + # umask + if self.finalized: + if self.umask is not None: + self.bus.log('umask already set to: %03o' % self.umask) + else: + if self.umask is None: + self.bus.log('umask not set', level=30) + else: + old_umask = os.umask(self.umask) + self.bus.log('umask old: %03o, new: %03o' % + (old_umask, self.umask)) + + self.finalized = True + # This is slightly higher than the priority for server.start + # in order to facilitate the most common use: starting on a low + # port (which requires root) and then dropping to another user. + start.priority = 77 + + +class Daemonizer(SimplePlugin): + """Daemonize the running script. + + Use this with a Web Site Process Bus via:: + + Daemonizer(bus).subscribe() + + When this component finishes, the process is completely decoupled from + the parent environment. Please note that when this component is used, + the return code from the parent process will still be 0 if a startup + error occurs in the forked children. Errors in the initial daemonizing + process still return proper exit codes. Therefore, if you use this + plugin to daemonize, don't use the return code as an accurate indicator + of whether the process fully started. In fact, that return code only + indicates if the process succesfully finished the first fork. + """ + + def __init__(self, bus, stdin='/dev/null', stdout='/dev/null', + stderr='/dev/null'): + SimplePlugin.__init__(self, bus) + self.stdin = stdin + self.stdout = stdout + self.stderr = stderr + self.finalized = False + + def start(self): + if self.finalized: + self.bus.log('Already deamonized.') + + # forking has issues with threads: + # http://www.opengroup.org/onlinepubs/000095399/functions/fork.html + # "The general problem with making fork() work in a multi-threaded + # world is what to do with all of the threads..." + # So we check for active threads: + if threading.activeCount() != 1: + self.bus.log('There are %r active threads. ' + 'Daemonizing now may cause strange failures.' % + threading.enumerate(), level=30) + + # See http://www.erlenstar.demon.co.uk/unix/faq_2.html#SEC16 + # (or http://www.faqs.org/faqs/unix-faq/programmer/faq/ section 1.7) + # and http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/66012 + + # Finish up with the current stdout/stderr + sys.stdout.flush() + sys.stderr.flush() + + # Do first fork. + try: + pid = os.fork() + if pid == 0: + # This is the child process. Continue. + pass + else: + # This is the first parent. Exit, now that we've forked. + self.bus.log('Forking once.') + os._exit(0) + except OSError: + # Python raises OSError rather than returning negative numbers. + exc = sys.exc_info()[1] + sys.exit("%s: fork #1 failed: (%d) %s\n" + % (sys.argv[0], exc.errno, exc.strerror)) + + os.setsid() + + # Do second fork + try: + pid = os.fork() + if pid > 0: + self.bus.log('Forking twice.') + os._exit(0) # Exit second parent + except OSError: + exc = sys.exc_info()[1] + sys.exit("%s: fork #2 failed: (%d) %s\n" + % (sys.argv[0], exc.errno, exc.strerror)) + + os.chdir("/") + os.umask(0) + + si = open(self.stdin, "r") + so = open(self.stdout, "a+") + se = open(self.stderr, "a+") + + # os.dup2(fd, fd2) will close fd2 if necessary, + # so we don't explicitly close stdin/out/err. + # See http://docs.python.org/lib/os-fd-ops.html + os.dup2(si.fileno(), sys.stdin.fileno()) + os.dup2(so.fileno(), sys.stdout.fileno()) + os.dup2(se.fileno(), sys.stderr.fileno()) + + self.bus.log('Daemonized to PID: %s' % os.getpid()) + self.finalized = True + start.priority = 65 + + +class PIDFile(SimplePlugin): + """Maintain a PID file via a WSPBus.""" + + def __init__(self, bus, pidfile): + SimplePlugin.__init__(self, bus) + self.pidfile = pidfile + self.finalized = False + + def start(self): + pid = os.getpid() + if self.finalized: + self.bus.log('PID %r already written to %r.' % (pid, self.pidfile)) + else: + open(self.pidfile, "wb").write(ntob("%s" % pid, 'utf8')) + self.bus.log('PID %r written to %r.' % (pid, self.pidfile)) + self.finalized = True + start.priority = 70 + + def exit(self): + try: + os.remove(self.pidfile) + self.bus.log('PID file removed: %r.' % self.pidfile) + except (KeyboardInterrupt, SystemExit): + raise + except: + pass + + +class PerpetualTimer(threading._Timer): + """A responsive subclass of threading._Timer whose run() method repeats. + + Use this timer only when you really need a very interruptible timer; + this checks its 'finished' condition up to 20 times a second, which can + results in pretty high CPU usage + """ + + def run(self): + while True: + self.finished.wait(self.interval) + if self.finished.isSet(): + return + try: + self.function(*self.args, **self.kwargs) + except Exception: + self.bus.log("Error in perpetual timer thread function %r." % + self.function, level=40, traceback=True) + # Quit on first error to avoid massive logs. + raise + + +class BackgroundTask(threading.Thread): + """A subclass of threading.Thread whose run() method repeats. + + Use this class for most repeating tasks. It uses time.sleep() to wait + for each interval, which isn't very responsive; that is, even if you call + self.cancel(), you'll have to wait until the sleep() call finishes before + the thread stops. To compensate, it defaults to being daemonic, which means + it won't delay stopping the whole process. + """ + + def __init__(self, interval, function, args=[], kwargs={}): + threading.Thread.__init__(self) + self.interval = interval + self.function = function + self.args = args + self.kwargs = kwargs + self.running = False + + def cancel(self): + self.running = False + + def run(self): + self.running = True + while self.running: + time.sleep(self.interval) + if not self.running: + return + try: + self.function(*self.args, **self.kwargs) + except Exception: + self.bus.log("Error in background task thread function %r." % + self.function, level=40, traceback=True) + # Quit on first error to avoid massive logs. + raise + + def _set_daemon(self): + return True + + +class Monitor(SimplePlugin): + """WSPBus listener to periodically run a callback in its own thread.""" + + callback = None + """The function to call at intervals.""" + + frequency = 60 + """The time in seconds between callback runs.""" + + thread = None + """A :class:`BackgroundTask` thread.""" + + def __init__(self, bus, callback, frequency=60, name=None): + SimplePlugin.__init__(self, bus) + self.callback = callback + self.frequency = frequency + self.thread = None + self.name = name + + def start(self): + """Start our callback in its own background thread.""" + if self.frequency > 0: + threadname = self.name or self.__class__.__name__ + if self.thread is None: + self.thread = BackgroundTask(self.frequency, self.callback) + self.thread.bus = self.bus + self.thread.setName(threadname) + self.thread.start() + self.bus.log("Started monitor thread %r." % threadname) + else: + self.bus.log("Monitor thread %r already started." % threadname) + start.priority = 70 + + def stop(self): + """Stop our callback's background task thread.""" + if self.thread is None: + self.bus.log("No thread running for %s." % self.name or self.__class__.__name__) + else: + if self.thread is not threading.currentThread(): + name = self.thread.getName() + self.thread.cancel() + if not get_daemon(self.thread): + self.bus.log("Joining %r" % name) + self.thread.join() + self.bus.log("Stopped thread %r." % name) + self.thread = None + + def graceful(self): + """Stop the callback's background task thread and restart it.""" + self.stop() + self.start() + + +class Autoreloader(Monitor): + """Monitor which re-executes the process when files change. + + This :ref:`plugin` restarts the process (via :func:`os.execv`) + if any of the files it monitors change (or is deleted). By default, the + autoreloader monitors all imported modules; you can add to the + set by adding to ``autoreload.files``:: + + cherrypy.engine.autoreload.files.add(myFile) + + If there are imported files you do *not* wish to monitor, you can adjust the + ``match`` attribute, a regular expression. For example, to stop monitoring + cherrypy itself:: + + cherrypy.engine.autoreload.match = r'^(?!cherrypy).+' + + Like all :class:`Monitor` plugins, + the autoreload plugin takes a ``frequency`` argument. The default is + 1 second; that is, the autoreloader will examine files once each second. + """ + + files = None + """The set of files to poll for modifications.""" + + frequency = 1 + """The interval in seconds at which to poll for modified files.""" + + match = '.*' + """A regular expression by which to match filenames.""" + + def __init__(self, bus, frequency=1, match='.*'): + self.mtimes = {} + self.files = set() + self.match = match + Monitor.__init__(self, bus, self.run, frequency) + + def start(self): + """Start our own background task thread for self.run.""" + if self.thread is None: + self.mtimes = {} + Monitor.start(self) + start.priority = 70 + + def sysfiles(self): + """Return a Set of sys.modules filenames to monitor.""" + files = set() + for k, m in sys.modules.items(): + if re.match(self.match, k): + if hasattr(m, '__loader__') and hasattr(m.__loader__, 'archive'): + f = m.__loader__.archive + else: + f = getattr(m, '__file__', None) + if f is not None and not os.path.isabs(f): + # ensure absolute paths so a os.chdir() in the app doesn't break me + f = os.path.normpath(os.path.join(_module__file__base, f)) + files.add(f) + return files + + def run(self): + """Reload the process if registered files have been modified.""" + for filename in self.sysfiles() | self.files: + if filename: + if filename.endswith('.pyc'): + filename = filename[:-1] + + oldtime = self.mtimes.get(filename, 0) + if oldtime is None: + # Module with no .py file. Skip it. + continue + + try: + mtime = os.stat(filename).st_mtime + except OSError: + # Either a module with no .py file, or it's been deleted. + mtime = None + + if filename not in self.mtimes: + # If a module has no .py file, this will be None. + self.mtimes[filename] = mtime + else: + if mtime is None or mtime > oldtime: + # The file has been deleted or modified. + self.bus.log("Restarting because %s changed." % filename) + self.thread.cancel() + self.bus.log("Stopped thread %r." % self.thread.getName()) + self.bus.restart() + return + + +class ThreadManager(SimplePlugin): + """Manager for HTTP request threads. + + If you have control over thread creation and destruction, publish to + the 'acquire_thread' and 'release_thread' channels (for each thread). + This will register/unregister the current thread and publish to + 'start_thread' and 'stop_thread' listeners in the bus as needed. + + If threads are created and destroyed by code you do not control + (e.g., Apache), then, at the beginning of every HTTP request, + publish to 'acquire_thread' only. You should not publish to + 'release_thread' in this case, since you do not know whether + the thread will be re-used or not. The bus will call + 'stop_thread' listeners for you when it stops. + """ + + threads = None + """A map of {thread ident: index number} pairs.""" + + def __init__(self, bus): + self.threads = {} + SimplePlugin.__init__(self, bus) + self.bus.listeners.setdefault('acquire_thread', set()) + self.bus.listeners.setdefault('start_thread', set()) + self.bus.listeners.setdefault('release_thread', set()) + self.bus.listeners.setdefault('stop_thread', set()) + + def acquire_thread(self): + """Run 'start_thread' listeners for the current thread. + + If the current thread has already been seen, any 'start_thread' + listeners will not be run again. + """ + thread_ident = get_thread_ident() + if thread_ident not in self.threads: + # We can't just use get_ident as the thread ID + # because some platforms reuse thread ID's. + i = len(self.threads) + 1 + self.threads[thread_ident] = i + self.bus.publish('start_thread', i) + + def release_thread(self): + """Release the current thread and run 'stop_thread' listeners.""" + thread_ident = get_thread_ident() + i = self.threads.pop(thread_ident, None) + if i is not None: + self.bus.publish('stop_thread', i) + + def stop(self): + """Release all threads and run all 'stop_thread' listeners.""" + for thread_ident, i in self.threads.items(): + self.bus.publish('stop_thread', i) + self.threads.clear() + graceful = stop + diff --git a/cherrypy/process/servers.py b/cherrypy/process/servers.py new file mode 100644 index 00000000..272e8436 --- /dev/null +++ b/cherrypy/process/servers.py @@ -0,0 +1,418 @@ +""" +Starting in CherryPy 3.1, cherrypy.server is implemented as an +:ref:`Engine Plugin`. It's an instance of +:class:`cherrypy._cpserver.Server`, which is a subclass of +:class:`cherrypy.process.servers.ServerAdapter`. The ``ServerAdapter`` class +is designed to control other servers, as well. + +Multiple servers/ports +====================== + +If you need to start more than one HTTP server (to serve on multiple ports, or +protocols, etc.), you can manually register each one and then start them all +with engine.start:: + + s1 = ServerAdapter(cherrypy.engine, MyWSGIServer(host='0.0.0.0', port=80)) + s2 = ServerAdapter(cherrypy.engine, another.HTTPServer(host='127.0.0.1', SSL=True)) + s1.subscribe() + s2.subscribe() + cherrypy.engine.start() + +.. index:: SCGI + +FastCGI/SCGI +============ + +There are also Flup\ **F**\ CGIServer and Flup\ **S**\ CGIServer classes in +:mod:`cherrypy.process.servers`. To start an fcgi server, for example, +wrap an instance of it in a ServerAdapter:: + + addr = ('0.0.0.0', 4000) + f = servers.FlupFCGIServer(application=cherrypy.tree, bindAddress=addr) + s = servers.ServerAdapter(cherrypy.engine, httpserver=f, bind_addr=addr) + s.subscribe() + +The :doc:`cherryd` startup script will do the above for +you via its `-f` flag. +Note that you need to download and install `flup `_ +yourself, whether you use ``cherryd`` or not. + +.. _fastcgi: +.. index:: FastCGI + +FastCGI +------- + +A very simple setup lets your cherry run with FastCGI. +You just need the flup library, +plus a running Apache server (with ``mod_fastcgi``) or lighttpd server. + +CherryPy code +^^^^^^^^^^^^^ + +hello.py:: + + #!/usr/bin/python + import cherrypy + + class HelloWorld: + \"""Sample request handler class.\""" + def index(self): + return "Hello world!" + index.exposed = True + + cherrypy.tree.mount(HelloWorld()) + # CherryPy autoreload must be disabled for the flup server to work + cherrypy.config.update({'engine.autoreload_on':False}) + +Then run :doc:`/deployguide/cherryd` with the '-f' arg:: + + cherryd -c -d -f -i hello.py + +Apache +^^^^^^ + +At the top level in httpd.conf:: + + FastCgiIpcDir /tmp + FastCgiServer /path/to/cherry.fcgi -idle-timeout 120 -processes 4 + +And inside the relevant VirtualHost section:: + + # FastCGI config + AddHandler fastcgi-script .fcgi + ScriptAliasMatch (.*$) /path/to/cherry.fcgi$1 + +Lighttpd +^^^^^^^^ + +For `Lighttpd `_ you can follow these +instructions. Within ``lighttpd.conf`` make sure ``mod_fastcgi`` is +active within ``server.modules``. Then, within your ``$HTTP["host"]`` +directive, configure your fastcgi script like the following:: + + $HTTP["url"] =~ "" { + fastcgi.server = ( + "/" => ( + "script.fcgi" => ( + "bin-path" => "/path/to/your/script.fcgi", + "socket" => "/tmp/script.sock", + "check-local" => "disable", + "disable-time" => 1, + "min-procs" => 1, + "max-procs" => 1, # adjust as needed + ), + ), + ) + } # end of $HTTP["url"] =~ "^/" + +Please see `Lighttpd FastCGI Docs +`_ for an explanation +of the possible configuration options. +""" + +import sys +import time + + +class ServerAdapter(object): + """Adapter for an HTTP server. + + If you need to start more than one HTTP server (to serve on multiple + ports, or protocols, etc.), you can manually register each one and then + start them all with bus.start: + + s1 = ServerAdapter(bus, MyWSGIServer(host='0.0.0.0', port=80)) + s2 = ServerAdapter(bus, another.HTTPServer(host='127.0.0.1', SSL=True)) + s1.subscribe() + s2.subscribe() + bus.start() + """ + + def __init__(self, bus, httpserver=None, bind_addr=None): + self.bus = bus + self.httpserver = httpserver + self.bind_addr = bind_addr + self.interrupt = None + self.running = False + + def subscribe(self): + self.bus.subscribe('start', self.start) + self.bus.subscribe('stop', self.stop) + + def unsubscribe(self): + self.bus.unsubscribe('start', self.start) + self.bus.unsubscribe('stop', self.stop) + + def start(self): + """Start the HTTP server.""" + if self.bind_addr is None: + on_what = "unknown interface (dynamic?)" + elif isinstance(self.bind_addr, tuple): + host, port = self.bind_addr + on_what = "%s:%s" % (host, port) + else: + on_what = "socket file: %s" % self.bind_addr + + if self.running: + self.bus.log("Already serving on %s" % on_what) + return + + self.interrupt = None + if not self.httpserver: + raise ValueError("No HTTP server has been created.") + + # Start the httpserver in a new thread. + if isinstance(self.bind_addr, tuple): + wait_for_free_port(*self.bind_addr) + + import threading + t = threading.Thread(target=self._start_http_thread) + t.setName("HTTPServer " + t.getName()) + t.start() + + self.wait() + self.running = True + self.bus.log("Serving on %s" % on_what) + start.priority = 75 + + def _start_http_thread(self): + """HTTP servers MUST be running in new threads, so that the + main thread persists to receive KeyboardInterrupt's. If an + exception is raised in the httpserver's thread then it's + trapped here, and the bus (and therefore our httpserver) + are shut down. + """ + try: + self.httpserver.start() + except KeyboardInterrupt: + self.bus.log(" hit: shutting down HTTP server") + self.interrupt = sys.exc_info()[1] + self.bus.exit() + except SystemExit: + self.bus.log("SystemExit raised: shutting down HTTP server") + self.interrupt = sys.exc_info()[1] + self.bus.exit() + raise + except: + self.interrupt = sys.exc_info()[1] + self.bus.log("Error in HTTP server: shutting down", + traceback=True, level=40) + self.bus.exit() + raise + + def wait(self): + """Wait until the HTTP server is ready to receive requests.""" + while not getattr(self.httpserver, "ready", False): + if self.interrupt: + raise self.interrupt + time.sleep(.1) + + # Wait for port to be occupied + if isinstance(self.bind_addr, tuple): + host, port = self.bind_addr + wait_for_occupied_port(host, port) + + def stop(self): + """Stop the HTTP server.""" + if self.running: + # stop() MUST block until the server is *truly* stopped. + self.httpserver.stop() + # Wait for the socket to be truly freed. + if isinstance(self.bind_addr, tuple): + wait_for_free_port(*self.bind_addr) + self.running = False + self.bus.log("HTTP Server %s shut down" % self.httpserver) + else: + self.bus.log("HTTP Server %s already shut down" % self.httpserver) + stop.priority = 25 + + def restart(self): + """Restart the HTTP server.""" + self.stop() + self.start() + + +class FlupCGIServer(object): + """Adapter for a flup.server.cgi.WSGIServer.""" + + def __init__(self, *args, **kwargs): + self.args = args + self.kwargs = kwargs + self.ready = False + + def start(self): + """Start the CGI server.""" + # We have to instantiate the server class here because its __init__ + # starts a threadpool. If we do it too early, daemonize won't work. + from flup.server.cgi import WSGIServer + + self.cgiserver = WSGIServer(*self.args, **self.kwargs) + self.ready = True + self.cgiserver.run() + + def stop(self): + """Stop the HTTP server.""" + self.ready = False + + +class FlupFCGIServer(object): + """Adapter for a flup.server.fcgi.WSGIServer.""" + + def __init__(self, *args, **kwargs): + if kwargs.get('bindAddress', None) is None: + import socket + if not hasattr(socket, 'fromfd'): + raise ValueError( + 'Dynamic FCGI server not available on this platform. ' + 'You must use a static or external one by providing a ' + 'legal bindAddress.') + self.args = args + self.kwargs = kwargs + self.ready = False + + def start(self): + """Start the FCGI server.""" + # We have to instantiate the server class here because its __init__ + # starts a threadpool. If we do it too early, daemonize won't work. + from flup.server.fcgi import WSGIServer + self.fcgiserver = WSGIServer(*self.args, **self.kwargs) + # TODO: report this bug upstream to flup. + # If we don't set _oldSIGs on Windows, we get: + # File "C:\Python24\Lib\site-packages\flup\server\threadedserver.py", + # line 108, in run + # self._restoreSignalHandlers() + # File "C:\Python24\Lib\site-packages\flup\server\threadedserver.py", + # line 156, in _restoreSignalHandlers + # for signum,handler in self._oldSIGs: + # AttributeError: 'WSGIServer' object has no attribute '_oldSIGs' + self.fcgiserver._installSignalHandlers = lambda: None + self.fcgiserver._oldSIGs = [] + self.ready = True + self.fcgiserver.run() + + def stop(self): + """Stop the HTTP server.""" + # Forcibly stop the fcgi server main event loop. + self.fcgiserver._keepGoing = False + # Force all worker threads to die off. + self.fcgiserver._threadPool.maxSpare = self.fcgiserver._threadPool._idleCount + self.ready = False + + +class FlupSCGIServer(object): + """Adapter for a flup.server.scgi.WSGIServer.""" + + def __init__(self, *args, **kwargs): + self.args = args + self.kwargs = kwargs + self.ready = False + + def start(self): + """Start the SCGI server.""" + # We have to instantiate the server class here because its __init__ + # starts a threadpool. If we do it too early, daemonize won't work. + from flup.server.scgi import WSGIServer + self.scgiserver = WSGIServer(*self.args, **self.kwargs) + # TODO: report this bug upstream to flup. + # If we don't set _oldSIGs on Windows, we get: + # File "C:\Python24\Lib\site-packages\flup\server\threadedserver.py", + # line 108, in run + # self._restoreSignalHandlers() + # File "C:\Python24\Lib\site-packages\flup\server\threadedserver.py", + # line 156, in _restoreSignalHandlers + # for signum,handler in self._oldSIGs: + # AttributeError: 'WSGIServer' object has no attribute '_oldSIGs' + self.scgiserver._installSignalHandlers = lambda: None + self.scgiserver._oldSIGs = [] + self.ready = True + self.scgiserver.run() + + def stop(self): + """Stop the HTTP server.""" + self.ready = False + # Forcibly stop the scgi server main event loop. + self.scgiserver._keepGoing = False + # Force all worker threads to die off. + self.scgiserver._threadPool.maxSpare = 0 + + +def client_host(server_host): + """Return the host on which a client can connect to the given listener.""" + if server_host == '0.0.0.0': + # 0.0.0.0 is INADDR_ANY, which should answer on localhost. + return '127.0.0.1' + if server_host in ('::', '::0', '::0.0.0.0'): + # :: is IN6ADDR_ANY, which should answer on localhost. + # ::0 and ::0.0.0.0 are non-canonical but common ways to write IN6ADDR_ANY. + return '::1' + return server_host + +def check_port(host, port, timeout=1.0): + """Raise an error if the given port is not free on the given host.""" + if not host: + raise ValueError("Host values of '' or None are not allowed.") + host = client_host(host) + port = int(port) + + import socket + + # AF_INET or AF_INET6 socket + # Get the correct address family for our host (allows IPv6 addresses) + try: + info = socket.getaddrinfo(host, port, socket.AF_UNSPEC, + socket.SOCK_STREAM) + except socket.gaierror: + if ':' in host: + info = [(socket.AF_INET6, socket.SOCK_STREAM, 0, "", (host, port, 0, 0))] + else: + info = [(socket.AF_INET, socket.SOCK_STREAM, 0, "", (host, port))] + + for res in info: + af, socktype, proto, canonname, sa = res + s = None + try: + s = socket.socket(af, socktype, proto) + # See http://groups.google.com/group/cherrypy-users/ + # browse_frm/thread/bbfe5eb39c904fe0 + s.settimeout(timeout) + s.connect((host, port)) + s.close() + raise IOError("Port %s is in use on %s; perhaps the previous " + "httpserver did not shut down properly." % + (repr(port), repr(host))) + except socket.error: + if s: + s.close() + +def wait_for_free_port(host, port): + """Wait for the specified port to become free (drop requests).""" + if not host: + raise ValueError("Host values of '' or None are not allowed.") + + for trial in range(50): + try: + # we are expecting a free port, so reduce the timeout + check_port(host, port, timeout=0.1) + except IOError: + # Give the old server thread time to free the port. + time.sleep(0.1) + else: + return + + raise IOError("Port %r not free on %r" % (port, host)) + +def wait_for_occupied_port(host, port): + """Wait for the specified port to become active (receive requests).""" + if not host: + raise ValueError("Host values of '' or None are not allowed.") + + for trial in range(50): + try: + check_port(host, port) + except IOError: + return + else: + time.sleep(.1) + + raise IOError("Port %r not bound on %r" % (port, host)) diff --git a/cherrypy/process/win32.py b/cherrypy/process/win32.py new file mode 100644 index 00000000..83f99a5d --- /dev/null +++ b/cherrypy/process/win32.py @@ -0,0 +1,174 @@ +"""Windows service. Requires pywin32.""" + +import os +import win32api +import win32con +import win32event +import win32service +import win32serviceutil + +from cherrypy.process import wspbus, plugins + + +class ConsoleCtrlHandler(plugins.SimplePlugin): + """A WSPBus plugin for handling Win32 console events (like Ctrl-C).""" + + def __init__(self, bus): + self.is_set = False + plugins.SimplePlugin.__init__(self, bus) + + def start(self): + if self.is_set: + self.bus.log('Handler for console events already set.', level=40) + return + + result = win32api.SetConsoleCtrlHandler(self.handle, 1) + if result == 0: + self.bus.log('Could not SetConsoleCtrlHandler (error %r)' % + win32api.GetLastError(), level=40) + else: + self.bus.log('Set handler for console events.', level=40) + self.is_set = True + + def stop(self): + if not self.is_set: + self.bus.log('Handler for console events already off.', level=40) + return + + try: + result = win32api.SetConsoleCtrlHandler(self.handle, 0) + except ValueError: + # "ValueError: The object has not been registered" + result = 1 + + if result == 0: + self.bus.log('Could not remove SetConsoleCtrlHandler (error %r)' % + win32api.GetLastError(), level=40) + else: + self.bus.log('Removed handler for console events.', level=40) + self.is_set = False + + def handle(self, event): + """Handle console control events (like Ctrl-C).""" + if event in (win32con.CTRL_C_EVENT, win32con.CTRL_LOGOFF_EVENT, + win32con.CTRL_BREAK_EVENT, win32con.CTRL_SHUTDOWN_EVENT, + win32con.CTRL_CLOSE_EVENT): + self.bus.log('Console event %s: shutting down bus' % event) + + # Remove self immediately so repeated Ctrl-C doesn't re-call it. + try: + self.stop() + except ValueError: + pass + + self.bus.exit() + # 'First to return True stops the calls' + return 1 + return 0 + + +class Win32Bus(wspbus.Bus): + """A Web Site Process Bus implementation for Win32. + + Instead of time.sleep, this bus blocks using native win32event objects. + """ + + def __init__(self): + self.events = {} + wspbus.Bus.__init__(self) + + def _get_state_event(self, state): + """Return a win32event for the given state (creating it if needed).""" + try: + return self.events[state] + except KeyError: + event = win32event.CreateEvent(None, 0, 0, + "WSPBus %s Event (pid=%r)" % + (state.name, os.getpid())) + self.events[state] = event + return event + + def _get_state(self): + return self._state + def _set_state(self, value): + self._state = value + event = self._get_state_event(value) + win32event.PulseEvent(event) + state = property(_get_state, _set_state) + + def wait(self, state, interval=0.1, channel=None): + """Wait for the given state(s), KeyboardInterrupt or SystemExit. + + Since this class uses native win32event objects, the interval + argument is ignored. + """ + if isinstance(state, (tuple, list)): + # Don't wait for an event that beat us to the punch ;) + if self.state not in state: + events = tuple([self._get_state_event(s) for s in state]) + win32event.WaitForMultipleObjects(events, 0, win32event.INFINITE) + else: + # Don't wait for an event that beat us to the punch ;) + if self.state != state: + event = self._get_state_event(state) + win32event.WaitForSingleObject(event, win32event.INFINITE) + + +class _ControlCodes(dict): + """Control codes used to "signal" a service via ControlService. + + User-defined control codes are in the range 128-255. We generally use + the standard Python value for the Linux signal and add 128. Example: + + >>> signal.SIGUSR1 + 10 + control_codes['graceful'] = 128 + 10 + """ + + def key_for(self, obj): + """For the given value, return its corresponding key.""" + for key, val in self.items(): + if val is obj: + return key + raise ValueError("The given object could not be found: %r" % obj) + +control_codes = _ControlCodes({'graceful': 138}) + + +def signal_child(service, command): + if command == 'stop': + win32serviceutil.StopService(service) + elif command == 'restart': + win32serviceutil.RestartService(service) + else: + win32serviceutil.ControlService(service, control_codes[command]) + + +class PyWebService(win32serviceutil.ServiceFramework): + """Python Web Service.""" + + _svc_name_ = "Python Web Service" + _svc_display_name_ = "Python Web Service" + _svc_deps_ = None # sequence of service names on which this depends + _exe_name_ = "pywebsvc" + _exe_args_ = None # Default to no arguments + + # Only exists on Windows 2000 or later, ignored on windows NT + _svc_description_ = "Python Web Service" + + def SvcDoRun(self): + from cherrypy import process + process.bus.start() + process.bus.block() + + def SvcStop(self): + from cherrypy import process + self.ReportServiceStatus(win32service.SERVICE_STOP_PENDING) + process.bus.exit() + + def SvcOther(self, control): + process.bus.publish(control_codes.key_for(control)) + + +if __name__ == '__main__': + win32serviceutil.HandleCommandLine(PyWebService) diff --git a/cherrypy/process/wspbus.py b/cherrypy/process/wspbus.py new file mode 100644 index 00000000..46cd75a2 --- /dev/null +++ b/cherrypy/process/wspbus.py @@ -0,0 +1,393 @@ +"""An implementation of the Web Site Process Bus. + +This module is completely standalone, depending only on the stdlib. + +Web Site Process Bus +-------------------- + +A Bus object is used to contain and manage site-wide behavior: +daemonization, HTTP server start/stop, process reload, signal handling, +drop privileges, PID file management, logging for all of these, +and many more. + +In addition, a Bus object provides a place for each web framework +to register code that runs in response to site-wide events (like +process start and stop), or which controls or otherwise interacts with +the site-wide components mentioned above. For example, a framework which +uses file-based templates would add known template filenames to an +autoreload component. + +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. + 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. + 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. + +The Bus object in this package uses topic-based publish-subscribe +messaging to accomplish all this. A few topic channels are built in +('start', 'stop', 'exit', 'graceful', 'log', and 'main'). Frameworks and +site containers are free to define their own. If a message is sent to a +channel that has not been defined or has no listeners, there is no effect. + +In general, there should only ever be a single Bus object per process. +Frameworks and site containers share a single Bus object by publishing +messages and subscribing listeners. + +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.:: + + O + | + V + STOPPING --> STOPPED --> EXITING -> X + A A | + | \___ | + | \ | + | V V + STARTED <-- STARTING + +""" + +import atexit +import os +import sys +import threading +import time +import traceback as _traceback +import warnings + +from cherrypy._cpcompat import set + +# Here I save the value of os.getcwd(), which, if I am imported early enough, +# will be the directory from which the startup script was run. This is needed +# by _do_execv(), to change back to the original directory before execv()ing a +# new process. This is a defense against the application having changed the +# current working directory (which could make sys.executable "not found" if +# sys.executable is a relative-path, and/or cause other problems). +_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): + # Don't use 'super' here; Exceptions are old-style in Py2.4 + # See http://www.cherrypy.org/ticket/959 + Exception.__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): + exception_strings = map(repr, self.get_instances()) + return self.delimiter.join(exception_strings) + + __repr__ = __str__ + + def __nonzero__(self): + return bool(self._exceptions) + +# Use a flag to indicate the state of the bus. +class _StateEnum(object): + class State(object): + name = None + def __repr__(self): + return "states.%s" % self.name + + def __setattr__(self, key, value): + if isinstance(value, self.State): + value.name = key + object.__setattr__(self, key, value) +states = _StateEnum() +states.STOPPED = states.State() +states.STARTING = states.State() +states.STARTED = states.State() +states.STOPPING = states.State() +states.EXITING = states.State() + + +class Bus(object): + """Process state-machine and messenger for HTTP site deployment. + + All listeners for a given channel are guaranteed to be called even + if others at the same channel fail. Each failure is logged, but + execution proceeds on to the next listener. The only way to stop all + processing from inside a listener is to raise SystemExit and stop the + whole server. + """ + + states = states + state = states.STOPPED + execv = False + + def __init__(self): + self.execv = False + self.state = states.STOPPED + self.listeners = dict( + [(channel, set()) for channel + in ('start', 'stop', 'exit', 'graceful', 'log', 'main')]) + self._priorities = {} + + def subscribe(self, channel, callback, priority=None): + """Add the given callback at the given channel (if not present).""" + if channel not in self.listeners: + self.listeners[channel] = set() + self.listeners[channel].add(callback) + + if priority is None: + priority = getattr(callback, 'priority', 50) + self._priorities[(channel, callback)] = priority + + def unsubscribe(self, channel, callback): + """Discard the given callback (if present).""" + listeners = self.listeners.get(channel) + if listeners and callback in listeners: + listeners.discard(callback) + del self._priorities[(channel, callback)] + + def publish(self, channel, *args, **kwargs): + """Return output of all subscribers for the given channel.""" + if channel not in self.listeners: + return [] + + exc = ChannelFailures() + output = [] + + items = [(self._priorities[(channel, listener)], listener) + for listener in self.listeners[channel]] + items.sort() + for priority, listener in items: + try: + output.append(listener(*args, **kwargs)) + except KeyboardInterrupt: + raise + except SystemExit, e: + # If we have previous errors ensure the exit code is non-zero + if exc and e.code == 0: + e.code = 1 + raise + except: + exc.handle_exception() + if channel == 'log': + # Assume any further messages to 'log' will fail. + pass + else: + self.log("Error in %r listener %r" % (channel, listener), + level=40, traceback=True) + if exc: + raise exc + return output + + def _clean_exit(self): + """An atexit handler which asserts the Bus is not running.""" + if self.state != states.EXITING: + warnings.warn( + "The main thread is exiting, but the Bus is in the %r state; " + "shutting it down automatically now. You must either call " + "bus.block() after start(), or call bus.exit() before the " + "main thread exits." % self.state, RuntimeWarning) + self.exit() + + def start(self): + """Start all services.""" + atexit.register(self._clean_exit) + + self.state = states.STARTING + self.log('Bus STARTING') + try: + self.publish('start') + self.state = states.STARTED + self.log('Bus STARTED') + except (KeyboardInterrupt, SystemExit): + raise + except: + self.log("Shutting down due to error in start listener:", + level=40, traceback=True) + e_info = sys.exc_info() + try: + self.exit() + except: + # Any stop/exit errors will be logged inside publish(). + pass + raise e_info[0], e_info[1], e_info[2] + + def exit(self): + """Stop all services and prepare to exit the process.""" + exitstate = self.state + try: + self.stop() + + self.state = states.EXITING + self.log('Bus EXITING') + self.publish('exit') + # This isn't strictly necessary, but it's better than seeing + # "Waiting for child threads to terminate..." and then nothing. + self.log('Bus EXITED') + except: + # This method is often called asynchronously (whether thread, + # signal handler, console handler, or atexit handler), so we + # can't just let exceptions propagate out unhandled. + # Assume it's been logged and just die. + os._exit(70) # EX_SOFTWARE + + if exitstate == states.STARTING: + # exit() was called before start() finished, possibly due to + # Ctrl-C because a start listener got stuck. In this case, + # we could get stuck in a loop where Ctrl-C never exits the + # process, so we just call os.exit here. + os._exit(70) # EX_SOFTWARE + + def restart(self): + """Restart the process (may close connections). + + This method does not restart the process from the calling thread; + instead, it stops the bus and asks the main thread to call execv. + """ + self.execv = True + self.exit() + + def graceful(self): + """Advise all services to reload.""" + self.log('Bus graceful') + self.publish('graceful') + + def block(self, interval=0.1): + """Wait for the EXITING state, KeyboardInterrupt or SystemExit. + + This function is intended to be called only by the main thread. + After waiting for the EXITING state, it also waits for all threads + to terminate, and then calls os.execv if self.execv is True. This + design allows another thread to call bus.restart, yet have the main + thread perform the actual execv call (required on some platforms). + """ + try: + self.wait(states.EXITING, interval=interval, channel='main') + except (KeyboardInterrupt, IOError): + # The time.sleep call might raise + # "IOError: [Errno 4] Interrupted function call" on KBInt. + self.log('Keyboard Interrupt: shutting down bus') + self.exit() + except SystemExit: + self.log('SystemExit raised: shutting down bus') + self.exit() + raise + + # Waiting for ALL child threads to finish is necessary on OS X. + # See http://www.cherrypy.org/ticket/581. + # It's also good to let them all shut down before allowing + # the main thread to call atexit handlers. + # See http://www.cherrypy.org/ticket/751. + self.log("Waiting for child threads to terminate...") + for t in threading.enumerate(): + if t != threading.currentThread() and t.isAlive(): + # Note that any dummy (external) threads are always daemonic. + if hasattr(threading.Thread, "daemon"): + # Python 2.6+ + d = t.daemon + else: + d = t.isDaemon() + if not d: + self.log("Waiting for thread %s." % t.getName()) + t.join() + + if self.execv: + self._do_execv() + + def wait(self, state, interval=0.1, channel=None): + """Poll for the given state(s) at intervals; publish to channel.""" + if isinstance(state, (tuple, list)): + states = state + else: + states = [state] + + def _wait(): + while self.state not in states: + time.sleep(interval) + self.publish(channel) + + # From http://psyco.sourceforge.net/psycoguide/bugs.html: + # "The compiled machine code does not include the regular polling + # done by Python, meaning that a KeyboardInterrupt will not be + # detected before execution comes back to the regular Python + # interpreter. Your program cannot be interrupted if caught + # into an infinite Psyco-compiled loop." + try: + sys.modules['psyco'].cannotcompile(_wait) + except (KeyError, AttributeError): + pass + + _wait() + + def _do_execv(self): + """Re-execute the current process. + + This must be called from the main thread, because certain platforms + (OS X) don't allow execv to be called in a child thread very well. + """ + args = sys.argv[:] + self.log('Re-spawning %s' % ' '.join(args)) + + if sys.platform[:4] == 'java': + from _systemrestart import SystemRestart + raise SystemRestart + else: + args.insert(0, sys.executable) + if sys.platform == 'win32': + args = ['"%s"' % arg for arg in args] + + os.chdir(_startup_cwd) + os.execv(sys.executable, args) + + def stop(self): + """Stop all services.""" + self.state = states.STOPPING + self.log('Bus STOPPING') + self.publish('stop') + self.state = states.STOPPED + self.log('Bus STOPPED') + + def start_with_callback(self, func, args=None, kwargs=None): + """Start 'func' in a new thread T, then start self (and return T).""" + if args is None: + args = () + if kwargs is None: + kwargs = {} + args = (func,) + args + + def _callback(func, *a, **kw): + self.wait(states.STARTED) + func(*a, **kw) + t = threading.Thread(target=_callback, args=args, kwargs=kwargs) + t.setName('Bus Callback ' + t.getName()) + t.start() + + self.start() + + return t + + def log(self, msg="", level=20, traceback=False): + """Log the given message. Append the last traceback if requested.""" + if traceback: + exc = sys.exc_info() + msg += "\n" + "".join(_traceback.format_exception(*exc)) + self.publish('log', msg, level) + +bus = Bus() diff --git a/cherrypy/scaffold/__init__.py b/cherrypy/scaffold/__init__.py new file mode 100644 index 00000000..00964ac5 --- /dev/null +++ b/cherrypy/scaffold/__init__.py @@ -0,0 +1,61 @@ +""", a CherryPy application. + +Use this as a base for creating new CherryPy applications. When you want +to make a new app, copy and paste this folder to some other location +(maybe site-packages) and rename it to the name of your project, +then tweak as desired. + +Even before any tweaking, this should serve a few demonstration pages. +Change to this directory and run: + + ../cherryd -c site.conf + +""" + +import cherrypy +from cherrypy import tools, url + +import os +local_dir = os.path.join(os.getcwd(), os.path.dirname(__file__)) + + +class Root: + + _cp_config = {'tools.log_tracebacks.on': True, + } + + def index(self): + return """ +Try some other path, +or a default path.
+Or, just look at the pretty picture:
+ +""" % (url("other"), url("else"), + url("files/made_with_cherrypy_small.png")) + index.exposed = True + + def default(self, *args, **kwargs): + return "args: %s kwargs: %s" % (args, kwargs) + default.exposed = True + + def other(self, a=2, b='bananas', c=None): + cherrypy.response.headers['Content-Type'] = 'text/plain' + if c is None: + return "Have %d %s." % (int(a), b) + else: + return "Have %d %s, %s." % (int(a), b, c) + other.exposed = True + + files = cherrypy.tools.staticdir.handler( + section="/files", + dir=os.path.join(local_dir, "static"), + # Ignore .php files, etc. + match=r'\.(css|gif|html?|ico|jpe?g|js|png|swf|xml)$', + ) + + +root = Root() + +# Uncomment the following to use your own favicon instead of CP's default. +#favicon_path = os.path.join(local_dir, "favicon.ico") +#root.favicon_ico = tools.staticfile.handler(filename=favicon_path) diff --git a/cherrypy/scaffold/apache-fcgi.conf b/cherrypy/scaffold/apache-fcgi.conf new file mode 100644 index 00000000..922398ea --- /dev/null +++ b/cherrypy/scaffold/apache-fcgi.conf @@ -0,0 +1,22 @@ +# Apache2 server conf file for using CherryPy with mod_fcgid. + +# This doesn't have to be "C:/", but it has to be a directory somewhere, and +# MUST match the directory used in the FastCgiExternalServer directive, below. +DocumentRoot "C:/" + +ServerName 127.0.0.1 +Listen 80 +LoadModule fastcgi_module modules/mod_fastcgi.dll +LoadModule rewrite_module modules/mod_rewrite.so + +Options ExecCGI +SetHandler fastcgi-script +RewriteEngine On +# Send requests for any URI to our fastcgi handler. +RewriteRule ^(.*)$ /fastcgi.pyc [L] + +# The FastCgiExternalServer directive defines filename as an external FastCGI application. +# If filename does not begin with a slash (/) then it is assumed to be relative to the ServerRoot. +# The filename does not have to exist in the local filesystem. URIs that Apache resolves to this +# filename will be handled by this external FastCGI application. +FastCgiExternalServer "C:/fastcgi.pyc" -host 127.0.0.1:8088 \ No newline at end of file diff --git a/cherrypy/scaffold/example.conf b/cherrypy/scaffold/example.conf new file mode 100644 index 00000000..93a6e53c --- /dev/null +++ b/cherrypy/scaffold/example.conf @@ -0,0 +1,3 @@ +[/] +log.error_file: "error.log" +log.access_file: "access.log" \ No newline at end of file diff --git a/cherrypy/scaffold/site.conf b/cherrypy/scaffold/site.conf new file mode 100644 index 00000000..6ed38983 --- /dev/null +++ b/cherrypy/scaffold/site.conf @@ -0,0 +1,14 @@ +[global] +# Uncomment this when you're done developing +#environment: "production" + +server.socket_host: "0.0.0.0" +server.socket_port: 8088 + +# Uncomment the following lines to run on HTTPS at the same time +#server.2.socket_host: "0.0.0.0" +#server.2.socket_port: 8433 +#server.2.ssl_certificate: '../test/test.pem' +#server.2.ssl_private_key: '../test/test.pem' + +tree.myapp: cherrypy.Application(scaffold.root, "/", "example.conf") diff --git a/cherrypy/scaffold/static/made_with_cherrypy_small.png b/cherrypy/scaffold/static/made_with_cherrypy_small.png new file mode 100644 index 0000000000000000000000000000000000000000..c3aafeed952190f5da9982bb359aa75b107ff079 GIT binary patch literal 7455 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 + + CherryPy Benchmark + + + + +""" + index.exposed = True + + def hello(self): + return "Hello, world\r\n" + hello.exposed = True + + def sizer(self, size): + resp = size_cache.get(size, None) + if resp is None: + size_cache[size] = resp = "X" * int(size) + return resp + sizer.exposed = True + + +cherrypy.config.update({ + 'log.error.file': '', + 'environment': 'production', + 'server.socket_host': '127.0.0.1', + 'server.socket_port': 8080, + 'server.max_request_header_size': 0, + 'server.max_request_body_size': 0, + 'engine.deadlock_poll_freq': 0, + }) + +# Cheat mode on ;) +del cherrypy.config['tools.log_tracebacks.on'] +del cherrypy.config['tools.log_headers.on'] +del cherrypy.config['tools.trailing_slash.on'] + +appconf = { + '/static': { + 'tools.staticdir.on': True, + 'tools.staticdir.dir': 'static', + 'tools.staticdir.root': curdir, + }, + } +app = cherrypy.tree.mount(Root(), SCRIPT_NAME, appconf) + + +class NullRequest: + """A null HTTP request class, returning 200 and an empty body.""" + + def __init__(self, local, remote, scheme="http"): + pass + + def close(self): + pass + + def run(self, method, path, query_string, protocol, headers, rfile): + cherrypy.response.status = "200 OK" + cherrypy.response.header_list = [("Content-Type", 'text/html'), + ("Server", "Null CherryPy"), + ("Date", httputil.HTTPDate()), + ("Content-Length", "0"), + ] + cherrypy.response.body = [""] + return cherrypy.response + + +class NullResponse: + pass + + +class ABSession: + """A session of 'ab', the Apache HTTP server benchmarking tool. + +Example output from ab: + +This is ApacheBench, Version 2.0.40-dev <$Revision: 1.121.2.1 $> apache-2.0 +Copyright (c) 1996 Adam Twiss, Zeus Technology Ltd, http://www.zeustech.net/ +Copyright (c) 1998-2002 The Apache Software Foundation, http://www.apache.org/ + +Benchmarking 127.0.0.1 (be patient) +Completed 100 requests +Completed 200 requests +Completed 300 requests +Completed 400 requests +Completed 500 requests +Completed 600 requests +Completed 700 requests +Completed 800 requests +Completed 900 requests + + +Server Software: CherryPy/3.1beta +Server Hostname: 127.0.0.1 +Server Port: 8080 + +Document Path: /static/index.html +Document Length: 14 bytes + +Concurrency Level: 10 +Time taken for tests: 9.643867 seconds +Complete requests: 1000 +Failed requests: 0 +Write errors: 0 +Total transferred: 189000 bytes +HTML transferred: 14000 bytes +Requests per second: 103.69 [#/sec] (mean) +Time per request: 96.439 [ms] (mean) +Time per request: 9.644 [ms] (mean, across all concurrent requests) +Transfer rate: 19.08 [Kbytes/sec] received + +Connection Times (ms) + min mean[+/-sd] median max +Connect: 0 0 2.9 0 10 +Processing: 20 94 7.3 90 130 +Waiting: 0 43 28.1 40 100 +Total: 20 95 7.3 100 130 + +Percentage of the requests served within a certain time (ms) + 50% 100 + 66% 100 + 75% 100 + 80% 100 + 90% 100 + 95% 100 + 98% 100 + 99% 110 + 100% 130 (longest request) +Finished 1000 requests +""" + + parse_patterns = [('complete_requests', 'Completed', + ntob(r'^Complete requests:\s*(\d+)')), + ('failed_requests', 'Failed', + ntob(r'^Failed requests:\s*(\d+)')), + ('requests_per_second', 'req/sec', + ntob(r'^Requests per second:\s*([0-9.]+)')), + ('time_per_request_concurrent', 'msec/req', + ntob(r'^Time per request:\s*([0-9.]+).*concurrent requests\)$')), + ('transfer_rate', 'KB/sec', + ntob(r'^Transfer rate:\s*([0-9.]+)')), + ] + + def __init__(self, path=SCRIPT_NAME + "/hello", requests=1000, concurrency=10): + self.path = path + self.requests = requests + self.concurrency = concurrency + + def args(self): + port = cherrypy.server.socket_port + assert self.concurrency > 0 + assert self.requests > 0 + # Don't use "localhost". + # Cf http://mail.python.org/pipermail/python-win32/2008-March/007050.html + return ("-k -n %s -c %s http://127.0.0.1:%s%s" % + (self.requests, self.concurrency, port, self.path)) + + def run(self): + # Parse output of ab, setting attributes on self + try: + self.output = _cpmodpy.read_process(AB_PATH or "ab", self.args()) + except: + print(_cperror.format_exc()) + raise + + for attr, name, pattern in self.parse_patterns: + val = re.search(pattern, self.output, re.MULTILINE) + if val: + val = val.group(1) + setattr(self, attr, val) + else: + setattr(self, attr, None) + + +safe_threads = (25, 50, 100, 200, 400) +if sys.platform in ("win32",): + # For some reason, ab crashes with > 50 threads on my Win2k laptop. + safe_threads = (10, 20, 30, 40, 50) + + +def thread_report(path=SCRIPT_NAME + "/hello", concurrency=safe_threads): + sess = ABSession(path) + attrs, names, patterns = list(zip(*sess.parse_patterns)) + avg = dict.fromkeys(attrs, 0.0) + + yield ('threads',) + names + for c in concurrency: + sess.concurrency = c + sess.run() + row = [c] + for attr in attrs: + val = getattr(sess, attr) + if val is None: + print(sess.output) + row = None + break + val = float(val) + avg[attr] += float(val) + row.append(val) + if row: + yield row + + # Add a row of averages. + yield ["Average"] + [str(avg[attr] / len(concurrency)) for attr in attrs] + +def size_report(sizes=(10, 100, 1000, 10000, 100000, 100000000), + concurrency=50): + sess = ABSession(concurrency=concurrency) + attrs, names, patterns = list(zip(*sess.parse_patterns)) + yield ('bytes',) + names + for sz in sizes: + sess.path = "%s/sizer?size=%s" % (SCRIPT_NAME, sz) + sess.run() + yield [sz] + [getattr(sess, attr) for attr in attrs] + +def print_report(rows): + for row in rows: + print("") + for i, val in enumerate(row): + sys.stdout.write(str(val).rjust(10) + " | ") + print("") + + +def run_standard_benchmarks(): + print("") + print("Client Thread Report (1000 requests, 14 byte response body, " + "%s server threads):" % cherrypy.server.thread_pool) + print_report(thread_report()) + + print("") + print("Client Thread Report (1000 requests, 14 bytes via staticdir, " + "%s server threads):" % cherrypy.server.thread_pool) + print_report(thread_report("%s/static/index.html" % SCRIPT_NAME)) + + print("") + print("Size Report (1000 requests, 50 client threads, " + "%s server threads):" % cherrypy.server.thread_pool) + print_report(size_report()) + + +# modpython and other WSGI # + +def startup_modpython(req=None): + """Start the CherryPy app server in 'serverless' mode (for modpython/WSGI).""" + if cherrypy.engine.state == cherrypy._cpengine.STOPPED: + if req: + if "nullreq" in req.get_options(): + cherrypy.engine.request_class = NullRequest + cherrypy.engine.response_class = NullResponse + ab_opt = req.get_options().get("ab", "") + if ab_opt: + global AB_PATH + AB_PATH = ab_opt + cherrypy.engine.start() + if cherrypy.engine.state == cherrypy._cpengine.STARTING: + cherrypy.engine.wait() + return 0 # apache.OK + + +def run_modpython(use_wsgi=False): + print("Starting mod_python...") + pyopts = [] + + # Pass the null and ab=path options through Apache + if "--null" in opts: + pyopts.append(("nullreq", "")) + + if "--ab" in opts: + pyopts.append(("ab", opts["--ab"])) + + s = _cpmodpy.ModPythonServer + if use_wsgi: + pyopts.append(("wsgi.application", "cherrypy::tree")) + pyopts.append(("wsgi.startup", "cherrypy.test.benchmark::startup_modpython")) + handler = "modpython_gateway::handler" + s = s(port=8080, opts=pyopts, apache_path=APACHE_PATH, handler=handler) + else: + pyopts.append(("cherrypy.setup", "cherrypy.test.benchmark::startup_modpython")) + s = s(port=8080, opts=pyopts, apache_path=APACHE_PATH) + + try: + s.start() + run() + finally: + s.stop() + + + +if __name__ == '__main__': + longopts = ['cpmodpy', 'modpython', 'null', 'notests', + 'help', 'ab=', 'apache='] + try: + switches, args = getopt.getopt(sys.argv[1:], "", longopts) + opts = dict(switches) + except getopt.GetoptError: + print(__doc__) + sys.exit(2) + + if "--help" in opts: + print(__doc__) + sys.exit(0) + + if "--ab" in opts: + AB_PATH = opts['--ab'] + + if "--notests" in opts: + # Return without stopping the server, so that the pages + # can be tested from a standard web browser. + def run(): + port = cherrypy.server.socket_port + print("You may now open http://127.0.0.1:%s%s/" % + (port, SCRIPT_NAME)) + + if "--null" in opts: + print("Using null Request object") + else: + def run(): + end = time.time() - start + print("Started in %s seconds" % end) + if "--null" in opts: + print("\nUsing null Request object") + try: + try: + run_standard_benchmarks() + except: + print(_cperror.format_exc()) + raise + finally: + cherrypy.engine.exit() + + print("Starting CherryPy app server...") + + class NullWriter(object): + """Suppresses the printing of socket errors.""" + def write(self, data): + pass + sys.stderr = NullWriter() + + start = time.time() + + if "--cpmodpy" in opts: + run_modpython() + elif "--modpython" in opts: + run_modpython(use_wsgi=True) + else: + if "--null" in opts: + cherrypy.server.request_class = NullRequest + cherrypy.server.response_class = NullResponse + + cherrypy.engine.start_with_callback(run) + cherrypy.engine.block() diff --git a/cherrypy/test/checkerdemo.py b/cherrypy/test/checkerdemo.py new file mode 100644 index 00000000..32a7dee2 --- /dev/null +++ b/cherrypy/test/checkerdemo.py @@ -0,0 +1,47 @@ +"""Demonstration app for cherrypy.checker. + +This application is intentionally broken and badly designed. +To demonstrate the output of the CherryPy Checker, simply execute +this module. +""" + +import os +import cherrypy +thisdir = os.path.dirname(os.path.abspath(__file__)) + +class Root: + pass + +if __name__ == '__main__': + conf = {'/base': {'tools.staticdir.root': thisdir, + # Obsolete key. + 'throw_errors': True, + }, + # This entry should be OK. + '/base/static': {'tools.staticdir.on': True, + 'tools.staticdir.dir': 'static'}, + # Warn on missing folder. + '/base/js': {'tools.staticdir.on': True, + 'tools.staticdir.dir': 'js'}, + # Warn on dir with an abs path even though we provide root. + '/base/static2': {'tools.staticdir.on': True, + 'tools.staticdir.dir': '/static'}, + # Warn on dir with a relative path with no root. + '/static3': {'tools.staticdir.on': True, + 'tools.staticdir.dir': 'static'}, + # Warn on unknown namespace + '/unknown': {'toobles.gzip.on': True}, + # Warn special on cherrypy..* + '/cpknown': {'cherrypy.tools.encode.on': True}, + # Warn on mismatched types + '/conftype': {'request.show_tracebacks': 14}, + # Warn on unknown tool. + '/web': {'tools.unknown.on': True}, + # Warn on server.* in app config. + '/app1': {'server.socket_host': '0.0.0.0'}, + # Warn on 'localhost' + 'global': {'server.socket_host': 'localhost'}, + # Warn on '[name]' + '[/extra_brackets]': {}, + } + cherrypy.quickstart(Root(), config=conf) diff --git a/cherrypy/test/fastcgi.conf b/cherrypy/test/fastcgi.conf new file mode 100644 index 00000000..e5c5163c --- /dev/null +++ b/cherrypy/test/fastcgi.conf @@ -0,0 +1,18 @@ + +# Apache2 server conf file for testing CherryPy with mod_fastcgi. +# fumanchu: I had to hard-code paths due to crazy Debian layouts :( +ServerRoot /usr/lib/apache2 +User #1000 +ErrorLog /usr/lib/python2.5/site-packages/cproot/trunk/cherrypy/test/mod_fastcgi.error.log + +DocumentRoot "/usr/lib/python2.5/site-packages/cproot/trunk/cherrypy/test" +ServerName 127.0.0.1 +Listen 8080 +LoadModule fastcgi_module modules/mod_fastcgi.so +LoadModule rewrite_module modules/mod_rewrite.so + +Options +ExecCGI +SetHandler fastcgi-script +RewriteEngine On +RewriteRule ^(.*)$ /fastcgi.pyc [L] +FastCgiExternalServer "/usr/lib/python2.5/site-packages/cproot/trunk/cherrypy/test/fastcgi.pyc" -host 127.0.0.1:4000 diff --git a/cherrypy/test/fcgi.conf b/cherrypy/test/fcgi.conf new file mode 100644 index 00000000..8cf24b64 --- /dev/null +++ b/cherrypy/test/fcgi.conf @@ -0,0 +1,14 @@ + +# Apache2 server conf file for testing CherryPy with mod_fcgid. + +DocumentRoot "C:\Python25\Lib\site-packages\cherrypy\test" +ServerName 127.0.0.1 +Listen 8080 +LoadModule fastcgi_module modules/mod_fastcgi.dll +LoadModule rewrite_module modules/mod_rewrite.so + +Options ExecCGI +SetHandler fastcgi-script +RewriteEngine On +RewriteRule ^(.*)$ /fastcgi.pyc [L] +FastCgiExternalServer "C:\\Python25\\Lib\\site-packages\\cherrypy\\test\\fastcgi.pyc" -host 127.0.0.1:4000 diff --git a/cherrypy/test/helper.py b/cherrypy/test/helper.py new file mode 100644 index 00000000..ff9e06cf --- /dev/null +++ b/cherrypy/test/helper.py @@ -0,0 +1,476 @@ +"""A library of helper functions for the CherryPy test suite.""" + +import datetime +import logging +log = logging.getLogger(__name__) +import os +thisdir = os.path.abspath(os.path.dirname(__file__)) +serverpem = os.path.join(os.getcwd(), thisdir, 'test.pem') + +import re +import sys +import time +import warnings + +import cherrypy +from cherrypy._cpcompat import basestring, copyitems, HTTPSConnection, ntob +from cherrypy.lib import httputil +from cherrypy.lib.reprconf import unrepr +from cherrypy.test import webtest + +import nose + +_testconfig = None + +def get_tst_config(overconf = {}): + global _testconfig + if _testconfig is None: + conf = { + 'scheme': 'http', + 'protocol': "HTTP/1.1", + 'port': 8080, + 'host': '127.0.0.1', + 'validate': False, + 'conquer': False, + 'server': 'wsgi', + } + try: + import testconfig + _conf = testconfig.config.get('supervisor', None) + if _conf is not None: + for k, v in _conf.items(): + if isinstance(v, basestring): + _conf[k] = unrepr(v) + conf.update(_conf) + except ImportError: + pass + _testconfig = conf + conf = _testconfig.copy() + conf.update(overconf) + + return conf + +class Supervisor(object): + """Base class for modeling and controlling servers during testing.""" + + def __init__(self, **kwargs): + for k, v in kwargs.items(): + if k == 'port': + setattr(self, k, int(v)) + setattr(self, k, v) + + +log_to_stderr = lambda msg, level: sys.stderr.write(msg + os.linesep) + +class LocalSupervisor(Supervisor): + """Base class for modeling/controlling servers which run in the same process. + + When the server side runs in a different process, start/stop can dump all + state between each test module easily. When the server side runs in the + same process as the client, however, we have to do a bit more work to ensure + config and mounted apps are reset between tests. + """ + + using_apache = False + using_wsgi = False + + def __init__(self, **kwargs): + for k, v in kwargs.items(): + setattr(self, k, v) + + cherrypy.server.httpserver = self.httpserver_class + + engine = cherrypy.engine + if hasattr(engine, "signal_handler"): + engine.signal_handler.subscribe() + if hasattr(engine, "console_control_handler"): + engine.console_control_handler.subscribe() + #engine.subscribe('log', log_to_stderr) + + def start(self, modulename=None): + """Load and start the HTTP server.""" + if modulename: + # Unhook httpserver so cherrypy.server.start() creates a new + # one (with config from setup_server, if declared). + cherrypy.server.httpserver = None + + cherrypy.engine.start() + + self.sync_apps() + + def sync_apps(self): + """Tell the server about any apps which the setup functions mounted.""" + pass + + def stop(self): + td = getattr(self, 'teardown', None) + if td: + td() + + cherrypy.engine.exit() + + for name, server in copyitems(getattr(cherrypy, 'servers', {})): + server.unsubscribe() + del cherrypy.servers[name] + + +class NativeServerSupervisor(LocalSupervisor): + """Server supervisor for the builtin HTTP server.""" + + httpserver_class = "cherrypy._cpnative_server.CPHTTPServer" + using_apache = False + using_wsgi = False + + def __str__(self): + return "Builtin HTTP Server on %s:%s" % (self.host, self.port) + + +class LocalWSGISupervisor(LocalSupervisor): + """Server supervisor for the builtin WSGI server.""" + + httpserver_class = "cherrypy._cpwsgi_server.CPWSGIServer" + using_apache = False + using_wsgi = True + + def __str__(self): + return "Builtin WSGI Server on %s:%s" % (self.host, self.port) + + def sync_apps(self): + """Hook a new WSGI app into the origin server.""" + cherrypy.server.httpserver.wsgi_app = self.get_app() + + def get_app(self, app=None): + """Obtain a new (decorated) WSGI app to hook into the origin server.""" + if app is None: + app = cherrypy.tree + + if self.conquer: + try: + import wsgiconq + except ImportError: + warnings.warn("Error importing wsgiconq. pyconquer will not run.") + else: + app = wsgiconq.WSGILogger(app, c_calls=True) + + if self.validate: + try: + from wsgiref import validate + except ImportError: + warnings.warn("Error importing wsgiref. The validator will not run.") + else: + #wraps the app in the validator + app = validate.validator(app) + + return app + + +def get_cpmodpy_supervisor(**options): + from cherrypy.test import modpy + sup = modpy.ModPythonSupervisor(**options) + sup.template = modpy.conf_cpmodpy + return sup + +def get_modpygw_supervisor(**options): + from cherrypy.test import modpy + sup = modpy.ModPythonSupervisor(**options) + sup.template = modpy.conf_modpython_gateway + sup.using_wsgi = True + return sup + +def get_modwsgi_supervisor(**options): + from cherrypy.test import modwsgi + return modwsgi.ModWSGISupervisor(**options) + +def get_modfcgid_supervisor(**options): + from cherrypy.test import modfcgid + return modfcgid.ModFCGISupervisor(**options) + +def get_modfastcgi_supervisor(**options): + from cherrypy.test import modfastcgi + return modfastcgi.ModFCGISupervisor(**options) + +def get_wsgi_u_supervisor(**options): + cherrypy.server.wsgi_version = ('u', 0) + return LocalWSGISupervisor(**options) + + +class CPWebCase(webtest.WebCase): + + script_name = "" + scheme = "http" + + available_servers = {'wsgi': LocalWSGISupervisor, + 'wsgi_u': get_wsgi_u_supervisor, + 'native': NativeServerSupervisor, + 'cpmodpy': get_cpmodpy_supervisor, + 'modpygw': get_modpygw_supervisor, + 'modwsgi': get_modwsgi_supervisor, + 'modfcgid': get_modfcgid_supervisor, + 'modfastcgi': get_modfastcgi_supervisor, + } + default_server = "wsgi" + + def _setup_server(cls, supervisor, conf): + v = sys.version.split()[0] + log.info("Python version used to run this test script: %s" % v) + log.info("CherryPy version: %s" % cherrypy.__version__) + if supervisor.scheme == "https": + ssl = " (ssl)" + else: + ssl = "" + log.info("HTTP server version: %s%s" % (supervisor.protocol, ssl)) + log.info("PID: %s" % os.getpid()) + + cherrypy.server.using_apache = supervisor.using_apache + cherrypy.server.using_wsgi = supervisor.using_wsgi + + if sys.platform[:4] == 'java': + cherrypy.config.update({'server.nodelay': False}) + + if isinstance(conf, basestring): + parser = cherrypy.lib.reprconf.Parser() + conf = parser.dict_from_file(conf).get('global', {}) + else: + conf = conf or {} + baseconf = conf.copy() + baseconf.update({'server.socket_host': supervisor.host, + 'server.socket_port': supervisor.port, + 'server.protocol_version': supervisor.protocol, + 'environment': "test_suite", + }) + if supervisor.scheme == "https": + #baseconf['server.ssl_module'] = 'builtin' + baseconf['server.ssl_certificate'] = serverpem + baseconf['server.ssl_private_key'] = serverpem + + # helper must be imported lazily so the coverage tool + # can run against module-level statements within cherrypy. + # Also, we have to do "from cherrypy.test import helper", + # exactly like each test module does, because a relative import + # would stick a second instance of webtest in sys.modules, + # and we wouldn't be able to globally override the port anymore. + if supervisor.scheme == "https": + webtest.WebCase.HTTP_CONN = HTTPSConnection + return baseconf + _setup_server = classmethod(_setup_server) + + def setup_class(cls): + '' + #Creates a server + conf = get_tst_config() + supervisor_factory = cls.available_servers.get(conf.get('server', 'wsgi')) + if supervisor_factory is None: + raise RuntimeError('Unknown server in config: %s' % conf['server']) + supervisor = supervisor_factory(**conf) + + #Copied from "run_test_suite" + cherrypy.config.reset() + baseconf = cls._setup_server(supervisor, conf) + cherrypy.config.update(baseconf) + setup_client() + + if hasattr(cls, 'setup_server'): + # Clear the cherrypy tree and clear the wsgi server so that + # it can be updated with the new root + cherrypy.tree = cherrypy._cptree.Tree() + cherrypy.server.httpserver = None + cls.setup_server() + supervisor.start(cls.__module__) + + cls.supervisor = supervisor + setup_class = classmethod(setup_class) + + def teardown_class(cls): + '' + if hasattr(cls, 'setup_server'): + cls.supervisor.stop() + teardown_class = classmethod(teardown_class) + + def prefix(self): + return self.script_name.rstrip("/") + + def base(self): + if ((self.scheme == "http" and self.PORT == 80) or + (self.scheme == "https" and self.PORT == 443)): + port = "" + else: + port = ":%s" % self.PORT + + return "%s://%s%s%s" % (self.scheme, self.HOST, port, + self.script_name.rstrip("/")) + + def exit(self): + sys.exit() + + def getPage(self, url, headers=None, method="GET", body=None, protocol=None): + """Open the url. Return status, headers, body.""" + if self.script_name: + url = httputil.urljoin(self.script_name, url) + return webtest.WebCase.getPage(self, url, headers, method, body, protocol) + + def skip(self, msg='skipped '): + raise nose.SkipTest(msg) + + def assertErrorPage(self, status, message=None, pattern=''): + """Compare the response body with a built in error page. + + The function will optionally look for the regexp pattern, + within the exception embedded in the error page.""" + + # This will never contain a traceback + page = cherrypy._cperror.get_error_page(status, message=message) + + # First, test the response body without checking the traceback. + # Stick a match-all group (.*) in to grab the traceback. + esc = re.escape + epage = esc(page) + epage = epage.replace(esc('
'),
+                              esc('
') + '(.*)' + esc('
'))
+        m = re.match(ntob(epage, self.encoding), self.body, re.DOTALL)
+        if not m:
+            self._handlewebError('Error page does not match; expected:\n' + page)
+            return
+        
+        # Now test the pattern against the traceback
+        if pattern is None:
+            # Special-case None to mean that there should be *no* traceback.
+            if m and m.group(1):
+                self._handlewebError('Error page contains traceback')
+        else:
+            if (m is None) or (
+                not re.search(ntob(re.escape(pattern), self.encoding),
+                              m.group(1))):
+                msg = 'Error page does not contain %s in traceback'
+                self._handlewebError(msg % repr(pattern))
+    
+    date_tolerance = 2
+    
+    def assertEqualDates(self, dt1, dt2, seconds=None):
+        """Assert abs(dt1 - dt2) is within Y seconds."""
+        if seconds is None:
+            seconds = self.date_tolerance
+        
+        if dt1 > dt2:
+            diff = dt1 - dt2
+        else:
+            diff = dt2 - dt1
+        if not diff < datetime.timedelta(seconds=seconds):
+            raise AssertionError('%r and %r are not within %r seconds.' %
+                                 (dt1, dt2, seconds))
+
+
+def setup_client():
+    """Set up the WebCase classes to match the server's socket settings."""
+    webtest.WebCase.PORT = cherrypy.server.socket_port
+    webtest.WebCase.HOST = cherrypy.server.socket_host
+    if cherrypy.server.ssl_certificate:
+        CPWebCase.scheme = 'https'
+
+# --------------------------- Spawning helpers --------------------------- #
+
+
+class CPProcess(object):
+    
+    pid_file = os.path.join(thisdir, 'test.pid')
+    config_file = os.path.join(thisdir, 'test.conf')
+    config_template = """[global]
+server.socket_host: '%(host)s'
+server.socket_port: %(port)s
+checker.on: False
+log.screen: False
+log.error_file: r'%(error_log)s'
+log.access_file: r'%(access_log)s'
+%(ssl)s
+%(extra)s
+"""
+    error_log = os.path.join(thisdir, 'test.error.log')
+    access_log = os.path.join(thisdir, 'test.access.log')
+    
+    def __init__(self, wait=False, daemonize=False, ssl=False, socket_host=None, socket_port=None):
+        self.wait = wait
+        self.daemonize = daemonize
+        self.ssl = ssl
+        self.host = socket_host or cherrypy.server.socket_host
+        self.port = socket_port or cherrypy.server.socket_port
+    
+    def write_conf(self, extra=""):
+        if self.ssl:
+            serverpem = os.path.join(thisdir, 'test.pem')
+            ssl = """
+server.ssl_certificate: r'%s'
+server.ssl_private_key: r'%s'
+""" % (serverpem, serverpem)
+        else:
+            ssl = ""
+        
+        conf = self.config_template % {
+            'host': self.host,
+            'port': self.port,
+            'error_log': self.error_log,
+            'access_log': self.access_log,
+            'ssl': ssl,
+            'extra': extra,
+            }
+        f = open(self.config_file, 'wb')
+        f.write(ntob(conf, 'utf-8'))
+        f.close()
+    
+    def start(self, imports=None):
+        """Start cherryd in a subprocess."""
+        cherrypy._cpserver.wait_for_free_port(self.host, self.port)
+        
+        args = [sys.executable, os.path.join(thisdir, '..', 'cherryd'),
+                '-c', self.config_file, '-p', self.pid_file]
+        
+        if not isinstance(imports, (list, tuple)):
+            imports = [imports]
+        for i in imports:
+            if i:
+                args.append('-i')
+                args.append(i)
+        
+        if self.daemonize:
+            args.append('-d')
+
+        env = os.environ.copy()
+        # Make sure we import the cherrypy package in which this module is defined.
+        grandparentdir = os.path.abspath(os.path.join(thisdir, '..', '..'))
+        if env.get('PYTHONPATH', ''):
+            env['PYTHONPATH'] = os.pathsep.join((grandparentdir, env['PYTHONPATH']))
+        else:
+            env['PYTHONPATH'] = grandparentdir
+        if self.wait:
+            self.exit_code = os.spawnve(os.P_WAIT, sys.executable, args, env)
+        else:
+            os.spawnve(os.P_NOWAIT, sys.executable, args, env)
+            cherrypy._cpserver.wait_for_occupied_port(self.host, self.port)
+        
+        # Give the engine a wee bit more time to finish STARTING
+        if self.daemonize:
+            time.sleep(2)
+        else:
+            time.sleep(1)
+    
+    def get_pid(self):
+        return int(open(self.pid_file, 'rb').read())
+    
+    def join(self):
+        """Wait for the process to exit."""
+        try:
+            try:
+                # Mac, UNIX
+                os.wait()
+            except AttributeError:
+                # Windows
+                try:
+                    pid = self.get_pid()
+                except IOError:
+                    # Assume the subprocess deleted the pidfile on shutdown.
+                    pass
+                else:
+                    os.waitpid(pid, 0)
+        except OSError:
+            x = sys.exc_info()[1]
+            if x.args != (10, 'No child processes'):
+                raise
+
diff --git a/cherrypy/test/logtest.py b/cherrypy/test/logtest.py
new file mode 100644
index 00000000..c093da2c
--- /dev/null
+++ b/cherrypy/test/logtest.py
@@ -0,0 +1,181 @@
+"""logtest, a unittest.TestCase helper for testing log output."""
+
+import sys
+import time
+
+import cherrypy
+
+
+try:
+    # On Windows, msvcrt.getch reads a single char without output.
+    import msvcrt
+    def getchar():
+        return msvcrt.getch()
+except ImportError:
+    # Unix getchr
+    import tty, termios
+    def getchar():
+        fd = sys.stdin.fileno()
+        old_settings = termios.tcgetattr(fd)
+        try:
+            tty.setraw(sys.stdin.fileno())
+            ch = sys.stdin.read(1)
+        finally:
+            termios.tcsetattr(fd, termios.TCSADRAIN, old_settings)
+        return ch
+
+
+class LogCase(object):
+    """unittest.TestCase mixin for testing log messages.
+    
+    logfile: a filename for the desired log. Yes, I know modes are evil,
+        but it makes the test functions so much cleaner to set this once.
+    
+    lastmarker: the last marker in the log. This can be used to search for
+        messages since the last marker.
+    
+    markerPrefix: a string with which to prefix log markers. This should be
+        unique enough from normal log output to use for marker identification.
+    """
+    
+    logfile = None
+    lastmarker = None
+    markerPrefix = "test suite marker: "
+    
+    def _handleLogError(self, msg, data, marker, pattern):
+        print("")
+        print("    ERROR: %s" % msg)
+        
+        if not self.interactive:
+            raise self.failureException(msg)
+        
+        p = "    Show: [L]og [M]arker [P]attern; [I]gnore, [R]aise, or sys.e[X]it >> "
+        print p,
+        # ARGH
+        sys.stdout.flush()
+        while True:
+            i = getchar().upper()
+            if i not in "MPLIRX":
+                continue
+            print(i.upper())  # Also prints new line
+            if i == "L":
+                for x, line in enumerate(data):
+                    if (x + 1) % self.console_height == 0:
+                        # The \r and comma should make the next line overwrite
+                        print "<-- More -->\r",
+                        m = getchar().lower()
+                        # Erase our "More" prompt
+                        print "            \r",
+                        if m == "q":
+                            break
+                    print(line.rstrip())
+            elif i == "M":
+                print(repr(marker or self.lastmarker))
+            elif i == "P":
+                print(repr(pattern))
+            elif i == "I":
+                # return without raising the normal exception
+                return
+            elif i == "R":
+                raise self.failureException(msg)
+            elif i == "X":
+                self.exit()
+            print p,
+    
+    def exit(self):
+        sys.exit()
+    
+    def emptyLog(self):
+        """Overwrite self.logfile with 0 bytes."""
+        open(self.logfile, 'wb').write("")
+    
+    def markLog(self, key=None):
+        """Insert a marker line into the log and set self.lastmarker."""
+        if key is None:
+            key = str(time.time())
+        self.lastmarker = key
+        
+        open(self.logfile, 'ab+').write("%s%s\n" % (self.markerPrefix, key))
+    
+    def _read_marked_region(self, marker=None):
+        """Return lines from self.logfile in the marked region.
+        
+        If marker is None, self.lastmarker is used. If the log hasn't
+        been marked (using self.markLog), the entire log will be returned.
+        """
+##        # Give the logger time to finish writing?
+##        time.sleep(0.5)
+        
+        logfile = self.logfile
+        marker = marker or self.lastmarker
+        if marker is None:
+            return open(logfile, 'rb').readlines()
+        
+        data = []
+        in_region = False
+        for line in open(logfile, 'rb'):
+            if in_region:
+                if (line.startswith(self.markerPrefix) and not marker in line):
+                    break
+                else:
+                    data.append(line)
+            elif marker in line:
+                in_region = True
+        return data
+    
+    def assertInLog(self, line, marker=None):
+        """Fail if the given (partial) line is not in the log.
+        
+        The log will be searched from the given marker to the next marker.
+        If marker is None, self.lastmarker is used. If the log hasn't
+        been marked (using self.markLog), the entire log will be searched.
+        """
+        data = self._read_marked_region(marker)
+        for logline in data:
+            if line in logline:
+                return
+        msg = "%r not found in log" % line
+        self._handleLogError(msg, data, marker, line)
+    
+    def assertNotInLog(self, line, marker=None):
+        """Fail if the given (partial) line is in the log.
+        
+        The log will be searched from the given marker to the next marker.
+        If marker is None, self.lastmarker is used. If the log hasn't
+        been marked (using self.markLog), the entire log will be searched.
+        """
+        data = self._read_marked_region(marker)
+        for logline in data:
+            if line in logline:
+                msg = "%r found in log" % line
+                self._handleLogError(msg, data, marker, line)
+    
+    def assertLog(self, sliceargs, lines, marker=None):
+        """Fail if log.readlines()[sliceargs] is not contained in 'lines'.
+        
+        The log will be searched from the given marker to the next marker.
+        If marker is None, self.lastmarker is used. If the log hasn't
+        been marked (using self.markLog), the entire log will be searched.
+        """
+        data = self._read_marked_region(marker)
+        if isinstance(sliceargs, int):
+            # Single arg. Use __getitem__ and allow lines to be str or list.
+            if isinstance(lines, (tuple, list)):
+                lines = lines[0]
+            if lines not in data[sliceargs]:
+                msg = "%r not found on log line %r" % (lines, sliceargs)
+                self._handleLogError(msg, [data[sliceargs]], marker, lines)
+        else:
+            # Multiple args. Use __getslice__ and require lines to be list.
+            if isinstance(lines, tuple):
+                lines = list(lines)
+            elif isinstance(lines, basestring):
+                raise TypeError("The 'lines' arg must be a list when "
+                                "'sliceargs' is a tuple.")
+            
+            start, stop = sliceargs
+            for line, logline in zip(lines, data[start:stop]):
+                if line not in logline:
+                    msg = "%r not found in log" % line
+                    self._handleLogError(msg, data[start:stop], marker, line)
+
diff --git a/cherrypy/test/modfastcgi.py b/cherrypy/test/modfastcgi.py
new file mode 100644
index 00000000..95acf141
--- /dev/null
+++ b/cherrypy/test/modfastcgi.py
@@ -0,0 +1,135 @@
+"""Wrapper for mod_fastcgi, for use as a CherryPy HTTP server when testing.
+
+To autostart fastcgi, the "apache" executable or script must be
+on your system path, or you must override the global APACHE_PATH.
+On some platforms, "apache" may be called "apachectl", "apache2ctl",
+or "httpd"--create a symlink to them if needed.
+
+You'll also need the WSGIServer from flup.servers.
+See http://projects.amor.org/misc/wiki/ModPythonGateway
+
+
+KNOWN BUGS
+==========
+
+1. Apache processes Range headers automatically; CherryPy's truncated
+    output is then truncated again by Apache. See test_core.testRanges.
+    This was worked around in http://www.cherrypy.org/changeset/1319.
+2. Apache does not allow custom HTTP methods like CONNECT as per the spec.
+    See test_core.testHTTPMethods.
+3. Max request header and body settings do not work with Apache.
+4. Apache replaces status "reason phrases" automatically. For example,
+    CherryPy may set "304 Not modified" but Apache will write out
+    "304 Not Modified" (capital "M").
+5. Apache does not allow custom error codes as per the spec.
+6. Apache (or perhaps modpython, or modpython_gateway) unquotes %xx in the
+    Request-URI too early.
+7. mod_python will not read request bodies which use the "chunked"
+    transfer-coding (it passes REQUEST_CHUNKED_ERROR to ap_setup_client_block
+    instead of REQUEST_CHUNKED_DECHUNK, see Apache2's http_protocol.c and
+    mod_python's requestobject.c).
+8. Apache will output a "Content-Length: 0" response header even if there's
+    no response entity body. This isn't really a bug; it just differs from
+    the CherryPy default.
+"""
+
+import os
+curdir = os.path.join(os.getcwd(), os.path.dirname(__file__))
+import re
+import sys
+import time
+
+import cherrypy
+from cherrypy.process import plugins, servers
+from cherrypy.test import helper
+
+
+def read_process(cmd, args=""):
+    pipein, pipeout = os.popen4("%s %s" % (cmd, args))
+    try:
+        firstline = pipeout.readline()
+        if (re.search(r"(not recognized|No such file|not found)", firstline,
+                      re.IGNORECASE)):
+            raise IOError('%s must be on your system path.' % cmd)
+        output = firstline + pipeout.read()
+    finally:
+        pipeout.close()
+    return output
+
+
+APACHE_PATH = "apache2ctl"
+CONF_PATH = "fastcgi.conf"
+
+conf_fastcgi = """
+# Apache2 server conf file for testing CherryPy with mod_fastcgi.
+# fumanchu: I had to hard-code paths due to crazy Debian layouts :(
+ServerRoot /usr/lib/apache2
+User #1000
+ErrorLog %(root)s/mod_fastcgi.error.log
+
+DocumentRoot "%(root)s"
+ServerName 127.0.0.1
+Listen %(port)s
+LoadModule fastcgi_module modules/mod_fastcgi.so
+LoadModule rewrite_module modules/mod_rewrite.so
+
+Options +ExecCGI
+SetHandler fastcgi-script
+RewriteEngine On
+RewriteRule ^(.*)$ /fastcgi.pyc [L]
+FastCgiExternalServer "%(server)s" -host 127.0.0.1:4000
+"""
+
+def erase_script_name(environ, start_response):
+    environ['SCRIPT_NAME'] = ''
+    return cherrypy.tree(environ, start_response)
+
+class ModFCGISupervisor(helper.LocalWSGISupervisor):
+    
+    httpserver_class = "cherrypy.process.servers.FlupFCGIServer"
+    using_apache = True
+    using_wsgi = True
+    template = conf_fastcgi
+    
+    def __str__(self):
+        return "FCGI Server on %s:%s" % (self.host, self.port)
+    
+    def start(self, modulename):
+        cherrypy.server.httpserver = servers.FlupFCGIServer(
+            application=erase_script_name, bindAddress=('127.0.0.1', 4000))
+        cherrypy.server.httpserver.bind_addr = ('127.0.0.1', 4000)
+        cherrypy.server.socket_port = 4000
+        # For FCGI, we both start apache...
+        self.start_apache()
+        # ...and our local server
+        cherrypy.engine.start()
+        self.sync_apps()
+    
+    def start_apache(self):
+        fcgiconf = CONF_PATH
+        if not os.path.isabs(fcgiconf):
+            fcgiconf = os.path.join(curdir, fcgiconf)
+        
+        # Write the Apache conf file.
+        f = open(fcgiconf, 'wb')
+        try:
+            server = repr(os.path.join(curdir, 'fastcgi.pyc'))[1:-1]
+            output = self.template % {'port': self.port, 'root': curdir,
+                                      'server': server}
+            output = output.replace('\r\n', '\n')
+            f.write(output)
+        finally:
+            f.close()
+        
+        result = read_process(APACHE_PATH, "-k start -f %s" % fcgiconf)
+        if result:
+            print(result)
+    
+    def stop(self):
+        """Gracefully shutdown a server that is serving forever."""
+        read_process(APACHE_PATH, "-k stop")
+        helper.LocalWSGISupervisor.stop(self)
+    
+    def sync_apps(self):
+        cherrypy.server.httpserver.fcgiserver.application = self.get_app(erase_script_name)
+
diff --git a/cherrypy/test/modfcgid.py b/cherrypy/test/modfcgid.py
new file mode 100644
index 00000000..736aa4c8
--- /dev/null
+++ b/cherrypy/test/modfcgid.py
@@ -0,0 +1,125 @@
+"""Wrapper for mod_fcgid, for use as a CherryPy HTTP server when testing.
+
+To autostart fcgid, the "apache" executable or script must be
+on your system path, or you must override the global APACHE_PATH.
+On some platforms, "apache" may be called "apachectl", "apache2ctl",
+or "httpd"--create a symlink to them if needed.
+
+You'll also need the WSGIServer from flup.servers.
+See http://projects.amor.org/misc/wiki/ModPythonGateway
+
+
+KNOWN BUGS
+==========
+
+1. Apache processes Range headers automatically; CherryPy's truncated
+    output is then truncated again by Apache. See test_core.testRanges.
+    This was worked around in http://www.cherrypy.org/changeset/1319.
+2. Apache does not allow custom HTTP methods like CONNECT as per the spec.
+    See test_core.testHTTPMethods.
+3. Max request header and body settings do not work with Apache.
+4. Apache replaces status "reason phrases" automatically. For example,
+    CherryPy may set "304 Not modified" but Apache will write out
+    "304 Not Modified" (capital "M").
+5. Apache does not allow custom error codes as per the spec.
+6. Apache (or perhaps modpython, or modpython_gateway) unquotes %xx in the
+    Request-URI too early.
+7. mod_python will not read request bodies which use the "chunked"
+    transfer-coding (it passes REQUEST_CHUNKED_ERROR to ap_setup_client_block
+    instead of REQUEST_CHUNKED_DECHUNK, see Apache2's http_protocol.c and
+    mod_python's requestobject.c).
+8. Apache will output a "Content-Length: 0" response header even if there's
+    no response entity body. This isn't really a bug; it just differs from
+    the CherryPy default.
+"""
+
+import os
+curdir = os.path.join(os.getcwd(), os.path.dirname(__file__))
+import re
+import sys
+import time
+
+import cherrypy
+from cherrypy._cpcompat import ntob
+from cherrypy.process import plugins, servers
+from cherrypy.test import helper
+
+
+def read_process(cmd, args=""):
+    pipein, pipeout = os.popen4("%s %s" % (cmd, args))
+    try:
+        firstline = pipeout.readline()
+        if (re.search(r"(not recognized|No such file|not found)", firstline,
+                      re.IGNORECASE)):
+            raise IOError('%s must be on your system path.' % cmd)
+        output = firstline + pipeout.read()
+    finally:
+        pipeout.close()
+    return output
+
+
+APACHE_PATH = "httpd"
+CONF_PATH = "fcgi.conf"
+
+conf_fcgid = """
+# Apache2 server conf file for testing CherryPy with mod_fcgid.
+
+DocumentRoot "%(root)s"
+ServerName 127.0.0.1
+Listen %(port)s
+LoadModule fastcgi_module modules/mod_fastcgi.dll
+LoadModule rewrite_module modules/mod_rewrite.so
+
+Options ExecCGI
+SetHandler fastcgi-script
+RewriteEngine On
+RewriteRule ^(.*)$ /fastcgi.pyc [L]
+FastCgiExternalServer "%(server)s" -host 127.0.0.1:4000
+"""
+
+class ModFCGISupervisor(helper.LocalSupervisor):
+    
+    using_apache = True
+    using_wsgi = True
+    template = conf_fcgid
+    
+    def __str__(self):
+        return "FCGI Server on %s:%s" % (self.host, self.port)
+    
+    def start(self, modulename):
+        cherrypy.server.httpserver = servers.FlupFCGIServer(
+            application=cherrypy.tree, bindAddress=('127.0.0.1', 4000))
+        cherrypy.server.httpserver.bind_addr = ('127.0.0.1', 4000)
+        # For FCGI, we both start apache...
+        self.start_apache()
+        # ...and our local server
+        helper.LocalServer.start(self, modulename)
+    
+    def start_apache(self):
+        fcgiconf = CONF_PATH
+        if not os.path.isabs(fcgiconf):
+            fcgiconf = os.path.join(curdir, fcgiconf)
+        
+        # Write the Apache conf file.
+        f = open(fcgiconf, 'wb')
+        try:
+            server = repr(os.path.join(curdir, 'fastcgi.pyc'))[1:-1]
+            output = self.template % {'port': self.port, 'root': curdir,
+                                      'server': server}
+            output = ntob(output.replace('\r\n', '\n'))
+            f.write(output)
+        finally:
+            f.close()
+        
+        result = read_process(APACHE_PATH, "-k start -f %s" % fcgiconf)
+        if result:
+            print(result)
+    
+    def stop(self):
+        """Gracefully shutdown a server that is serving forever."""
+        read_process(APACHE_PATH, "-k stop")
+        helper.LocalServer.stop(self)
+    
+    def sync_apps(self):
+        cherrypy.server.httpserver.fcgiserver.application = self.get_app()
+
diff --git a/cherrypy/test/modpy.py b/cherrypy/test/modpy.py
new file mode 100644
index 00000000..519571fc
--- /dev/null
+++ b/cherrypy/test/modpy.py
@@ -0,0 +1,163 @@
+"""Wrapper for mod_python, for use as a CherryPy HTTP server when testing.
+
+To autostart modpython, the "apache" executable or script must be
+on your system path, or you must override the global APACHE_PATH.
+On some platforms, "apache" may be called "apachectl" or "apache2ctl"--
+create a symlink to them if needed.
+
+If you wish to test the WSGI interface instead of our _cpmodpy interface,
+you also need the 'modpython_gateway' module at:
+http://projects.amor.org/misc/wiki/ModPythonGateway
+
+
+KNOWN BUGS
+==========
+
+1. Apache processes Range headers automatically; CherryPy's truncated
+    output is then truncated again by Apache. See test_core.testRanges.
+    This was worked around in http://www.cherrypy.org/changeset/1319.
+2. Apache does not allow custom HTTP methods like CONNECT as per the spec.
+    See test_core.testHTTPMethods.
+3. Max request header and body settings do not work with Apache.
+4. Apache replaces status "reason phrases" automatically. For example,
+    CherryPy may set "304 Not modified" but Apache will write out
+    "304 Not Modified" (capital "M").
+5. Apache does not allow custom error codes as per the spec.
+6. Apache (or perhaps modpython, or modpython_gateway) unquotes %xx in the
+    Request-URI too early.
+7. mod_python will not read request bodies which use the "chunked"
+    transfer-coding (it passes REQUEST_CHUNKED_ERROR to ap_setup_client_block
+    instead of REQUEST_CHUNKED_DECHUNK, see Apache2's http_protocol.c and
+    mod_python's requestobject.c).
+8. Apache will output a "Content-Length: 0" response header even if there's
+    no response entity body. This isn't really a bug; it just differs from
+    the CherryPy default.
+"""
+
+import os
+curdir = os.path.join(os.getcwd(), os.path.dirname(__file__))
+import re
+import time
+
+from cherrypy.test import helper
+
+
+def read_process(cmd, args=""):
+    pipein, pipeout = os.popen4("%s %s" % (cmd, args))
+    try:
+        firstline = pipeout.readline()
+        if (re.search(r"(not recognized|No such file|not found)", firstline,
+                      re.IGNORECASE)):
+            raise IOError('%s must be on your system path.' % cmd)
+        output = firstline + pipeout.read()
+    finally:
+        pipeout.close()
+    return output
+
+
+APACHE_PATH = "httpd"
+CONF_PATH = "test_mp.conf"
+
+conf_modpython_gateway = """
+# Apache2 server conf file for testing CherryPy with modpython_gateway.
+
+ServerName 127.0.0.1
+DocumentRoot "/"
+Listen %(port)s
+LoadModule python_module modules/mod_python.so
+
+SetHandler python-program
+PythonFixupHandler cherrypy.test.modpy::wsgisetup
+PythonOption testmod %(modulename)s
+PythonHandler modpython_gateway::handler
+PythonOption wsgi.application cherrypy::tree
+PythonOption socket_host %(host)s
+PythonDebug On
+"""
+
+conf_cpmodpy = """
+# Apache2 server conf file for testing CherryPy with _cpmodpy.
+
+ServerName 127.0.0.1
+DocumentRoot "/"
+Listen %(port)s
+LoadModule python_module modules/mod_python.so
+
+SetHandler python-program
+PythonFixupHandler cherrypy.test.modpy::cpmodpysetup
+PythonHandler cherrypy._cpmodpy::handler
+PythonOption cherrypy.setup cherrypy.test.%(modulename)s::setup_server
+PythonOption socket_host %(host)s
+PythonDebug On
+"""
+
+class ModPythonSupervisor(helper.Supervisor):
+    
+    using_apache = True
+    using_wsgi = False
+    template = None
+    
+    def __str__(self):
+        return "ModPython Server on %s:%s" % (self.host, self.port)
+    
+    def start(self, modulename):
+        mpconf = CONF_PATH
+        if not os.path.isabs(mpconf):
+            mpconf = os.path.join(curdir, mpconf)
+        
+        f = open(mpconf, 'wb')
+        try:
+            f.write(self.template %
+                    {'port': self.port, 'modulename': modulename,
+                     'host': self.host})
+        finally:
+            f.close()
+        
+        result = read_process(APACHE_PATH, "-k start -f %s" % mpconf)
+        if result:
+            print(result)
+    
+    def stop(self):
+        """Gracefully shutdown a server that is serving forever."""
+        read_process(APACHE_PATH, "-k stop")
+
+
+loaded = False
+def wsgisetup(req):
+    global loaded
+    if not loaded:
+        loaded = True
+        options = req.get_options()
+        
+        import cherrypy
+        cherrypy.config.update({
+            "log.error_file": os.path.join(curdir, "test.log"),
+            "environment": "test_suite",
+            "server.socket_host": options['socket_host'],
+            })
+        
+        modname = options['testmod']
+        mod = __import__(modname, globals(), locals(), [''])
+        mod.setup_server()
+        
+        cherrypy.server.unsubscribe()
+        cherrypy.engine.start()
+    from mod_python import apache
+    return apache.OK
+
+
+def cpmodpysetup(req):
+    global loaded
+    if not loaded:
+        loaded = True
+        options = req.get_options()
+        
+        import cherrypy
+        cherrypy.config.update({
+            "log.error_file": os.path.join(curdir, "test.log"),
+            "environment": "test_suite",
+            "server.socket_host": options['socket_host'],
+            })
+    from mod_python import apache
+    return apache.OK
+
diff --git a/cherrypy/test/modwsgi.py b/cherrypy/test/modwsgi.py
new file mode 100644
index 00000000..309a541c
--- /dev/null
+++ b/cherrypy/test/modwsgi.py
@@ -0,0 +1,148 @@
+"""Wrapper for mod_wsgi, for use as a CherryPy HTTP server.
+
+To autostart modwsgi, the "apache" executable or script must be
+on your system path, or you must override the global APACHE_PATH.
+On some platforms, "apache" may be called "apachectl" or "apache2ctl"--
+create a symlink to them if needed.
+
+
+KNOWN BUGS
+==========
+
+##1. Apache processes Range headers automatically; CherryPy's truncated
+##    output is then truncated again by Apache. See test_core.testRanges.
+##    This was worked around in http://www.cherrypy.org/changeset/1319.
+2. Apache does not allow custom HTTP methods like CONNECT as per the spec.
+    See test_core.testHTTPMethods.
+3. Max request header and body settings do not work with Apache.
+##4. Apache replaces status "reason phrases" automatically. For example,
+##    CherryPy may set "304 Not modified" but Apache will write out
+##    "304 Not Modified" (capital "M").
+##5. Apache does not allow custom error codes as per the spec.
+##6. Apache (or perhaps modpython, or modpython_gateway) unquotes %xx in the
+##    Request-URI too early.
+7. mod_wsgi will not read request bodies which use the "chunked"
+    transfer-coding (it passes REQUEST_CHUNKED_ERROR to ap_setup_client_block
+    instead of REQUEST_CHUNKED_DECHUNK, see Apache2's http_protocol.c and
+    mod_python's requestobject.c).
+8. When responding with 204 No Content, mod_wsgi adds a Content-Length
+    header for you.
+9. When an error is raised, mod_wsgi has no facility for printing a
+    traceback as the response content (it's sent to the Apache log instead).
+10. Startup and shutdown of Apache when running mod_wsgi seems slow.
+"""
+
+import os
+curdir = os.path.abspath(os.path.dirname(__file__))
+import re
+import sys
+import time
+
+import cherrypy
+from cherrypy.test import helper, webtest
+
+
+def read_process(cmd, args=""):
+    pipein, pipeout = os.popen4("%s %s" % (cmd, args))
+    try:
+        firstline = pipeout.readline()
+        if (re.search(r"(not recognized|No such file|not found)", firstline,
+                      re.IGNORECASE)):
+            raise IOError('%s must be on your system path.' % cmd)
+        output = firstline + pipeout.read()
+    finally:
+        pipeout.close()
+    return output
+
+
+if sys.platform == 'win32':
+    APACHE_PATH = "httpd"
+else:
+    APACHE_PATH = "apache"
+
+CONF_PATH = "test_mw.conf"
+
+conf_modwsgi = r"""
+# Apache2 server conf file for testing CherryPy with modpython_gateway.
+
+ServerName 127.0.0.1
+DocumentRoot "/"
+Listen %(port)s
+
+AllowEncodedSlashes On
+LoadModule rewrite_module modules/mod_rewrite.so
+RewriteEngine on
+RewriteMap escaping int:escape
+
+LoadModule log_config_module modules/mod_log_config.so
+LogFormat "%%h %%l %%u %%t \"%%r\" %%>s %%b \"%%{Referer}i\" \"%%{User-agent}i\"" combined
+CustomLog "%(curdir)s/apache.access.log" combined
+ErrorLog "%(curdir)s/apache.error.log"
+LogLevel debug
+
+LoadModule wsgi_module modules/mod_wsgi.so
+LoadModule env_module modules/mod_env.so
+
+WSGIScriptAlias / "%(curdir)s/modwsgi.py"
+SetEnv testmod %(testmod)s
+"""
+
+
+class ModWSGISupervisor(helper.Supervisor):
+    """Server Controller for ModWSGI and CherryPy."""
+    
+    using_apache = True
+    using_wsgi = True
+    template=conf_modwsgi
+    
+    def __str__(self):
+        return "ModWSGI Server on %s:%s" % (self.host, self.port)
+    
+    def start(self, modulename):
+        mpconf = CONF_PATH
+        if not os.path.isabs(mpconf):
+            mpconf = os.path.join(curdir, mpconf)
+        
+        f = open(mpconf, 'wb')
+        try:
+            output = (self.template %
+                      {'port': self.port, 'testmod': modulename,
+                       'curdir': curdir})
+            f.write(output)
+        finally:
+            f.close()
+        
+        result = read_process(APACHE_PATH, "-k start -f %s" % mpconf)
+        if result:
+            print(result)
+        
+        # Make a request so mod_wsgi starts up our app.
+        # If we don't, concurrent initial requests will 404.
+        cherrypy._cpserver.wait_for_occupied_port("127.0.0.1", self.port)
+        webtest.openURL('/ihopetheresnodefault', port=self.port)
+        time.sleep(1)
+    
+    def stop(self):
+        """Gracefully shutdown a server that is serving forever."""
+        read_process(APACHE_PATH, "-k stop")
+
+
+loaded = False
+def application(environ, start_response):
+    import cherrypy
+    global loaded
+    if not loaded:
+        loaded = True
+        modname = "cherrypy.test." + environ['testmod']
+        mod = __import__(modname, globals(), locals(), [''])
+        mod.setup_server()
+        
+        cherrypy.config.update({
+            "log.error_file": os.path.join(curdir, "test.error.log"),
+            "log.access_file": os.path.join(curdir, "test.access.log"),
+            "environment": "test_suite",
+            "engine.SIGHUP": None,
+            "engine.SIGTERM": None,
+            })
+    return cherrypy.tree(environ, start_response)
+
diff --git a/cherrypy/test/native-server.ini b/cherrypy/test/native-server.ini
new file mode 100644
index 00000000..b32d98dd
--- /dev/null
+++ b/cherrypy/test/native-server.ini
@@ -0,0 +1,9 @@
+[supervisor]
+scheme="http"
+protocol="HTTP/1.1"
+port= 8080
+host= "127.0.0.1"
+profile= False
+validate= False
+conquer= False
+server="wsgi"
diff --git a/cherrypy/test/sessiondemo.py b/cherrypy/test/sessiondemo.py
new file mode 100755
index 00000000..342e5b59
--- /dev/null
+++ b/cherrypy/test/sessiondemo.py
@@ -0,0 +1,153 @@
+#!/usr/bin/python
+"""A session demonstration app."""
+
+import calendar
+from datetime import datetime
+import sys
+import cherrypy
+from cherrypy.lib import sessions
+from cherrypy._cpcompat import copyitems
+
+
+page = """
+
+
+
+
+
+
+
+
Session Demo

+
Reload this page. The session ID should not change from one reload to the next

+
Index | Expire | Regenerate

+
+    
+    
+    
+    
+    
+    
+    
+    
+
Session ID:%(sessionid)s
%(changemsg)s
Request Cookie%(reqcookie)s
Response Cookie%(respcookie)s
Session Data%(sessiondata)s
Server Time%(servertime)s (Unix time: %(serverunixtime)s)
Browser Time 
Cherrypy Version:%(cpversion)s
Python Version:%(pyversion)s

+
+"""
+
+class Root(object):
+    
+    def page(self):
+        changemsg = []
+        if cherrypy.session.id != cherrypy.session.originalid:
+            if cherrypy.session.originalid is None:
+                changemsg.append('Created new session because no session id was given.')
+            if cherrypy.session.missing:
+                changemsg.append('Created new session due to missing (expired or malicious) session.')
+            if cherrypy.session.regenerated:
+                changemsg.append('Application generated a new session.')
+        
+        try:
+            expires = cherrypy.response.cookie['session_id']['expires']
+        except KeyError:
+            expires = ''
+        
+        return page % {
+            'sessionid': cherrypy.session.id,
+            'changemsg': '
'.join(changemsg),
+            'respcookie': cherrypy.response.cookie.output(),
+            'reqcookie': cherrypy.request.cookie.output(),
+            'sessiondata': copyitems(cherrypy.session),
+            'servertime': datetime.utcnow().strftime("%Y/%m/%d %H:%M") + " UTC",
+            'serverunixtime': calendar.timegm(datetime.utcnow().timetuple()),
+            'cpversion': cherrypy.__version__,
+            'pyversion': sys.version,
+            'expires': expires,
+            }
+    
+    def index(self):
+        # Must modify data or the session will not be saved.
+        cherrypy.session['color'] = 'green'
+        return self.page()
+    index.exposed = True
+    
+    def expire(self):
+        sessions.expire()
+        return self.page()
+    expire.exposed = True
+    
+    def regen(self):
+        cherrypy.session.regenerate()
+        # Must modify data or the session will not be saved.
+        cherrypy.session['color'] = 'yellow'
+        return self.page()
+    regen.exposed = True
+
+if __name__ == '__main__':
+    cherrypy.config.update({
+        #'environment': 'production',
+        'log.screen': True,
+        'tools.sessions.on': True,
+        })
+    cherrypy.quickstart(Root())
+
diff --git a/cherrypy/test/static/dirback.jpg b/cherrypy/test/static/dirback.jpg
new file mode 100644
index 0000000000000000000000000000000000000000..530e6d6a386fc097f3a1dbabbde2d80fec1175ac
GIT binary patch
literal 18238
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
+# -*- coding: utf-8 -*-
+# vim:ts=4:sw=4:expandtab:fileencoding=utf-8
+
+import cherrypy
+from cherrypy._cpcompat import md5, ntob
+from cherrypy.lib import auth_basic
+from cherrypy.test import helper
+
+
+class BasicAuthTest(helper.CPWebCase):
+
+    def setup_server():
+        class Root:
+            def index(self):
+                return "This is public."
+            index.exposed = True
+
+        class BasicProtected:
+            def index(self):
+                return "Hello %s, you've been authorized." % cherrypy.request.login
+            index.exposed = True
+
+        class BasicProtected2:
+            def index(self):
+                return "Hello %s, you've been authorized." % cherrypy.request.login
+            index.exposed = True
+
+        userpassdict = {'xuser' : 'xpassword'}
+        userhashdict = {'xuser' : md5(ntob('xpassword')).hexdigest()}
+
+        def checkpasshash(realm, user, password):
+            p = userhashdict.get(user)
+            return p and p == md5(ntob(password)).hexdigest() or False
+
+        conf = {'/basic': {'tools.auth_basic.on': True,
+                           'tools.auth_basic.realm': 'wonderland',
+                           'tools.auth_basic.checkpassword': auth_basic.checkpassword_dict(userpassdict)},
+                '/basic2': {'tools.auth_basic.on': True,
+                            'tools.auth_basic.realm': 'wonderland',
+                            'tools.auth_basic.checkpassword': checkpasshash},
+               }
+
+        root = Root()
+        root.basic = BasicProtected()
+        root.basic2 = BasicProtected2()
+        cherrypy.tree.mount(root, config=conf)
+    setup_server = staticmethod(setup_server)
+
+    def testPublic(self):
+        self.getPage("/")
+        self.assertStatus('200 OK')
+        self.assertHeader('Content-Type', 'text/html;charset=utf-8')
+        self.assertBody('This is public.')
+
+    def testBasic(self):
+        self.getPage("/basic/")
+        self.assertStatus(401)
+        self.assertHeader('WWW-Authenticate', 'Basic realm="wonderland"')
+
+        self.getPage('/basic/', [('Authorization', 'Basic eHVzZXI6eHBhc3N3b3JX')])
+        self.assertStatus(401)
+
+        self.getPage('/basic/', [('Authorization', 'Basic eHVzZXI6eHBhc3N3b3Jk')])
+        self.assertStatus('200 OK')
+        self.assertBody("Hello xuser, you've been authorized.")
+
+    def testBasic2(self):
+        self.getPage("/basic2/")
+        self.assertStatus(401)
+        self.assertHeader('WWW-Authenticate', 'Basic realm="wonderland"')
+
+        self.getPage('/basic2/', [('Authorization', 'Basic eHVzZXI6eHBhc3N3b3JX')])
+        self.assertStatus(401)
+
+        self.getPage('/basic2/', [('Authorization', 'Basic eHVzZXI6eHBhc3N3b3Jk')])
+        self.assertStatus('200 OK')
+        self.assertBody("Hello xuser, you've been authorized.")
+
diff --git a/cherrypy/test/test_auth_digest.py b/cherrypy/test/test_auth_digest.py
new file mode 100644
index 00000000..1960fa81
--- /dev/null
+++ b/cherrypy/test/test_auth_digest.py
@@ -0,0 +1,115 @@
+# This file is part of CherryPy 
+# -*- coding: utf-8 -*-
+# vim:ts=4:sw=4:expandtab:fileencoding=utf-8
+
+
+import cherrypy
+from cherrypy.lib import auth_digest
+
+from cherrypy.test import helper
+
+class DigestAuthTest(helper.CPWebCase):
+
+    def setup_server():
+        class Root:
+            def index(self):
+                return "This is public."
+            index.exposed = True
+
+        class DigestProtected:
+            def index(self):
+                return "Hello %s, you've been authorized." % cherrypy.request.login
+            index.exposed = True
+
+        def fetch_users():
+            return {'test': 'test'}
+
+
+        get_ha1 = cherrypy.lib.auth_digest.get_ha1_dict_plain(fetch_users())
+        conf = {'/digest': {'tools.auth_digest.on': True,
+                            'tools.auth_digest.realm': 'localhost',
+                            'tools.auth_digest.get_ha1': get_ha1,
+                            'tools.auth_digest.key': 'a565c27146791cfb',
+                            'tools.auth_digest.debug': 'True'}}
+
+        root = Root()
+        root.digest = DigestProtected()
+        cherrypy.tree.mount(root, config=conf)
+    setup_server = staticmethod(setup_server)
+    
+    def testPublic(self):
+        self.getPage("/")
+        self.assertStatus('200 OK')
+        self.assertHeader('Content-Type', 'text/html;charset=utf-8')
+        self.assertBody('This is public.')
+
+    def testDigest(self):
+        self.getPage("/digest/")
+        self.assertStatus(401)
+
+        value = None
+        for k, v in self.headers:
+            if k.lower() == "www-authenticate":
+                if v.startswith("Digest"):
+                    value = v
+                    break
+
+        if value is None:
+            self._handlewebError("Digest authentification scheme was not found")
+
+        value = value[7:]
+        items = value.split(', ')
+        tokens = {}
+        for item in items:
+            key, value = item.split('=')
+            tokens[key.lower()] = value
+
+        missing_msg = "%s is missing"
+        bad_value_msg = "'%s' was expecting '%s' but found '%s'"
+        nonce = None
+        if 'realm' not in tokens:
+            self._handlewebError(missing_msg % 'realm')
+        elif tokens['realm'] != '"localhost"':
+            self._handlewebError(bad_value_msg % ('realm', '"localhost"', tokens['realm']))
+        if 'nonce' not in tokens:
+            self._handlewebError(missing_msg % 'nonce')
+        else:
+            nonce = tokens['nonce'].strip('"')
+        if 'algorithm' not in tokens:
+            self._handlewebError(missing_msg % 'algorithm')
+        elif tokens['algorithm'] != '"MD5"':
+            self._handlewebError(bad_value_msg % ('algorithm', '"MD5"', tokens['algorithm']))
+        if 'qop' not in tokens:
+            self._handlewebError(missing_msg % 'qop')
+        elif tokens['qop'] != '"auth"':
+            self._handlewebError(bad_value_msg % ('qop', '"auth"', tokens['qop']))
+
+        get_ha1 = auth_digest.get_ha1_dict_plain({'test' : 'test'})
+
+        # Test user agent response with a wrong value for 'realm'
+        base_auth = 'Digest username="test", realm="wrong realm", nonce="%s", uri="/digest/", algorithm=MD5, response="%s", qop=auth, nc=%s, cnonce="1522e61005789929"'
+
+        auth_header = base_auth % (nonce, '11111111111111111111111111111111', '00000001')
+        auth = auth_digest.HttpDigestAuthorization(auth_header, 'GET')
+        # calculate the response digest
+        ha1 = get_ha1(auth.realm, 'test')
+        response = auth.request_digest(ha1)
+        # send response with correct response digest, but wrong realm
+        auth_header = base_auth % (nonce, response, '00000001')
+        self.getPage('/digest/', [('Authorization', auth_header)])
+        self.assertStatus(401)
+
+        # Test that must pass
+        base_auth = 'Digest username="test", realm="localhost", nonce="%s", uri="/digest/", algorithm=MD5, response="%s", qop=auth, nc=%s, cnonce="1522e61005789929"'
+
+        auth_header = base_auth % (nonce, '11111111111111111111111111111111', '00000001')
+        auth = auth_digest.HttpDigestAuthorization(auth_header, 'GET')
+        # calculate the response digest
+        ha1 = get_ha1('localhost', 'test')
+        response = auth.request_digest(ha1)
+        # send response with correct response digest
+        auth_header = base_auth % (nonce, response, '00000001')
+        self.getPage('/digest/', [('Authorization', auth_header)])
+        self.assertStatus('200 OK')
+        self.assertBody("Hello test, you've been authorized.")
+
diff --git a/cherrypy/test/test_bus.py b/cherrypy/test/test_bus.py
new file mode 100644
index 00000000..51c10220
--- /dev/null
+++ b/cherrypy/test/test_bus.py
@@ -0,0 +1,263 @@
+import threading
+import time
+import unittest
+
+import cherrypy
+from cherrypy._cpcompat import get_daemon, set
+from cherrypy.process import wspbus
+
+
+msg = "Listener %d on channel %s: %s."
+
+
+class PublishSubscribeTests(unittest.TestCase):
+
+    def get_listener(self, channel, index):
+        def listener(arg=None):
+            self.responses.append(msg % (index, channel, arg))
+        return listener
+
+    def test_builtin_channels(self):
+        b = wspbus.Bus()
+
+        self.responses, expected = [], []
+
+        for channel in b.listeners:
+            for index, priority in enumerate([100, 50, 0, 51]):
+                b.subscribe(channel, self.get_listener(channel, index), priority)
+
+        for channel in b.listeners:
+            b.publish(channel)
+            expected.extend([msg % (i, channel, None) for i in (2, 1, 3, 0)])
+            b.publish(channel, arg=79347)
+            expected.extend([msg % (i, channel, 79347) for i in (2, 1, 3, 0)])
+
+        self.assertEqual(self.responses, expected)
+
+    def test_custom_channels(self):
+        b = wspbus.Bus()
+
+        self.responses, expected = [], []
+
+        custom_listeners = ('hugh', 'louis', 'dewey')
+        for channel in custom_listeners:
+            for index, priority in enumerate([None, 10, 60, 40]):
+                b.subscribe(channel, self.get_listener(channel, index), priority)
+
+        for channel in custom_listeners:
+            b.publish(channel, 'ah so')
+            expected.extend([msg % (i, channel, 'ah so') for i in (1, 3, 0, 2)])
+            b.publish(channel)
+            expected.extend([msg % (i, channel, None) for i in (1, 3, 0, 2)])
+
+        self.assertEqual(self.responses, expected)
+
+    def test_listener_errors(self):
+        b = wspbus.Bus()
+
+        self.responses, expected = [], []
+        channels = [c for c in b.listeners if c != 'log']
+
+        for channel in channels:
+            b.subscribe(channel, self.get_listener(channel, 1))
+            # This will break since the lambda takes no args.
+            b.subscribe(channel, lambda: None, priority=20)
+
+        for channel in channels:
+            self.assertRaises(wspbus.ChannelFailures, b.publish, channel, 123)
+            expected.append(msg % (1, channel, 123))
+
+        self.assertEqual(self.responses, expected)
+
+
+class BusMethodTests(unittest.TestCase):
+
+    def log(self, bus):
+        self._log_entries = []
+        def logit(msg, level):
+            self._log_entries.append(msg)
+        bus.subscribe('log', logit)
+
+    def assertLog(self, entries):
+        self.assertEqual(self._log_entries, entries)
+
+    def get_listener(self, channel, index):
+        def listener(arg=None):
+            self.responses.append(msg % (index, channel, arg))
+        return listener
+
+    def test_start(self):
+        b = wspbus.Bus()
+        self.log(b)
+
+        self.responses = []
+        num = 3
+        for index in range(num):
+            b.subscribe('start', self.get_listener('start', index))
+
+        b.start()
+        try:
+            # The start method MUST call all 'start' listeners.
+            self.assertEqual(set(self.responses),
+                             set([msg % (i, 'start', None) for i in range(num)]))
+            # The start method MUST move the state to STARTED
+            # (or EXITING, if errors occur)
+            self.assertEqual(b.state, b.states.STARTED)
+            # The start method MUST log its states.
+            self.assertLog(['Bus STARTING', 'Bus STARTED'])
+        finally:
+            # Exit so the atexit handler doesn't complain.
+            b.exit()
+
+    def test_stop(self):
+        b = wspbus.Bus()
+        self.log(b)
+
+        self.responses = []
+        num = 3
+        for index in range(num):
+            b.subscribe('stop', self.get_listener('stop', index))
+
+        b.stop()
+
+        # The stop method MUST call all 'stop' listeners.
+        self.assertEqual(set(self.responses),
+                         set([msg % (i, 'stop', None) for i in range(num)]))
+        # The stop method MUST move the state to STOPPED
+        self.assertEqual(b.state, b.states.STOPPED)
+        # The stop method MUST log its states.
+        self.assertLog(['Bus STOPPING', 'Bus STOPPED'])
+
+    def test_graceful(self):
+        b = wspbus.Bus()
+        self.log(b)
+
+        self.responses = []
+        num = 3
+        for index in range(num):
+            b.subscribe('graceful', self.get_listener('graceful', index))
+
+        b.graceful()
+
+        # The graceful method MUST call all 'graceful' listeners.
+        self.assertEqual(set(self.responses),
+                         set([msg % (i, 'graceful', None) for i in range(num)]))
+        # The graceful method MUST log its states.
+        self.assertLog(['Bus graceful'])
+
+    def test_exit(self):
+        b = wspbus.Bus()
+        self.log(b)
+
+        self.responses = []
+        num = 3
+        for index in range(num):
+            b.subscribe('stop', self.get_listener('stop', index))
+            b.subscribe('exit', self.get_listener('exit', index))
+
+        b.exit()
+
+        # The exit method MUST call all 'stop' listeners,
+        # and then all 'exit' listeners.
+        self.assertEqual(set(self.responses),
+                         set([msg % (i, 'stop', None) for i in range(num)] +
+                             [msg % (i, 'exit', None) for i in range(num)]))
+        # The exit method MUST move the state to EXITING
+        self.assertEqual(b.state, b.states.EXITING)
+        # The exit method MUST log its states.
+        self.assertLog(['Bus STOPPING', 'Bus STOPPED', 'Bus EXITING', 'Bus EXITED'])
+
+    def test_wait(self):
+        b = wspbus.Bus()
+
+        def f(method):
+            time.sleep(0.2)
+            getattr(b, method)()
+
+        for method, states in [('start', [b.states.STARTED]),
+                               ('stop', [b.states.STOPPED]),
+                               ('start', [b.states.STARTING, b.states.STARTED]),
+                               ('exit', [b.states.EXITING]),
+                               ]:
+            threading.Thread(target=f, args=(method,)).start()
+            b.wait(states)
+
+            # The wait method MUST wait for the given state(s).
+            if b.state not in states:
+                self.fail("State %r not in %r" % (b.state, states))
+
+    def test_block(self):
+        b = wspbus.Bus()
+        self.log(b)
+
+        def f():
+            time.sleep(0.2)
+            b.exit()
+        def g():
+            time.sleep(0.4)
+        threading.Thread(target=f).start()
+        threading.Thread(target=g).start()
+        threads = [t for t in threading.enumerate() if not get_daemon(t)]
+        self.assertEqual(len(threads), 3)
+
+        b.block()
+
+        # The block method MUST wait for the EXITING state.
+        self.assertEqual(b.state, b.states.EXITING)
+        # The block method MUST wait for ALL non-main, non-daemon threads to finish.
+        threads = [t for t in threading.enumerate() if not get_daemon(t)]
+        self.assertEqual(len(threads), 1)
+        # The last message will mention an indeterminable thread name; ignore it
+        self.assertEqual(self._log_entries[:-1],
+                         ['Bus STOPPING', 'Bus STOPPED',
+                          'Bus EXITING', 'Bus EXITED',
+                          'Waiting for child threads to terminate...'])
+
+    def test_start_with_callback(self):
+        b = wspbus.Bus()
+        self.log(b)
+        try:
+            events = []
+            def f(*args, **kwargs):
+                events.append(("f", args, kwargs))
+            def g():
+                events.append("g")
+            b.subscribe("start", g)
+            b.start_with_callback(f, (1, 3, 5), {"foo": "bar"})
+            # Give wait() time to run f()
+            time.sleep(0.2)
+
+            # The callback method MUST wait for the STARTED state.
+            self.assertEqual(b.state, b.states.STARTED)
+            # The callback method MUST run after all start methods.
+            self.assertEqual(events, ["g", ("f", (1, 3, 5), {"foo": "bar"})])
+        finally:
+            b.exit()
+
+    def test_log(self):
+        b = wspbus.Bus()
+        self.log(b)
+        self.assertLog([])
+
+        # Try a normal message.
+        expected = []
+        for msg in ["O mah darlin'"] * 3 + ["Clementiiiiiiiine"]:
+            b.log(msg)
+            expected.append(msg)
+            self.assertLog(expected)
+
+        # Try an error message
+        try:
+            foo
+        except NameError:
+            b.log("You are lost and gone forever", traceback=True)
+            lastmsg = self._log_entries[-1]
+            if "Traceback" not in lastmsg or "NameError" not in lastmsg:
+                self.fail("Last log message %r did not contain "
+                          "the expected traceback." % lastmsg)
+        else:
+            self.fail("NameError was not raised as expected.")
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/cherrypy/test/test_caching.py b/cherrypy/test/test_caching.py
new file mode 100644
index 00000000..720a933a
--- /dev/null
+++ b/cherrypy/test/test_caching.py
@@ -0,0 +1,329 @@
+import datetime
+import gzip
+from itertools import count
+import os
+curdir = os.path.join(os.getcwd(), os.path.dirname(__file__))
+import sys
+import threading
+import time
+import urllib
+
+import cherrypy
+from cherrypy._cpcompat import next, ntob, quote, xrange
+from cherrypy.lib import httputil
+
+gif_bytes = ntob('GIF89a\x01\x00\x01\x00\x82\x00\x01\x99"\x1e\x00\x00\x00\x00\x00'
+             '\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00'
+             '\x00,\x00\x00\x00\x00\x01\x00\x01\x00\x02\x03\x02\x08\t\x00;')
+
+
+
+from cherrypy.test import helper
+
+class CacheTest(helper.CPWebCase):
+
+    def setup_server():
+        
+        class Root:
+            
+            _cp_config = {'tools.caching.on': True}
+            
+            def __init__(self):
+                self.counter = 0
+                self.control_counter = 0
+                self.longlock = threading.Lock()
+            
+            def index(self):
+                self.counter += 1
+                msg = "visit #%s" % self.counter
+                return msg
+            index.exposed = True
+            
+            def control(self):
+                self.control_counter += 1
+                return "visit #%s" % self.control_counter
+            control.exposed = True
+            
+            def a_gif(self):
+                cherrypy.response.headers['Last-Modified'] = httputil.HTTPDate()
+                return gif_bytes
+            a_gif.exposed = True
+            
+            def long_process(self, seconds='1'):
+                try:
+                    self.longlock.acquire()
+                    time.sleep(float(seconds))
+                finally:
+                    self.longlock.release()
+                return 'success!'
+            long_process.exposed = True
+            
+            def clear_cache(self, path):
+                cherrypy._cache.store[cherrypy.request.base + path].clear()
+            clear_cache.exposed = True
+        
+        class VaryHeaderCachingServer(object):
+            
+            _cp_config = {'tools.caching.on': True,
+                'tools.response_headers.on': True,
+                'tools.response_headers.headers': [('Vary', 'Our-Varying-Header')],
+                }
+            
+            def __init__(self):
+                self.counter = count(1)
+            
+            def index(self):
+                return "visit #%s" % next(self.counter)
+            index.exposed = True
+        
+        class UnCached(object):
+            _cp_config = {'tools.expires.on': True,
+                          'tools.expires.secs': 60,
+                          'tools.staticdir.on': True,
+                          'tools.staticdir.dir': 'static',
+                          'tools.staticdir.root': curdir,
+                          }
+
+            def force(self):
+                cherrypy.response.headers['Etag'] = 'bibbitybobbityboo'
+                self._cp_config['tools.expires.force'] = True
+                self._cp_config['tools.expires.secs'] = 0
+                return "being forceful"
+            force.exposed = True
+            force._cp_config = {'tools.expires.secs': 0}
+
+            def dynamic(self):
+                cherrypy.response.headers['Etag'] = 'bibbitybobbityboo'
+                cherrypy.response.headers['Cache-Control'] = 'private'
+                return "D-d-d-dynamic!"
+            dynamic.exposed = True
+
+            def cacheable(self):
+                cherrypy.response.headers['Etag'] = 'bibbitybobbityboo'
+                return "Hi, I'm cacheable."
+            cacheable.exposed = True
+
+            def specific(self):
+                cherrypy.response.headers['Etag'] = 'need_this_to_make_me_cacheable'
+                return "I am being specific"
+            specific.exposed = True
+            specific._cp_config = {'tools.expires.secs': 86400}
+
+            class Foo(object):pass
+            
+            def wrongtype(self):
+                cherrypy.response.headers['Etag'] = 'need_this_to_make_me_cacheable'
+                return "Woops"
+            wrongtype.exposed = True
+            wrongtype._cp_config = {'tools.expires.secs': Foo()}
+        
+        cherrypy.tree.mount(Root())
+        cherrypy.tree.mount(UnCached(), "/expires")
+        cherrypy.tree.mount(VaryHeaderCachingServer(), "/varying_headers")
+        cherrypy.config.update({'tools.gzip.on': True})
+    setup_server = staticmethod(setup_server)
+
+    def testCaching(self):
+        elapsed = 0.0
+        for trial in range(10):
+            self.getPage("/")
+            # The response should be the same every time,
+            # except for the Age response header.
+            self.assertBody('visit #1')
+            if trial != 0:
+                age = int(self.assertHeader("Age"))
+                self.assert_(age >= elapsed)
+                elapsed = age
+        
+        # POST, PUT, DELETE should not be cached.
+        self.getPage("/", method="POST")
+        self.assertBody('visit #2')
+        # Because gzip is turned on, the Vary header should always Vary for content-encoding
+        self.assertHeader('Vary', 'Accept-Encoding')
+        # The previous request should have invalidated the cache,
+        # so this request will recalc the response.
+        self.getPage("/", method="GET")
+        self.assertBody('visit #3')
+        # ...but this request should get the cached copy.
+        self.getPage("/", method="GET")
+        self.assertBody('visit #3')
+        self.getPage("/", method="DELETE")
+        self.assertBody('visit #4')
+        
+        # The previous request should have invalidated the cache,
+        # so this request will recalc the response.
+        self.getPage("/", method="GET", headers=[('Accept-Encoding', 'gzip')])
+        self.assertHeader('Content-Encoding', 'gzip')
+        self.assertHeader('Vary')
+        self.assertEqual(cherrypy.lib.encoding.decompress(self.body), ntob("visit #5"))
+        
+        # Now check that a second request gets the gzip header and gzipped body
+        # This also tests a bug in 3.0 to 3.0.2 whereby the cached, gzipped
+        # response body was being gzipped a second time.
+        self.getPage("/", method="GET", headers=[('Accept-Encoding', 'gzip')])
+        self.assertHeader('Content-Encoding', 'gzip')
+        self.assertEqual(cherrypy.lib.encoding.decompress(self.body), ntob("visit #5"))
+        
+        # Now check that a third request that doesn't accept gzip
+        # skips the cache (because the 'Vary' header denies it).
+        self.getPage("/", method="GET")
+        self.assertNoHeader('Content-Encoding')
+        self.assertBody('visit #6')
+    
+    def testVaryHeader(self):
+        self.getPage("/varying_headers/")
+        self.assertStatus("200 OK")
+        self.assertHeaderItemValue('Vary', 'Our-Varying-Header')
+        self.assertBody('visit #1')
+        
+        # Now check that different 'Vary'-fields don't evict each other.
+        # This test creates 2 requests with different 'Our-Varying-Header'
+        # and then tests if the first one still exists.
+        self.getPage("/varying_headers/", headers=[('Our-Varying-Header', 'request 2')])
+        self.assertStatus("200 OK")
+        self.assertBody('visit #2')
+        
+        self.getPage("/varying_headers/", headers=[('Our-Varying-Header', 'request 2')])
+        self.assertStatus("200 OK")
+        self.assertBody('visit #2')
+        
+        self.getPage("/varying_headers/")
+        self.assertStatus("200 OK")
+        self.assertBody('visit #1')
+        
+    def testExpiresTool(self):
+        # test setting an expires header
+        self.getPage("/expires/specific")
+        self.assertStatus("200 OK")
+        self.assertHeader("Expires")
+        
+        # test exceptions for bad time values
+        self.getPage("/expires/wrongtype")
+        self.assertStatus(500)
+        self.assertInBody("TypeError")
+        
+        # static content should not have "cache prevention" headers
+        self.getPage("/expires/index.html")
+        self.assertStatus("200 OK")
+        self.assertNoHeader("Pragma")
+        self.assertNoHeader("Cache-Control")
+        self.assertHeader("Expires")
+        
+        # dynamic content that sets indicators should not have
+        # "cache prevention" headers
+        self.getPage("/expires/cacheable")
+        self.assertStatus("200 OK")
+        self.assertNoHeader("Pragma")
+        self.assertNoHeader("Cache-Control")
+        self.assertHeader("Expires")
+        
+        self.getPage('/expires/dynamic')
+        self.assertBody("D-d-d-dynamic!")
+        # the Cache-Control header should be untouched
+        self.assertHeader("Cache-Control", "private")
+        self.assertHeader("Expires")
+        
+        # configure the tool to ignore indicators and replace existing headers
+        self.getPage("/expires/force")
+        self.assertStatus("200 OK")
+        # This also gives us a chance to test 0 expiry with no other headers
+        self.assertHeader("Pragma", "no-cache")
+        if cherrypy.server.protocol_version == "HTTP/1.1":
+            self.assertHeader("Cache-Control", "no-cache, must-revalidate")
+        self.assertHeader("Expires", "Sun, 28 Jan 2007 00:00:00 GMT")
+        
+        # static content should now have "cache prevention" headers
+        self.getPage("/expires/index.html")
+        self.assertStatus("200 OK")
+        self.assertHeader("Pragma", "no-cache")
+        if cherrypy.server.protocol_version == "HTTP/1.1":
+            self.assertHeader("Cache-Control", "no-cache, must-revalidate")
+        self.assertHeader("Expires", "Sun, 28 Jan 2007 00:00:00 GMT")
+        
+        # the cacheable handler should now have "cache prevention" headers
+        self.getPage("/expires/cacheable")
+        self.assertStatus("200 OK")
+        self.assertHeader("Pragma", "no-cache")
+        if cherrypy.server.protocol_version == "HTTP/1.1":
+            self.assertHeader("Cache-Control", "no-cache, must-revalidate")
+        self.assertHeader("Expires", "Sun, 28 Jan 2007 00:00:00 GMT")
+        
+        self.getPage('/expires/dynamic')
+        self.assertBody("D-d-d-dynamic!")
+        # dynamic sets Cache-Control to private but it should  be
+        # overwritten here ...
+        self.assertHeader("Pragma", "no-cache")
+        if cherrypy.server.protocol_version == "HTTP/1.1":
+            self.assertHeader("Cache-Control", "no-cache, must-revalidate")
+        self.assertHeader("Expires", "Sun, 28 Jan 2007 00:00:00 GMT")
+    
+    def testLastModified(self):
+        self.getPage("/a.gif")
+        self.assertStatus(200)
+        self.assertBody(gif_bytes)
+        lm1 = self.assertHeader("Last-Modified")
+        
+        # this request should get the cached copy.
+        self.getPage("/a.gif")
+        self.assertStatus(200)
+        self.assertBody(gif_bytes)
+        self.assertHeader("Age")
+        lm2 = self.assertHeader("Last-Modified")
+        self.assertEqual(lm1, lm2)
+        
+        # this request should match the cached copy, but raise 304.
+        self.getPage("/a.gif", [('If-Modified-Since', lm1)])
+        self.assertStatus(304)
+        self.assertNoHeader("Last-Modified")
+        if not getattr(cherrypy.server, "using_apache", False):
+            self.assertHeader("Age")
+    
+    def test_antistampede(self):
+        SECONDS = 4
+        # We MUST make an initial synchronous request in order to create the
+        # AntiStampedeCache object, and populate its selecting_headers,
+        # before the actual stampede.
+        self.getPage("/long_process?seconds=%d" % SECONDS)
+        self.assertBody('success!')
+        self.getPage("/clear_cache?path=" +
+            quote('/long_process?seconds=%d' % SECONDS, safe=''))
+        self.assertStatus(200)
+        sys.stdout.write("prepped... ")
+        sys.stdout.flush()
+        
+        start = datetime.datetime.now()
+        def run():
+            self.getPage("/long_process?seconds=%d" % SECONDS)
+            # The response should be the same every time
+            self.assertBody('success!')
+        ts = [threading.Thread(target=run) for i in xrange(100)]
+        for t in ts:
+            t.start()
+        for t in ts:
+            t.join()
+        self.assertEqualDates(start, datetime.datetime.now(),
+                              # Allow a second for our thread/TCP overhead etc.
+                              seconds=SECONDS + 1.1)
+    
+    def test_cache_control(self):
+        self.getPage("/control")
+        self.assertBody('visit #1')
+        self.getPage("/control")
+        self.assertBody('visit #1')
+        
+        self.getPage("/control", headers=[('Cache-Control', 'no-cache')])
+        self.assertBody('visit #2')
+        self.getPage("/control")
+        self.assertBody('visit #2')
+        
+        self.getPage("/control", headers=[('Pragma', 'no-cache')])
+        self.assertBody('visit #3')
+        self.getPage("/control")
+        self.assertBody('visit #3')
+        
+        time.sleep(1)
+        self.getPage("/control", headers=[('Cache-Control', 'max-age=0')])
+        self.assertBody('visit #4')
+        self.getPage("/control")
+        self.assertBody('visit #4')
+
diff --git a/cherrypy/test/test_config.py b/cherrypy/test/test_config.py
new file mode 100644
index 00000000..a0bd8ab9
--- /dev/null
+++ b/cherrypy/test/test_config.py
@@ -0,0 +1,249 @@
+"""Tests for the CherryPy configuration system."""
+
+import os, sys
+localDir = os.path.join(os.getcwd(), os.path.dirname(__file__))
+
+from cherrypy._cpcompat import ntob, StringIO
+import unittest
+
+import cherrypy
+
+def setup_server():
+
+    class Root:
+
+        _cp_config = {'foo': 'this',
+                      'bar': 'that'}
+
+        def __init__(self):
+            cherrypy.config.namespaces['db'] = self.db_namespace
+
+        def db_namespace(self, k, v):
+            if k == "scheme":
+                self.db = v
+
+        # @cherrypy.expose(alias=('global_', 'xyz'))
+        def index(self, key):
+            return cherrypy.request.config.get(key, "None")
+        index = cherrypy.expose(index, alias=('global_', 'xyz'))
+
+        def repr(self, key):
+            return repr(cherrypy.request.config.get(key, None))
+        repr.exposed = True
+
+        def dbscheme(self):
+            return self.db
+        dbscheme.exposed = True
+
+        def plain(self, x):
+            return x
+        plain.exposed = True
+        plain._cp_config = {'request.body.attempt_charsets': ['utf-16']}
+
+        favicon_ico = cherrypy.tools.staticfile.handler(
+                        filename=os.path.join(localDir, '../favicon.ico'))
+
+    class Foo:
+
+        _cp_config = {'foo': 'this2',
+                      'baz': 'that2'}
+
+        def index(self, key):
+            return cherrypy.request.config.get(key, "None")
+        index.exposed = True
+        nex = index
+
+        def silly(self):
+            return 'Hello world'
+        silly.exposed = True
+        silly._cp_config = {'response.headers.X-silly': 'sillyval'}
+
+        def bar(self, key):
+            return repr(cherrypy.request.config.get(key, None))
+        bar.exposed = True
+        bar._cp_config = {'foo': 'this3', 'bax': 'this4'}
+
+    class Another:
+
+        def index(self, key):
+            return str(cherrypy.request.config.get(key, "None"))
+        index.exposed = True
+
+
+    def raw_namespace(key, value):
+        if key == 'input.map':
+            handler = cherrypy.request.handler
+            def wrapper():
+                params = cherrypy.request.params
+                for name, coercer in list(value.items()):
+                    try:
+                        params[name] = coercer(params[name])
+                    except KeyError:
+                        pass
+                return handler()
+            cherrypy.request.handler = wrapper
+        elif key == 'output':
+            handler = cherrypy.request.handler
+            def wrapper():
+                # 'value' is a type (like int or str).
+                return value(handler())
+            cherrypy.request.handler = wrapper
+
+    class Raw:
+
+        _cp_config = {'raw.output': repr}
+
+        def incr(self, num):
+            return num + 1
+        incr.exposed = True
+        incr._cp_config = {'raw.input.map': {'num': int}}
+
+    ioconf = StringIO("""
+[/]
+neg: -1234
+filename: os.path.join(sys.prefix, "hello.py")
+thing1: cherrypy.lib.httputil.response_codes[404]
+thing2: __import__('cherrypy.tutorial', globals(), locals(), ['']).thing2
+complex: 3+2j
+ones: "11"
+twos: "22"
+stradd: %%(ones)s + %%(twos)s + "33"
+
+[/favicon.ico]
+tools.staticfile.filename = %r
+""" % os.path.join(localDir, 'static/dirback.jpg'))
+
+    root = Root()
+    root.foo = Foo()
+    root.raw = Raw()
+    app = cherrypy.tree.mount(root, config=ioconf)
+    app.request_class.namespaces['raw'] = raw_namespace
+
+    cherrypy.tree.mount(Another(), "/another")
+    cherrypy.config.update({'luxuryyacht': 'throatwobblermangrove',
+                            'db.scheme': r"sqlite///memory",
+                            })
+
+
+#                             Client-side code                             #
+
+from cherrypy.test import helper
+
+class ConfigTests(helper.CPWebCase):
+    setup_server = staticmethod(setup_server)
+
+    def testConfig(self):
+        tests = [
+            ('/',        'nex', 'None'),
+            ('/',        'foo', 'this'),
+            ('/',        'bar', 'that'),
+            ('/xyz',     'foo', 'this'),
+            ('/foo/',    'foo', 'this2'),
+            ('/foo/',    'bar', 'that'),
+            ('/foo/',    'bax', 'None'),
+            ('/foo/bar', 'baz', "'that2'"),
+            ('/foo/nex', 'baz', 'that2'),
+            # If 'foo' == 'this', then the mount point '/another' leaks into '/'.
+            ('/another/','foo', 'None'),
+        ]
+        for path, key, expected in tests:
+            self.getPage(path + "?key=" + key)
+            self.assertBody(expected)
+
+        expectedconf = {
+            # From CP defaults
+            'tools.log_headers.on': False,
+            'tools.log_tracebacks.on': True,
+            'request.show_tracebacks': True,
+            'log.screen': False,
+            'environment': 'test_suite',
+            'engine.autoreload_on': False,
+            # From global config
+            'luxuryyacht': 'throatwobblermangrove',
+            # From Root._cp_config
+            'bar': 'that',
+            # From Foo._cp_config
+            'baz': 'that2',
+            # From Foo.bar._cp_config
+            'foo': 'this3',
+            'bax': 'this4',
+            }
+        for key, expected in expectedconf.items():
+            self.getPage("/foo/bar?key=" + key)
+            self.assertBody(repr(expected))
+
+    def testUnrepr(self):
+        self.getPage("/repr?key=neg")
+        self.assertBody("-1234")
+
+        self.getPage("/repr?key=filename")
+        self.assertBody(repr(os.path.join(sys.prefix, "hello.py")))
+
+        self.getPage("/repr?key=thing1")
+        self.assertBody(repr(cherrypy.lib.httputil.response_codes[404]))
+
+        if not getattr(cherrypy.server, "using_apache", False):
+            # The object ID's won't match up when using Apache, since the
+            # server and client are running in different processes.
+            self.getPage("/repr?key=thing2")
+            from cherrypy.tutorial import thing2
+            self.assertBody(repr(thing2))
+
+        self.getPage("/repr?key=complex")
+        self.assertBody("(3+2j)")
+
+        self.getPage("/repr?key=stradd")
+        self.assertBody(repr("112233"))
+
+    def testRespNamespaces(self):
+        self.getPage("/foo/silly")
+        self.assertHeader('X-silly', 'sillyval')
+        self.assertBody('Hello world')
+
+    def testCustomNamespaces(self):
+        self.getPage("/raw/incr?num=12")
+        self.assertBody("13")
+
+        self.getPage("/dbscheme")
+        self.assertBody(r"sqlite///memory")
+
+    def testHandlerToolConfigOverride(self):
+        # Assert that config overrides tool constructor args. Above, we set
+        # the favicon in the page handler to be '../favicon.ico',
+        # but then overrode it in config to be './static/dirback.jpg'.
+        self.getPage("/favicon.ico")
+        self.assertBody(open(os.path.join(localDir, "static/dirback.jpg"),
+                             "rb").read())
+
+    def test_request_body_namespace(self):
+        self.getPage("/plain", method='POST', headers=[
+            ('Content-Type', 'application/x-www-form-urlencoded'),
+            ('Content-Length', '13')],
+            body=ntob('\xff\xfex\x00=\xff\xfea\x00b\x00c\x00'))
+        self.assertBody("abc")
+
+
+class VariableSubstitutionTests(unittest.TestCase):
+    setup_server = staticmethod(setup_server)
+
+    def test_config(self):
+        from textwrap import dedent
+
+        # variable substitution with [DEFAULT]
+        conf = dedent("""
+        [DEFAULT]
+        dir = "/some/dir"
+        my.dir = %(dir)s + "/sub"
+
+        [my]
+        my.dir = %(dir)s + "/my/dir"
+        my.dir2 = %(my.dir)s + '/dir2'
+
+        """)
+
+        fp = StringIO(conf)
+
+        cherrypy.config.update(fp)
+        self.assertEqual(cherrypy.config["my"]["my.dir"], "/some/dir/my/dir")
+        self.assertEqual(cherrypy.config["my"]["my.dir2"], "/some/dir/my/dir/dir2")
+
diff --git a/cherrypy/test/test_config_server.py b/cherrypy/test/test_config_server.py
new file mode 100644
index 00000000..0b9718da
--- /dev/null
+++ b/cherrypy/test/test_config_server.py
@@ -0,0 +1,121 @@
+"""Tests for the CherryPy configuration system."""
+
+import os, sys
+localDir = os.path.join(os.getcwd(), os.path.dirname(__file__))
+import socket
+import time
+
+import cherrypy
+
+
+#                             Client-side code                             #
+
+from cherrypy.test import helper
+
+class ServerConfigTests(helper.CPWebCase):
+
+    def setup_server():
+        
+        class Root:
+            def index(self):
+                return cherrypy.request.wsgi_environ['SERVER_PORT']
+            index.exposed = True
+            
+            def upload(self, file):
+                return "Size: %s" % len(file.file.read())
+            upload.exposed = True
+            
+            def tinyupload(self):
+                return cherrypy.request.body.read()
+            tinyupload.exposed = True
+            tinyupload._cp_config = {'request.body.maxbytes': 100}
+        
+        cherrypy.tree.mount(Root())
+        
+        cherrypy.config.update({
+            'server.socket_host': '0.0.0.0',
+            'server.socket_port': 9876,
+            'server.max_request_body_size': 200,
+            'server.max_request_header_size': 500,
+            'server.socket_timeout': 0.5,
+            
+            # Test explicit server.instance
+            'server.2.instance': 'cherrypy._cpwsgi_server.CPWSGIServer',
+            'server.2.socket_port': 9877,
+            
+            # Test non-numeric 
+            # Also test default server.instance = builtin server
+            'server.yetanother.socket_port': 9878,
+            })
+    setup_server = staticmethod(setup_server)
+    
+    PORT = 9876
+    
+    def testBasicConfig(self):
+        self.getPage("/")
+        self.assertBody(str(self.PORT))
+    
+    def testAdditionalServers(self):
+        if self.scheme == 'https':
+            return self.skip("not available under ssl")
+        self.PORT = 9877
+        self.getPage("/")
+        self.assertBody(str(self.PORT))
+        self.PORT = 9878
+        self.getPage("/")
+        self.assertBody(str(self.PORT))
+    
+    def testMaxRequestSizePerHandler(self):
+        if getattr(cherrypy.server, "using_apache", False):
+            return self.skip("skipped due to known Apache differences... ")
+        
+        self.getPage('/tinyupload', method="POST",
+                     headers=[('Content-Type', 'text/plain'),
+                              ('Content-Length', '100')],
+                     body="x" * 100)
+        self.assertStatus(200)
+        self.assertBody("x" * 100)
+        
+        self.getPage('/tinyupload', method="POST",
+                     headers=[('Content-Type', 'text/plain'),
+                              ('Content-Length', '101')],
+                     body="x" * 101)
+        self.assertStatus(413)
+    
+    def testMaxRequestSize(self):
+        if getattr(cherrypy.server, "using_apache", False):
+            return self.skip("skipped due to known Apache differences... ")
+        
+        for size in (500, 5000, 50000):
+            self.getPage("/", headers=[('From', "x" * 500)])
+            self.assertStatus(413)
+        
+        # Test for http://www.cherrypy.org/ticket/421
+        # (Incorrect border condition in readline of SizeCheckWrapper).
+        # This hangs in rev 891 and earlier.
+        lines256 = "x" * 248
+        self.getPage("/",
+                     headers=[('Host', '%s:%s' % (self.HOST, self.PORT)),
+                              ('From', lines256)])
+        
+        # Test upload
+        body = '\r\n'.join([
+            '--x',
+            'Content-Disposition: form-data; name="file"; filename="hello.txt"',
+            'Content-Type: text/plain',
+            '',
+            '%s',
+            '--x--'])
+        partlen = 200 - len(body)
+        b = body % ("x" * partlen)
+        h = [("Content-type", "multipart/form-data; boundary=x"),
+             ("Content-Length", "%s" % len(b))]
+        self.getPage('/upload', h, "POST", b)
+        self.assertBody('Size: %d' % partlen)
+        
+        b = body % ("x" * 200)
+        h = [("Content-type", "multipart/form-data; boundary=x"),
+             ("Content-Length", "%s" % len(b))]
+        self.getPage('/upload', h, "POST", b)
+        self.assertStatus(413)
+
diff --git a/cherrypy/test/test_conn.py b/cherrypy/test/test_conn.py
new file mode 100644
index 00000000..1346f593
--- /dev/null
+++ b/cherrypy/test/test_conn.py
@@ -0,0 +1,734 @@
+"""Tests for TCP connection handling, including proper and timely close."""
+
+import socket
+import sys
+import time
+timeout = 1
+
+
+import cherrypy
+from cherrypy._cpcompat import HTTPConnection, HTTPSConnection, NotConnected, BadStatusLine
+from cherrypy._cpcompat import ntob, urlopen, unicodestr
+from cherrypy.test import webtest
+from cherrypy import _cperror
+
+
+pov = 'pPeErRsSiIsStTeEnNcCeE oOfF vViIsSiIoOnN'
+
+def setup_server():
+
+    def raise500():
+        raise cherrypy.HTTPError(500)
+
+    class Root:
+
+        def index(self):
+            return pov
+        index.exposed = True
+        page1 = index
+        page2 = index
+        page3 = index
+
+        def hello(self):
+            return "Hello, world!"
+        hello.exposed = True
+
+        def timeout(self, t):
+            return str(cherrypy.server.httpserver.timeout)
+        timeout.exposed = True
+
+        def stream(self, set_cl=False):
+            if set_cl:
+                cherrypy.response.headers['Content-Length'] = 10
+
+            def content():
+                for x in range(10):
+                    yield str(x)
+
+            return content()
+        stream.exposed = True
+        stream._cp_config = {'response.stream': True}
+
+        def error(self, code=500):
+            raise cherrypy.HTTPError(code)
+        error.exposed = True
+
+        def upload(self):
+            if not cherrypy.request.method == 'POST':
+                raise AssertionError("'POST' != request.method %r" %
+                                     cherrypy.request.method)
+            return "thanks for '%s'" % cherrypy.request.body.read()
+        upload.exposed = True
+
+        def custom(self, response_code):
+            cherrypy.response.status = response_code
+            return "Code = %s" % response_code
+        custom.exposed = True
+
+        def err_before_read(self):
+            return "ok"
+        err_before_read.exposed = True
+        err_before_read._cp_config = {'hooks.on_start_resource': raise500}
+
+        def one_megabyte_of_a(self):
+            return ["a" * 1024] * 1024
+        one_megabyte_of_a.exposed = True
+
+        def custom_cl(self, body, cl):
+            cherrypy.response.headers['Content-Length'] = cl
+            if not isinstance(body, list):
+                body = [body]
+            newbody = []
+            for chunk in body:
+                if isinstance(chunk, unicodestr):
+                    chunk = chunk.encode('ISO-8859-1')
+                newbody.append(chunk)
+            return newbody
+        custom_cl.exposed = True
+        # Turn off the encoding tool so it doens't collapse
+        # our response body and reclaculate the Content-Length.
+        custom_cl._cp_config = {'tools.encode.on': False}
+
+    cherrypy.tree.mount(Root())
+    cherrypy.config.update({
+        'server.max_request_body_size': 1001,
+        'server.socket_timeout': timeout,
+        })
+
+
+from cherrypy.test import helper
+
+class ConnectionCloseTests(helper.CPWebCase):
+    setup_server = staticmethod(setup_server)
+
+    def test_HTTP11(self):
+        if cherrypy.server.protocol_version != "HTTP/1.1":
+            return self.skip()
+
+        self.PROTOCOL = "HTTP/1.1"
+
+        self.persistent = True
+
+        # Make the first request and assert there's no "Connection: close".
+        self.getPage("/")
+        self.assertStatus('200 OK')
+        self.assertBody(pov)
+        self.assertNoHeader("Connection")
+
+        # Make another request on the same connection.
+        self.getPage("/page1")
+        self.assertStatus('200 OK')
+        self.assertBody(pov)
+        self.assertNoHeader("Connection")
+
+        # Test client-side close.
+        self.getPage("/page2", headers=[("Connection", "close")])
+        self.assertStatus('200 OK')
+        self.assertBody(pov)
+        self.assertHeader("Connection", "close")
+
+        # Make another request on the same connection, which should error.
+        self.assertRaises(NotConnected, self.getPage, "/")
+
+    def test_Streaming_no_len(self):
+        self._streaming(set_cl=False)
+
+    def test_Streaming_with_len(self):
+        self._streaming(set_cl=True)
+
+    def _streaming(self, set_cl):
+        if cherrypy.server.protocol_version == "HTTP/1.1":
+            self.PROTOCOL = "HTTP/1.1"
+
+            self.persistent = True
+
+            # Make the first request and assert there's no "Connection: close".
+            self.getPage("/")
+            self.assertStatus('200 OK')
+            self.assertBody(pov)
+            self.assertNoHeader("Connection")
+
+            # Make another, streamed request on the same connection.
+            if set_cl:
+                # When a Content-Length is provided, the content should stream
+                # without closing the connection.
+                self.getPage("/stream?set_cl=Yes")
+                self.assertHeader("Content-Length")
+                self.assertNoHeader("Connection", "close")
+                self.assertNoHeader("Transfer-Encoding")
+
+                self.assertStatus('200 OK')
+                self.assertBody('0123456789')
+            else:
+                # When no Content-Length response header is provided,
+                # streamed output will either close the connection, or use
+                # chunked encoding, to determine transfer-length.
+                self.getPage("/stream")
+                self.assertNoHeader("Content-Length")
+                self.assertStatus('200 OK')
+                self.assertBody('0123456789')
+
+                chunked_response = False
+                for k, v in self.headers:
+                    if k.lower() == "transfer-encoding":
+                        if str(v) == "chunked":
+                            chunked_response = True
+
+                if chunked_response:
+                    self.assertNoHeader("Connection", "close")
+                else:
+                    self.assertHeader("Connection", "close")
+
+                    # Make another request on the same connection, which should error.
+                    self.assertRaises(NotConnected, self.getPage, "/")
+
+                # Try HEAD. See http://www.cherrypy.org/ticket/864.
+                self.getPage("/stream", method='HEAD')
+                self.assertStatus('200 OK')
+                self.assertBody('')
+                self.assertNoHeader("Transfer-Encoding")
+        else:
+            self.PROTOCOL = "HTTP/1.0"
+
+            self.persistent = True
+
+            # Make the first request and assert Keep-Alive.
+            self.getPage("/", headers=[("Connection", "Keep-Alive")])
+            self.assertStatus('200 OK')
+            self.assertBody(pov)
+            self.assertHeader("Connection", "Keep-Alive")
+
+            # Make another, streamed request on the same connection.
+            if set_cl:
+                # When a Content-Length is provided, the content should
+                # stream without closing the connection.
+                self.getPage("/stream?set_cl=Yes",
+                             headers=[("Connection", "Keep-Alive")])
+                self.assertHeader("Content-Length")
+                self.assertHeader("Connection", "Keep-Alive")
+                self.assertNoHeader("Transfer-Encoding")
+                self.assertStatus('200 OK')
+                self.assertBody('0123456789')
+            else:
+                # When a Content-Length is not provided,
+                # the server should close the connection.
+                self.getPage("/stream", headers=[("Connection", "Keep-Alive")])
+                self.assertStatus('200 OK')
+                self.assertBody('0123456789')
+
+                self.assertNoHeader("Content-Length")
+                self.assertNoHeader("Connection", "Keep-Alive")
+                self.assertNoHeader("Transfer-Encoding")
+
+                # Make another request on the same connection, which should error.
+                self.assertRaises(NotConnected, self.getPage, "/")
+
+    def test_HTTP10_KeepAlive(self):
+        self.PROTOCOL = "HTTP/1.0"
+        if self.scheme == "https":
+            self.HTTP_CONN = HTTPSConnection
+        else:
+            self.HTTP_CONN = HTTPConnection
+
+        # Test a normal HTTP/1.0 request.
+        self.getPage("/page2")
+        self.assertStatus('200 OK')
+        self.assertBody(pov)
+        # Apache, for example, may emit a Connection header even for HTTP/1.0
+##        self.assertNoHeader("Connection")
+
+        # Test a keep-alive HTTP/1.0 request.
+        self.persistent = True
+
+        self.getPage("/page3", headers=[("Connection", "Keep-Alive")])
+        self.assertStatus('200 OK')
+        self.assertBody(pov)
+        self.assertHeader("Connection", "Keep-Alive")
+
+        # Remove the keep-alive header again.
+        self.getPage("/page3")
+        self.assertStatus('200 OK')
+        self.assertBody(pov)
+        # Apache, for example, may emit a Connection header even for HTTP/1.0
+##        self.assertNoHeader("Connection")
+
+
+class PipelineTests(helper.CPWebCase):
+    setup_server = staticmethod(setup_server)
+
+    def test_HTTP11_Timeout(self):
+        # If we timeout without sending any data,
+        # the server will close the conn with a 408.
+        if cherrypy.server.protocol_version != "HTTP/1.1":
+            return self.skip()
+
+        self.PROTOCOL = "HTTP/1.1"
+
+        # Connect but send nothing.
+        self.persistent = True
+        conn = self.HTTP_CONN
+        conn.auto_open = False
+        conn.connect()
+
+        # Wait for our socket timeout
+        time.sleep(timeout * 2)
+
+        # The request should have returned 408 already.
+        response = conn.response_class(conn.sock, method="GET")
+        response.begin()
+        self.assertEqual(response.status, 408)
+        conn.close()
+
+        # Connect but send half the headers only.
+        self.persistent = True
+        conn = self.HTTP_CONN
+        conn.auto_open = False
+        conn.connect()
+        conn.send(ntob('GET /hello HTTP/1.1'))
+        conn.send(("Host: %s" % self.HOST).encode('ascii'))
+
+        # Wait for our socket timeout
+        time.sleep(timeout * 2)
+
+        # The conn should have already sent 408.
+        response = conn.response_class(conn.sock, method="GET")
+        response.begin()
+        self.assertEqual(response.status, 408)
+        conn.close()
+
+    def test_HTTP11_Timeout_after_request(self):
+        # If we timeout after at least one request has succeeded,
+        # the server will close the conn without 408.
+        if cherrypy.server.protocol_version != "HTTP/1.1":
+            return self.skip()
+
+        self.PROTOCOL = "HTTP/1.1"
+
+        # Make an initial request
+        self.persistent = True
+        conn = self.HTTP_CONN
+        conn.putrequest("GET", "/timeout?t=%s" % timeout, skip_host=True)
+        conn.putheader("Host", self.HOST)
+        conn.endheaders()
+        response = conn.response_class(conn.sock, method="GET")
+        response.begin()
+        self.assertEqual(response.status, 200)
+        self.body = response.read()
+        self.assertBody(str(timeout))
+
+        # Make a second request on the same socket
+        conn._output(ntob('GET /hello HTTP/1.1'))
+        conn._output(ntob("Host: %s" % self.HOST, 'ascii'))
+        conn._send_output()
+        response = conn.response_class(conn.sock, method="GET")
+        response.begin()
+        self.assertEqual(response.status, 200)
+        self.body = response.read()
+        self.assertBody("Hello, world!")
+
+        # Wait for our socket timeout
+        time.sleep(timeout * 2)
+
+        # Make another request on the same socket, which should error
+        conn._output(ntob('GET /hello HTTP/1.1'))
+        conn._output(ntob("Host: %s" % self.HOST, 'ascii'))
+        conn._send_output()
+        response = conn.response_class(conn.sock, method="GET")
+        try:
+            response.begin()
+        except:
+            if not isinstance(sys.exc_info()[1],
+                              (socket.error, BadStatusLine)):
+                self.fail("Writing to timed out socket didn't fail"
+                          " as it should have: %s" % sys.exc_info()[1])
+        else:
+            if response.status != 408:
+                self.fail("Writing to timed out socket didn't fail"
+                          " as it should have: %s" %
+                          response.read())
+
+        conn.close()
+
+        # Make another request on a new socket, which should work
+        self.persistent = True
+        conn = self.HTTP_CONN
+        conn.putrequest("GET", "/", skip_host=True)
+        conn.putheader("Host", self.HOST)
+        conn.endheaders()
+        response = conn.response_class(conn.sock, method="GET")
+        response.begin()
+        self.assertEqual(response.status, 200)
+        self.body = response.read()
+        self.assertBody(pov)
+
+
+        # Make another request on the same socket,
+        # but timeout on the headers
+        conn.send(ntob('GET /hello HTTP/1.1'))
+        # Wait for our socket timeout
+        time.sleep(timeout * 2)
+        response = conn.response_class(conn.sock, method="GET")
+        try:
+            response.begin()
+        except:
+            if not isinstance(sys.exc_info()[1],
+                              (socket.error, BadStatusLine)):
+                self.fail("Writing to timed out socket didn't fail"
+                          " as it should have: %s" % sys.exc_info()[1])
+        else:
+            self.fail("Writing to timed out socket didn't fail"
+                      " as it should have: %s" %
+                      response.read())
+
+        conn.close()
+
+        # Retry the request on a new connection, which should work
+        self.persistent = True
+        conn = self.HTTP_CONN
+        conn.putrequest("GET", "/", skip_host=True)
+        conn.putheader("Host", self.HOST)
+        conn.endheaders()
+        response = conn.response_class(conn.sock, method="GET")
+        response.begin()
+        self.assertEqual(response.status, 200)
+        self.body = response.read()
+        self.assertBody(pov)
+        conn.close()
+
+    def test_HTTP11_pipelining(self):
+        if cherrypy.server.protocol_version != "HTTP/1.1":
+            return self.skip()
+
+        self.PROTOCOL = "HTTP/1.1"
+
+        # Test pipelining. httplib doesn't support this directly.
+        self.persistent = True
+        conn = self.HTTP_CONN
+
+        # Put request 1
+        conn.putrequest("GET", "/hello", skip_host=True)
+        conn.putheader("Host", self.HOST)
+        conn.endheaders()
+
+        for trial in range(5):
+            # Put next request
+            conn._output(ntob('GET /hello HTTP/1.1'))
+            conn._output(ntob("Host: %s" % self.HOST, 'ascii'))
+            conn._send_output()
+
+            # Retrieve previous response
+            response = conn.response_class(conn.sock, method="GET")
+            response.begin()
+            body = response.read(13)
+            self.assertEqual(response.status, 200)
+            self.assertEqual(body, ntob("Hello, world!"))
+
+        # Retrieve final response
+        response = conn.response_class(conn.sock, method="GET")
+        response.begin()
+        body = response.read()
+        self.assertEqual(response.status, 200)
+        self.assertEqual(body, ntob("Hello, world!"))
+
+        conn.close()
+
+    def test_100_Continue(self):
+        if cherrypy.server.protocol_version != "HTTP/1.1":
+            return self.skip()
+
+        self.PROTOCOL = "HTTP/1.1"
+
+        self.persistent = True
+        conn = self.HTTP_CONN
+
+        # Try a page without an Expect request header first.
+        # Note that httplib's response.begin automatically ignores
+        # 100 Continue responses, so we must manually check for it.
+        conn.putrequest("POST", "/upload", skip_host=True)
+        conn.putheader("Host", self.HOST)
+        conn.putheader("Content-Type", "text/plain")
+        conn.putheader("Content-Length", "4")
+        conn.endheaders()
+        conn.send(ntob("d'oh"))
+        response = conn.response_class(conn.sock, method="POST")
+        version, status, reason = response._read_status()
+        self.assertNotEqual(status, 100)
+        conn.close()
+
+        # Now try a page with an Expect header...
+        conn.connect()
+        conn.putrequest("POST", "/upload", skip_host=True)
+        conn.putheader("Host", self.HOST)
+        conn.putheader("Content-Type", "text/plain")
+        conn.putheader("Content-Length", "17")
+        conn.putheader("Expect", "100-continue")
+        conn.endheaders()
+        response = conn.response_class(conn.sock, method="POST")
+
+        # ...assert and then skip the 100 response
+        version, status, reason = response._read_status()
+        self.assertEqual(status, 100)
+        while True:
+            line = response.fp.readline().strip()
+            if line:
+                self.fail("100 Continue should not output any headers. Got %r" % line)
+            else:
+                break
+
+        # ...send the body
+        body = ntob("I am a small file")
+        conn.send(body)
+
+        # ...get the final response
+        response.begin()
+        self.status, self.headers, self.body = webtest.shb(response)
+        self.assertStatus(200)
+        self.assertBody("thanks for '%s'" % body)
+        conn.close()
+
+
+class ConnectionTests(helper.CPWebCase):
+    setup_server = staticmethod(setup_server)
+
+    def test_readall_or_close(self):
+        if cherrypy.server.protocol_version != "HTTP/1.1":
+            return self.skip()
+
+        self.PROTOCOL = "HTTP/1.1"
+
+        if self.scheme == "https":
+            self.HTTP_CONN = HTTPSConnection
+        else:
+            self.HTTP_CONN = HTTPConnection
+
+        # Test a max of 0 (the default) and then reset to what it was above.
+        old_max = cherrypy.server.max_request_body_size
+        for new_max in (0, old_max):
+            cherrypy.server.max_request_body_size = new_max
+
+            self.persistent = True
+            conn = self.HTTP_CONN
+
+            # Get a POST page with an error
+            conn.putrequest("POST", "/err_before_read", skip_host=True)
+            conn.putheader("Host", self.HOST)
+            conn.putheader("Content-Type", "text/plain")
+            conn.putheader("Content-Length", "1000")
+            conn.putheader("Expect", "100-continue")
+            conn.endheaders()
+            response = conn.response_class(conn.sock, method="POST")
+
+            # ...assert and then skip the 100 response
+            version, status, reason = response._read_status()
+            self.assertEqual(status, 100)
+            while True:
+                skip = response.fp.readline().strip()
+                if not skip:
+                    break
+
+            # ...send the body
+            conn.send(ntob("x" * 1000))
+
+            # ...get the final response
+            response.begin()
+            self.status, self.headers, self.body = webtest.shb(response)
+            self.assertStatus(500)
+
+            # Now try a working page with an Expect header...
+            conn._output(ntob('POST /upload HTTP/1.1'))
+            conn._output(ntob("Host: %s" % self.HOST, 'ascii'))
+            conn._output(ntob("Content-Type: text/plain"))
+            conn._output(ntob("Content-Length: 17"))
+            conn._output(ntob("Expect: 100-continue"))
+            conn._send_output()
+            response = conn.response_class(conn.sock, method="POST")
+
+            # ...assert and then skip the 100 response
+            version, status, reason = response._read_status()
+            self.assertEqual(status, 100)
+            while True:
+                skip = response.fp.readline().strip()
+                if not skip:
+                    break
+
+            # ...send the body
+            body = ntob("I am a small file")
+            conn.send(body)
+
+            # ...get the final response
+            response.begin()
+            self.status, self.headers, self.body = webtest.shb(response)
+            self.assertStatus(200)
+            self.assertBody("thanks for '%s'" % body)
+            conn.close()
+
+    def test_No_Message_Body(self):
+        if cherrypy.server.protocol_version != "HTTP/1.1":
+            return self.skip()
+
+        self.PROTOCOL = "HTTP/1.1"
+
+        # Set our HTTP_CONN to an instance so it persists between requests.
+        self.persistent = True
+
+        # Make the first request and assert there's no "Connection: close".
+        self.getPage("/")
+        self.assertStatus('200 OK')
+        self.assertBody(pov)
+        self.assertNoHeader("Connection")
+
+        # Make a 204 request on the same connection.
+        self.getPage("/custom/204")
+        self.assertStatus(204)
+        self.assertNoHeader("Content-Length")
+        self.assertBody("")
+        self.assertNoHeader("Connection")
+
+        # Make a 304 request on the same connection.
+        self.getPage("/custom/304")
+        self.assertStatus(304)
+        self.assertNoHeader("Content-Length")
+        self.assertBody("")
+        self.assertNoHeader("Connection")
+
+    def test_Chunked_Encoding(self):
+        if cherrypy.server.protocol_version != "HTTP/1.1":
+            return self.skip()
+
+        if (hasattr(self, 'harness') and
+            "modpython" in self.harness.__class__.__name__.lower()):
+            # mod_python forbids chunked encoding
+            return self.skip()
+
+        self.PROTOCOL = "HTTP/1.1"
+
+        # Set our HTTP_CONN to an instance so it persists between requests.
+        self.persistent = True
+        conn = self.HTTP_CONN
+
+        # Try a normal chunked request (with extensions)
+        body = ntob("8;key=value\r\nxx\r\nxxxx\r\n5\r\nyyyyy\r\n0\r\n"
+                "Content-Type: application/json\r\n"
+                "\r\n")
+        conn.putrequest("POST", "/upload", skip_host=True)
+        conn.putheader("Host", self.HOST)
+        conn.putheader("Transfer-Encoding", "chunked")
+        conn.putheader("Trailer", "Content-Type")
+        # Note that this is somewhat malformed:
+        # we shouldn't be sending Content-Length.
+        # RFC 2616 says the server should ignore it.
+        conn.putheader("Content-Length", "3")
+        conn.endheaders()
+        conn.send(body)
+        response = conn.getresponse()
+        self.status, self.headers, self.body = webtest.shb(response)
+        self.assertStatus('200 OK')
+        self.assertBody("thanks for '%s'" % ntob('xx\r\nxxxxyyyyy'))
+
+        # Try a chunked request that exceeds server.max_request_body_size.
+        # Note that the delimiters and trailer are included.
+        body = ntob("3e3\r\n" + ("x" * 995) + "\r\n0\r\n\r\n")
+        conn.putrequest("POST", "/upload", skip_host=True)
+        conn.putheader("Host", self.HOST)
+        conn.putheader("Transfer-Encoding", "chunked")
+        conn.putheader("Content-Type", "text/plain")
+        # Chunked requests don't need a content-length
+##        conn.putheader("Content-Length", len(body))
+        conn.endheaders()
+        conn.send(body)
+        response = conn.getresponse()
+        self.status, self.headers, self.body = webtest.shb(response)
+        self.assertStatus(413)
+        conn.close()
+
+    def test_Content_Length_in(self):
+        # Try a non-chunked request where Content-Length exceeds
+        # server.max_request_body_size. Assert error before body send.
+        self.persistent = True
+        conn = self.HTTP_CONN
+        conn.putrequest("POST", "/upload", skip_host=True)
+        conn.putheader("Host", self.HOST)
+        conn.putheader("Content-Type", "text/plain")
+        conn.putheader("Content-Length", "9999")
+        conn.endheaders()
+        response = conn.getresponse()
+        self.status, self.headers, self.body = webtest.shb(response)
+        self.assertStatus(413)
+        self.assertBody("The entity sent with the request exceeds "
+                        "the maximum allowed bytes.")
+        conn.close()
+
+    def test_Content_Length_out_preheaders(self):
+        # Try a non-chunked response where Content-Length is less than
+        # the actual bytes in the response body.
+        self.persistent = True
+        conn = self.HTTP_CONN
+        conn.putrequest("GET", "/custom_cl?body=I+have+too+many+bytes&cl=5",
+                        skip_host=True)
+        conn.putheader("Host", self.HOST)
+        conn.endheaders()
+        response = conn.getresponse()
+        self.status, self.headers, self.body = webtest.shb(response)
+        self.assertStatus(500)
+        self.assertBody(
+            "The requested resource returned more bytes than the "
+            "declared Content-Length.")
+        conn.close()
+
+    def test_Content_Length_out_postheaders(self):
+        # Try a non-chunked response where Content-Length is less than
+        # the actual bytes in the response body.
+        self.persistent = True
+        conn = self.HTTP_CONN
+        conn.putrequest("GET", "/custom_cl?body=I+too&body=+have+too+many&cl=5",
+                        skip_host=True)
+        conn.putheader("Host", self.HOST)
+        conn.endheaders()
+        response = conn.getresponse()
+        self.status, self.headers, self.body = webtest.shb(response)
+        self.assertStatus(200)
+        self.assertBody("I too")
+        conn.close()
+
+    def test_598(self):
+        remote_data_conn = urlopen('%s://%s:%s/one_megabyte_of_a/' %
+                                          (self.scheme, self.HOST, self.PORT,))
+        buf = remote_data_conn.read(512)
+        time.sleep(timeout * 0.6)
+        remaining = (1024 * 1024) - 512
+        while remaining:
+            data = remote_data_conn.read(remaining)
+            if not data:
+                break
+            else:
+                buf += data
+            remaining -= len(data)
+
+        self.assertEqual(len(buf), 1024 * 1024)
+        self.assertEqual(buf, ntob("a" * 1024 * 1024))
+        self.assertEqual(remaining, 0)
+        remote_data_conn.close()
+
+
+class BadRequestTests(helper.CPWebCase):
+    setup_server = staticmethod(setup_server)
+
+    def test_No_CRLF(self):
+        self.persistent = True
+
+        conn = self.HTTP_CONN
+        conn.send(ntob('GET /hello HTTP/1.1\n\n'))
+        response = conn.response_class(conn.sock, method="GET")
+        response.begin()
+        self.body = response.read()
+        self.assertBody("HTTP requires CRLF terminators")
+        conn.close()
+
+        conn.connect()
+        conn.send(ntob('GET /hello HTTP/1.1\r\n\n'))
+        response = conn.response_class(conn.sock, method="GET")
+        response.begin()
+        self.body = response.read()
+        self.assertBody("HTTP requires CRLF terminators")
+        conn.close()
+
diff --git a/cherrypy/test/test_core.py b/cherrypy/test/test_core.py
new file mode 100644
index 00000000..09544e34
--- /dev/null
+++ b/cherrypy/test/test_core.py
@@ -0,0 +1,617 @@
+"""Basic tests for the CherryPy core: request handling."""
+
+import os
+localDir = os.path.dirname(__file__)
+import sys
+import types
+
+import cherrypy
+from cherrypy._cpcompat import IncompleteRead, itervalues, ntob
+from cherrypy import _cptools, tools
+from cherrypy.lib import httputil, static
+
+
+favicon_path = os.path.join(os.getcwd(), localDir, "../favicon.ico")
+
+#                             Client-side code                             #
+
+from cherrypy.test import helper
+
+class CoreRequestHandlingTest(helper.CPWebCase):
+
+    def setup_server():
+        class Root:
+            
+            def index(self):
+                return "hello"
+            index.exposed = True
+            
+            favicon_ico = tools.staticfile.handler(filename=favicon_path)
+            
+            def defct(self, newct):
+                newct = "text/%s" % newct
+                cherrypy.config.update({'tools.response_headers.on': True,
+                                        'tools.response_headers.headers':
+                                        [('Content-Type', newct)]})
+            defct.exposed = True
+            
+            def baseurl(self, path_info, relative=None):
+                return cherrypy.url(path_info, relative=bool(relative))
+            baseurl.exposed = True
+        
+        root = Root()
+                
+        if sys.version_info >= (2, 5):
+            from cherrypy.test._test_decorators import ExposeExamples
+            root.expose_dec = ExposeExamples()
+
+
+        class TestType(type):
+            """Metaclass which automatically exposes all functions in each subclass,
+            and adds an instance of the subclass as an attribute of root.
+            """
+            def __init__(cls, name, bases, dct):
+                type.__init__(cls, name, bases, dct)
+                for value in itervalues(dct):
+                    if isinstance(value, types.FunctionType):
+                        value.exposed = True
+                setattr(root, name.lower(), cls())
+        class Test(object):
+            __metaclass__ = TestType
+        
+        
+        class URL(Test):
+            
+            _cp_config = {'tools.trailing_slash.on': False}
+            
+            def index(self, path_info, relative=None):
+                if relative != 'server':
+                    relative = bool(relative)
+                return cherrypy.url(path_info, relative=relative)
+            
+            def leaf(self, path_info, relative=None):
+                if relative != 'server':
+                    relative = bool(relative)
+                return cherrypy.url(path_info, relative=relative)
+
+
+        class Status(Test):
+            
+            def index(self):
+                return "normal"
+            
+            def blank(self):
+                cherrypy.response.status = ""
+            
+            # According to RFC 2616, new status codes are OK as long as they
+            # are between 100 and 599.
+            
+            # Here is an illegal code...
+            def illegal(self):
+                cherrypy.response.status = 781
+                return "oops"
+            
+            # ...and here is an unknown but legal code.
+            def unknown(self):
+                cherrypy.response.status = "431 My custom error"
+                return "funky"
+            
+            # Non-numeric code
+            def bad(self):
+                cherrypy.response.status = "error"
+                return "bad news"
+
+
+        class Redirect(Test):
+            
+            class Error:
+                _cp_config = {"tools.err_redirect.on": True,
+                              "tools.err_redirect.url": "/errpage",
+                              "tools.err_redirect.internal": False,
+                              }
+                
+                def index(self):
+                    raise NameError("redirect_test")
+                index.exposed = True
+            error = Error()
+            
+            def index(self):
+                return "child"
+            
+            def custom(self, url, code):
+                raise cherrypy.HTTPRedirect(url, code)
+            
+            def by_code(self, code):
+                raise cherrypy.HTTPRedirect("somewhere%20else", code)
+            by_code._cp_config = {'tools.trailing_slash.extra': True}
+            
+            def nomodify(self):
+                raise cherrypy.HTTPRedirect("", 304)
+            
+            def proxy(self):
+                raise cherrypy.HTTPRedirect("proxy", 305)
+            
+            def stringify(self):
+                return str(cherrypy.HTTPRedirect("/"))
+            
+            def fragment(self, frag):
+                raise cherrypy.HTTPRedirect("/some/url#%s" % frag)
+        
+        def login_redir():
+            if not getattr(cherrypy.request, "login", None):
+                raise cherrypy.InternalRedirect("/internalredirect/login")
+        tools.login_redir = _cptools.Tool('before_handler', login_redir)
+        
+        def redir_custom():
+            raise cherrypy.InternalRedirect("/internalredirect/custom_err")
+        
+        class InternalRedirect(Test):
+            
+            def index(self):
+                raise cherrypy.InternalRedirect("/")
+            
+            def choke(self):
+                return 3 / 0
+            choke.exposed = True
+            choke._cp_config = {'hooks.before_error_response': redir_custom}
+            
+            def relative(self, a, b):
+                raise cherrypy.InternalRedirect("cousin?t=6")
+            
+            def cousin(self, t):
+                assert cherrypy.request.prev.closed
+                return cherrypy.request.prev.query_string
+            
+            def petshop(self, user_id):
+                if user_id == "parrot":
+                    # Trade it for a slug when redirecting
+                    raise cherrypy.InternalRedirect('/image/getImagesByUser?user_id=slug')
+                elif user_id == "terrier":
+                    # Trade it for a fish when redirecting
+                    raise cherrypy.InternalRedirect('/image/getImagesByUser?user_id=fish')
+                else:
+                    # This should pass the user_id through to getImagesByUser
+                    raise cherrypy.InternalRedirect(
+                        '/image/getImagesByUser?user_id=%s' % str(user_id))
+            
+            # We support Python 2.3, but the @-deco syntax would look like this:
+            # @tools.login_redir()
+            def secure(self):
+                return "Welcome!"
+            secure = tools.login_redir()(secure)
+            # Since calling the tool returns the same function you pass in,
+            # you could skip binding the return value, and just write:
+            # tools.login_redir()(secure)
+            
+            def login(self):
+                return "Please log in"
+            
+            def custom_err(self):
+                return "Something went horribly wrong."
+            
+            def early_ir(self, arg):
+                return "whatever"
+            early_ir._cp_config = {'hooks.before_request_body': redir_custom}
+        
+        
+        class Image(Test):
+            
+            def getImagesByUser(self, user_id):
+                return "0 images for %s" % user_id
+
+
+        class Flatten(Test):
+            
+            def as_string(self):
+                return "content"
+            
+            def as_list(self):
+                return ["con", "tent"]
+            
+            def as_yield(self):
+                yield ntob("content")
+            
+            def as_dblyield(self):
+                yield self.as_yield()
+            as_dblyield._cp_config = {'tools.flatten.on': True}
+            
+            def as_refyield(self):
+                for chunk in self.as_yield():
+                    yield chunk
+        
+        
+        class Ranges(Test):
+            
+            def get_ranges(self, bytes):
+                return repr(httputil.get_ranges('bytes=%s' % bytes, 8))
+            
+            def slice_file(self):
+                path = os.path.join(os.getcwd(), os.path.dirname(__file__))
+                return static.serve_file(os.path.join(path, "static/index.html"))
+
+
+        class Cookies(Test):
+            
+            def single(self, name):
+                cookie = cherrypy.request.cookie[name]
+                # Python2's SimpleCookie.__setitem__ won't take unicode keys.
+                cherrypy.response.cookie[str(name)] = cookie.value
+            
+            def multiple(self, names):
+                for name in names:
+                    cookie = cherrypy.request.cookie[name]
+                    # Python2's SimpleCookie.__setitem__ won't take unicode keys.
+                    cherrypy.response.cookie[str(name)] = cookie.value
+
+
+        cherrypy.tree.mount(root)
+    setup_server = staticmethod(setup_server)
+
+
+    def testStatus(self):
+        self.getPage("/status/")
+        self.assertBody('normal')
+        self.assertStatus(200)
+        
+        self.getPage("/status/blank")
+        self.assertBody('')
+        self.assertStatus(200)
+        
+        self.getPage("/status/illegal")
+        self.assertStatus(500)
+        msg = "Illegal response status from server (781 is out of range)."
+        self.assertErrorPage(500, msg)
+        
+        if not getattr(cherrypy.server, 'using_apache', False):
+            self.getPage("/status/unknown")
+            self.assertBody('funky')
+            self.assertStatus(431)
+        
+        self.getPage("/status/bad")
+        self.assertStatus(500)
+        msg = "Illegal response status from server ('error' is non-numeric)."
+        self.assertErrorPage(500, msg)
+    
+    def testSlashes(self):
+        # Test that requests for index methods without a trailing slash
+        # get redirected to the same URI path with a trailing slash.
+        # Make sure GET params are preserved.
+        self.getPage("/redirect?id=3")
+        self.assertStatus(301)
+        self.assertInBody(""
+                          "%s/redirect/?id=3" % (self.base(), self.base()))
+        
+        if self.prefix():
+            # Corner case: the "trailing slash" redirect could be tricky if
+            # we're using a virtual root and the URI is "/vroot" (no slash).
+            self.getPage("")
+            self.assertStatus(301)
+            self.assertInBody("%s/" %
+                              (self.base(), self.base()))
+        
+        # Test that requests for NON-index methods WITH a trailing slash
+        # get redirected to the same URI path WITHOUT a trailing slash.
+        # Make sure GET params are preserved.
+        self.getPage("/redirect/by_code/?code=307")
+        self.assertStatus(301)
+        self.assertInBody(""
+                          "%s/redirect/by_code?code=307"
+                          % (self.base(), self.base()))
+        
+        # If the trailing_slash tool is off, CP should just continue
+        # as if the slashes were correct. But it needs some help
+        # inside cherrypy.url to form correct output.
+        self.getPage('/url?path_info=page1')
+        self.assertBody('%s/url/page1' % self.base())
+        self.getPage('/url/leaf/?path_info=page1')
+        self.assertBody('%s/url/page1' % self.base())
+    
+    def testRedirect(self):
+        self.getPage("/redirect/")
+        self.assertBody('child')
+        self.assertStatus(200)
+        
+        self.getPage("/redirect/by_code?code=300")
+        self.assertMatchesBody(r"\1somewhere%20else")
+        self.assertStatus(300)
+        
+        self.getPage("/redirect/by_code?code=301")
+        self.assertMatchesBody(r"\1somewhere%20else")
+        self.assertStatus(301)
+        
+        self.getPage("/redirect/by_code?code=302")
+        self.assertMatchesBody(r"\1somewhere%20else")
+        self.assertStatus(302)
+        
+        self.getPage("/redirect/by_code?code=303")
+        self.assertMatchesBody(r"\1somewhere%20else")
+        self.assertStatus(303)
+        
+        self.getPage("/redirect/by_code?code=307")
+        self.assertMatchesBody(r"\1somewhere%20else")
+        self.assertStatus(307)
+        
+        self.getPage("/redirect/nomodify")
+        self.assertBody('')
+        self.assertStatus(304)
+        
+        self.getPage("/redirect/proxy")
+        self.assertBody('')
+        self.assertStatus(305)
+        
+        # HTTPRedirect on error
+        self.getPage("/redirect/error/")
+        self.assertStatus(('302 Found', '303 See Other'))
+        self.assertInBody('/errpage')
+        
+        # Make sure str(HTTPRedirect()) works.
+        self.getPage("/redirect/stringify", protocol="HTTP/1.0")
+        self.assertStatus(200)
+        self.assertBody("(['%s/'], 302)" % self.base())
+        if cherrypy.server.protocol_version == "HTTP/1.1":
+            self.getPage("/redirect/stringify", protocol="HTTP/1.1")
+            self.assertStatus(200)
+            self.assertBody("(['%s/'], 303)" % self.base())
+        
+        # check that #fragments are handled properly
+        # http://skrb.org/ietf/http_errata.html#location-fragments
+        frag = "foo"
+        self.getPage("/redirect/fragment/%s" % frag)
+        self.assertMatchesBody(r"\1\/some\/url\#%s" % (frag, frag))
+        loc = self.assertHeader('Location')
+        assert loc.endswith("#%s" % frag)
+        self.assertStatus(('302 Found', '303 See Other'))
+        
+        # check injection protection
+        # See http://www.cherrypy.org/ticket/1003
+        self.getPage("/redirect/custom?code=303&url=/foobar/%0d%0aSet-Cookie:%20somecookie=someval")
+        self.assertStatus(303)
+        loc = self.assertHeader('Location')
+        assert 'Set-Cookie' in loc
+        self.assertNoHeader('Set-Cookie')
+    
+    def test_InternalRedirect(self):
+        # InternalRedirect
+        self.getPage("/internalredirect/")
+        self.assertBody('hello')
+        self.assertStatus(200)
+        
+        # Test passthrough
+        self.getPage("/internalredirect/petshop?user_id=Sir-not-appearing-in-this-film")
+        self.assertBody('0 images for Sir-not-appearing-in-this-film')
+        self.assertStatus(200)
+        
+        # Test args
+        self.getPage("/internalredirect/petshop?user_id=parrot")
+        self.assertBody('0 images for slug')
+        self.assertStatus(200)
+        
+        # Test POST
+        self.getPage("/internalredirect/petshop", method="POST",
+                     body="user_id=terrier")
+        self.assertBody('0 images for fish')
+        self.assertStatus(200)
+        
+        # Test ir before body read
+        self.getPage("/internalredirect/early_ir", method="POST",
+                     body="arg=aha!")
+        self.assertBody("Something went horribly wrong.")
+        self.assertStatus(200)
+        
+        self.getPage("/internalredirect/secure")
+        self.assertBody('Please log in')
+        self.assertStatus(200)
+        
+        # Relative path in InternalRedirect.
+        # Also tests request.prev.
+        self.getPage("/internalredirect/relative?a=3&b=5")
+        self.assertBody("a=3&b=5")
+        self.assertStatus(200)
+        
+        # InternalRedirect on error
+        self.getPage("/internalredirect/choke")
+        self.assertStatus(200)
+        self.assertBody("Something went horribly wrong.")
+    
+    def testFlatten(self):
+        for url in ["/flatten/as_string", "/flatten/as_list",
+                    "/flatten/as_yield", "/flatten/as_dblyield",
+                    "/flatten/as_refyield"]:
+            self.getPage(url)
+            self.assertBody('content')
+    
+    def testRanges(self):
+        self.getPage("/ranges/get_ranges?bytes=3-6")
+        self.assertBody("[(3, 7)]")
+        
+        # Test multiple ranges and a suffix-byte-range-spec, for good measure.
+        self.getPage("/ranges/get_ranges?bytes=2-4,-1")
+        self.assertBody("[(2, 5), (7, 8)]")
+        
+        # Get a partial file.
+        if cherrypy.server.protocol_version == "HTTP/1.1":
+            self.getPage("/ranges/slice_file", [('Range', 'bytes=2-5')])
+            self.assertStatus(206)
+            self.assertHeader("Content-Type", "text/html;charset=utf-8")
+            self.assertHeader("Content-Range", "bytes 2-5/14")
+            self.assertBody("llo,")
+            
+            # What happens with overlapping ranges (and out of order, too)?
+            self.getPage("/ranges/slice_file", [('Range', 'bytes=4-6,2-5')])
+            self.assertStatus(206)
+            ct = self.assertHeader("Content-Type")
+            expected_type = "multipart/byteranges; boundary="
+            self.assert_(ct.startswith(expected_type))
+            boundary = ct[len(expected_type):]
+            expected_body = ("\r\n--%s\r\n"
+                             "Content-type: text/html\r\n"
+                             "Content-range: bytes 4-6/14\r\n"
+                             "\r\n"
+                             "o, \r\n"
+                             "--%s\r\n"
+                             "Content-type: text/html\r\n"
+                             "Content-range: bytes 2-5/14\r\n"
+                             "\r\n"
+                             "llo,\r\n"
+                             "--%s--\r\n" % (boundary, boundary, boundary))
+            self.assertBody(expected_body)
+            self.assertHeader("Content-Length")
+            
+            # Test "416 Requested Range Not Satisfiable"
+            self.getPage("/ranges/slice_file", [('Range', 'bytes=2300-2900')])
+            self.assertStatus(416)
+            # "When this status code is returned for a byte-range request,
+            # the response SHOULD include a Content-Range entity-header
+            # field specifying the current length of the selected resource"
+            self.assertHeader("Content-Range", "bytes */14")
+        elif cherrypy.server.protocol_version == "HTTP/1.0":
+            # Test Range behavior with HTTP/1.0 request
+            self.getPage("/ranges/slice_file", [('Range', 'bytes=2-5')])
+            self.assertStatus(200)
+            self.assertBody("Hello, world\r\n")
+    
+    def testFavicon(self):
+        # favicon.ico is served by staticfile.
+        icofilename = os.path.join(localDir, "../favicon.ico")
+        icofile = open(icofilename, "rb")
+        data = icofile.read()
+        icofile.close()
+        
+        self.getPage("/favicon.ico")
+        self.assertBody(data)
+    
+    def testCookies(self):
+        if sys.version_info >= (2, 5):
+            header_value = lambda x: x
+        else:
+            header_value = lambda x: x+';'
+        
+        self.getPage("/cookies/single?name=First",
+                     [('Cookie', 'First=Dinsdale;')])
+        self.assertHeader('Set-Cookie', header_value('First=Dinsdale'))
+        
+        self.getPage("/cookies/multiple?names=First&names=Last",
+                     [('Cookie', 'First=Dinsdale; Last=Piranha;'),
+                      ])
+        self.assertHeader('Set-Cookie', header_value('First=Dinsdale'))
+        self.assertHeader('Set-Cookie', header_value('Last=Piranha'))
+        
+        self.getPage("/cookies/single?name=Something-With:Colon",
+            [('Cookie', 'Something-With:Colon=some-value')])
+        self.assertStatus(400)
+    
+    def testDefaultContentType(self):
+        self.getPage('/')
+        self.assertHeader('Content-Type', 'text/html;charset=utf-8')
+        self.getPage('/defct/plain')
+        self.getPage('/')
+        self.assertHeader('Content-Type', 'text/plain;charset=utf-8')
+        self.getPage('/defct/html')
+    
+    def test_cherrypy_url(self):
+        # Input relative to current
+        self.getPage('/url/leaf?path_info=page1')
+        self.assertBody('%s/url/page1' % self.base())
+        self.getPage('/url/?path_info=page1')
+        self.assertBody('%s/url/page1' % self.base())
+        # Other host header
+        host = 'www.mydomain.example'
+        self.getPage('/url/leaf?path_info=page1',
+                     headers=[('Host', host)])
+        self.assertBody('%s://%s/url/page1' % (self.scheme, host))
+        
+        # Input is 'absolute'; that is, relative to script_name
+        self.getPage('/url/leaf?path_info=/page1')
+        self.assertBody('%s/page1' % self.base())
+        self.getPage('/url/?path_info=/page1')
+        self.assertBody('%s/page1' % self.base())
+        
+        # Single dots
+        self.getPage('/url/leaf?path_info=./page1')
+        self.assertBody('%s/url/page1' % self.base())
+        self.getPage('/url/leaf?path_info=other/./page1')
+        self.assertBody('%s/url/other/page1' % self.base())
+        self.getPage('/url/?path_info=/other/./page1')
+        self.assertBody('%s/other/page1' % self.base())
+        
+        # Double dots
+        self.getPage('/url/leaf?path_info=../page1')
+        self.assertBody('%s/page1' % self.base())
+        self.getPage('/url/leaf?path_info=other/../page1')
+        self.assertBody('%s/url/page1' % self.base())
+        self.getPage('/url/leaf?path_info=/other/../page1')
+        self.assertBody('%s/page1' % self.base())
+        
+        # Output relative to current path or script_name
+        self.getPage('/url/?path_info=page1&relative=True')
+        self.assertBody('page1')
+        self.getPage('/url/leaf?path_info=/page1&relative=True')
+        self.assertBody('../page1')
+        self.getPage('/url/leaf?path_info=page1&relative=True')
+        self.assertBody('page1')
+        self.getPage('/url/leaf?path_info=leaf/page1&relative=True')
+        self.assertBody('leaf/page1')
+        self.getPage('/url/leaf?path_info=../page1&relative=True')
+        self.assertBody('../page1')
+        self.getPage('/url/?path_info=other/../page1&relative=True')
+        self.assertBody('page1')
+        
+        # Output relative to /
+        self.getPage('/baseurl?path_info=ab&relative=True')
+        self.assertBody('ab')
+        # Output relative to /
+        self.getPage('/baseurl?path_info=/ab&relative=True')
+        self.assertBody('ab')
+        
+        # absolute-path references ("server-relative")
+        # Input relative to current
+        self.getPage('/url/leaf?path_info=page1&relative=server')
+        self.assertBody('/url/page1')
+        self.getPage('/url/?path_info=page1&relative=server')
+        self.assertBody('/url/page1')
+        # Input is 'absolute'; that is, relative to script_name
+        self.getPage('/url/leaf?path_info=/page1&relative=server')
+        self.assertBody('/page1')
+        self.getPage('/url/?path_info=/page1&relative=server')
+        self.assertBody('/page1')
+    
+    def test_expose_decorator(self):
+        if not sys.version_info >= (2, 5):
+            return self.skip("skipped (Python 2.5+ only) ")
+        
+        # Test @expose
+        self.getPage("/expose_dec/no_call")
+        self.assertStatus(200)
+        self.assertBody("Mr E. R. Bradshaw")
+        
+        # Test @expose()
+        self.getPage("/expose_dec/call_empty")
+        self.assertStatus(200)
+        self.assertBody("Mrs. B.J. Smegma")
+        
+        # Test @expose("alias")
+        self.getPage("/expose_dec/call_alias")
+        self.assertStatus(200)
+        self.assertBody("Mr Nesbitt")
+        # Does the original name work?
+        self.getPage("/expose_dec/nesbitt")
+        self.assertStatus(200)
+        self.assertBody("Mr Nesbitt")
+        
+        # Test @expose(["alias1", "alias2"])
+        self.getPage("/expose_dec/alias1")
+        self.assertStatus(200)
+        self.assertBody("Mr Ken Andrews")
+        self.getPage("/expose_dec/alias2")
+        self.assertStatus(200)
+        self.assertBody("Mr Ken Andrews")
+        # Does the original name work?
+        self.getPage("/expose_dec/andrews")
+        self.assertStatus(200)
+        self.assertBody("Mr Ken Andrews")
+        
+        # Test @expose(alias="alias")
+        self.getPage("/expose_dec/alias3")
+        self.assertStatus(200)
+        self.assertBody("Mr. and Mrs. Watson")
+
diff --git a/cherrypy/test/test_dynamicobjectmapping.py b/cherrypy/test/test_dynamicobjectmapping.py
new file mode 100644
index 00000000..1e04d089
--- /dev/null
+++ b/cherrypy/test/test_dynamicobjectmapping.py
@@ -0,0 +1,403 @@
+import cherrypy
+from cherrypy._cptree import Application
+from cherrypy.test import helper
+
+script_names = ["", "/foo", "/users/fred/blog", "/corp/blog"]
+
+
+
+def setup_server():
+    class SubSubRoot:
+        def index(self):
+            return "SubSubRoot index"
+        index.exposed = True
+
+        def default(self, *args):
+            return "SubSubRoot default"
+        default.exposed = True
+
+        def handler(self):
+            return "SubSubRoot handler"
+        handler.exposed = True
+
+        def dispatch(self):
+            return "SubSubRoot dispatch"
+        dispatch.exposed = True
+
+    subsubnodes = {
+        '1': SubSubRoot(),
+        '2': SubSubRoot(),
+    }
+
+    class SubRoot:
+        def index(self):
+            return "SubRoot index"
+        index.exposed = True
+
+        def default(self, *args):
+            return "SubRoot %s" % (args,)
+        default.exposed = True
+
+        def handler(self):
+            return "SubRoot handler"
+        handler.exposed = True
+
+        def _cp_dispatch(self, vpath):
+            return subsubnodes.get(vpath[0], None)
+
+    subnodes = {
+        '1': SubRoot(),
+        '2': SubRoot(),
+    }
+    class Root:
+        def index(self):
+            return "index"
+        index.exposed = True
+
+        def default(self, *args):
+            return "default %s" % (args,)
+        default.exposed = True
+
+        def handler(self):
+            return "handler"
+        handler.exposed = True
+
+        def _cp_dispatch(self, vpath):
+            return subnodes.get(vpath[0])
+
+    #--------------------------------------------------------------------------
+    # DynamicNodeAndMethodDispatcher example.
+    # This example exposes a fairly naive HTTP api
+    class User(object):
+        def __init__(self, id, name):
+            self.id = id
+            self.name = name
+
+        def __unicode__(self):
+            return unicode(self.name)
+
+    user_lookup = {
+        1: User(1, 'foo'),
+        2: User(2, 'bar'),
+    }
+
+    def make_user(name, id=None):
+        if not id:
+            id = max(*user_lookup.keys()) + 1
+        user_lookup[id] = User(id, name)
+        return id
+
+    class UserContainerNode(object):
+        exposed = True
+
+        def POST(self, name):
+            """
+            Allow the creation of a new Object
+            """
+            return "POST %d" % make_user(name)
+
+        def GET(self):
+            keys = user_lookup.keys()
+            keys.sort()
+            return unicode(keys)
+
+        def dynamic_dispatch(self, vpath):
+            try:
+                id = int(vpath[0])
+            except (ValueError, IndexError):
+                return None
+            return UserInstanceNode(id)
+
+    class UserInstanceNode(object):
+        exposed = True
+        def __init__(self, id):
+            self.id = id
+            self.user = user_lookup.get(id, None)
+
+            # For all but PUT methods there MUST be a valid user identified
+            # by self.id
+            if not self.user and cherrypy.request.method != 'PUT':
+                raise cherrypy.HTTPError(404)
+
+        def GET(self, *args, **kwargs):
+            """
+            Return the appropriate representation of the instance.
+            """
+            return unicode(self.user)
+
+        def POST(self, name):
+            """
+            Update the fields of the user instance.
+            """
+            self.user.name = name
+            return "POST %d" % self.user.id
+
+        def PUT(self, name):
+            """
+            Create a new user with the specified id, or edit it if it already exists
+            """
+            if self.user:
+                # Edit the current user
+                self.user.name = name
+                return "PUT %d" % self.user.id
+            else:
+                # Make a new user with said attributes.
+                return "PUT %d" % make_user(name, self.id)
+
+        def DELETE(self):
+            """
+            Delete the user specified at the id.
+            """
+            id = self.user.id
+            del user_lookup[self.user.id]
+            del self.user
+            return "DELETE %d" % id
+
+    
+    class ABHandler:
+        class CustomDispatch:
+            def index(self, a, b):
+                return "custom"
+            index.exposed = True
+                
+        def _cp_dispatch(self, vpath):
+            """Make sure that if we don't pop anything from vpath,
+            processing still works.
+            """
+            return self.CustomDispatch()
+        
+        def index(self, a, b=None):
+            body = [ 'a:' + str(a) ]
+            if b is not None:
+                body.append(',b:' + str(b))
+            return ''.join(body)
+        index.exposed = True
+            
+        def delete(self, a, b):
+            return 'deleting ' + str(a) + ' and ' + str(b)
+        delete.exposed = True
+            
+    class IndexOnly:
+        def _cp_dispatch(self, vpath):
+            """Make sure that popping ALL of vpath still shows the index 
+            handler.
+            """
+            while vpath:
+                vpath.pop()
+            return self
+            
+        def index(self):
+            return "IndexOnly index"
+        index.exposed = True
+    
+    class DecoratedPopArgs:
+        """Test _cp_dispatch with @cherrypy.popargs."""
+        def index(self):
+            return "no params"
+        index.exposed = True
+        
+        def hi(self):
+            return "hi was not interpreted as 'a' param"
+        hi.exposed = True
+    DecoratedPopArgs = cherrypy.popargs('a', 'b', handler=ABHandler())(DecoratedPopArgs)
+            
+    class NonDecoratedPopArgs:
+        """Test _cp_dispatch = cherrypy.popargs()"""
+        
+        _cp_dispatch = cherrypy.popargs('a')
+        
+        def index(self, a):
+            return "index: " + str(a)
+        index.exposed = True
+            
+    class ParameterizedHandler:
+        """Special handler created for each request"""
+        
+        def __init__(self, a):
+            self.a = a
+            
+        def index(self):
+            if 'a' in cherrypy.request.params:
+                raise Exception("Parameterized handler argument ended up in request.params")
+            return self.a
+        index.exposed = True
+            
+    class ParameterizedPopArgs:
+        """Test cherrypy.popargs() with a function call handler"""
+    ParameterizedPopArgs = cherrypy.popargs('a', handler=ParameterizedHandler)(ParameterizedPopArgs)
+            
+    Root.decorated = DecoratedPopArgs()
+    Root.undecorated = NonDecoratedPopArgs()
+    Root.index_only = IndexOnly()
+    Root.parameter_test = ParameterizedPopArgs()
+
+    Root.users = UserContainerNode()
+
+    md = cherrypy.dispatch.MethodDispatcher('dynamic_dispatch')
+    for url in script_names:
+        conf = {'/': {
+                    'user': (url or "/").split("/")[-2],
+                },
+                '/users': {
+                    'request.dispatch': md
+                },
+            }
+        cherrypy.tree.mount(Root(), url, conf)
+
+class DynamicObjectMappingTest(helper.CPWebCase):
+    setup_server = staticmethod(setup_server)
+
+    def testObjectMapping(self):
+        for url in script_names:
+            prefix = self.script_name = url
+
+            self.getPage('/')
+            self.assertBody('index')
+
+            self.getPage('/handler')
+            self.assertBody('handler')
+
+            # Dynamic dispatch will succeed here for the subnodes
+            # so the subroot gets called
+            self.getPage('/1/')
+            self.assertBody('SubRoot index')
+
+            self.getPage('/2/')
+            self.assertBody('SubRoot index')
+
+            self.getPage('/1/handler')
+            self.assertBody('SubRoot handler')
+
+            self.getPage('/2/handler')
+            self.assertBody('SubRoot handler')
+
+            # Dynamic dispatch will fail here for the subnodes
+            # so the default gets called
+            self.getPage('/asdf/')
+            self.assertBody("default ('asdf',)")
+
+            self.getPage('/asdf/asdf')
+            self.assertBody("default ('asdf', 'asdf')")
+
+            self.getPage('/asdf/handler')
+            self.assertBody("default ('asdf', 'handler')")
+
+            # Dynamic dispatch will succeed here for the subsubnodes
+            # so the subsubroot gets called
+            self.getPage('/1/1/')
+            self.assertBody('SubSubRoot index')
+
+            self.getPage('/2/2/')
+            self.assertBody('SubSubRoot index')
+
+            self.getPage('/1/1/handler')
+            self.assertBody('SubSubRoot handler')
+
+            self.getPage('/2/2/handler')
+            self.assertBody('SubSubRoot handler')
+
+            self.getPage('/2/2/dispatch')
+            self.assertBody('SubSubRoot dispatch')
+
+            # The exposed dispatch will not be called as a dispatch
+            # method.
+            self.getPage('/2/2/foo/foo')
+            self.assertBody("SubSubRoot default")
+
+            # Dynamic dispatch will fail here for the subsubnodes
+            # so the SubRoot gets called
+            self.getPage('/1/asdf/')
+            self.assertBody("SubRoot ('asdf',)")
+
+            self.getPage('/1/asdf/asdf')
+            self.assertBody("SubRoot ('asdf', 'asdf')")
+
+            self.getPage('/1/asdf/handler')
+            self.assertBody("SubRoot ('asdf', 'handler')")
+
+    def testMethodDispatch(self):
+        # GET acts like a container
+        self.getPage("/users")
+        self.assertBody("[1, 2]")
+        self.assertHeader('Allow', 'GET, HEAD, POST')
+
+        # POST to the container URI allows creation
+        self.getPage("/users", method="POST", body="name=baz")
+        self.assertBody("POST 3")
+        self.assertHeader('Allow', 'GET, HEAD, POST')
+
+        # POST to a specific instanct URI results in a 404
+        # as the resource does not exit.
+        self.getPage("/users/5", method="POST", body="name=baz")
+        self.assertStatus(404)
+
+        # PUT to a specific instanct URI results in creation
+        self.getPage("/users/5", method="PUT", body="name=boris")
+        self.assertBody("PUT 5")
+        self.assertHeader('Allow', 'DELETE, GET, HEAD, POST, PUT')
+
+        # GET acts like a container
+        self.getPage("/users")
+        self.assertBody("[1, 2, 3, 5]")
+        self.assertHeader('Allow', 'GET, HEAD, POST')
+
+        test_cases = (
+            (1, 'foo', 'fooupdated', 'DELETE, GET, HEAD, POST, PUT'),
+            (2, 'bar', 'barupdated', 'DELETE, GET, HEAD, POST, PUT'),
+            (3, 'baz', 'bazupdated', 'DELETE, GET, HEAD, POST, PUT'),
+            (5, 'boris', 'borisupdated', 'DELETE, GET, HEAD, POST, PUT'),
+        )
+        for id, name, updatedname, headers in test_cases:
+            self.getPage("/users/%d" % id)
+            self.assertBody(name)
+            self.assertHeader('Allow', headers)
+
+            # Make sure POSTs update already existings resources
+            self.getPage("/users/%d" % id, method='POST', body="name=%s" % updatedname)
+            self.assertBody("POST %d" % id)
+            self.assertHeader('Allow', headers)
+
+            # Make sure PUTs Update already existing resources.
+            self.getPage("/users/%d" % id, method='PUT', body="name=%s" % updatedname)
+            self.assertBody("PUT %d" % id)
+            self.assertHeader('Allow', headers)
+
+            # Make sure DELETES Remove already existing resources.
+            self.getPage("/users/%d" % id, method='DELETE')
+            self.assertBody("DELETE %d" % id)
+            self.assertHeader('Allow', headers)
+
+
+        # GET acts like a container
+        self.getPage("/users")
+        self.assertBody("[]")
+        self.assertHeader('Allow', 'GET, HEAD, POST')
+        
+    def testVpathDispatch(self):
+        self.getPage("/decorated/")
+        self.assertBody("no params")
+        
+        self.getPage("/decorated/hi")
+        self.assertBody("hi was not interpreted as 'a' param")
+        
+        self.getPage("/decorated/yo/")
+        self.assertBody("a:yo")
+        
+        self.getPage("/decorated/yo/there/")
+        self.assertBody("a:yo,b:there")
+        
+        self.getPage("/decorated/yo/there/delete")
+        self.assertBody("deleting yo and there")
+        
+        self.getPage("/decorated/yo/there/handled_by_dispatch/")
+        self.assertBody("custom")
+        
+        self.getPage("/undecorated/blah/")
+        self.assertBody("index: blah")
+        
+        self.getPage("/index_only/a/b/c/d/e/f/g/")
+        self.assertBody("IndexOnly index")
+        
+        self.getPage("/parameter_test/argument2/")
+        self.assertBody("argument2")
+
diff --git a/cherrypy/test/test_encoding.py b/cherrypy/test/test_encoding.py
new file mode 100644
index 00000000..67b28ede
--- /dev/null
+++ b/cherrypy/test/test_encoding.py
@@ -0,0 +1,363 @@
+
+import gzip
+import sys
+
+import cherrypy
+from cherrypy._cpcompat import BytesIO, IncompleteRead, ntob, ntou
+
+europoundUnicode = ntou('\x80\xa3')
+sing = u"\u6bdb\u6cfd\u4e1c: Sing, Little Birdie?"
+sing8 = sing.encode('utf-8')
+sing16 = sing.encode('utf-16')
+
+
+from cherrypy.test import helper
+
+
+class EncodingTests(helper.CPWebCase):
+
+    def setup_server():
+        class Root:
+            def index(self, param):
+                assert param == europoundUnicode, "%r != %r" % (param, europoundUnicode)
+                yield europoundUnicode
+            index.exposed = True
+            
+            def mao_zedong(self):
+                return sing
+            mao_zedong.exposed = True
+            
+            def utf8(self):
+                return sing8
+            utf8.exposed = True
+            utf8._cp_config = {'tools.encode.encoding': 'utf-8'}
+            
+            def cookies_and_headers(self):
+                # if the headers have non-ascii characters and a cookie has
+                #  any part which is unicode (even ascii), the response
+                #  should not fail.
+                cherrypy.response.cookie['candy'] = 'bar'
+                cherrypy.response.cookie['candy']['domain'] = 'cherrypy.org'
+                cherrypy.response.headers['Some-Header'] = 'My d\xc3\xb6g has fleas'
+                return 'Any content'
+            cookies_and_headers.exposed = True
+
+            def reqparams(self, *args, **kwargs):
+                return ntob(', ').join([": ".join((k, v)).encode('utf8')
+                                  for k, v in cherrypy.request.params.items()])
+            reqparams.exposed = True
+            
+            def nontext(self, *args, **kwargs):
+                cherrypy.response.headers['Content-Type'] = 'application/binary'
+                return '\x00\x01\x02\x03'
+            nontext.exposed = True
+            nontext._cp_config = {'tools.encode.text_only': False,
+                                  'tools.encode.add_charset': True,
+                                  }
+        
+        class GZIP:
+            def index(self):
+                yield "Hello, world"
+            index.exposed = True
+            
+            def noshow(self):
+                # Test for ticket #147, where yield showed no exceptions (content-
+                # encoding was still gzip even though traceback wasn't zipped).
+                raise IndexError()
+                yield "Here be dragons"
+            noshow.exposed = True
+            # Turn encoding off so the gzip tool is the one doing the collapse.
+            noshow._cp_config = {'tools.encode.on': False}
+            
+            def noshow_stream(self):
+                # Test for ticket #147, where yield showed no exceptions (content-
+                # encoding was still gzip even though traceback wasn't zipped).
+                raise IndexError()
+                yield "Here be dragons"
+            noshow_stream.exposed = True
+            noshow_stream._cp_config = {'response.stream': True}
+        
+        class Decode:
+            def extra_charset(self, *args, **kwargs):
+                return ', '.join([": ".join((k, v))
+                                  for k, v in cherrypy.request.params.items()])
+            extra_charset.exposed = True
+            extra_charset._cp_config = {
+                'tools.decode.on': True,
+                'tools.decode.default_encoding': ['utf-16'],
+                }
+            
+            def force_charset(self, *args, **kwargs):
+                return ', '.join([": ".join((k, v))
+                                  for k, v in cherrypy.request.params.items()])
+            force_charset.exposed = True
+            force_charset._cp_config = {
+                'tools.decode.on': True,
+                'tools.decode.encoding': 'utf-16',
+                }
+        
+        root = Root()
+        root.gzip = GZIP()
+        root.decode = Decode()
+        cherrypy.tree.mount(root, config={'/gzip': {'tools.gzip.on': True}})
+    setup_server = staticmethod(setup_server)
+
+    def test_query_string_decoding(self):
+        europoundUtf8 = europoundUnicode.encode('utf-8')
+        self.getPage(ntob('/?param=') + europoundUtf8)
+        self.assertBody(europoundUtf8)
+        
+        # Encoded utf8 query strings MUST be parsed correctly.
+        # Here, q is the POUND SIGN U+00A3 encoded in utf8 and then %HEX
+        self.getPage("/reqparams?q=%C2%A3")
+        # The return value will be encoded as utf8.
+        self.assertBody(ntob("q: \xc2\xa3"))
+        
+        # Query strings that are incorrectly encoded MUST raise 404.
+        # Here, q is the POUND SIGN U+00A3 encoded in latin1 and then %HEX
+        self.getPage("/reqparams?q=%A3")
+        self.assertStatus(404)
+        self.assertErrorPage(404, 
+            "The given query string could not be processed. Query "
+            "strings for this resource must be encoded with 'utf8'.")
+    
+    def test_urlencoded_decoding(self):
+        # Test the decoding of an application/x-www-form-urlencoded entity.
+        europoundUtf8 = europoundUnicode.encode('utf-8')
+        body=ntob("param=") + europoundUtf8
+        self.getPage('/', method='POST',
+                     headers=[("Content-Type", "application/x-www-form-urlencoded"),
+                              ("Content-Length", str(len(body))),
+                              ],
+                     body=body),
+        self.assertBody(europoundUtf8)
+        
+        # Encoded utf8 entities MUST be parsed and decoded correctly.
+        # Here, q is the POUND SIGN U+00A3 encoded in utf8
+        body = ntob("q=\xc2\xa3")
+        self.getPage('/reqparams', method='POST',
+                     headers=[("Content-Type", "application/x-www-form-urlencoded"),
+                              ("Content-Length", str(len(body))),
+                              ],
+                     body=body),
+        self.assertBody(ntob("q: \xc2\xa3"))
+        
+        # ...and in utf16, which is not in the default attempt_charsets list:
+        body = ntob("\xff\xfeq\x00=\xff\xfe\xa3\x00")
+        self.getPage('/reqparams', method='POST',
+                     headers=[("Content-Type", "application/x-www-form-urlencoded;charset=utf-16"),
+                              ("Content-Length", str(len(body))),
+                              ],
+                     body=body),
+        self.assertBody(ntob("q: \xc2\xa3"))
+        
+        # Entities that are incorrectly encoded MUST raise 400.
+        # Here, q is the POUND SIGN U+00A3 encoded in utf16, but
+        # the Content-Type incorrectly labels it utf-8.
+        body = ntob("\xff\xfeq\x00=\xff\xfe\xa3\x00")
+        self.getPage('/reqparams', method='POST',
+                     headers=[("Content-Type", "application/x-www-form-urlencoded;charset=utf-8"),
+                              ("Content-Length", str(len(body))),
+                              ],
+                     body=body),
+        self.assertStatus(400)
+        self.assertErrorPage(400, 
+            "The request entity could not be decoded. The following charsets "
+            "were attempted: ['utf-8']")
+    
+    def test_decode_tool(self):
+        # An extra charset should be tried first, and succeed if it matches.
+        # Here, we add utf-16 as a charset and pass a utf-16 body.
+        body = ntob("\xff\xfeq\x00=\xff\xfe\xa3\x00")
+        self.getPage('/decode/extra_charset', method='POST',
+                     headers=[("Content-Type", "application/x-www-form-urlencoded"),
+                              ("Content-Length", str(len(body))),
+                              ],
+                     body=body),
+        self.assertBody(ntob("q: \xc2\xa3"))
+        
+        # An extra charset should be tried first, and continue to other default
+        # charsets if it doesn't match.
+        # Here, we add utf-16 as a charset but still pass a utf-8 body.
+        body = ntob("q=\xc2\xa3")
+        self.getPage('/decode/extra_charset', method='POST',
+                     headers=[("Content-Type", "application/x-www-form-urlencoded"),
+                              ("Content-Length", str(len(body))),
+                              ],
+                     body=body),
+        self.assertBody(ntob("q: \xc2\xa3"))
+        
+        # An extra charset should error if force is True and it doesn't match.
+        # Here, we force utf-16 as a charset but still pass a utf-8 body.
+        body = ntob("q=\xc2\xa3")
+        self.getPage('/decode/force_charset', method='POST',
+                     headers=[("Content-Type", "application/x-www-form-urlencoded"),
+                              ("Content-Length", str(len(body))),
+                              ],
+                     body=body),
+        self.assertErrorPage(400, 
+            "The request entity could not be decoded. The following charsets "
+            "were attempted: ['utf-16']")
+    
+    def test_multipart_decoding(self):
+        # Test the decoding of a multipart entity when the charset (utf16) is
+        # explicitly given.
+        body=ntob('\r\n'.join(['--X',
+                               'Content-Type: text/plain;charset=utf-16',
+                               'Content-Disposition: form-data; name="text"',
+                               '',
+                               '\xff\xfea\x00b\x00\x1c c\x00',
+                               '--X',
+                               'Content-Type: text/plain;charset=utf-16',
+                               'Content-Disposition: form-data; name="submit"',
+                               '',
+                               '\xff\xfeC\x00r\x00e\x00a\x00t\x00e\x00',
+                               '--X--']))
+        self.getPage('/reqparams', method='POST',
+                     headers=[("Content-Type", "multipart/form-data;boundary=X"),
+                              ("Content-Length", str(len(body))),
+                              ],
+                     body=body),
+        self.assertBody(ntob("text: ab\xe2\x80\x9cc, submit: Create"))
+    
+    def test_multipart_decoding_no_charset(self):
+        # Test the decoding of a multipart entity when the charset (utf8) is
+        # NOT explicitly given, but is in the list of charsets to attempt.
+        body=ntob('\r\n'.join(['--X',
+                               'Content-Disposition: form-data; name="text"',
+                               '',
+                               '\xe2\x80\x9c',
+                               '--X',
+                               'Content-Disposition: form-data; name="submit"',
+                               '',
+                               'Create',
+                               '--X--']))
+        self.getPage('/reqparams', method='POST',
+                     headers=[("Content-Type", "multipart/form-data;boundary=X"),
+                              ("Content-Length", str(len(body))),
+                              ],
+                     body=body),
+        self.assertBody(ntob("text: \xe2\x80\x9c, submit: Create"))
+    
+    def test_multipart_decoding_no_successful_charset(self):
+        # Test the decoding of a multipart entity when the charset (utf16) is
+        # NOT explicitly given, and is NOT in the list of charsets to attempt.
+        body=ntob('\r\n'.join(['--X',
+                               'Content-Disposition: form-data; name="text"',
+                               '',
+                               '\xff\xfea\x00b\x00\x1c c\x00',
+                               '--X',
+                               'Content-Disposition: form-data; name="submit"',
+                               '',
+                               '\xff\xfeC\x00r\x00e\x00a\x00t\x00e\x00',
+                               '--X--']))
+        self.getPage('/reqparams', method='POST',
+                     headers=[("Content-Type", "multipart/form-data;boundary=X"),
+                              ("Content-Length", str(len(body))),
+                              ],
+                     body=body),
+        self.assertStatus(400)
+        self.assertErrorPage(400, 
+            "The request entity could not be decoded. The following charsets "
+            "were attempted: ['us-ascii', 'utf-8']")
+    
+    def test_nontext(self):
+        self.getPage('/nontext')
+        self.assertHeader('Content-Type', 'application/binary;charset=utf-8')
+        self.assertBody('\x00\x01\x02\x03')
+    
+    def testEncoding(self):
+        # Default encoding should be utf-8
+        self.getPage('/mao_zedong')
+        self.assertBody(sing8)
+        
+        # Ask for utf-16.
+        self.getPage('/mao_zedong', [('Accept-Charset', 'utf-16')])
+        self.assertHeader('Content-Type', 'text/html;charset=utf-16')
+        self.assertBody(sing16)
+        
+        # Ask for multiple encodings. ISO-8859-1 should fail, and utf-16
+        # should be produced.
+        self.getPage('/mao_zedong', [('Accept-Charset',
+                                      'iso-8859-1;q=1, utf-16;q=0.5')])
+        self.assertBody(sing16)
+        
+        # The "*" value should default to our default_encoding, utf-8
+        self.getPage('/mao_zedong', [('Accept-Charset', '*;q=1, utf-7;q=.2')])
+        self.assertBody(sing8)
+        
+        # Only allow iso-8859-1, which should fail and raise 406.
+        self.getPage('/mao_zedong', [('Accept-Charset', 'iso-8859-1, *;q=0')])
+        self.assertStatus("406 Not Acceptable")
+        self.assertInBody("Your client sent this Accept-Charset header: "
+                          "iso-8859-1, *;q=0. We tried these charsets: "
+                          "iso-8859-1.")
+        
+        # Ask for x-mac-ce, which should be unknown. See ticket #569.
+        self.getPage('/mao_zedong', [('Accept-Charset',
+                                      'us-ascii, ISO-8859-1, x-mac-ce')])
+        self.assertStatus("406 Not Acceptable")
+        self.assertInBody("Your client sent this Accept-Charset header: "
+                          "us-ascii, ISO-8859-1, x-mac-ce. We tried these "
+                          "charsets: ISO-8859-1, us-ascii, x-mac-ce.")
+        
+        # Test the 'encoding' arg to encode.
+        self.getPage('/utf8')
+        self.assertBody(sing8)
+        self.getPage('/utf8', [('Accept-Charset', 'us-ascii, ISO-8859-1')])
+        self.assertStatus("406 Not Acceptable")
+    
+    def testGzip(self):
+        zbuf = BytesIO()
+        zfile = gzip.GzipFile(mode='wb', fileobj=zbuf, compresslevel=9)
+        zfile.write(ntob("Hello, world"))
+        zfile.close()
+        
+        self.getPage('/gzip/', headers=[("Accept-Encoding", "gzip")])
+        self.assertInBody(zbuf.getvalue()[:3])
+        self.assertHeader("Vary", "Accept-Encoding")
+        self.assertHeader("Content-Encoding", "gzip")
+        
+        # Test when gzip is denied.
+        self.getPage('/gzip/', headers=[("Accept-Encoding", "identity")])
+        self.assertHeader("Vary", "Accept-Encoding")
+        self.assertNoHeader("Content-Encoding")
+        self.assertBody("Hello, world")
+        
+        self.getPage('/gzip/', headers=[("Accept-Encoding", "gzip;q=0")])
+        self.assertHeader("Vary", "Accept-Encoding")
+        self.assertNoHeader("Content-Encoding")
+        self.assertBody("Hello, world")
+        
+        self.getPage('/gzip/', headers=[("Accept-Encoding", "*;q=0")])
+        self.assertStatus(406)
+        self.assertNoHeader("Content-Encoding")
+        self.assertErrorPage(406, "identity, gzip")
+        
+        # Test for ticket #147
+        self.getPage('/gzip/noshow', headers=[("Accept-Encoding", "gzip")])
+        self.assertNoHeader('Content-Encoding')
+        self.assertStatus(500)
+        self.assertErrorPage(500, pattern="IndexError\n")
+        
+        # In this case, there's nothing we can do to deliver a
+        # readable page, since 1) the gzip header is already set,
+        # and 2) we may have already written some of the body.
+        # The fix is to never stream yields when using gzip.
+        if (cherrypy.server.protocol_version == "HTTP/1.0" or
+            getattr(cherrypy.server, "using_apache", False)):
+            self.getPage('/gzip/noshow_stream',
+                         headers=[("Accept-Encoding", "gzip")])
+            self.assertHeader('Content-Encoding', 'gzip')
+            self.assertInBody('\x1f\x8b\x08\x00')
+        else:
+            # The wsgiserver will simply stop sending data, and the HTTP client
+            # will error due to an incomplete chunk-encoded stream.
+            self.assertRaises((ValueError, IncompleteRead), self.getPage,
+                              '/gzip/noshow_stream',
+                              headers=[("Accept-Encoding", "gzip")])
+
+    def test_UnicodeHeaders(self):
+        self.getPage('/cookies_and_headers')
+        self.assertBody('Any content')
+
diff --git a/cherrypy/test/test_etags.py b/cherrypy/test/test_etags.py
new file mode 100644
index 00000000..026f9d65
--- /dev/null
+++ b/cherrypy/test/test_etags.py
@@ -0,0 +1,81 @@
+import cherrypy
+from cherrypy.test import helper
+
+
+class ETagTest(helper.CPWebCase):
+
+    def setup_server():
+        class Root:
+            def resource(self):
+                return "Oh wah ta goo Siam."
+            resource.exposed = True
+            
+            def fail(self, code):
+                code = int(code)
+                if 300 <= code <= 399:
+                    raise cherrypy.HTTPRedirect([], code)
+                else:
+                    raise cherrypy.HTTPError(code)
+            fail.exposed = True
+            
+            def unicoded(self):
+                return u'I am a \u1ee4nicode string.'
+            unicoded.exposed = True
+            unicoded._cp_config = {'tools.encode.on': True}
+
+        conf = {'/': {'tools.etags.on': True,
+                      'tools.etags.autotags': True,
+                      }}
+        cherrypy.tree.mount(Root(), config=conf)
+    setup_server = staticmethod(setup_server)
+    
+    def test_etags(self):
+        self.getPage("/resource")
+        self.assertStatus('200 OK')
+        self.assertHeader('Content-Type', 'text/html;charset=utf-8')
+        self.assertBody('Oh wah ta goo Siam.')
+        etag = self.assertHeader('ETag')
+        
+        # Test If-Match (both valid and invalid)
+        self.getPage("/resource", headers=[('If-Match', etag)])
+        self.assertStatus("200 OK")
+        self.getPage("/resource", headers=[('If-Match', "*")])
+        self.assertStatus("200 OK")
+        self.getPage("/resource", headers=[('If-Match', "*")], method="POST")
+        self.assertStatus("200 OK")
+        self.getPage("/resource", headers=[('If-Match', "a bogus tag")])
+        self.assertStatus("412 Precondition Failed")
+        
+        # Test If-None-Match (both valid and invalid)
+        self.getPage("/resource", headers=[('If-None-Match', etag)])
+        self.assertStatus(304)
+        self.getPage("/resource", method='POST', headers=[('If-None-Match', etag)])
+        self.assertStatus("412 Precondition Failed")
+        self.getPage("/resource", headers=[('If-None-Match', "*")])
+        self.assertStatus(304)
+        self.getPage("/resource", headers=[('If-None-Match', "a bogus tag")])
+        self.assertStatus("200 OK")
+    
+    def test_errors(self):
+        self.getPage("/resource")
+        self.assertStatus(200)
+        etag = self.assertHeader('ETag')
+        
+        # Test raising errors in page handler
+        self.getPage("/fail/412", headers=[('If-Match', etag)])
+        self.assertStatus(412)
+        self.getPage("/fail/304", headers=[('If-Match', etag)])
+        self.assertStatus(304)
+        self.getPage("/fail/412", headers=[('If-None-Match', "*")])
+        self.assertStatus(412)
+        self.getPage("/fail/304", headers=[('If-None-Match', "*")])
+        self.assertStatus(304)
+    
+    def test_unicode_body(self):
+        self.getPage("/unicoded")
+        self.assertStatus(200)
+        etag1 = self.assertHeader('ETag')
+        self.getPage("/unicoded", headers=[('If-Match', etag1)])
+        self.assertStatus(200)
+        self.assertHeader('ETag', etag1)
+
diff --git a/cherrypy/test/test_http.py b/cherrypy/test/test_http.py
new file mode 100644
index 00000000..eb72b5bf
--- /dev/null
+++ b/cherrypy/test/test_http.py
@@ -0,0 +1,168 @@
+"""Tests for managing HTTP issues (malformed requests, etc)."""
+
+import mimetypes
+
+import cherrypy
+from cherrypy._cpcompat import HTTPConnection, HTTPSConnection, ntob
+
+
+def encode_multipart_formdata(files):
+    """Return (content_type, body) ready for httplib.HTTP instance.
+    
+    files: a sequence of (name, filename, value) tuples for multipart uploads.
+    """
+    BOUNDARY = '________ThIs_Is_tHe_bouNdaRY_$'
+    L = []
+    for key, filename, value in files:
+        L.append('--' + BOUNDARY)
+        L.append('Content-Disposition: form-data; name="%s"; filename="%s"' %
+                 (key, filename))
+        ct = mimetypes.guess_type(filename)[0] or 'application/octet-stream'
+        L.append('Content-Type: %s' % ct)
+        L.append('')
+        L.append(value)
+    L.append('--' + BOUNDARY + '--')
+    L.append('')
+    body = '\r\n'.join(L)
+    content_type = 'multipart/form-data; boundary=%s' % BOUNDARY
+    return content_type, body
+
+
+
+
+from cherrypy.test import helper
+
+class HTTPTests(helper.CPWebCase):
+
+    def setup_server():
+        class Root:
+            def index(self, *args, **kwargs):
+                return "Hello world!"
+            index.exposed = True
+            
+            def no_body(self, *args, **kwargs):
+                return "Hello world!"
+            no_body.exposed = True
+            no_body._cp_config = {'request.process_request_body': False}
+            
+            def post_multipart(self, file):
+                """Return a summary ("a * 65536\nb * 65536") of the uploaded file."""
+                contents = file.file.read()
+                summary = []
+                curchar = ""
+                count = 0
+                for c in contents:
+                    if c == curchar:
+                        count += 1
+                    else:
+                        if count:
+                            summary.append("%s * %d" % (curchar, count))
+                        count = 1
+                        curchar = c
+                if count:
+                    summary.append("%s * %d" % (curchar, count))
+                return ", ".join(summary)
+            post_multipart.exposed = True
+        
+        cherrypy.tree.mount(Root())
+        cherrypy.config.update({'server.max_request_body_size': 30000000})
+    setup_server = staticmethod(setup_server)
+    
+    def test_no_content_length(self):
+        # "The presence of a message-body in a request is signaled by the
+        # inclusion of a Content-Length or Transfer-Encoding header field in
+        # the request's message-headers."
+        # 
+        # Send a message with neither header and no body. Even though
+        # the request is of method POST, this should be OK because we set
+        # request.process_request_body to False for our handler.
+        if self.scheme == "https":
+            c = HTTPSConnection('%s:%s' % (self.interface(), self.PORT))
+        else:
+            c = HTTPConnection('%s:%s' % (self.interface(), self.PORT))
+        c.request("POST", "/no_body")
+        response = c.getresponse()
+        self.body = response.fp.read()
+        self.status = str(response.status)
+        self.assertStatus(200)
+        self.assertBody(ntob('Hello world!'))
+        
+        # Now send a message that has no Content-Length, but does send a body.
+        # Verify that CP times out the socket and responds
+        # with 411 Length Required.
+        if self.scheme == "https":
+            c = HTTPSConnection('%s:%s' % (self.interface(), self.PORT))
+        else:
+            c = HTTPConnection('%s:%s' % (self.interface(), self.PORT))
+        c.request("POST", "/")
+        response = c.getresponse()
+        self.body = response.fp.read()
+        self.status = str(response.status)
+        self.assertStatus(411)
+    
+    def test_post_multipart(self):
+        alphabet = "abcdefghijklmnopqrstuvwxyz"
+        # generate file contents for a large post
+        contents = "".join([c * 65536 for c in alphabet])
+        
+        # encode as multipart form data
+        files=[('file', 'file.txt', contents)]
+        content_type, body = encode_multipart_formdata(files)
+        body = body.encode('Latin-1')
+        
+        # post file
+        if self.scheme == 'https':
+            c = HTTPSConnection('%s:%s' % (self.interface(), self.PORT))
+        else:
+            c = HTTPConnection('%s:%s' % (self.interface(), self.PORT))
+        c.putrequest('POST', '/post_multipart')
+        c.putheader('Content-Type', content_type)
+        c.putheader('Content-Length', str(len(body)))
+        c.endheaders()
+        c.send(body)
+        
+        response = c.getresponse()
+        self.body = response.fp.read()
+        self.status = str(response.status)
+        self.assertStatus(200)
+        self.assertBody(", ".join(["%s * 65536" % c for c in alphabet]))
+
+    def test_malformed_request_line(self):
+        if getattr(cherrypy.server, "using_apache", False):
+            return self.skip("skipped due to known Apache differences...")
+        
+        # Test missing version in Request-Line
+        if self.scheme == 'https':
+            c = HTTPSConnection('%s:%s' % (self.interface(), self.PORT))
+        else:
+            c = HTTPConnection('%s:%s' % (self.interface(), self.PORT))
+        c._output(ntob('GET /'))
+        c._send_output()
+        if hasattr(c, 'strict'):
+            response = c.response_class(c.sock, strict=c.strict, method='GET')
+        else:
+            # Python 3.2 removed the 'strict' feature, saying:
+            # "http.client now always assumes HTTP/1.x compliant servers."
+            response = c.response_class(c.sock, method='GET')
+        response.begin()
+        self.assertEqual(response.status, 400)
+        self.assertEqual(response.fp.read(22), ntob("Malformed Request-Line"))
+        c.close()
+    
+    def test_malformed_header(self):
+        if self.scheme == 'https':
+            c = HTTPSConnection('%s:%s' % (self.interface(), self.PORT))
+        else:
+            c = HTTPConnection('%s:%s' % (self.interface(), self.PORT))
+        c.putrequest('GET', '/')
+        c.putheader('Content-Type', 'text/plain')
+        # See http://www.cherrypy.org/ticket/941 
+        c._output(ntob('Re, 1.2.3.4#015#012'))
+        c.endheaders()
+        
+        response = c.getresponse()
+        self.status = str(response.status)
+        self.assertStatus(400)
+        self.body = response.fp.read(20)
+        self.assertBody("Illegal header line.")
+
diff --git a/cherrypy/test/test_httpauth.py b/cherrypy/test/test_httpauth.py
new file mode 100644
index 00000000..9d0eecb2
--- /dev/null
+++ b/cherrypy/test/test_httpauth.py
@@ -0,0 +1,151 @@
+import cherrypy
+from cherrypy._cpcompat import md5, sha, ntob
+from cherrypy.lib import httpauth
+
+from cherrypy.test import helper
+
+class HTTPAuthTest(helper.CPWebCase):
+
+    def setup_server():
+        class Root:
+            def index(self):
+                return "This is public."
+            index.exposed = True
+
+        class DigestProtected:
+            def index(self):
+                return "Hello %s, you've been authorized." % cherrypy.request.login
+            index.exposed = True
+
+        class BasicProtected:
+            def index(self):
+                return "Hello %s, you've been authorized." % cherrypy.request.login
+            index.exposed = True
+
+        class BasicProtected2:
+            def index(self):
+                return "Hello %s, you've been authorized." % cherrypy.request.login
+            index.exposed = True
+
+        def fetch_users():
+            return {'test': 'test'}
+
+        def sha_password_encrypter(password):
+            return sha(ntob(password)).hexdigest()
+        
+        def fetch_password(username):
+            return sha(ntob('test')).hexdigest()
+
+        conf = {'/digest': {'tools.digest_auth.on': True,
+                            'tools.digest_auth.realm': 'localhost',
+                            'tools.digest_auth.users': fetch_users},
+                '/basic': {'tools.basic_auth.on': True,
+                           'tools.basic_auth.realm': 'localhost',
+                           'tools.basic_auth.users': {'test': md5(ntob('test')).hexdigest()}},
+                '/basic2': {'tools.basic_auth.on': True,
+                            'tools.basic_auth.realm': 'localhost',
+                            'tools.basic_auth.users': fetch_password,
+                            'tools.basic_auth.encrypt': sha_password_encrypter}}
+                
+        root = Root()
+        root.digest = DigestProtected()
+        root.basic = BasicProtected()
+        root.basic2 = BasicProtected2()
+        cherrypy.tree.mount(root, config=conf)
+    setup_server = staticmethod(setup_server)
+
+
+    def testPublic(self):
+        self.getPage("/")
+        self.assertStatus('200 OK')
+        self.assertHeader('Content-Type', 'text/html;charset=utf-8')
+        self.assertBody('This is public.')
+
+    def testBasic(self):
+        self.getPage("/basic/")
+        self.assertStatus(401)
+        self.assertHeader('WWW-Authenticate', 'Basic realm="localhost"')
+
+        self.getPage('/basic/', [('Authorization', 'Basic dGVzdDp0ZX60')])
+        self.assertStatus(401)
+        
+        self.getPage('/basic/', [('Authorization', 'Basic dGVzdDp0ZXN0')])
+        self.assertStatus('200 OK')
+        self.assertBody("Hello test, you've been authorized.")
+
+    def testBasic2(self):
+        self.getPage("/basic2/")
+        self.assertStatus(401)
+        self.assertHeader('WWW-Authenticate', 'Basic realm="localhost"')
+
+        self.getPage('/basic2/', [('Authorization', 'Basic dGVzdDp0ZX60')])
+        self.assertStatus(401)
+        
+        self.getPage('/basic2/', [('Authorization', 'Basic dGVzdDp0ZXN0')])
+        self.assertStatus('200 OK')
+        self.assertBody("Hello test, you've been authorized.")
+
+    def testDigest(self):
+        self.getPage("/digest/")
+        self.assertStatus(401)
+        
+        value = None
+        for k, v in self.headers:
+            if k.lower() == "www-authenticate":
+                if v.startswith("Digest"):
+                    value = v
+                    break
+
+        if value is None:
+            self._handlewebError("Digest authentification scheme was not found")
+
+        value = value[7:]
+        items = value.split(', ')
+        tokens = {}
+        for item in items:
+            key, value = item.split('=')
+            tokens[key.lower()] = value
+            
+        missing_msg = "%s is missing"
+        bad_value_msg = "'%s' was expecting '%s' but found '%s'"
+        nonce = None
+        if 'realm' not in tokens:
+            self._handlewebError(missing_msg % 'realm')
+        elif tokens['realm'] != '"localhost"':
+            self._handlewebError(bad_value_msg % ('realm', '"localhost"', tokens['realm']))
+        if 'nonce' not in tokens:
+            self._handlewebError(missing_msg % 'nonce')
+        else:
+            nonce = tokens['nonce'].strip('"')
+        if 'algorithm' not in tokens:
+            self._handlewebError(missing_msg % 'algorithm')
+        elif tokens['algorithm'] != '"MD5"':
+            self._handlewebError(bad_value_msg % ('algorithm', '"MD5"', tokens['algorithm']))
+        if 'qop' not in tokens:
+            self._handlewebError(missing_msg % 'qop')
+        elif tokens['qop'] != '"auth"':
+            self._handlewebError(bad_value_msg % ('qop', '"auth"', tokens['qop']))
+
+        # Test a wrong 'realm' value
+        base_auth = 'Digest username="test", realm="wrong realm", nonce="%s", uri="/digest/", algorithm=MD5, response="%s", qop=auth, nc=%s, cnonce="1522e61005789929"'
+
+        auth = base_auth % (nonce, '', '00000001')
+        params = httpauth.parseAuthorization(auth)
+        response = httpauth._computeDigestResponse(params, 'test')
+        
+        auth = base_auth % (nonce, response, '00000001')
+        self.getPage('/digest/', [('Authorization', auth)])
+        self.assertStatus(401)
+
+        # Test that must pass
+        base_auth = 'Digest username="test", realm="localhost", nonce="%s", uri="/digest/", algorithm=MD5, response="%s", qop=auth, nc=%s, cnonce="1522e61005789929"'
+
+        auth = base_auth % (nonce, '', '00000001')
+        params = httpauth.parseAuthorization(auth)
+        response = httpauth._computeDigestResponse(params, 'test')
+        
+        auth = base_auth % (nonce, response, '00000001')
+        self.getPage('/digest/', [('Authorization', auth)])
+        self.assertStatus('200 OK')
+        self.assertBody("Hello test, you've been authorized.")
+
diff --git a/cherrypy/test/test_httplib.py b/cherrypy/test/test_httplib.py
new file mode 100644
index 00000000..5dc40fd2
--- /dev/null
+++ b/cherrypy/test/test_httplib.py
@@ -0,0 +1,29 @@
+"""Tests for cherrypy/lib/httputil.py."""
+
+import unittest
+from cherrypy.lib import httputil
+
+
+class UtilityTests(unittest.TestCase):
+    
+    def test_urljoin(self):
+        # Test all slash+atom combinations for SCRIPT_NAME and PATH_INFO
+        self.assertEqual(httputil.urljoin("/sn/", "/pi/"), "/sn/pi/")
+        self.assertEqual(httputil.urljoin("/sn/", "/pi"), "/sn/pi")
+        self.assertEqual(httputil.urljoin("/sn/", "/"), "/sn/")
+        self.assertEqual(httputil.urljoin("/sn/", ""), "/sn/")
+        self.assertEqual(httputil.urljoin("/sn", "/pi/"), "/sn/pi/")
+        self.assertEqual(httputil.urljoin("/sn", "/pi"), "/sn/pi")
+        self.assertEqual(httputil.urljoin("/sn", "/"), "/sn/")
+        self.assertEqual(httputil.urljoin("/sn", ""), "/sn")
+        self.assertEqual(httputil.urljoin("/", "/pi/"), "/pi/")
+        self.assertEqual(httputil.urljoin("/", "/pi"), "/pi")
+        self.assertEqual(httputil.urljoin("/", "/"), "/")
+        self.assertEqual(httputil.urljoin("/", ""), "/")
+        self.assertEqual(httputil.urljoin("", "/pi/"), "/pi/")
+        self.assertEqual(httputil.urljoin("", "/pi"), "/pi")
+        self.assertEqual(httputil.urljoin("", "/"), "/")
+        self.assertEqual(httputil.urljoin("", ""), "/")
+
+if __name__ == '__main__':
+    unittest.main()
diff --git a/cherrypy/test/test_json.py b/cherrypy/test/test_json.py
new file mode 100644
index 00000000..a02c0767
--- /dev/null
+++ b/cherrypy/test/test_json.py
@@ -0,0 +1,79 @@
+import cherrypy
+from cherrypy.test import helper
+
+from cherrypy._cpcompat import json
+
+class JsonTest(helper.CPWebCase):
+    def setup_server():
+        class Root(object):
+            def plain(self):
+                return 'hello'
+            plain.exposed = True
+
+            def json_string(self):
+                return 'hello'
+            json_string.exposed = True
+            json_string._cp_config = {'tools.json_out.on': True}
+
+            def json_list(self):
+                return ['a', 'b', 42]
+            json_list.exposed = True
+            json_list._cp_config = {'tools.json_out.on': True}
+
+            def json_dict(self):
+                return {'answer': 42}
+            json_dict.exposed = True
+            json_dict._cp_config = {'tools.json_out.on': True}
+
+            def json_post(self):
+                if cherrypy.request.json == [13, 'c']:
+                    return 'ok'
+                else:
+                    return 'nok'
+            json_post.exposed = True
+            json_post._cp_config = {'tools.json_in.on': True}
+
+        root = Root()
+        cherrypy.tree.mount(root)
+    setup_server = staticmethod(setup_server)
+    
+    def test_json_output(self):
+        if json is None:
+            self.skip("json not found ")
+            return
+        
+        self.getPage("/plain")
+        self.assertBody("hello")
+
+        self.getPage("/json_string")
+        self.assertBody('"hello"')
+
+        self.getPage("/json_list")
+        self.assertBody('["a", "b", 42]')
+
+        self.getPage("/json_dict")
+        self.assertBody('{"answer": 42}')
+
+    def test_json_input(self):
+        if json is None:
+            self.skip("json not found ")
+            return
+        
+        body = '[13, "c"]'
+        headers = [('Content-Type', 'application/json'),
+                   ('Content-Length', str(len(body)))]
+        self.getPage("/json_post", method="POST", headers=headers, body=body)
+        self.assertBody('ok')
+            
+        body = '[13, "c"]'
+        headers = [('Content-Type', 'text/plain'),
+                   ('Content-Length', str(len(body)))]
+        self.getPage("/json_post", method="POST", headers=headers, body=body)
+        self.assertStatus(415, 'Expected an application/json content type')
+            
+        body = '[13, -]'
+        headers = [('Content-Type', 'application/json'),
+                   ('Content-Length', str(len(body)))]
+        self.getPage("/json_post", method="POST", headers=headers, body=body)
+        self.assertStatus(400, 'Invalid JSON document')
+
diff --git a/cherrypy/test/test_logging.py b/cherrypy/test/test_logging.py
new file mode 100644
index 00000000..5a13cd4a
--- /dev/null
+++ b/cherrypy/test/test_logging.py
@@ -0,0 +1,149 @@
+"""Basic tests for the CherryPy core: request handling."""
+
+import os
+localDir = os.path.dirname(__file__)
+
+import cherrypy
+
+access_log = os.path.join(localDir, "access.log")
+error_log = os.path.join(localDir, "error.log")
+
+# Some unicode strings.
+tartaros = u'\u03a4\u1f71\u03c1\u03c4\u03b1\u03c1\u03bf\u03c2'
+erebos = u'\u0388\u03c1\u03b5\u03b2\u03bf\u03c2.com'
+
+
+def setup_server():
+    class Root:
+        
+        def index(self):
+            return "hello"
+        index.exposed = True
+        
+        def uni_code(self):
+            cherrypy.request.login = tartaros
+            cherrypy.request.remote.name = erebos
+        uni_code.exposed = True
+        
+        def slashes(self):
+            cherrypy.request.request_line = r'GET /slashed\path HTTP/1.1'
+        slashes.exposed = True
+        
+        def whitespace(self):
+            # User-Agent = "User-Agent" ":" 1*( product | comment )
+            # comment    = "(" *( ctext | quoted-pair | comment ) ")"
+            # ctext      = 
+            # TEXT       = 
+            # LWS        = [CRLF] 1*( SP | HT )
+            cherrypy.request.headers['User-Agent'] = 'Browzuh (1.0\r\n\t\t.3)'
+        whitespace.exposed = True
+        
+        def as_string(self):
+            return "content"
+        as_string.exposed = True
+        
+        def as_yield(self):
+            yield "content"
+        as_yield.exposed = True
+        
+        def error(self):
+            raise ValueError()
+        error.exposed = True
+        error._cp_config = {'tools.log_tracebacks.on': True}
+    
+    root = Root()
+
+
+    cherrypy.config.update({'log.error_file': error_log,
+                            'log.access_file': access_log,
+                            })
+    cherrypy.tree.mount(root)
+
+
+
+from cherrypy.test import helper, logtest
+
+class AccessLogTests(helper.CPWebCase, logtest.LogCase):
+    setup_server = staticmethod(setup_server)
+    
+    logfile = access_log
+    
+    def testNormalReturn(self):
+        self.markLog()
+        self.getPage("/as_string",
+                     headers=[('Referer', 'http://www.cherrypy.org/'),
+                              ('User-Agent', 'Mozilla/5.0')])
+        self.assertBody('content')
+        self.assertStatus(200)
+        
+        intro = '%s - - [' % self.interface()
+        
+        self.assertLog(-1, intro)
+        
+        if [k for k, v in self.headers if k.lower() == 'content-length']:
+            self.assertLog(-1, '] "GET %s/as_string HTTP/1.1" 200 7 '
+                           '"http://www.cherrypy.org/" "Mozilla/5.0"'
+                           % self.prefix())
+        else:
+            self.assertLog(-1, '] "GET %s/as_string HTTP/1.1" 200 - '
+                           '"http://www.cherrypy.org/" "Mozilla/5.0"'
+                           % self.prefix())
+    
+    def testNormalYield(self):
+        self.markLog()
+        self.getPage("/as_yield")
+        self.assertBody('content')
+        self.assertStatus(200)
+        
+        intro = '%s - - [' % self.interface()
+        
+        self.assertLog(-1, intro)
+        if [k for k, v in self.headers if k.lower() == 'content-length']:
+            self.assertLog(-1, '] "GET %s/as_yield HTTP/1.1" 200 7 "" ""' %
+                           self.prefix())
+        else:
+            self.assertLog(-1, '] "GET %s/as_yield HTTP/1.1" 200 - "" ""'
+                           % self.prefix())
+    
+    def testEscapedOutput(self):
+        # Test unicode in access log pieces.
+        self.markLog()
+        self.getPage("/uni_code")
+        self.assertStatus(200)
+        self.assertLog(-1, repr(tartaros.encode('utf8'))[1:-1])
+        # Test the erebos value. Included inline for your enlightenment.
+        # Note the 'r' prefix--those backslashes are literals.
+        self.assertLog(-1, r'\xce\x88\xcf\x81\xce\xb5\xce\xb2\xce\xbf\xcf\x82')
+        
+        # Test backslashes in output.
+        self.markLog()
+        self.getPage("/slashes")
+        self.assertStatus(200)
+        self.assertLog(-1, r'"GET /slashed\\path HTTP/1.1"')
+        
+        # Test whitespace in output.
+        self.markLog()
+        self.getPage("/whitespace")
+        self.assertStatus(200)
+        # Again, note the 'r' prefix.
+        self.assertLog(-1, r'"Browzuh (1.0\r\n\t\t.3)"')
+
+
+class ErrorLogTests(helper.CPWebCase, logtest.LogCase):
+    setup_server = staticmethod(setup_server)
+    
+    logfile = error_log
+    
+    def testTracebacks(self):
+        # Test that tracebacks get written to the error log.
+        self.markLog()
+        ignore = helper.webtest.ignored_exceptions
+        ignore.append(ValueError)
+        try:
+            self.getPage("/error")
+            self.assertInBody("raise ValueError()")
+            self.assertLog(0, 'HTTP Traceback (most recent call last):')
+            self.assertLog(-3, 'raise ValueError()')
+        finally:
+            ignore.pop()
+
diff --git a/cherrypy/test/test_mime.py b/cherrypy/test/test_mime.py
new file mode 100644
index 00000000..605071b8
--- /dev/null
+++ b/cherrypy/test/test_mime.py
@@ -0,0 +1,128 @@
+"""Tests for various MIME issues, including the safe_multipart Tool."""
+
+import cherrypy
+from cherrypy._cpcompat import ntob, ntou, sorted
+
+def setup_server():
+    
+    class Root:
+        
+        def multipart(self, parts):
+            return repr(parts)
+        multipart.exposed = True
+        
+        def multipart_form_data(self, **kwargs):
+            return repr(list(sorted(kwargs.items())))
+        multipart_form_data.exposed = True
+        
+        def flashupload(self, Filedata, Upload, Filename):
+            return ("Upload: %r, Filename: %r, Filedata: %r" %
+                    (Upload, Filename, Filedata.file.read()))
+        flashupload.exposed = True
+    
+    cherrypy.config.update({'server.max_request_body_size': 0})
+    cherrypy.tree.mount(Root())
+
+
+#                             Client-side code                             #
+
+from cherrypy.test import helper
+
+class MultipartTest(helper.CPWebCase):
+    setup_server = staticmethod(setup_server)
+    
+    def test_multipart(self):
+        text_part = ntou("This is the text version")
+        html_part = ntou("""
+
+
+ 
+
+
+
+This is the HTML version
+
+
+""")
+        body = '\r\n'.join([
+            "--123456789",
+            "Content-Type: text/plain; charset='ISO-8859-1'",
+            "Content-Transfer-Encoding: 7bit",
+            "",
+            text_part,
+            "--123456789",
+            "Content-Type: text/html; charset='ISO-8859-1'",
+            "",
+            html_part,
+            "--123456789--"])
+        headers = [
+            ('Content-Type', 'multipart/mixed; boundary=123456789'),
+            ('Content-Length', str(len(body))),
+            ]
+        self.getPage('/multipart', headers, "POST", body)
+        self.assertBody(repr([text_part, html_part]))
+    
+    def test_multipart_form_data(self):
+        body='\r\n'.join(['--X',
+                          'Content-Disposition: form-data; name="foo"',
+                          '',
+                          'bar',
+                          '--X',
+                          # Test a param with more than one value.
+                          # See http://www.cherrypy.org/ticket/1028
+                          'Content-Disposition: form-data; name="baz"',
+                          '',
+                          '111',
+                          '--X',
+                          'Content-Disposition: form-data; name="baz"',
+                          '',
+                          '333',
+                          '--X--'])
+        self.getPage('/multipart_form_data', method='POST',
+                     headers=[("Content-Type", "multipart/form-data;boundary=X"),
+                              ("Content-Length", str(len(body))),
+                              ],
+                     body=body),
+        self.assertBody(repr([('baz', [u'111', u'333']), ('foo', u'bar')]))
+
+
+class SafeMultipartHandlingTest(helper.CPWebCase):
+    setup_server = staticmethod(setup_server)
+
+    def test_Flash_Upload(self):
+        headers = [
+            ('Accept', 'text/*'),
+            ('Content-Type', 'multipart/form-data; '
+                 'boundary=----------KM7Ij5cH2KM7Ef1gL6ae0ae0cH2gL6'),
+            ('User-Agent', 'Shockwave Flash'),
+            ('Host', 'www.example.com:8080'),
+            ('Content-Length', '499'),
+            ('Connection', 'Keep-Alive'),
+            ('Cache-Control', 'no-cache'),
+            ]
+        filedata = ntob('\r\n'
+                        '\r\n'
+                        '\r\n')
+        body = (ntob(
+            '------------KM7Ij5cH2KM7Ef1gL6ae0ae0cH2gL6\r\n'
+            'Content-Disposition: form-data; name="Filename"\r\n'
+            '\r\n'
+            '.project\r\n'
+            '------------KM7Ij5cH2KM7Ef1gL6ae0ae0cH2gL6\r\n'
+            'Content-Disposition: form-data; '
+                'name="Filedata"; filename=".project"\r\n'
+            'Content-Type: application/octet-stream\r\n'
+            '\r\n')
+            + filedata + 
+            ntob('\r\n'
+            '------------KM7Ij5cH2KM7Ef1gL6ae0ae0cH2gL6\r\n'
+            'Content-Disposition: form-data; name="Upload"\r\n'
+            '\r\n'
+            'Submit Query\r\n'
+            # Flash apps omit the trailing \r\n on the last line:
+            '------------KM7Ij5cH2KM7Ef1gL6ae0ae0cH2gL6--'
+            ))
+        self.getPage('/flashupload', headers, "POST", body)
+        self.assertBody("Upload: u'Submit Query', Filename: u'.project', "
+                        "Filedata: %r" % filedata)
+
diff --git a/cherrypy/test/test_misc_tools.py b/cherrypy/test/test_misc_tools.py
new file mode 100644
index 00000000..fb94e860
--- /dev/null
+++ b/cherrypy/test/test_misc_tools.py
@@ -0,0 +1,202 @@
+import os
+localDir = os.path.dirname(__file__)
+logfile = os.path.join(localDir, "test_misc_tools.log")
+
+import cherrypy
+from cherrypy import tools
+
+
+def setup_server():
+    class Root:
+        def index(self):
+            yield "Hello, world"
+        index.exposed = True
+        h = [("Content-Language", "en-GB"), ('Content-Type', 'text/plain')]
+        tools.response_headers(headers=h)(index)
+        
+        def other(self):
+            return "salut"
+        other.exposed = True
+        other._cp_config = {
+            'tools.response_headers.on': True,
+            'tools.response_headers.headers': [("Content-Language", "fr"),
+                                               ('Content-Type', 'text/plain')],
+            'tools.log_hooks.on': True,
+            }
+    
+    
+    class Accept:
+        _cp_config = {'tools.accept.on': True}
+        
+        def index(self):
+            return 'Atom feed'
+        index.exposed = True
+        
+        # In Python 2.4+, we could use a decorator instead:
+        # @tools.accept('application/atom+xml')
+        def feed(self):
+            return """
+
+    Unknown Blog
+"""
+        feed.exposed = True
+        feed._cp_config = {'tools.accept.media': 'application/atom+xml'}
+        
+        def select(self):
+            # We could also write this: mtype = cherrypy.lib.accept.accept(...)
+            mtype = tools.accept.callable(['text/html', 'text/plain'])
+            if mtype == 'text/html':
+                return "
Page Title
"
+            else:
+                return "PAGE TITLE"
+        select.exposed = True
+    
+    class Referer:
+        def accept(self):
+            return "Accepted!"
+        accept.exposed = True
+        reject = accept
+    
+    class AutoVary:
+        def index(self):
+            # Read a header directly with 'get'
+            ae = cherrypy.request.headers.get('Accept-Encoding')
+            # Read a header directly with '__getitem__'
+            cl = cherrypy.request.headers['Host']
+            # Read a header directly with '__contains__'
+            hasif = 'If-Modified-Since' in cherrypy.request.headers
+            # Read a header directly with 'has_key'
+            has = cherrypy.request.headers.has_key('Range')
+            # Call a lib function
+            mtype = tools.accept.callable(['text/html', 'text/plain'])
+            return "Hello, world!"
+        index.exposed = True
+    
+    conf = {'/referer': {'tools.referer.on': True,
+                         'tools.referer.pattern': r'http://[^/]*example\.com',
+                         },
+            '/referer/reject': {'tools.referer.accept': False,
+                                'tools.referer.accept_missing': True,
+                                },
+            '/autovary': {'tools.autovary.on': True},
+            }
+    
+    root = Root()
+    root.referer = Referer()
+    root.accept = Accept()
+    root.autovary = AutoVary()
+    cherrypy.tree.mount(root, config=conf)
+    cherrypy.config.update({'log.error_file': logfile})
+
+
+from cherrypy.test import helper
+
+class ResponseHeadersTest(helper.CPWebCase):
+    setup_server = staticmethod(setup_server)
+
+    def testResponseHeadersDecorator(self):
+        self.getPage('/')
+        self.assertHeader("Content-Language", "en-GB")
+        self.assertHeader('Content-Type', 'text/plain;charset=utf-8')
+
+    def testResponseHeaders(self):
+        self.getPage('/other')
+        self.assertHeader("Content-Language", "fr")
+        self.assertHeader('Content-Type', 'text/plain;charset=utf-8')
+
+
+class RefererTest(helper.CPWebCase):
+    setup_server = staticmethod(setup_server)
+    
+    def testReferer(self):
+        self.getPage('/referer/accept')
+        self.assertErrorPage(403, 'Forbidden Referer header.')
+        
+        self.getPage('/referer/accept',
+                     headers=[('Referer', 'http://www.example.com/')])
+        self.assertStatus(200)
+        self.assertBody('Accepted!')
+        
+        # Reject
+        self.getPage('/referer/reject')
+        self.assertStatus(200)
+        self.assertBody('Accepted!')
+        
+        self.getPage('/referer/reject',
+                     headers=[('Referer', 'http://www.example.com/')])
+        self.assertErrorPage(403, 'Forbidden Referer header.')
+
+
+class AcceptTest(helper.CPWebCase):
+    setup_server = staticmethod(setup_server)
+    
+    def test_Accept_Tool(self):
+        # Test with no header provided
+        self.getPage('/accept/feed')
+        self.assertStatus(200)
+        self.assertInBody('Unknown Blog')
+        
+        # Specify exact media type
+        self.getPage('/accept/feed', headers=[('Accept', 'application/atom+xml')])
+        self.assertStatus(200)
+        self.assertInBody('Unknown Blog')
+        
+        # Specify matching media range
+        self.getPage('/accept/feed', headers=[('Accept', 'application/*')])
+        self.assertStatus(200)
+        self.assertInBody('Unknown Blog')
+        
+        # Specify all media ranges
+        self.getPage('/accept/feed', headers=[('Accept', '*/*')])
+        self.assertStatus(200)
+        self.assertInBody('Unknown Blog')
+        
+        # Specify unacceptable media types
+        self.getPage('/accept/feed', headers=[('Accept', 'text/html')])
+        self.assertErrorPage(406,
+                             "Your client sent this Accept header: text/html. "
+                             "But this resource only emits these media types: "
+                             "application/atom+xml.")
+        
+        # Test resource where tool is 'on' but media is None (not set).
+        self.getPage('/accept/')
+        self.assertStatus(200)
+        self.assertBody('Atom feed')
+    
+    def test_accept_selection(self):
+        # Try both our expected media types
+        self.getPage('/accept/select', [('Accept', 'text/html')])
+        self.assertStatus(200)
+        self.assertBody('
Page Title
')
+        self.getPage('/accept/select', [('Accept', 'text/plain')])
+        self.assertStatus(200)
+        self.assertBody('PAGE TITLE')
+        self.getPage('/accept/select', [('Accept', 'text/plain, text/*;q=0.5')])
+        self.assertStatus(200)
+        self.assertBody('PAGE TITLE')
+        
+        # text/* and */* should prefer text/html since it comes first
+        # in our 'media' argument to tools.accept
+        self.getPage('/accept/select', [('Accept', 'text/*')])
+        self.assertStatus(200)
+        self.assertBody('
Page Title
')
+        self.getPage('/accept/select', [('Accept', '*/*')])
+        self.assertStatus(200)
+        self.assertBody('
Page Title
')
+        
+        # Try unacceptable media types
+        self.getPage('/accept/select', [('Accept', 'application/xml')])
+        self.assertErrorPage(406,
+                             "Your client sent this Accept header: application/xml. "
+                             "But this resource only emits these media types: "
+                             "text/html, text/plain.")
+
+
+class AutoVaryTest(helper.CPWebCase):
+    setup_server = staticmethod(setup_server)
+
+    def testAutoVary(self):
+        self.getPage('/autovary/')
+        self.assertHeader(
+            "Vary", 'Accept, Accept-Charset, Accept-Encoding, Host, If-Modified-Since, Range')
+
diff --git a/cherrypy/test/test_objectmapping.py b/cherrypy/test/test_objectmapping.py
new file mode 100644
index 00000000..46816fcb
--- /dev/null
+++ b/cherrypy/test/test_objectmapping.py
@@ -0,0 +1,403 @@
+import cherrypy
+from cherrypy._cptree import Application
+from cherrypy.test import helper
+
+script_names = ["", "/foo", "/users/fred/blog", "/corp/blog"]
+
+
+class ObjectMappingTest(helper.CPWebCase):
+
+    def setup_server():
+        class Root:
+            def index(self, name="world"):
+                return name
+            index.exposed = True
+            
+            def foobar(self):
+                return "bar"
+            foobar.exposed = True
+            
+            def default(self, *params, **kwargs):
+                return "default:" + repr(params)
+            default.exposed = True
+            
+            def other(self):
+                return "other"
+            other.exposed = True
+            
+            def extra(self, *p):
+                return repr(p)
+            extra.exposed = True
+            
+            def redirect(self):
+                raise cherrypy.HTTPRedirect('dir1/', 302)
+            redirect.exposed = True
+            
+            def notExposed(self):
+                return "not exposed"
+            
+            def confvalue(self):
+                return cherrypy.request.config.get("user")
+            confvalue.exposed = True
+            
+            def redirect_via_url(self, path):
+                raise cherrypy.HTTPRedirect(cherrypy.url(path))
+            redirect_via_url.exposed = True
+            
+            def translate_html(self):
+                return "OK"
+            translate_html.exposed = True
+        
+        def mapped_func(self, ID=None):
+            return "ID is %s" % ID
+        mapped_func.exposed = True
+        setattr(Root, "Von B\xfclow", mapped_func)
+        
+        
+        class Exposing:
+            def base(self):
+                return "expose works!"
+            cherrypy.expose(base)
+            cherrypy.expose(base, "1")
+            cherrypy.expose(base, "2")
+        
+        class ExposingNewStyle(object):
+            def base(self):
+                return "expose works!"
+            cherrypy.expose(base)
+            cherrypy.expose(base, "1")
+            cherrypy.expose(base, "2")
+        
+        
+        class Dir1:
+            def index(self):
+                return "index for dir1"
+            index.exposed = True
+            
+            def myMethod(self):
+                return "myMethod from dir1, path_info is:" + repr(cherrypy.request.path_info)
+            myMethod.exposed = True
+            myMethod._cp_config = {'tools.trailing_slash.extra': True}
+            
+            def default(self, *params):
+                return "default for dir1, param is:" + repr(params)
+            default.exposed = True
+
+
+        class Dir2:
+            def index(self):
+                return "index for dir2, path is:" + cherrypy.request.path_info
+            index.exposed = True
+            
+            def script_name(self):
+                return cherrypy.tree.script_name()
+            script_name.exposed = True
+            
+            def cherrypy_url(self):
+                return cherrypy.url("/extra")
+            cherrypy_url.exposed = True
+            
+            def posparam(self, *vpath):
+                return "/".join(vpath)
+            posparam.exposed = True
+        
+        
+        class Dir3:
+            def default(self):
+                return "default for dir3, not exposed"
+        
+        class Dir4:
+            def index(self):
+                return "index for dir4, not exposed"
+        
+        class DefNoIndex:
+            def default(self, *args):
+                raise cherrypy.HTTPRedirect("contact")
+            default.exposed = True
+        
+        # MethodDispatcher code
+        class ByMethod:
+            exposed = True
+            
+            def __init__(self, *things):
+                self.things = list(things)
+            
+            def GET(self):
+                return repr(self.things)
+            
+            def POST(self, thing):
+                self.things.append(thing)
+        
+        class Collection:
+            default = ByMethod('a', 'bit')
+        
+        Root.exposing = Exposing()
+        Root.exposingnew = ExposingNewStyle()
+        Root.dir1 = Dir1()
+        Root.dir1.dir2 = Dir2()
+        Root.dir1.dir2.dir3 = Dir3()
+        Root.dir1.dir2.dir3.dir4 = Dir4()
+        Root.defnoindex = DefNoIndex()
+        Root.bymethod = ByMethod('another')
+        Root.collection = Collection()
+        
+        d = cherrypy.dispatch.MethodDispatcher()
+        for url in script_names:
+            conf = {'/': {'user': (url or "/").split("/")[-2]},
+                    '/bymethod': {'request.dispatch': d},
+                    '/collection': {'request.dispatch': d},
+                    }
+            cherrypy.tree.mount(Root(), url, conf)
+        
+        
+        class Isolated:
+            def index(self):
+                return "made it!"
+            index.exposed = True
+        
+        cherrypy.tree.mount(Isolated(), "/isolated")
+        
+        class AnotherApp:
+            
+            exposed = True
+            
+            def GET(self):
+                return "milk"
+        
+        cherrypy.tree.mount(AnotherApp(), "/app", {'/': {'request.dispatch': d}})
+    setup_server = staticmethod(setup_server)
+
+    
+    def testObjectMapping(self):
+        for url in script_names:
+            prefix = self.script_name = url
+            
+            self.getPage('/')
+            self.assertBody('world')
+            
+            self.getPage("/dir1/myMethod")
+            self.assertBody("myMethod from dir1, path_info is:'/dir1/myMethod'")
+            
+            self.getPage("/this/method/does/not/exist")
+            self.assertBody("default:('this', 'method', 'does', 'not', 'exist')")
+            
+            self.getPage("/extra/too/much")
+            self.assertBody("('too', 'much')")
+            
+            self.getPage("/other")
+            self.assertBody('other')
+            
+            self.getPage("/notExposed")
+            self.assertBody("default:('notExposed',)")
+            
+            self.getPage("/dir1/dir2/")
+            self.assertBody('index for dir2, path is:/dir1/dir2/')
+            
+            # Test omitted trailing slash (should be redirected by default).
+            self.getPage("/dir1/dir2")
+            self.assertStatus(301)
+            self.assertHeader('Location', '%s/dir1/dir2/' % self.base())
+            
+            # Test extra trailing slash (should be redirected if configured).
+            self.getPage("/dir1/myMethod/")
+            self.assertStatus(301)
+            self.assertHeader('Location', '%s/dir1/myMethod' % self.base())
+            
+            # Test that default method must be exposed in order to match.
+            self.getPage("/dir1/dir2/dir3/dir4/index")
+            self.assertBody("default for dir1, param is:('dir2', 'dir3', 'dir4', 'index')")
+            
+            # Test *vpath when default() is defined but not index()
+            # This also tests HTTPRedirect with default.
+            self.getPage("/defnoindex")
+            self.assertStatus((302, 303))
+            self.assertHeader('Location', '%s/contact' % self.base())
+            self.getPage("/defnoindex/")
+            self.assertStatus((302, 303))
+            self.assertHeader('Location', '%s/defnoindex/contact' % self.base())
+            self.getPage("/defnoindex/page")
+            self.assertStatus((302, 303))
+            self.assertHeader('Location', '%s/defnoindex/contact' % self.base())
+            
+            self.getPage("/redirect")
+            self.assertStatus('302 Found')
+            self.assertHeader('Location', '%s/dir1/' % self.base())
+            
+            if not getattr(cherrypy.server, "using_apache", False):
+                # Test that we can use URL's which aren't all valid Python identifiers
+                # This should also test the %XX-unquoting of URL's.
+                self.getPage("/Von%20B%fclow?ID=14")
+                self.assertBody("ID is 14")
+                
+                # Test that %2F in the path doesn't get unquoted too early;
+                # that is, it should not be used to separate path components.
+                # See ticket #393.
+                self.getPage("/page%2Fname")
+                self.assertBody("default:('page/name',)")
+            
+            self.getPage("/dir1/dir2/script_name")
+            self.assertBody(url)
+            self.getPage("/dir1/dir2/cherrypy_url")
+            self.assertBody("%s/extra" % self.base())
+            
+            # Test that configs don't overwrite each other from diferent apps
+            self.getPage("/confvalue")
+            self.assertBody((url or "/").split("/")[-2])
+        
+        self.script_name = ""
+        
+        # Test absoluteURI's in the Request-Line
+        self.getPage('http://%s:%s/' % (self.interface(), self.PORT))
+        self.assertBody('world')
+        
+        self.getPage('http://%s:%s/abs/?service=http://192.168.0.1/x/y/z' %
+                     (self.interface(), self.PORT))
+        self.assertBody("default:('abs',)")
+        
+        self.getPage('/rel/?service=http://192.168.120.121:8000/x/y/z')
+        self.assertBody("default:('rel',)")
+        
+        # Test that the "isolated" app doesn't leak url's into the root app.
+        # If it did leak, Root.default() would answer with
+        #   "default:('isolated', 'doesnt', 'exist')".
+        self.getPage("/isolated/")
+        self.assertStatus("200 OK")
+        self.assertBody("made it!")
+        self.getPage("/isolated/doesnt/exist")
+        self.assertStatus("404 Not Found")
+        
+        # Make sure /foobar maps to Root.foobar and not to the app
+        # mounted at /foo. See http://www.cherrypy.org/ticket/573
+        self.getPage("/foobar")
+        self.assertBody("bar")
+    
+    def test_translate(self):
+        self.getPage("/translate_html")
+        self.assertStatus("200 OK")
+        self.assertBody("OK")
+        
+        self.getPage("/translate.html")
+        self.assertStatus("200 OK")
+        self.assertBody("OK")
+        
+        self.getPage("/translate-html")
+        self.assertStatus("200 OK")
+        self.assertBody("OK")
+    
+    def test_redir_using_url(self):
+        for url in script_names:
+            prefix = self.script_name = url
+            
+            # Test the absolute path to the parent (leading slash)
+            self.getPage('/redirect_via_url?path=./')
+            self.assertStatus(('302 Found', '303 See Other'))
+            self.assertHeader('Location', '%s/' % self.base())
+            
+            # Test the relative path to the parent (no leading slash)
+            self.getPage('/redirect_via_url?path=./')
+            self.assertStatus(('302 Found', '303 See Other'))
+            self.assertHeader('Location', '%s/' % self.base())
+            
+            # Test the absolute path to the parent (leading slash)
+            self.getPage('/redirect_via_url/?path=./')
+            self.assertStatus(('302 Found', '303 See Other'))
+            self.assertHeader('Location', '%s/' % self.base())
+            
+            # Test the relative path to the parent (no leading slash)
+            self.getPage('/redirect_via_url/?path=./')
+            self.assertStatus(('302 Found', '303 See Other'))
+            self.assertHeader('Location', '%s/' % self.base())
+    
+    def testPositionalParams(self):
+        self.getPage("/dir1/dir2/posparam/18/24/hut/hike")
+        self.assertBody("18/24/hut/hike")
+        
+        # intermediate index methods should not receive posparams;
+        # only the "final" index method should do so.
+        self.getPage("/dir1/dir2/5/3/sir")
+        self.assertBody("default for dir1, param is:('dir2', '5', '3', 'sir')")
+        
+        # test that extra positional args raises an 404 Not Found
+        # See http://www.cherrypy.org/ticket/733.
+        self.getPage("/dir1/dir2/script_name/extra/stuff")
+        self.assertStatus(404)
+    
+    def testExpose(self):
+        # Test the cherrypy.expose function/decorator
+        self.getPage("/exposing/base")
+        self.assertBody("expose works!")
+        
+        self.getPage("/exposing/1")
+        self.assertBody("expose works!")
+        
+        self.getPage("/exposing/2")
+        self.assertBody("expose works!")
+        
+        self.getPage("/exposingnew/base")
+        self.assertBody("expose works!")
+        
+        self.getPage("/exposingnew/1")
+        self.assertBody("expose works!")
+        
+        self.getPage("/exposingnew/2")
+        self.assertBody("expose works!")
+    
+    def testMethodDispatch(self):
+        self.getPage("/bymethod")
+        self.assertBody("['another']")
+        self.assertHeader('Allow', 'GET, HEAD, POST')
+        
+        self.getPage("/bymethod", method="HEAD")
+        self.assertBody("")
+        self.assertHeader('Allow', 'GET, HEAD, POST')
+        
+        self.getPage("/bymethod", method="POST", body="thing=one")
+        self.assertBody("")
+        self.assertHeader('Allow', 'GET, HEAD, POST')
+        
+        self.getPage("/bymethod")
+        self.assertBody("['another', u'one']")
+        self.assertHeader('Allow', 'GET, HEAD, POST')
+        
+        self.getPage("/bymethod", method="PUT")
+        self.assertErrorPage(405)
+        self.assertHeader('Allow', 'GET, HEAD, POST')
+        
+        # Test default with posparams
+        self.getPage("/collection/silly", method="POST")
+        self.getPage("/collection", method="GET")
+        self.assertBody("['a', 'bit', 'silly']")
+        
+        # Test custom dispatcher set on app root (see #737).
+        self.getPage("/app")
+        self.assertBody("milk")
+
+    def testTreeMounting(self):
+        class Root(object):
+            def hello(self):
+                return "Hello world!"
+            hello.exposed = True
+        
+        # When mounting an application instance, 
+        # we can't specify a different script name in the call to mount.
+        a = Application(Root(), '/somewhere')
+        self.assertRaises(ValueError, cherrypy.tree.mount, a, '/somewhereelse')
+        
+        # When mounting an application instance...
+        a = Application(Root(), '/somewhere')
+        # ...we MUST allow in identical script name in the call to mount...
+        cherrypy.tree.mount(a, '/somewhere')
+        self.getPage('/somewhere/hello')
+        self.assertStatus(200)
+        # ...and MUST allow a missing script_name.
+        del cherrypy.tree.apps['/somewhere']
+        cherrypy.tree.mount(a)
+        self.getPage('/somewhere/hello')
+        self.assertStatus(200)
+        
+        # In addition, we MUST be able to create an Application using
+        # script_name == None for access to the wsgi_environ.
+        a = Application(Root(), script_name=None)
+        # However, this does not apply to tree.mount
+        self.assertRaises(TypeError, cherrypy.tree.mount, a, None)
+
diff --git a/cherrypy/test/test_proxy.py b/cherrypy/test/test_proxy.py
new file mode 100644
index 00000000..2fbb619a
--- /dev/null
+++ b/cherrypy/test/test_proxy.py
@@ -0,0 +1,129 @@
+import cherrypy
+from cherrypy.test import helper
+
+script_names = ["", "/path/to/myapp"]
+
+
+class ProxyTest(helper.CPWebCase):
+
+    def setup_server():
+        
+        # Set up site
+        cherrypy.config.update({
+            'tools.proxy.on': True,
+            'tools.proxy.base': 'www.mydomain.test',
+            })
+        
+        # Set up application
+        
+        class Root:
+            
+            def __init__(self, sn):
+                # Calculate a URL outside of any requests.
+                self.thisnewpage = cherrypy.url("/this/new/page", script_name=sn)
+            
+            def pageurl(self):
+                return self.thisnewpage
+            pageurl.exposed = True
+            
+            def index(self):
+                raise cherrypy.HTTPRedirect('dummy')
+            index.exposed = True
+            
+            def remoteip(self):
+                return cherrypy.request.remote.ip
+            remoteip.exposed = True
+            
+            def xhost(self):
+                raise cherrypy.HTTPRedirect('blah')
+            xhost.exposed = True
+            xhost._cp_config = {'tools.proxy.local': 'X-Host',
+                                'tools.trailing_slash.extra': True,
+                                }
+            
+            def base(self):
+                return cherrypy.request.base
+            base.exposed = True
+            
+            def ssl(self):
+                return cherrypy.request.base
+            ssl.exposed = True
+            ssl._cp_config = {'tools.proxy.scheme': 'X-Forwarded-Ssl'}
+            
+            def newurl(self):
+                return ("Browse to this page."
+                        % cherrypy.url("/this/new/page"))
+            newurl.exposed = True
+        
+        for sn in script_names:
+            cherrypy.tree.mount(Root(sn), sn)
+    setup_server = staticmethod(setup_server)
+    
+    def testProxy(self):
+        self.getPage("/")
+        self.assertHeader('Location',
+                          "%s://www.mydomain.test%s/dummy" %
+                          (self.scheme, self.prefix()))
+        
+        # Test X-Forwarded-Host (Apache 1.3.33+ and Apache 2)
+        self.getPage("/", headers=[('X-Forwarded-Host', 'http://www.example.test')])
+        self.assertHeader('Location', "http://www.example.test/dummy")
+        self.getPage("/", headers=[('X-Forwarded-Host', 'www.example.test')])
+        self.assertHeader('Location', "%s://www.example.test/dummy" % self.scheme)
+        # Test multiple X-Forwarded-Host headers
+        self.getPage("/", headers=[
+            ('X-Forwarded-Host', 'http://www.example.test, www.cherrypy.test'),
+            ])
+        self.assertHeader('Location', "http://www.example.test/dummy")
+        
+        # Test X-Forwarded-For (Apache2)
+        self.getPage("/remoteip",
+                     headers=[('X-Forwarded-For', '192.168.0.20')])
+        self.assertBody("192.168.0.20")
+        self.getPage("/remoteip",
+                     headers=[('X-Forwarded-For', '67.15.36.43, 192.168.0.20')])
+        self.assertBody("192.168.0.20")
+        
+        # Test X-Host (lighttpd; see https://trac.lighttpd.net/trac/ticket/418)
+        self.getPage("/xhost", headers=[('X-Host', 'www.example.test')])
+        self.assertHeader('Location', "%s://www.example.test/blah" % self.scheme)
+        
+        # Test X-Forwarded-Proto (lighttpd)
+        self.getPage("/base", headers=[('X-Forwarded-Proto', 'https')])
+        self.assertBody("https://www.mydomain.test")
+        
+        # Test X-Forwarded-Ssl (webfaction?)
+        self.getPage("/ssl", headers=[('X-Forwarded-Ssl', 'on')])
+        self.assertBody("https://www.mydomain.test")
+        
+        # Test cherrypy.url()
+        for sn in script_names:
+            # Test the value inside requests
+            self.getPage(sn + "/newurl")
+            self.assertBody("Browse to this page.")
+            self.getPage(sn + "/newurl", headers=[('X-Forwarded-Host',
+                                                   'http://www.example.test')])
+            self.assertBody("Browse to this page.")
+            
+            # Test the value outside requests
+            port = ""
+            if self.scheme == "http" and self.PORT != 80:
+                port = ":%s" % self.PORT
+            elif self.scheme == "https" and self.PORT != 443:
+                port = ":%s" % self.PORT
+            host = self.HOST
+            if host in ('0.0.0.0', '::'):
+                import socket
+                host = socket.gethostname()
+            expected = ("%s://%s%s%s/this/new/page"
+                        % (self.scheme, host, port, sn))
+            self.getPage(sn + "/pageurl")
+            self.assertBody(expected)
+        
+        # Test trailing slash (see http://www.cherrypy.org/ticket/562).
+        self.getPage("/xhost/", headers=[('X-Host', 'www.example.test')])
+        self.assertHeader('Location', "%s://www.example.test/xhost"
+                          % self.scheme)
+
diff --git a/cherrypy/test/test_refleaks.py b/cherrypy/test/test_refleaks.py
new file mode 100644
index 00000000..4df1f082
--- /dev/null
+++ b/cherrypy/test/test_refleaks.py
@@ -0,0 +1,119 @@
+"""Tests for refleaks."""
+
+import gc
+from cherrypy._cpcompat import HTTPConnection, HTTPSConnection, ntob
+import threading
+
+import cherrypy
+from cherrypy import _cprequest
+
+
+data = object()
+
+def get_instances(cls):
+    return [x for x in gc.get_objects() if isinstance(x, cls)]
+
+
+from cherrypy.test import helper
+
+
+class ReferenceTests(helper.CPWebCase):
+
+    def setup_server():
+        
+        class Root:
+            def index(self, *args, **kwargs):
+                cherrypy.request.thing = data
+                return "Hello world!"
+            index.exposed = True
+            
+            def gc_stats(self):
+                output = ["Statistics:"]
+                
+                # Uncollectable garbage
+                
+                # gc_collect isn't perfectly synchronous, because it may
+                # break reference cycles that then take time to fully
+                # finalize. Call it twice and hope for the best.
+                gc.collect()
+                unreachable = gc.collect()
+                if unreachable:
+                    output.append("\n%s unreachable objects:" % unreachable)
+                    trash = {}
+                    for x in gc.garbage:
+                        trash[type(x)] = trash.get(type(x), 0) + 1
+                    trash = [(v, k) for k, v in trash.items()]
+                    trash.sort()
+                    for pair in trash:
+                        output.append("    " + repr(pair))
+                
+                # Request references
+                reqs = get_instances(_cprequest.Request)
+                lenreqs = len(reqs)
+                if lenreqs < 2:
+                    output.append("\nMissing Request reference. Should be 1 in "
+                                  "this request thread and 1 in the main thread.")
+                elif lenreqs > 2:
+                    output.append("\nToo many Request references (%r)." % lenreqs)
+                    for req in reqs:
+                        output.append("Referrers for %s:" % repr(req))
+                        for ref in gc.get_referrers(req):
+                            if ref is not reqs:
+                                output.append("    %s" % repr(ref))
+                
+                # Response references
+                resps = get_instances(_cprequest.Response)
+                lenresps = len(resps)
+                if lenresps < 2:
+                    output.append("\nMissing Response reference. Should be 1 in "
+                                  "this request thread and 1 in the main thread.")
+                elif lenresps > 2:
+                    output.append("\nToo many Response references (%r)." % lenresps)
+                    for resp in resps:
+                        output.append("Referrers for %s:" % repr(resp))
+                        for ref in gc.get_referrers(resp):
+                            if ref is not resps:
+                                output.append("    %s" % repr(ref))
+                
+                return "\n".join(output)
+            gc_stats.exposed = True
+        
+        cherrypy.tree.mount(Root())
+    setup_server = staticmethod(setup_server)
+
+    
+    def test_threadlocal_garbage(self):
+        success = []
+        
+        def getpage():
+            host = '%s:%s' % (self.interface(), self.PORT)
+            if self.scheme == 'https':
+                c = HTTPSConnection(host)
+            else:
+                c = HTTPConnection(host)
+            try:
+                c.putrequest('GET', '/')
+                c.endheaders()
+                response = c.getresponse()
+                body = response.read()
+                self.assertEqual(response.status, 200)
+                self.assertEqual(body, ntob("Hello world!"))
+            finally:
+                c.close()
+            success.append(True)
+        
+        ITERATIONS = 25
+        ts = []
+        for _ in range(ITERATIONS):
+            t = threading.Thread(target=getpage)
+            ts.append(t)
+            t.start()
+        
+        for t in ts:
+            t.join()
+        
+        self.assertEqual(len(success), ITERATIONS)
+        
+        self.getPage("/gc_stats")
+        self.assertBody("Statistics:")
+
diff --git a/cherrypy/test/test_request_obj.py b/cherrypy/test/test_request_obj.py
new file mode 100644
index 00000000..91ee4fd0
--- /dev/null
+++ b/cherrypy/test/test_request_obj.py
@@ -0,0 +1,722 @@
+"""Basic tests for the cherrypy.Request object."""
+
+import os
+localDir = os.path.dirname(__file__)
+import sys
+import types
+from cherrypy._cpcompat import IncompleteRead, ntob, unicodestr
+
+import cherrypy
+from cherrypy import _cptools, tools
+from cherrypy.lib import httputil
+
+defined_http_methods = ("OPTIONS", "GET", "HEAD", "POST", "PUT", "DELETE",
+                        "TRACE", "PROPFIND")
+
+
+#                             Client-side code                             #
+
+from cherrypy.test import helper
+
+class RequestObjectTests(helper.CPWebCase):
+
+    def setup_server():
+        class Root:
+            
+            def index(self):
+                return "hello"
+            index.exposed = True
+            
+            def scheme(self):
+                return cherrypy.request.scheme
+            scheme.exposed = True
+        
+        root = Root()
+        
+        
+        class TestType(type):
+            """Metaclass which automatically exposes all functions in each subclass,
+            and adds an instance of the subclass as an attribute of root.
+            """
+            def __init__(cls, name, bases, dct):
+                type.__init__(cls, name, bases, dct)
+                for value in dct.values():
+                    if isinstance(value, types.FunctionType):
+                        value.exposed = True
+                setattr(root, name.lower(), cls())
+        class Test(object):
+            __metaclass__ = TestType
+        
+        
+        class Params(Test):
+            
+            def index(self, thing):
+                return repr(thing)
+            
+            def ismap(self, x, y):
+                return "Coordinates: %s, %s" % (x, y)
+            
+            def default(self, *args, **kwargs):
+                return "args: %s kwargs: %s" % (args, kwargs)
+            default._cp_config = {'request.query_string_encoding': 'latin1'}
+
+
+        class ParamErrorsCallable(object):
+            exposed = True
+            def __call__(self):
+                return "data"
+
+        class ParamErrors(Test):
+
+            def one_positional(self, param1):
+                return "data"
+            one_positional.exposed = True
+
+            def one_positional_args(self, param1, *args):
+                return "data"
+            one_positional_args.exposed = True
+
+            def one_positional_args_kwargs(self, param1, *args, **kwargs):
+                return "data"
+            one_positional_args_kwargs.exposed = True
+
+            def one_positional_kwargs(self, param1, **kwargs):
+                return "data"
+            one_positional_kwargs.exposed = True
+
+            def no_positional(self):
+                return "data"
+            no_positional.exposed = True
+
+            def no_positional_args(self, *args):
+                return "data"
+            no_positional_args.exposed = True
+
+            def no_positional_args_kwargs(self, *args, **kwargs):
+                return "data"
+            no_positional_args_kwargs.exposed = True
+
+            def no_positional_kwargs(self, **kwargs):
+                return "data"
+            no_positional_kwargs.exposed = True
+
+            callable_object = ParamErrorsCallable()
+
+            def raise_type_error(self, **kwargs):
+                raise TypeError("Client Error")
+            raise_type_error.exposed = True
+
+            def raise_type_error_with_default_param(self, x, y=None):
+                return '%d' % 'a' # throw an exception
+            raise_type_error_with_default_param.exposed = True
+
+        def callable_error_page(status, **kwargs):
+            return "Error %s - Well, I'm very sorry but you haven't paid!" % status
+        
+        
+        class Error(Test):
+            
+            _cp_config = {'tools.log_tracebacks.on': True,
+                          }
+            
+            def reason_phrase(self):
+                raise cherrypy.HTTPError("410 Gone fishin'")
+            
+            def custom(self, err='404'):
+                raise cherrypy.HTTPError(int(err), "No, really, not found!")
+            custom._cp_config = {'error_page.404': os.path.join(localDir, "static/index.html"),
+                                 'error_page.401': callable_error_page,
+                                 }
+            
+            def custom_default(self):
+                return 1 + 'a' # raise an unexpected error
+            custom_default._cp_config = {'error_page.default': callable_error_page}
+            
+            def noexist(self):
+                raise cherrypy.HTTPError(404, "No, really, not found!")
+            noexist._cp_config = {'error_page.404': "nonexistent.html"}
+            
+            def page_method(self):
+                raise ValueError()
+            
+            def page_yield(self):
+                yield "howdy"
+                raise ValueError()
+            
+            def page_streamed(self):
+                yield "word up"
+                raise ValueError()
+                yield "very oops"
+            page_streamed._cp_config = {"response.stream": True}
+            
+            def cause_err_in_finalize(self):
+                # Since status must start with an int, this should error.
+                cherrypy.response.status = "ZOO OK"
+            cause_err_in_finalize._cp_config = {'request.show_tracebacks': False}
+            
+            def rethrow(self):
+                """Test that an error raised here will be thrown out to the server."""
+                raise ValueError()
+            rethrow._cp_config = {'request.throw_errors': True}
+        
+        
+        class Expect(Test):
+            
+            def expectation_failed(self):
+                expect = cherrypy.request.headers.elements("Expect")
+                if expect and expect[0].value != '100-continue':
+                    raise cherrypy.HTTPError(400)
+                raise cherrypy.HTTPError(417, 'Expectation Failed')
+
+        class Headers(Test):
+            
+            def default(self, headername):
+                """Spit back out the value for the requested header."""
+                return cherrypy.request.headers[headername]
+            
+            def doubledheaders(self):
+                # From http://www.cherrypy.org/ticket/165:
+                # "header field names should not be case sensitive sayes the rfc.
+                # if i set a headerfield in complete lowercase i end up with two
+                # header fields, one in lowercase, the other in mixed-case."
+                
+                # Set the most common headers
+                hMap = cherrypy.response.headers
+                hMap['content-type'] = "text/html"
+                hMap['content-length'] = 18
+                hMap['server'] = 'CherryPy headertest'
+                hMap['location'] = ('%s://%s:%s/headers/'
+                                    % (cherrypy.request.local.ip,
+                                       cherrypy.request.local.port,
+                                       cherrypy.request.scheme))
+                
+                # Set a rare header for fun
+                hMap['Expires'] = 'Thu, 01 Dec 2194 16:00:00 GMT'
+                
+                return "double header test"
+            
+            def ifmatch(self):
+                val = cherrypy.request.headers['If-Match']
+                assert isinstance(val, unicodestr)
+                cherrypy.response.headers['ETag'] = val
+                return val
+        
+        
+        class HeaderElements(Test):
+            
+            def get_elements(self, headername):
+                e = cherrypy.request.headers.elements(headername)
+                return "\n".join([unicodestr(x) for x in e])
+        
+        
+        class Method(Test):
+            
+            def index(self):
+                m = cherrypy.request.method
+                if m in defined_http_methods or m == "CONNECT":
+                    return m
+                
+                if m == "LINK":
+                    raise cherrypy.HTTPError(405)
+                else:
+                    raise cherrypy.HTTPError(501)
+            
+            def parameterized(self, data):
+                return data
+            
+            def request_body(self):
+                # This should be a file object (temp file),
+                # which CP will just pipe back out if we tell it to.
+                return cherrypy.request.body
+            
+            def reachable(self):
+                return "success"
+
+        class Divorce:
+            """HTTP Method handlers shouldn't collide with normal method names.
+            For example, a GET-handler shouldn't collide with a method named 'get'.
+            
+            If you build HTTP method dispatching into CherryPy, rewrite this class
+            to use your new dispatch mechanism and make sure that:
+                "GET /divorce HTTP/1.1" maps to divorce.index() and
+                "GET /divorce/get?ID=13 HTTP/1.1" maps to divorce.get()
+            """
+            
+            documents = {}
+            
+            def index(self):
+                yield "
Choose your document
\n"
+                yield "
    \n"
+                for id, contents in self.documents.items():
+                    yield ("    
  • %s: %s
    • \n"
+                           % (id, id, contents))
+                yield "
"
+            index.exposed = True
+            
+            def get(self, ID):
+                return ("Divorce document %s: %s" %
+                        (ID, self.documents.get(ID, "empty")))
+            get.exposed = True
+
+        root.divorce = Divorce()
+
+
+        class ThreadLocal(Test):
+            
+            def index(self):
+                existing = repr(getattr(cherrypy.request, "asdf", None))
+                cherrypy.request.asdf = "rassfrassin"
+                return existing
+        
+        appconf = {
+            '/method': {'request.methods_with_bodies': ("POST", "PUT", "PROPFIND")},
+            }
+        cherrypy.tree.mount(root, config=appconf)
+    setup_server = staticmethod(setup_server)
+
+    def test_scheme(self):
+        self.getPage("/scheme")
+        self.assertBody(self.scheme)
+    
+    def testParams(self):
+        self.getPage("/params/?thing=a")
+        self.assertBody("u'a'")
+        
+        self.getPage("/params/?thing=a&thing=b&thing=c")
+        self.assertBody("[u'a', u'b', u'c']")
+
+        # Test friendly error message when given params are not accepted.
+        cherrypy.config.update({"request.show_mismatched_params": True})
+        self.getPage("/params/?notathing=meeting")
+        self.assertInBody("Missing parameters: thing")
+        self.getPage("/params/?thing=meeting¬athing=meeting")
+        self.assertInBody("Unexpected query string parameters: notathing")
+        
+        # Test ability to turn off friendly error messages
+        cherrypy.config.update({"request.show_mismatched_params": False})
+        self.getPage("/params/?notathing=meeting")
+        self.assertInBody("Not Found")
+        self.getPage("/params/?thing=meeting¬athing=meeting")
+        self.assertInBody("Not Found")
+
+        # Test "% HEX HEX"-encoded URL, param keys, and values
+        self.getPage("/params/%d4%20%e3/cheese?Gruy%E8re=Bulgn%e9ville")
+        self.assertBody(r"args: ('\xd4 \xe3', 'cheese') "
+                        r"kwargs: {'Gruy\xe8re': u'Bulgn\xe9ville'}")
+        
+        # Make sure that encoded = and & get parsed correctly
+        self.getPage("/params/code?url=http%3A//cherrypy.org/index%3Fa%3D1%26b%3D2")
+        self.assertBody(r"args: ('code',) "
+                        r"kwargs: {'url': u'http://cherrypy.org/index?a=1&b=2'}")
+        
+        # Test coordinates sent by 
+        self.getPage("/params/ismap?223,114")
+        self.assertBody("Coordinates: 223, 114")
+        
+        # Test "name[key]" dict-like params
+        self.getPage("/params/dictlike?a[1]=1&a[2]=2&b=foo&b[bar]=baz")
+        self.assertBody(
+            "args: ('dictlike',) "
+            "kwargs: {'a[1]': u'1', 'b[bar]': u'baz', 'b': u'foo', 'a[2]': u'2'}")
+
+    def testParamErrors(self):
+
+        # test that all of the handlers work when given 
+        # the correct parameters in order to ensure that the
+        # errors below aren't coming from some other source.
+        for uri in (
+                '/paramerrors/one_positional?param1=foo',
+                '/paramerrors/one_positional_args?param1=foo',
+                '/paramerrors/one_positional_args/foo',
+                '/paramerrors/one_positional_args/foo/bar/baz',
+                '/paramerrors/one_positional_args_kwargs?param1=foo¶m2=bar',
+                '/paramerrors/one_positional_args_kwargs/foo?param2=bar¶m3=baz',
+                '/paramerrors/one_positional_args_kwargs/foo/bar/baz?param2=bar¶m3=baz',
+                '/paramerrors/one_positional_kwargs?param1=foo¶m2=bar¶m3=baz',
+                '/paramerrors/one_positional_kwargs/foo?param4=foo¶m2=bar¶m3=baz',
+                '/paramerrors/no_positional',
+                '/paramerrors/no_positional_args/foo',
+                '/paramerrors/no_positional_args/foo/bar/baz',
+                '/paramerrors/no_positional_args_kwargs?param1=foo¶m2=bar',
+                '/paramerrors/no_positional_args_kwargs/foo?param2=bar',
+                '/paramerrors/no_positional_args_kwargs/foo/bar/baz?param2=bar¶m3=baz',
+                '/paramerrors/no_positional_kwargs?param1=foo¶m2=bar',
+                '/paramerrors/callable_object',
+            ):
+            self.getPage(uri)
+            self.assertStatus(200)
+
+        # query string parameters are part of the URI, so if they are wrong
+        # for a particular handler, the status MUST be a 404.
+        error_msgs = [
+                'Missing parameters',
+                'Nothing matches the given URI',
+                'Multiple values for parameters',
+                'Unexpected query string parameters',
+                'Unexpected body parameters',
+            ]
+        for uri, msg in (
+            ('/paramerrors/one_positional', error_msgs[0]),
+            ('/paramerrors/one_positional?foo=foo', error_msgs[0]),
+            ('/paramerrors/one_positional/foo/bar/baz', error_msgs[1]),
+            ('/paramerrors/one_positional/foo?param1=foo', error_msgs[2]),
+            ('/paramerrors/one_positional/foo?param1=foo¶m2=foo', error_msgs[2]),
+            ('/paramerrors/one_positional_args/foo?param1=foo¶m2=foo', error_msgs[2]),
+            ('/paramerrors/one_positional_args/foo/bar/baz?param2=foo', error_msgs[3]),
+            ('/paramerrors/one_positional_args_kwargs/foo/bar/baz?param1=bar¶m3=baz', error_msgs[2]),
+            ('/paramerrors/one_positional_kwargs/foo?param1=foo¶m2=bar¶m3=baz', error_msgs[2]),
+            ('/paramerrors/no_positional/boo', error_msgs[1]),
+            ('/paramerrors/no_positional?param1=foo', error_msgs[3]),
+            ('/paramerrors/no_positional_args/boo?param1=foo', error_msgs[3]),
+            ('/paramerrors/no_positional_kwargs/boo?param1=foo', error_msgs[1]),
+            ('/paramerrors/callable_object?param1=foo', error_msgs[3]),
+            ('/paramerrors/callable_object/boo', error_msgs[1]),
+            ):
+            for show_mismatched_params in (True, False):
+                cherrypy.config.update({'request.show_mismatched_params': show_mismatched_params})
+                self.getPage(uri)
+                self.assertStatus(404)
+                if show_mismatched_params:
+                    self.assertInBody(msg)
+                else:
+                    self.assertInBody("Not Found")
+
+        # if body parameters are wrong, a 400 must be returned.
+        for uri, body, msg in (
+                ('/paramerrors/one_positional/foo', 'param1=foo', error_msgs[2]),
+                ('/paramerrors/one_positional/foo', 'param1=foo¶m2=foo', error_msgs[2]),
+                ('/paramerrors/one_positional_args/foo', 'param1=foo¶m2=foo', error_msgs[2]),
+                ('/paramerrors/one_positional_args/foo/bar/baz', 'param2=foo', error_msgs[4]),
+                ('/paramerrors/one_positional_args_kwargs/foo/bar/baz', 'param1=bar¶m3=baz', error_msgs[2]),
+                ('/paramerrors/one_positional_kwargs/foo', 'param1=foo¶m2=bar¶m3=baz', error_msgs[2]),
+                ('/paramerrors/no_positional', 'param1=foo', error_msgs[4]),
+                ('/paramerrors/no_positional_args/boo', 'param1=foo', error_msgs[4]),
+                ('/paramerrors/callable_object', 'param1=foo', error_msgs[4]),
+            ):
+            for show_mismatched_params in (True, False):
+                cherrypy.config.update({'request.show_mismatched_params': show_mismatched_params})
+                self.getPage(uri, method='POST', body=body)
+                self.assertStatus(400)
+                if show_mismatched_params:
+                    self.assertInBody(msg)
+                else:
+                    self.assertInBody("Bad Request")
+
+
+        # even if body parameters are wrong, if we get the uri wrong, then 
+        # it's a 404
+        for uri, body, msg in (
+                ('/paramerrors/one_positional?param2=foo', 'param1=foo', error_msgs[3]),
+                ('/paramerrors/one_positional/foo/bar', 'param2=foo', error_msgs[1]),
+                ('/paramerrors/one_positional_args/foo/bar?param2=foo', 'param3=foo', error_msgs[3]),
+                ('/paramerrors/one_positional_kwargs/foo/bar', 'param2=bar¶m3=baz', error_msgs[1]),
+                ('/paramerrors/no_positional?param1=foo', 'param2=foo', error_msgs[3]),
+                ('/paramerrors/no_positional_args/boo?param2=foo', 'param1=foo', error_msgs[3]),
+                ('/paramerrors/callable_object?param2=bar', 'param1=foo', error_msgs[3]),
+            ):
+            for show_mismatched_params in (True, False):
+                cherrypy.config.update({'request.show_mismatched_params': show_mismatched_params})
+                self.getPage(uri, method='POST', body=body)
+                self.assertStatus(404)
+                if show_mismatched_params:
+                    self.assertInBody(msg)
+                else:
+                    self.assertInBody("Not Found")
+
+        # In the case that a handler raises a TypeError we should
+        # let that type error through.
+        for uri in (
+                '/paramerrors/raise_type_error',
+                '/paramerrors/raise_type_error_with_default_param?x=0',
+                '/paramerrors/raise_type_error_with_default_param?x=0&y=0',
+            ):
+            self.getPage(uri, method='GET')
+            self.assertStatus(500)
+            self.assertTrue('Client Error', self.body)
+
+    def testErrorHandling(self):
+        self.getPage("/error/missing")
+        self.assertStatus(404)
+        self.assertErrorPage(404, "The path '/error/missing' was not found.")
+        
+        ignore = helper.webtest.ignored_exceptions
+        ignore.append(ValueError)
+        try:
+            valerr = '\n    raise ValueError()\nValueError'
+            self.getPage("/error/page_method")
+            self.assertErrorPage(500, pattern=valerr)
+            
+            self.getPage("/error/page_yield")
+            self.assertErrorPage(500, pattern=valerr)
+            
+            if (cherrypy.server.protocol_version == "HTTP/1.0" or
+                getattr(cherrypy.server, "using_apache", False)):
+                self.getPage("/error/page_streamed")
+                # Because this error is raised after the response body has
+                # started, the status should not change to an error status.
+                self.assertStatus(200)
+                self.assertBody("word up")
+            else:
+                # Under HTTP/1.1, the chunked transfer-coding is used.
+                # The HTTP client will choke when the output is incomplete.
+                self.assertRaises((ValueError, IncompleteRead), self.getPage,
+                                  "/error/page_streamed")
+            
+            # No traceback should be present
+            self.getPage("/error/cause_err_in_finalize")
+            msg = "Illegal response status from server ('ZOO' is non-numeric)."
+            self.assertErrorPage(500, msg, None)
+        finally:
+            ignore.pop()
+        
+        # Test HTTPError with a reason-phrase in the status arg.
+        self.getPage('/error/reason_phrase')
+        self.assertStatus("410 Gone fishin'")
+        
+        # Test custom error page for a specific error.
+        self.getPage("/error/custom")
+        self.assertStatus(404)
+        self.assertBody("Hello, world\r\n" + (" " * 499))
+        
+        # Test custom error page for a specific error.
+        self.getPage("/error/custom?err=401")
+        self.assertStatus(401)
+        self.assertBody("Error 401 Unauthorized - Well, I'm very sorry but you haven't paid!")
+        
+        # Test default custom error page.
+        self.getPage("/error/custom_default")
+        self.assertStatus(500)
+        self.assertBody("Error 500 Internal Server Error - Well, I'm very sorry but you haven't paid!".ljust(513))
+        
+        # Test error in custom error page (ticket #305).
+        # Note that the message is escaped for HTML (ticket #310).
+        self.getPage("/error/noexist")
+        self.assertStatus(404)
+        msg = ("No, <b>really</b>, not found!
"
+               "In addition, the custom error page failed:\n
"
+               "IOError: [Errno 2] No such file or directory: 'nonexistent.html'")
+        self.assertInBody(msg)
+        
+        if getattr(cherrypy.server, "using_apache", False):
+            pass
+        else:
+            # Test throw_errors (ticket #186).
+            self.getPage("/error/rethrow")
+            self.assertInBody("raise ValueError()")
+    
+    def testExpect(self):
+        e = ('Expect', '100-continue')
+        self.getPage("/headerelements/get_elements?headername=Expect", [e])
+        self.assertBody('100-continue')
+        
+        self.getPage("/expect/expectation_failed", [e])
+        self.assertStatus(417)
+    
+    def testHeaderElements(self):
+        # Accept-* header elements should be sorted, with most preferred first.
+        h = [('Accept', 'audio/*; q=0.2, audio/basic')]
+        self.getPage("/headerelements/get_elements?headername=Accept", h)
+        self.assertStatus(200)
+        self.assertBody("audio/basic\n"
+                        "audio/*;q=0.2")
+        
+        h = [('Accept', 'text/plain; q=0.5, text/html, text/x-dvi; q=0.8, text/x-c')]
+        self.getPage("/headerelements/get_elements?headername=Accept", h)
+        self.assertStatus(200)
+        self.assertBody("text/x-c\n"
+                        "text/html\n"
+                        "text/x-dvi;q=0.8\n"
+                        "text/plain;q=0.5")
+        
+        # Test that more specific media ranges get priority.
+        h = [('Accept', 'text/*, text/html, text/html;level=1, */*')]
+        self.getPage("/headerelements/get_elements?headername=Accept", h)
+        self.assertStatus(200)
+        self.assertBody("text/html;level=1\n"
+                        "text/html\n"
+                        "text/*\n"
+                        "*/*")
+        
+        # Test Accept-Charset
+        h = [('Accept-Charset', 'iso-8859-5, unicode-1-1;q=0.8')]
+        self.getPage("/headerelements/get_elements?headername=Accept-Charset", h)
+        self.assertStatus("200 OK")
+        self.assertBody("iso-8859-5\n"
+                        "unicode-1-1;q=0.8")
+        
+        # Test Accept-Encoding
+        h = [('Accept-Encoding', 'gzip;q=1.0, identity; q=0.5, *;q=0')]
+        self.getPage("/headerelements/get_elements?headername=Accept-Encoding", h)
+        self.assertStatus("200 OK")
+        self.assertBody("gzip;q=1.0\n"
+                        "identity;q=0.5\n"
+                        "*;q=0")
+        
+        # Test Accept-Language
+        h = [('Accept-Language', 'da, en-gb;q=0.8, en;q=0.7')]
+        self.getPage("/headerelements/get_elements?headername=Accept-Language", h)
+        self.assertStatus("200 OK")
+        self.assertBody("da\n"
+                        "en-gb;q=0.8\n"
+                        "en;q=0.7")
+        
+        # Test malformed header parsing. See http://www.cherrypy.org/ticket/763.
+        self.getPage("/headerelements/get_elements?headername=Content-Type",
+                     # Note the illegal trailing ";"
+                     headers=[('Content-Type', 'text/html; charset=utf-8;')])
+        self.assertStatus(200)
+        self.assertBody("text/html;charset=utf-8")
+    
+    def test_repeated_headers(self):
+        # Test that two request headers are collapsed into one.
+        # See http://www.cherrypy.org/ticket/542.
+        self.getPage("/headers/Accept-Charset",
+                     headers=[("Accept-Charset", "iso-8859-5"),
+                              ("Accept-Charset", "unicode-1-1;q=0.8")])
+        self.assertBody("iso-8859-5, unicode-1-1;q=0.8")
+        
+        # Tests that each header only appears once, regardless of case.
+        self.getPage("/headers/doubledheaders")
+        self.assertBody("double header test")
+        hnames = [name.title() for name, val in self.headers]
+        for key in ['Content-Length', 'Content-Type', 'Date',
+                    'Expires', 'Location', 'Server']:
+            self.assertEqual(hnames.count(key), 1, self.headers)
+    
+    def test_encoded_headers(self):
+        # First, make sure the innards work like expected.
+        self.assertEqual(httputil.decode_TEXT(u"=?utf-8?q?f=C3=BCr?="), u"f\xfcr")
+        
+        if cherrypy.server.protocol_version == "HTTP/1.1":
+            # Test RFC-2047-encoded request and response header values
+            u = u'\u212bngstr\xf6m'
+            c = u"=E2=84=ABngstr=C3=B6m"
+            self.getPage("/headers/ifmatch", [('If-Match', u'=?utf-8?q?%s?=' % c)])
+            # The body should be utf-8 encoded.
+            self.assertBody("\xe2\x84\xabngstr\xc3\xb6m")
+            # But the Etag header should be RFC-2047 encoded (binary)
+            self.assertHeader("ETag", u'=?utf-8?b?4oSrbmdzdHLDtm0=?=')
+            
+            # Test a *LONG* RFC-2047-encoded request and response header value
+            self.getPage("/headers/ifmatch",
+                         [('If-Match', u'=?utf-8?q?%s?=' % (c * 10))])
+            self.assertBody("\xe2\x84\xabngstr\xc3\xb6m" * 10)
+            # Note: this is different output for Python3, but it decodes fine.
+            etag = self.assertHeader("ETag",
+                '=?utf-8?b?4oSrbmdzdHLDtm3ihKtuZ3N0csO2beKEq25nc3Ryw7Zt'
+                '4oSrbmdzdHLDtm3ihKtuZ3N0csO2beKEq25nc3Ryw7Zt'
+                '4oSrbmdzdHLDtm3ihKtuZ3N0csO2beKEq25nc3Ryw7Zt'
+                '4oSrbmdzdHLDtm0=?=')
+            self.assertEqual(httputil.decode_TEXT(etag), u * 10)
+    
+    def test_header_presence(self):
+        # If we don't pass a Content-Type header, it should not be present
+        # in cherrypy.request.headers
+        self.getPage("/headers/Content-Type",
+                     headers=[])
+        self.assertStatus(500)
+        
+        # If Content-Type is present in the request, it should be present in
+        # cherrypy.request.headers
+        self.getPage("/headers/Content-Type",
+                     headers=[("Content-type", "application/json")])
+        self.assertBody("application/json")
+    
+    def test_basic_HTTPMethods(self):
+        helper.webtest.methods_with_bodies = ("POST", "PUT", "PROPFIND")
+        
+        # Test that all defined HTTP methods work.
+        for m in defined_http_methods:
+            self.getPage("/method/", method=m)
+            
+            # HEAD requests should not return any body.
+            if m == "HEAD":
+                self.assertBody("")
+            elif m == "TRACE":
+                # Some HTTP servers (like modpy) have their own TRACE support
+                self.assertEqual(self.body[:5], ntob("TRACE"))
+            else:
+                self.assertBody(m)
+        
+        # Request a PUT method with a form-urlencoded body
+        self.getPage("/method/parameterized", method="PUT",
+                       body="data=on+top+of+other+things")
+        self.assertBody("on top of other things")
+        
+        # Request a PUT method with a file body
+        b = "one thing on top of another"
+        h = [("Content-Type", "text/plain"),
+             ("Content-Length", str(len(b)))]
+        self.getPage("/method/request_body", headers=h, method="PUT", body=b)
+        self.assertStatus(200)
+        self.assertBody(b)
+        
+        # Request a PUT method with a file body but no Content-Type.
+        # See http://www.cherrypy.org/ticket/790.
+        b = ntob("one thing on top of another")
+        self.persistent = True
+        try:
+            conn = self.HTTP_CONN
+            conn.putrequest("PUT", "/method/request_body", skip_host=True)
+            conn.putheader("Host", self.HOST)
+            conn.putheader('Content-Length', str(len(b)))
+            conn.endheaders()
+            conn.send(b)
+            response = conn.response_class(conn.sock, method="PUT")
+            response.begin()
+            self.assertEqual(response.status, 200)
+            self.body = response.read()
+            self.assertBody(b)
+        finally:
+            self.persistent = False
+        
+        # Request a PUT method with no body whatsoever (not an empty one).
+        # See http://www.cherrypy.org/ticket/650.
+        # Provide a C-T or webtest will provide one (and a C-L) for us.
+        h = [("Content-Type", "text/plain")]
+        self.getPage("/method/reachable", headers=h, method="PUT")
+        self.assertStatus(411)
+        
+        # Request a custom method with a request body
+        b = ('\n\n'
+             ''
+             '')
+        h = [('Content-Type', 'text/xml'),
+             ('Content-Length', str(len(b)))]
+        self.getPage("/method/request_body", headers=h, method="PROPFIND", body=b)
+        self.assertStatus(200)
+        self.assertBody(b)
+        
+        # Request a disallowed method
+        self.getPage("/method/", method="LINK")
+        self.assertStatus(405)
+        
+        # Request an unknown method
+        self.getPage("/method/", method="SEARCH")
+        self.assertStatus(501)
+        
+        # For method dispatchers: make sure that an HTTP method doesn't
+        # collide with a virtual path atom. If you build HTTP-method
+        # dispatching into the core, rewrite these handlers to use
+        # your dispatch idioms.
+        self.getPage("/divorce/get?ID=13")
+        self.assertBody('Divorce document 13: empty')
+        self.assertStatus(200)
+        self.getPage("/divorce/", method="GET")
+        self.assertBody('
Choose your document
\n
    \n
')
+        self.assertStatus(200)
+    
+    def test_CONNECT_method(self):
+        if getattr(cherrypy.server, "using_apache", False):
+            return self.skip("skipped due to known Apache differences... ")
+        
+        self.getPage("/method/", method="CONNECT")
+        self.assertBody("CONNECT")
+    
+    def testEmptyThreadlocals(self):
+        results = []
+        for x in range(20):
+            self.getPage("/threadlocal/")
+            results.append(self.body)
+        self.assertEqual(results, [ntob("None")] * 20)
+
diff --git a/cherrypy/test/test_routes.py b/cherrypy/test/test_routes.py
new file mode 100644
index 00000000..a8062f8f
--- /dev/null
+++ b/cherrypy/test/test_routes.py
@@ -0,0 +1,69 @@
+import os
+curdir = os.path.join(os.getcwd(), os.path.dirname(__file__))
+
+import cherrypy
+
+from cherrypy.test import helper
+import nose
+
+class RoutesDispatchTest(helper.CPWebCase):
+
+    def setup_server():
+
+        try:
+            import routes
+        except ImportError:
+            raise nose.SkipTest('Install routes to test RoutesDispatcher code')
+
+        class Dummy:
+            def index(self):
+                return "I said good day!"
+        
+        class City:
+            
+            def __init__(self, name):
+                self.name = name
+                self.population = 10000
+            
+            def index(self, **kwargs):
+                return "Welcome to %s, pop. %s" % (self.name, self.population)
+            index._cp_config = {'tools.response_headers.on': True,
+                                'tools.response_headers.headers': [('Content-Language', 'en-GB')]}
+            
+            def update(self, **kwargs):
+                self.population = kwargs['pop']
+                return "OK"
+            
+        d = cherrypy.dispatch.RoutesDispatcher()
+        d.connect(action='index', name='hounslow', route='/hounslow',
+                  controller=City('Hounslow'))
+        d.connect(name='surbiton', route='/surbiton', controller=City('Surbiton'),
+                  action='index', conditions=dict(method=['GET']))
+        d.mapper.connect('/surbiton', controller='surbiton',
+                         action='update', conditions=dict(method=['POST']))
+        d.connect('main', ':action', controller=Dummy())
+        
+        conf = {'/': {'request.dispatch': d}}
+        cherrypy.tree.mount(root=None, config=conf)
+    setup_server = staticmethod(setup_server)
+
+    def test_Routes_Dispatch(self):
+        self.getPage("/hounslow")
+        self.assertStatus("200 OK")
+        self.assertBody("Welcome to Hounslow, pop. 10000")
+        
+        self.getPage("/foo")
+        self.assertStatus("404 Not Found")
+        
+        self.getPage("/surbiton")
+        self.assertStatus("200 OK")
+        self.assertBody("Welcome to Surbiton, pop. 10000")
+        
+        self.getPage("/surbiton", method="POST", body="pop=1327")
+        self.assertStatus("200 OK")
+        self.assertBody("OK")
+        self.getPage("/surbiton")
+        self.assertStatus("200 OK")
+        self.assertHeader("Content-Language", "en-GB")
+        self.assertBody("Welcome to Surbiton, pop. 1327")
+
diff --git a/cherrypy/test/test_session.py b/cherrypy/test/test_session.py
new file mode 100755
index 00000000..874023e2
--- /dev/null
+++ b/cherrypy/test/test_session.py
@@ -0,0 +1,464 @@
+import os
+localDir = os.path.dirname(__file__)
+import sys
+import threading
+import time
+
+import cherrypy
+from cherrypy._cpcompat import copykeys, HTTPConnection, HTTPSConnection
+from cherrypy.lib import sessions
+from cherrypy.lib.httputil import response_codes
+
+def http_methods_allowed(methods=['GET', 'HEAD']):
+    method = cherrypy.request.method.upper()
+    if method not in methods:
+        cherrypy.response.headers['Allow'] = ", ".join(methods)
+        raise cherrypy.HTTPError(405)
+
+cherrypy.tools.allow = cherrypy.Tool('on_start_resource', http_methods_allowed)
+
+
+def setup_server():
+    
+    class Root:
+        
+        _cp_config = {'tools.sessions.on': True,
+                      'tools.sessions.storage_type' : 'ram',
+                      'tools.sessions.storage_path' : localDir,
+                      'tools.sessions.timeout': (1.0 / 60),
+                      'tools.sessions.clean_freq': (1.0 / 60),
+                      }
+        
+        def clear(self):
+            cherrypy.session.cache.clear()
+        clear.exposed = True
+        
+        def data(self):
+            cherrypy.session['aha'] = 'foo'
+            return repr(cherrypy.session._data)
+        data.exposed = True
+        
+        def testGen(self):
+            counter = cherrypy.session.get('counter', 0) + 1
+            cherrypy.session['counter'] = counter
+            yield str(counter)
+        testGen.exposed = True
+        
+        def testStr(self):
+            counter = cherrypy.session.get('counter', 0) + 1
+            cherrypy.session['counter'] = counter
+            return str(counter)
+        testStr.exposed = True
+        
+        def setsessiontype(self, newtype):
+            self.__class__._cp_config.update({'tools.sessions.storage_type': newtype})
+            if hasattr(cherrypy, "session"):
+                del cherrypy.session
+            cls = getattr(sessions, newtype.title() + 'Session')
+            if cls.clean_thread:
+                cls.clean_thread.stop()
+                cls.clean_thread.unsubscribe()
+                del cls.clean_thread
+        setsessiontype.exposed = True
+        setsessiontype._cp_config = {'tools.sessions.on': False}
+        
+        def index(self):
+            sess = cherrypy.session
+            c = sess.get('counter', 0) + 1
+            time.sleep(0.01)
+            sess['counter'] = c
+            return str(c)
+        index.exposed = True
+        
+        def keyin(self, key):
+            return str(key in cherrypy.session)
+        keyin.exposed = True
+        
+        def delete(self):
+            cherrypy.session.delete()
+            sessions.expire()
+            return "done"
+        delete.exposed = True
+        
+        def delkey(self, key):
+            del cherrypy.session[key]
+            return "OK"
+        delkey.exposed = True
+        
+        def blah(self):
+            return self._cp_config['tools.sessions.storage_type']
+        blah.exposed = True
+        
+        def iredir(self):
+            raise cherrypy.InternalRedirect('/blah')
+        iredir.exposed = True
+        
+        def restricted(self):
+            return cherrypy.request.method
+        restricted.exposed = True
+        restricted._cp_config = {'tools.allow.on': True,
+                                 'tools.allow.methods': ['GET']}
+        
+        def regen(self):
+            cherrypy.tools.sessions.regenerate()
+            return "logged in"
+        regen.exposed = True
+        
+        def length(self):
+            return str(len(cherrypy.session))
+        length.exposed = True
+        
+        def session_cookie(self):
+            # Must load() to start the clean thread.
+            cherrypy.session.load()
+            return cherrypy.session.id
+        session_cookie.exposed = True
+        session_cookie._cp_config = {
+            'tools.sessions.path': '/session_cookie',
+            'tools.sessions.name': 'temp',
+            'tools.sessions.persistent': False}
+    
+    cherrypy.tree.mount(Root())
+
+
+from cherrypy.test import helper
+
+class SessionTest(helper.CPWebCase):
+    setup_server = staticmethod(setup_server)
+    
+    def tearDown(self):
+        # Clean up sessions.
+        for fname in os.listdir(localDir):
+            if fname.startswith(sessions.FileSession.SESSION_PREFIX):
+                os.unlink(os.path.join(localDir, fname))
+    
+    def test_0_Session(self):
+        self.getPage('/setsessiontype/ram')
+        self.getPage('/clear')
+        
+        # Test that a normal request gets the same id in the cookies.
+        # Note: this wouldn't work if /data didn't load the session.
+        self.getPage('/data')
+        self.assertBody("{'aha': 'foo'}")
+        c = self.cookies[0]
+        self.getPage('/data', self.cookies)
+        self.assertEqual(self.cookies[0], c)
+        
+        self.getPage('/testStr')
+        self.assertBody('1')
+        cookie_parts = dict([p.strip().split('=')
+                             for p in self.cookies[0][1].split(";")])
+        # Assert there is an 'expires' param
+        self.assertEqual(set(cookie_parts.keys()),
+                         set(['session_id', 'expires', 'Path']))
+        self.getPage('/testGen', self.cookies)
+        self.assertBody('2')
+        self.getPage('/testStr', self.cookies)
+        self.assertBody('3')
+        self.getPage('/data', self.cookies)
+        self.assertBody("{'aha': 'foo', 'counter': 3}")
+        self.getPage('/length', self.cookies)
+        self.assertBody('2')
+        self.getPage('/delkey?key=counter', self.cookies)
+        self.assertStatus(200)
+        
+        self.getPage('/setsessiontype/file')
+        self.getPage('/testStr')
+        self.assertBody('1')
+        self.getPage('/testGen', self.cookies)
+        self.assertBody('2')
+        self.getPage('/testStr', self.cookies)
+        self.assertBody('3')
+        self.getPage('/delkey?key=counter', self.cookies)
+        self.assertStatus(200)
+        
+        # Wait for the session.timeout (1 second)
+        time.sleep(2)
+        self.getPage('/')
+        self.assertBody('1')
+        self.getPage('/length', self.cookies)
+        self.assertBody('1')
+        
+        # Test session __contains__
+        self.getPage('/keyin?key=counter', self.cookies)
+        self.assertBody("True")
+        cookieset1 = self.cookies
+        
+        # Make a new session and test __len__ again
+        self.getPage('/')
+        self.getPage('/length', self.cookies)
+        self.assertBody('2')
+        
+        # Test session delete
+        self.getPage('/delete', self.cookies)
+        self.assertBody("done")
+        self.getPage('/delete', cookieset1)
+        self.assertBody("done")
+        f = lambda: [x for x in os.listdir(localDir) if x.startswith('session-')]
+        self.assertEqual(f(), [])
+        
+        # Wait for the cleanup thread to delete remaining session files
+        self.getPage('/')
+        f = lambda: [x for x in os.listdir(localDir) if x.startswith('session-')]
+        self.assertNotEqual(f(), [])
+        time.sleep(2)
+        self.assertEqual(f(), [])
+    
+    def test_1_Ram_Concurrency(self):
+        self.getPage('/setsessiontype/ram')
+        self._test_Concurrency()
+    
+    def test_2_File_Concurrency(self):
+        self.getPage('/setsessiontype/file')
+        self._test_Concurrency()
+    
+    def _test_Concurrency(self):
+        client_thread_count = 5
+        request_count = 30
+        
+        # Get initial cookie
+        self.getPage("/")
+        self.assertBody("1")
+        cookies = self.cookies
+        
+        data_dict = {}
+        errors = []
+        
+        def request(index):
+            if self.scheme == 'https':
+                c = HTTPSConnection('%s:%s' % (self.interface(), self.PORT))
+            else:
+                c = HTTPConnection('%s:%s' % (self.interface(), self.PORT))
+            for i in range(request_count):
+                c.putrequest('GET', '/')
+                for k, v in cookies:
+                    c.putheader(k, v)
+                c.endheaders()
+                response = c.getresponse()
+                body = response.read()
+                if response.status != 200 or not body.isdigit():
+                    errors.append((response.status, body))
+                else:
+                    data_dict[index] = max(data_dict[index], int(body))
+                # Uncomment the following line to prove threads overlap.
+##                sys.stdout.write("%d " % index)
+        
+        # Start  requests from each of
+        #  concurrent clients
+        ts = []
+        for c in range(client_thread_count):
+            data_dict[c] = 0
+            t = threading.Thread(target=request, args=(c,))
+            ts.append(t)
+            t.start()
+        
+        for t in ts:
+            t.join()
+        
+        hitcount = max(data_dict.values())
+        expected = 1 + (client_thread_count * request_count)
+        
+        for e in errors:
+            print(e)
+        self.assertEqual(hitcount, expected)
+    
+    def test_3_Redirect(self):
+        # Start a new session
+        self.getPage('/testStr')
+        self.getPage('/iredir', self.cookies)
+        self.assertBody("file")
+    
+    def test_4_File_deletion(self):
+        # Start a new session
+        self.getPage('/testStr')
+        # Delete the session file manually and retry.
+        id = self.cookies[0][1].split(";", 1)[0].split("=", 1)[1]
+        path = os.path.join(localDir, "session-" + id)
+        os.unlink(path)
+        self.getPage('/testStr', self.cookies)
+    
+    def test_5_Error_paths(self):
+        self.getPage('/unknown/page')
+        self.assertErrorPage(404, "The path '/unknown/page' was not found.")
+        
+        # Note: this path is *not* the same as above. The above
+        # takes a normal route through the session code; this one
+        # skips the session code's before_handler and only calls
+        # before_finalize (save) and on_end (close). So the session
+        # code has to survive calling save/close without init.
+        self.getPage('/restricted', self.cookies, method='POST')
+        self.assertErrorPage(405, response_codes[405])
+    
+    def test_6_regenerate(self):
+        self.getPage('/testStr')
+        # grab the cookie ID
+        id1 = self.cookies[0][1].split(";", 1)[0].split("=", 1)[1]
+        self.getPage('/regen')
+        self.assertBody('logged in')
+        id2 = self.cookies[0][1].split(";", 1)[0].split("=", 1)[1]
+        self.assertNotEqual(id1, id2)
+        
+        self.getPage('/testStr')
+        # grab the cookie ID
+        id1 = self.cookies[0][1].split(";", 1)[0].split("=", 1)[1]
+        self.getPage('/testStr',
+                     headers=[('Cookie',
+                               'session_id=maliciousid; '
+                               'expires=Sat, 27 Oct 2017 04:18:28 GMT; Path=/;')])
+        id2 = self.cookies[0][1].split(";", 1)[0].split("=", 1)[1]
+        self.assertNotEqual(id1, id2)
+        self.assertNotEqual(id2, 'maliciousid')
+    
+    def test_7_session_cookies(self):
+        self.getPage('/setsessiontype/ram')
+        self.getPage('/clear')
+        self.getPage('/session_cookie')
+        # grab the cookie ID
+        cookie_parts = dict([p.strip().split('=') for p in self.cookies[0][1].split(";")])
+        # Assert there is no 'expires' param
+        self.assertEqual(set(cookie_parts.keys()), set(['temp', 'Path']))
+        id1 = cookie_parts['temp']
+        self.assertEqual(copykeys(sessions.RamSession.cache), [id1])
+        
+        # Send another request in the same "browser session".
+        self.getPage('/session_cookie', self.cookies)
+        cookie_parts = dict([p.strip().split('=') for p in self.cookies[0][1].split(";")])
+        # Assert there is no 'expires' param
+        self.assertEqual(set(cookie_parts.keys()), set(['temp', 'Path']))
+        self.assertBody(id1)
+        self.assertEqual(copykeys(sessions.RamSession.cache), [id1])
+        
+        # Simulate a browser close by just not sending the cookies
+        self.getPage('/session_cookie')
+        # grab the cookie ID
+        cookie_parts = dict([p.strip().split('=') for p in self.cookies[0][1].split(";")])
+        # Assert there is no 'expires' param
+        self.assertEqual(set(cookie_parts.keys()), set(['temp', 'Path']))
+        # Assert a new id has been generated...
+        id2 = cookie_parts['temp']
+        self.assertNotEqual(id1, id2)
+        self.assertEqual(set(sessions.RamSession.cache.keys()), set([id1, id2]))
+        
+        # Wait for the session.timeout on both sessions
+        time.sleep(2.5)
+        cache = copykeys(sessions.RamSession.cache)
+        if cache:
+            if cache == [id2]:
+                self.fail("The second session did not time out.")
+            else:
+                self.fail("Unknown session id in cache: %r", cache)
+
+
+import socket
+try:
+    import memcache
+    
+    host, port = '127.0.0.1', 11211
+    for res in socket.getaddrinfo(host, port, socket.AF_UNSPEC,
+                                  socket.SOCK_STREAM):
+        af, socktype, proto, canonname, sa = res
+        s = None
+        try:
+            s = socket.socket(af, socktype, proto)
+            # See http://groups.google.com/group/cherrypy-users/
+            #        browse_frm/thread/bbfe5eb39c904fe0
+            s.settimeout(1.0)
+            s.connect((host, port))
+            s.close()
+        except socket.error:
+            if s:
+                s.close()
+            raise
+        break
+except (ImportError, socket.error):
+    class MemcachedSessionTest(helper.CPWebCase):
+        setup_server = staticmethod(setup_server)
+        
+        def test(self):
+            return self.skip("memcached not reachable ")
+else:
+    class MemcachedSessionTest(helper.CPWebCase):
+        setup_server = staticmethod(setup_server)
+        
+        def test_0_Session(self):
+            self.getPage('/setsessiontype/memcached')
+            
+            self.getPage('/testStr')
+            self.assertBody('1')
+            self.getPage('/testGen', self.cookies)
+            self.assertBody('2')
+            self.getPage('/testStr', self.cookies)
+            self.assertBody('3')
+            self.getPage('/length', self.cookies)
+            self.assertErrorPage(500)
+            self.assertInBody("NotImplementedError")
+            self.getPage('/delkey?key=counter', self.cookies)
+            self.assertStatus(200)
+            
+            # Wait for the session.timeout (1 second)
+            time.sleep(1.25)
+            self.getPage('/')
+            self.assertBody('1')
+            
+            # Test session __contains__
+            self.getPage('/keyin?key=counter', self.cookies)
+            self.assertBody("True")
+            
+            # Test session delete
+            self.getPage('/delete', self.cookies)
+            self.assertBody("done")
+        
+        def test_1_Concurrency(self):
+            client_thread_count = 5
+            request_count = 30
+            
+            # Get initial cookie
+            self.getPage("/")
+            self.assertBody("1")
+            cookies = self.cookies
+            
+            data_dict = {}
+            
+            def request(index):
+                for i in range(request_count):
+                    self.getPage("/", cookies)
+                    # Uncomment the following line to prove threads overlap.
+##                    sys.stdout.write("%d " % index)
+                if not self.body.isdigit():
+                    self.fail(self.body)
+                data_dict[index] = v = int(self.body)
+            
+            # Start  concurrent requests from
+            # each of  clients
+            ts = []
+            for c in range(client_thread_count):
+                data_dict[c] = 0
+                t = threading.Thread(target=request, args=(c,))
+                ts.append(t)
+                t.start()
+            
+            for t in ts:
+                t.join()
+            
+            hitcount = max(data_dict.values())
+            expected = 1 + (client_thread_count * request_count)
+            self.assertEqual(hitcount, expected)
+        
+        def test_3_Redirect(self):
+            # Start a new session
+            self.getPage('/testStr')
+            self.getPage('/iredir', self.cookies)
+            self.assertBody("memcached")
+        
+        def test_5_Error_paths(self):
+            self.getPage('/unknown/page')
+            self.assertErrorPage(404, "The path '/unknown/page' was not found.")
+            
+            # Note: this path is *not* the same as above. The above
+            # takes a normal route through the session code; this one
+            # skips the session code's before_handler and only calls
+            # before_finalize (save) and on_end (close). So the session
+            # code has to survive calling save/close without init.
+            self.getPage('/restricted', self.cookies, method='POST')
+            self.assertErrorPage(405, response_codes[405])
+
diff --git a/cherrypy/test/test_sessionauthenticate.py b/cherrypy/test/test_sessionauthenticate.py
new file mode 100644
index 00000000..ab1fe51e
--- /dev/null
+++ b/cherrypy/test/test_sessionauthenticate.py
@@ -0,0 +1,62 @@
+import cherrypy
+from cherrypy.test import helper
+
+
+class SessionAuthenticateTest(helper.CPWebCase):
+
+    def setup_server():
+        
+        def check(username, password):
+            # Dummy check_username_and_password function
+            if username != 'test' or password != 'password':
+                return 'Wrong login/password'
+        
+        def augment_params():
+            # A simple tool to add some things to request.params
+            # This is to check to make sure that session_auth can handle request
+            # params (ticket #780)
+            cherrypy.request.params["test"] = "test"
+
+        cherrypy.tools.augment_params = cherrypy.Tool('before_handler',
+                 augment_params, None, priority=30)
+
+        class Test:
+            
+            _cp_config = {'tools.sessions.on': True,
+                          'tools.session_auth.on': True,
+                          'tools.session_auth.check_username_and_password': check,
+                          'tools.augment_params.on': True,
+                          }
+            
+            def index(self, **kwargs):
+                return "Hi %s, you are logged in" % cherrypy.request.login
+            index.exposed = True
+        
+        cherrypy.tree.mount(Test())
+    setup_server = staticmethod(setup_server)
+
+    
+    def testSessionAuthenticate(self):
+        # request a page and check for login form
+        self.getPage('/')
+        self.assertInBody('
')
+        
+        # setup credentials
+        login_body = 'username=test&password=password&from_page=/'
+        
+        # attempt a login
+        self.getPage('/do_login', method='POST', body=login_body)
+        self.assertStatus((302, 303))
+        
+        # get the page now that we are logged in
+        self.getPage('/', self.cookies)
+        self.assertBody('Hi test, you are logged in')
+        
+        # do a logout
+        self.getPage('/do_logout', self.cookies, method='POST')
+        self.assertStatus((302, 303))
+        
+        # verify we are logged out
+        self.getPage('/', self.cookies)
+        self.assertInBody('')
+
diff --git a/cherrypy/test/test_states.py b/cherrypy/test/test_states.py
new file mode 100644
index 00000000..0f973374
--- /dev/null
+++ b/cherrypy/test/test_states.py
@@ -0,0 +1,436 @@
+from cherrypy._cpcompat import BadStatusLine, ntob
+import os
+import sys
+import threading
+import time
+
+import cherrypy
+engine = cherrypy.engine
+thisdir = os.path.join(os.getcwd(), os.path.dirname(__file__))
+
+
+class Dependency:
+
+    def __init__(self, bus):
+        self.bus = bus
+        self.running = False
+        self.startcount = 0
+        self.gracecount = 0
+        self.threads = {}
+
+    def subscribe(self):
+        self.bus.subscribe('start', self.start)
+        self.bus.subscribe('stop', self.stop)
+        self.bus.subscribe('graceful', self.graceful)
+        self.bus.subscribe('start_thread', self.startthread)
+        self.bus.subscribe('stop_thread', self.stopthread)
+
+    def start(self):
+        self.running = True
+        self.startcount += 1
+
+    def stop(self):
+        self.running = False
+
+    def graceful(self):
+        self.gracecount += 1
+
+    def startthread(self, thread_id):
+        self.threads[thread_id] = None
+
+    def stopthread(self, thread_id):
+        del self.threads[thread_id]
+
+db_connection = Dependency(engine)
+
+def setup_server():
+    class Root:
+        def index(self):
+            return "Hello World"
+        index.exposed = True
+
+        def ctrlc(self):
+            raise KeyboardInterrupt()
+        ctrlc.exposed = True
+
+        def graceful(self):
+            engine.graceful()
+            return "app was (gracefully) restarted succesfully"
+        graceful.exposed = True
+
+        def block_explicit(self):
+            while True:
+                if cherrypy.response.timed_out:
+                    cherrypy.response.timed_out = False
+                    return "broken!"
+                time.sleep(0.01)
+        block_explicit.exposed = True
+
+        def block_implicit(self):
+            time.sleep(0.5)
+            return "response.timeout = %s" % cherrypy.response.timeout
+        block_implicit.exposed = True
+
+    cherrypy.tree.mount(Root())
+    cherrypy.config.update({
+        'environment': 'test_suite',
+        'engine.deadlock_poll_freq': 0.1,
+        })
+
+    db_connection.subscribe()
+
+
+
+# ------------ Enough helpers. Time for real live test cases. ------------ #
+
+
+from cherrypy.test import helper
+
+class ServerStateTests(helper.CPWebCase):
+    setup_server = staticmethod(setup_server)
+
+    def setUp(self):
+        cherrypy.server.socket_timeout = 0.1
+
+    def test_0_NormalStateFlow(self):
+        engine.stop()
+        # Our db_connection should not be running
+        self.assertEqual(db_connection.running, False)
+        self.assertEqual(db_connection.startcount, 1)
+        self.assertEqual(len(db_connection.threads), 0)
+
+        # Test server start
+        engine.start()
+        self.assertEqual(engine.state, engine.states.STARTED)
+
+        host = cherrypy.server.socket_host
+        port = cherrypy.server.socket_port
+        self.assertRaises(IOError, cherrypy._cpserver.check_port, host, port)
+
+        # The db_connection should be running now
+        self.assertEqual(db_connection.running, True)
+        self.assertEqual(db_connection.startcount, 2)
+        self.assertEqual(len(db_connection.threads), 0)
+
+        self.getPage("/")
+        self.assertBody("Hello World")
+        self.assertEqual(len(db_connection.threads), 1)
+
+        # Test engine stop. This will also stop the HTTP server.
+        engine.stop()
+        self.assertEqual(engine.state, engine.states.STOPPED)
+
+        # Verify that our custom stop function was called
+        self.assertEqual(db_connection.running, False)
+        self.assertEqual(len(db_connection.threads), 0)
+
+        # Block the main thread now and verify that exit() works.
+        def exittest():
+            self.getPage("/")
+            self.assertBody("Hello World")
+            engine.exit()
+        cherrypy.server.start()
+        engine.start_with_callback(exittest)
+        engine.block()
+        self.assertEqual(engine.state, engine.states.EXITING)
+
+    def test_1_Restart(self):
+        cherrypy.server.start()
+        engine.start()
+
+        # The db_connection should be running now
+        self.assertEqual(db_connection.running, True)
+        grace = db_connection.gracecount
+
+        self.getPage("/")
+        self.assertBody("Hello World")
+        self.assertEqual(len(db_connection.threads), 1)
+
+        # Test server restart from this thread
+        engine.graceful()
+        self.assertEqual(engine.state, engine.states.STARTED)
+        self.getPage("/")
+        self.assertBody("Hello World")
+        self.assertEqual(db_connection.running, True)
+        self.assertEqual(db_connection.gracecount, grace + 1)
+        self.assertEqual(len(db_connection.threads), 1)
+
+        # Test server restart from inside a page handler
+        self.getPage("/graceful")
+        self.assertEqual(engine.state, engine.states.STARTED)
+        self.assertBody("app was (gracefully) restarted succesfully")
+        self.assertEqual(db_connection.running, True)
+        self.assertEqual(db_connection.gracecount, grace + 2)
+        # Since we are requesting synchronously, is only one thread used?
+        # Note that the "/graceful" request has been flushed.
+        self.assertEqual(len(db_connection.threads), 0)
+
+        engine.stop()
+        self.assertEqual(engine.state, engine.states.STOPPED)
+        self.assertEqual(db_connection.running, False)
+        self.assertEqual(len(db_connection.threads), 0)
+
+    def test_2_KeyboardInterrupt(self):
+        # Raise a keyboard interrupt in the HTTP server's main thread.
+        # We must start the server in this, the main thread
+        engine.start()
+        cherrypy.server.start()
+
+        self.persistent = True
+        try:
+            # Make the first request and assert there's no "Connection: close".
+            self.getPage("/")
+            self.assertStatus('200 OK')
+            self.assertBody("Hello World")
+            self.assertNoHeader("Connection")
+
+            cherrypy.server.httpserver.interrupt = KeyboardInterrupt
+            engine.block()
+
+            self.assertEqual(db_connection.running, False)
+            self.assertEqual(len(db_connection.threads), 0)
+            self.assertEqual(engine.state, engine.states.EXITING)
+        finally:
+            self.persistent = False
+
+        # Raise a keyboard interrupt in a page handler; on multithreaded
+        # servers, this should occur in one of the worker threads.
+        # This should raise a BadStatusLine error, since the worker
+        # thread will just die without writing a response.
+        engine.start()
+        cherrypy.server.start()
+
+        try:
+            self.getPage("/ctrlc")
+        except BadStatusLine:
+            pass
+        else:
+            print(self.body)
+            self.fail("AssertionError: BadStatusLine not raised")
+
+        engine.block()
+        self.assertEqual(db_connection.running, False)
+        self.assertEqual(len(db_connection.threads), 0)
+
+    def test_3_Deadlocks(self):
+        cherrypy.config.update({'response.timeout': 0.2})
+
+        engine.start()
+        cherrypy.server.start()
+        try:
+            self.assertNotEqual(engine.timeout_monitor.thread, None)
+
+            # Request a "normal" page.
+            self.assertEqual(engine.timeout_monitor.servings, [])
+            self.getPage("/")
+            self.assertBody("Hello World")
+            # request.close is called async.
+            while engine.timeout_monitor.servings:
+                sys.stdout.write(".")
+                time.sleep(0.01)
+
+            # Request a page that explicitly checks itself for deadlock.
+            # The deadlock_timeout should be 2 secs.
+            self.getPage("/block_explicit")
+            self.assertBody("broken!")
+
+            # Request a page that implicitly breaks deadlock.
+            # If we deadlock, we want to touch as little code as possible,
+            # so we won't even call handle_error, just bail ASAP.
+            self.getPage("/block_implicit")
+            self.assertStatus(500)
+            self.assertInBody("raise cherrypy.TimeoutError()")
+        finally:
+            engine.exit()
+
+    def test_4_Autoreload(self):
+        # Start the demo script in a new process
+        p = helper.CPProcess(ssl=(self.scheme.lower()=='https'))
+        p.write_conf(
+                extra='test_case_name: "test_4_Autoreload"')
+        p.start(imports='cherrypy.test._test_states_demo')
+        try:
+            self.getPage("/start")
+            start = float(self.body)
+
+            # Give the autoreloader time to cache the file time.
+            time.sleep(2)
+
+            # Touch the file
+            os.utime(os.path.join(thisdir, "_test_states_demo.py"), None)
+
+            # Give the autoreloader time to re-exec the process
+            time.sleep(2)
+            host = cherrypy.server.socket_host
+            port = cherrypy.server.socket_port
+            cherrypy._cpserver.wait_for_occupied_port(host, port)
+
+            self.getPage("/start")
+            self.assert_(float(self.body) > start)
+        finally:
+            # Shut down the spawned process
+            self.getPage("/exit")
+        p.join()
+
+    def test_5_Start_Error(self):
+        # If a process errors during start, it should stop the engine
+        # and exit with a non-zero exit code.
+        p = helper.CPProcess(ssl=(self.scheme.lower()=='https'),
+                             wait=True)
+        p.write_conf(
+                extra="""starterror: True
+test_case_name: "test_5_Start_Error"
+"""
+        )
+        p.start(imports='cherrypy.test._test_states_demo')
+        if p.exit_code == 0:
+            self.fail("Process failed to return nonzero exit code.")
+
+
+class PluginTests(helper.CPWebCase):
+    def test_daemonize(self):
+        if os.name not in ['posix']:
+            return self.skip("skipped (not on posix) ")
+        self.HOST = '127.0.0.1'
+        self.PORT = 8081
+        # Spawn the process and wait, when this returns, the original process
+        # is finished.  If it daemonized properly, we should still be able
+        # to access pages.
+        p = helper.CPProcess(ssl=(self.scheme.lower()=='https'),
+                             wait=True, daemonize=True,
+                             socket_host='127.0.0.1',
+                             socket_port=8081)
+        p.write_conf(
+             extra='test_case_name: "test_daemonize"')
+        p.start(imports='cherrypy.test._test_states_demo')
+        try:
+            # Just get the pid of the daemonization process.
+            self.getPage("/pid")
+            self.assertStatus(200)
+            page_pid = int(self.body)
+            self.assertEqual(page_pid, p.get_pid())
+        finally:
+            # Shut down the spawned process
+            self.getPage("/exit")
+        p.join()
+
+        # Wait until here to test the exit code because we want to ensure
+        # that we wait for the daemon to finish running before we fail.
+        if p.exit_code != 0:
+            self.fail("Daemonized parent process failed to exit cleanly.")
+
+
+class SignalHandlingTests(helper.CPWebCase):
+    def test_SIGHUP_tty(self):
+        # When not daemonized, SIGHUP should shut down the server.
+        try:
+            from signal import SIGHUP
+        except ImportError:
+            return self.skip("skipped (no SIGHUP) ")
+
+        # Spawn the process.
+        p = helper.CPProcess(ssl=(self.scheme.lower()=='https'))
+        p.write_conf(
+                extra='test_case_name: "test_SIGHUP_tty"')
+        p.start(imports='cherrypy.test._test_states_demo')
+        # Send a SIGHUP
+        os.kill(p.get_pid(), SIGHUP)
+        # This might hang if things aren't working right, but meh.
+        p.join()
+
+    def test_SIGHUP_daemonized(self):
+        # When daemonized, SIGHUP should restart the server.
+        try:
+            from signal import SIGHUP
+        except ImportError:
+            return self.skip("skipped (no SIGHUP) ")
+
+        if os.name not in ['posix']:
+            return self.skip("skipped (not on posix) ")
+
+        # Spawn the process and wait, when this returns, the original process
+        # is finished.  If it daemonized properly, we should still be able
+        # to access pages.
+        p = helper.CPProcess(ssl=(self.scheme.lower()=='https'),
+                             wait=True, daemonize=True)
+        p.write_conf(
+             extra='test_case_name: "test_SIGHUP_daemonized"')
+        p.start(imports='cherrypy.test._test_states_demo')
+
+        pid = p.get_pid()
+        try:
+            # Send a SIGHUP
+            os.kill(pid, SIGHUP)
+            # Give the server some time to restart
+            time.sleep(2)
+            self.getPage("/pid")
+            self.assertStatus(200)
+            new_pid = int(self.body)
+            self.assertNotEqual(new_pid, pid)
+        finally:
+            # Shut down the spawned process
+            self.getPage("/exit")
+        p.join()
+
+    def test_SIGTERM(self):
+        # SIGTERM should shut down the server whether daemonized or not.
+        try:
+            from signal import SIGTERM
+        except ImportError:
+            return self.skip("skipped (no SIGTERM) ")
+
+        try:
+            from os import kill
+        except ImportError:
+            return self.skip("skipped (no os.kill) ")
+
+        # Spawn a normal, undaemonized process.
+        p = helper.CPProcess(ssl=(self.scheme.lower()=='https'))
+        p.write_conf(
+                extra='test_case_name: "test_SIGTERM"')
+        p.start(imports='cherrypy.test._test_states_demo')
+        # Send a SIGTERM
+        os.kill(p.get_pid(), SIGTERM)
+        # This might hang if things aren't working right, but meh.
+        p.join()
+
+        if os.name in ['posix']:
+            # Spawn a daemonized process and test again.
+            p = helper.CPProcess(ssl=(self.scheme.lower()=='https'),
+                                 wait=True, daemonize=True)
+            p.write_conf(
+                 extra='test_case_name: "test_SIGTERM_2"')
+            p.start(imports='cherrypy.test._test_states_demo')
+            # Send a SIGTERM
+            os.kill(p.get_pid(), SIGTERM)
+            # This might hang if things aren't working right, but meh.
+            p.join()
+
+    def test_signal_handler_unsubscribe(self):
+        try:
+            from signal import SIGTERM
+        except ImportError:
+            return self.skip("skipped (no SIGTERM) ")
+
+        try:
+            from os import kill
+        except ImportError:
+            return self.skip("skipped (no os.kill) ")
+
+        # Spawn a normal, undaemonized process.
+        p = helper.CPProcess(ssl=(self.scheme.lower()=='https'))
+        p.write_conf(
+            extra="""unsubsig: True
+test_case_name: "test_signal_handler_unsubscribe"
+""")
+        p.start(imports='cherrypy.test._test_states_demo')
+        # Send a SIGTERM
+        os.kill(p.get_pid(), SIGTERM)
+        # This might hang if things aren't working right, but meh.
+        p.join()
+
+        # Assert the old handler ran.
+        target_line = open(p.error_log, 'rb').readlines()[-10]
+        if not ntob("I am an old SIGTERM handler.") in target_line:
+            self.fail("Old SIGTERM handler did not run.\n%r" % target_line)
+
diff --git a/cherrypy/test/test_static.py b/cherrypy/test/test_static.py
new file mode 100644
index 00000000..871420bd
--- /dev/null
+++ b/cherrypy/test/test_static.py
@@ -0,0 +1,300 @@
+from cherrypy._cpcompat import HTTPConnection, HTTPSConnection, ntob
+from cherrypy._cpcompat import BytesIO
+
+import os
+curdir = os.path.join(os.getcwd(), os.path.dirname(__file__))
+has_space_filepath = os.path.join(curdir, 'static', 'has space.html')
+bigfile_filepath = os.path.join(curdir, "static", "bigfile.log")
+BIGFILE_SIZE = 1024 * 1024
+import threading
+
+import cherrypy
+from cherrypy.lib import static
+from cherrypy.test import helper
+
+
+class StaticTest(helper.CPWebCase):
+
+    def setup_server():
+        if not os.path.exists(has_space_filepath):
+            open(has_space_filepath, 'wb').write(ntob('Hello, world\r\n'))
+        if not os.path.exists(bigfile_filepath):
+            open(bigfile_filepath, 'wb').write(ntob("x" * BIGFILE_SIZE))
+        
+        class Root:
+            
+            def bigfile(self):
+                from cherrypy.lib import static
+                self.f = static.serve_file(bigfile_filepath)
+                return self.f
+            bigfile.exposed = True
+            bigfile._cp_config = {'response.stream': True}
+            
+            def tell(self):
+                if self.f.input.closed:
+                    return ''
+                return repr(self.f.input.tell()).rstrip('L')
+            tell.exposed = True
+            
+            def fileobj(self):
+                f = open(os.path.join(curdir, 'style.css'), 'rb')
+                return static.serve_fileobj(f, content_type='text/css')
+            fileobj.exposed = True
+            
+            def bytesio(self):
+                f = BytesIO(ntob('Fee\nfie\nfo\nfum'))
+                return static.serve_fileobj(f, content_type='text/plain')
+            bytesio.exposed = True
+        
+        class Static:
+            
+            def index(self):
+                return 'You want the Baron? You can have the Baron!'
+            index.exposed = True
+            
+            def dynamic(self):
+                return "This is a DYNAMIC page"
+            dynamic.exposed = True
+        
+        
+        root = Root()
+        root.static = Static()
+        
+        rootconf = {
+            '/static': {
+                'tools.staticdir.on': True,
+                'tools.staticdir.dir': 'static',
+                'tools.staticdir.root': curdir,
+            },
+            '/style.css': {
+                'tools.staticfile.on': True,
+                'tools.staticfile.filename': os.path.join(curdir, 'style.css'),
+            },
+            '/docroot': {
+                'tools.staticdir.on': True,
+                'tools.staticdir.root': curdir,
+                'tools.staticdir.dir': 'static',
+                'tools.staticdir.index': 'index.html',
+            },
+            '/error': {
+                'tools.staticdir.on': True,
+                'request.show_tracebacks': True,
+            },
+            }
+        rootApp = cherrypy.Application(root)
+        rootApp.merge(rootconf)
+        
+        test_app_conf = {
+            '/test': {
+                'tools.staticdir.index': 'index.html',
+                'tools.staticdir.on': True,
+                'tools.staticdir.root': curdir,
+                'tools.staticdir.dir': 'static',
+                },
+            }
+        testApp = cherrypy.Application(Static())
+        testApp.merge(test_app_conf)
+        
+        vhost = cherrypy._cpwsgi.VirtualHost(rootApp, {'virt.net': testApp})
+        cherrypy.tree.graft(vhost)
+    setup_server = staticmethod(setup_server)
+
+
+    def teardown_server():
+        for f in (has_space_filepath, bigfile_filepath):
+            if os.path.exists(f):
+                try:
+                    os.unlink(f)
+                except:
+                    pass
+    teardown_server = staticmethod(teardown_server)
+
+    
+    def testStatic(self):
+        self.getPage("/static/index.html")
+        self.assertStatus('200 OK')
+        self.assertHeader('Content-Type', 'text/html')
+        self.assertBody('Hello, world\r\n')
+        
+        # Using a staticdir.root value in a subdir...
+        self.getPage("/docroot/index.html")
+        self.assertStatus('200 OK')
+        self.assertHeader('Content-Type', 'text/html')
+        self.assertBody('Hello, world\r\n')
+        
+        # Check a filename with spaces in it
+        self.getPage("/static/has%20space.html")
+        self.assertStatus('200 OK')
+        self.assertHeader('Content-Type', 'text/html')
+        self.assertBody('Hello, world\r\n')
+        
+        self.getPage("/style.css")
+        self.assertStatus('200 OK')
+        self.assertHeader('Content-Type', 'text/css')
+        # Note: The body should be exactly 'Dummy stylesheet\n', but
+        #   unfortunately some tools such as WinZip sometimes turn \n
+        #   into \r\n on Windows when extracting the CherryPy tarball so
+        #   we just check the content
+        self.assertMatchesBody('^Dummy stylesheet')
+    
+    def test_fallthrough(self):
+        # Test that NotFound will then try dynamic handlers (see [878]).
+        self.getPage("/static/dynamic")
+        self.assertBody("This is a DYNAMIC page")
+        
+        # Check a directory via fall-through to dynamic handler.
+        self.getPage("/static/")
+        self.assertStatus('200 OK')
+        self.assertHeader('Content-Type', 'text/html;charset=utf-8')
+        self.assertBody('You want the Baron? You can have the Baron!')
+    
+    def test_index(self):
+        # Check a directory via "staticdir.index".
+        self.getPage("/docroot/")
+        self.assertStatus('200 OK')
+        self.assertHeader('Content-Type', 'text/html')
+        self.assertBody('Hello, world\r\n')
+        # The same page should be returned even if redirected.
+        self.getPage("/docroot")
+        self.assertStatus(301)
+        self.assertHeader('Location', '%s/docroot/' % self.base())
+        self.assertMatchesBody("This resource .* "
+                               "%s/docroot/." % (self.base(), self.base()))
+    
+    def test_config_errors(self):
+        # Check that we get an error if no .file or .dir
+        self.getPage("/error/thing.html")
+        self.assertErrorPage(500)
+        self.assertMatchesBody(ntob("TypeError: staticdir\(\) takes at least 2 "
+                                    "(positional )?arguments \(0 given\)"))
+    
+    def test_security(self):
+        # Test up-level security
+        self.getPage("/static/../../test/style.css")
+        self.assertStatus((400, 403))
+    
+    def test_modif(self):
+        # Test modified-since on a reasonably-large file
+        self.getPage("/static/dirback.jpg")
+        self.assertStatus("200 OK")
+        lastmod = ""
+        for k, v in self.headers:
+            if k == 'Last-Modified':
+                lastmod = v
+        ims = ("If-Modified-Since", lastmod)
+        self.getPage("/static/dirback.jpg", headers=[ims])
+        self.assertStatus(304)
+        self.assertNoHeader("Content-Type")
+        self.assertNoHeader("Content-Length")
+        self.assertNoHeader("Content-Disposition")
+        self.assertBody("")
+    
+    def test_755_vhost(self):
+        self.getPage("/test/", [('Host', 'virt.net')])
+        self.assertStatus(200)
+        self.getPage("/test", [('Host', 'virt.net')])
+        self.assertStatus(301)
+        self.assertHeader('Location', self.scheme + '://virt.net/test/')
+    
+    def test_serve_fileobj(self):
+        self.getPage("/fileobj")
+        self.assertStatus('200 OK')
+        self.assertHeader('Content-Type', 'text/css;charset=utf-8')
+        self.assertMatchesBody('^Dummy stylesheet')
+    
+    def test_serve_bytesio(self):
+        self.getPage("/bytesio")
+        self.assertStatus('200 OK')
+        self.assertHeader('Content-Type', 'text/plain;charset=utf-8')
+        self.assertHeader('Content-Length', 14)
+        self.assertMatchesBody('Fee\nfie\nfo\nfum')
+    
+    def test_file_stream(self):
+        if cherrypy.server.protocol_version != "HTTP/1.1":
+            return self.skip()
+        
+        self.PROTOCOL = "HTTP/1.1"
+        
+        # Make an initial request
+        self.persistent = True
+        conn = self.HTTP_CONN
+        conn.putrequest("GET", "/bigfile", skip_host=True)
+        conn.putheader("Host", self.HOST)
+        conn.endheaders()
+        response = conn.response_class(conn.sock, method="GET")
+        response.begin()
+        self.assertEqual(response.status, 200)
+        
+        body = ntob('')
+        remaining = BIGFILE_SIZE
+        while remaining > 0:
+            data = response.fp.read(65536)
+            if not data:
+                break
+            body += data
+            remaining -= len(data)
+            
+            if self.scheme == "https":
+                newconn = HTTPSConnection
+            else:
+                newconn = HTTPConnection
+            s, h, b = helper.webtest.openURL(
+                ntob("/tell"), headers=[], host=self.HOST, port=self.PORT,
+                http_conn=newconn)
+            if not b:
+                # The file was closed on the server.
+                tell_position = BIGFILE_SIZE
+            else:
+                tell_position = int(b)
+            
+            expected = len(body)
+            if tell_position >= BIGFILE_SIZE:
+                # We can't exactly control how much content the server asks for.
+                # Fudge it by only checking the first half of the reads.
+                if expected < (BIGFILE_SIZE / 2):
+                    self.fail(
+                        "The file should have advanced to position %r, but has "
+                        "already advanced to the end of the file. It may not be "
+                        "streamed as intended, or at the wrong chunk size (64k)" %
+                        expected)
+            elif tell_position < expected:
+                self.fail(
+                    "The file should have advanced to position %r, but has "
+                    "only advanced to position %r. It may not be streamed "
+                    "as intended, or at the wrong chunk size (65536)" %
+                    (expected, tell_position))
+        
+        if body != ntob("x" * BIGFILE_SIZE):
+            self.fail("Body != 'x' * %d. Got %r instead (%d bytes)." %
+                      (BIGFILE_SIZE, body[:50], len(body)))
+        conn.close()
+    
+    def test_file_stream_deadlock(self):
+        if cherrypy.server.protocol_version != "HTTP/1.1":
+            return self.skip()
+        
+        self.PROTOCOL = "HTTP/1.1"
+        
+        # Make an initial request but abort early.
+        self.persistent = True
+        conn = self.HTTP_CONN
+        conn.putrequest("GET", "/bigfile", skip_host=True)
+        conn.putheader("Host", self.HOST)
+        conn.endheaders()
+        response = conn.response_class(conn.sock, method="GET")
+        response.begin()
+        self.assertEqual(response.status, 200)
+        body = response.fp.read(65536)
+        if body != ntob("x" * len(body)):
+            self.fail("Body != 'x' * %d. Got %r instead (%d bytes)." %
+                      (65536, body[:50], len(body)))
+        response.close()
+        conn.close()
+        
+        # Make a second request, which should fetch the whole file.
+        self.persistent = False
+        self.getPage("/bigfile")
+        if self.body != ntob("x" * BIGFILE_SIZE):
+            self.fail("Body != 'x' * %d. Got %r instead (%d bytes)." %
+                      (BIGFILE_SIZE, self.body[:50], len(body)))
+
diff --git a/cherrypy/test/test_tools.py b/cherrypy/test/test_tools.py
new file mode 100644
index 00000000..bc8579f0
--- /dev/null
+++ b/cherrypy/test/test_tools.py
@@ -0,0 +1,393 @@
+"""Test the various means of instantiating and invoking tools."""
+
+import gzip
+import sys
+from cherrypy._cpcompat import BytesIO, copyitems, itervalues, IncompleteRead, ntob, ntou, xrange
+import time
+timeout = 0.2
+import types
+
+import cherrypy
+from cherrypy import tools
+
+
+europoundUnicode = ntou('\x80\xa3')
+
+
+#                             Client-side code                             #
+
+from cherrypy.test import helper
+
+
+class ToolTests(helper.CPWebCase):
+    def setup_server():
+        
+        # Put check_access in a custom toolbox with its own namespace
+        myauthtools = cherrypy._cptools.Toolbox("myauth")
+        
+        def check_access(default=False):
+            if not getattr(cherrypy.request, "userid", default):
+                raise cherrypy.HTTPError(401)
+        myauthtools.check_access = cherrypy.Tool('before_request_body', check_access)
+        
+        def numerify():
+            def number_it(body):
+                for chunk in body:
+                    for k, v in cherrypy.request.numerify_map:
+                        chunk = chunk.replace(k, v)
+                    yield chunk
+            cherrypy.response.body = number_it(cherrypy.response.body)
+        
+        class NumTool(cherrypy.Tool):
+            def _setup(self):
+                def makemap():
+                    m = self._merged_args().get("map", {})
+                    cherrypy.request.numerify_map = copyitems(m)
+                cherrypy.request.hooks.attach('on_start_resource', makemap)
+                
+                def critical():
+                    cherrypy.request.error_response = cherrypy.HTTPError(502).set_response
+                critical.failsafe = True
+                
+                cherrypy.request.hooks.attach('on_start_resource', critical)
+                cherrypy.request.hooks.attach(self._point, self.callable)
+        
+        tools.numerify = NumTool('before_finalize', numerify)
+        
+        # It's not mandatory to inherit from cherrypy.Tool.
+        class NadsatTool:
+            
+            def __init__(self):
+                self.ended = {}
+                self._name = "nadsat"
+            
+            def nadsat(self):
+                def nadsat_it_up(body):
+                    for chunk in body:
+                        chunk = chunk.replace(ntob("good"), ntob("horrorshow"))
+                        chunk = chunk.replace(ntob("piece"), ntob("lomtick"))
+                        yield chunk
+                cherrypy.response.body = nadsat_it_up(cherrypy.response.body)
+            nadsat.priority = 0
+            
+            def cleanup(self):
+                # This runs after the request has been completely written out.
+                cherrypy.response.body = [ntob("razdrez")]
+                id = cherrypy.request.params.get("id")
+                if id:
+                    self.ended[id] = True
+            cleanup.failsafe = True
+            
+            def _setup(self):
+                cherrypy.request.hooks.attach('before_finalize', self.nadsat)
+                cherrypy.request.hooks.attach('on_end_request', self.cleanup)
+        tools.nadsat = NadsatTool()
+        
+        def pipe_body():
+            cherrypy.request.process_request_body = False
+            clen = int(cherrypy.request.headers['Content-Length'])
+            cherrypy.request.body = cherrypy.request.rfile.read(clen)
+        
+        # Assert that we can use a callable object instead of a function.
+        class Rotator(object):
+            def __call__(self, scale):
+                r = cherrypy.response
+                r.collapse_body()
+                r.body = [chr((ord(x) + scale) % 256) for x in r.body[0]]
+        cherrypy.tools.rotator = cherrypy.Tool('before_finalize', Rotator())
+        
+        def stream_handler(next_handler, *args, **kwargs):
+            cherrypy.response.output = o = BytesIO()
+            try:
+                response = next_handler(*args, **kwargs)
+                # Ignore the response and return our accumulated output instead.
+                return o.getvalue()
+            finally:
+                o.close()
+        cherrypy.tools.streamer = cherrypy._cptools.HandlerWrapperTool(stream_handler)
+        
+        class Root:
+            def index(self):
+                return "Howdy earth!"
+            index.exposed = True
+            
+            def tarfile(self):
+                cherrypy.response.output.write(ntob('I am '))
+                cherrypy.response.output.write(ntob('a tarfile'))
+            tarfile.exposed = True
+            tarfile._cp_config = {'tools.streamer.on': True}
+            
+            def euro(self):
+                hooks = list(cherrypy.request.hooks['before_finalize'])
+                hooks.sort()
+                cbnames = [x.callback.__name__ for x in hooks]
+                assert cbnames == ['gzip'], cbnames
+                priorities = [x.priority for x in hooks]
+                assert priorities == [80], priorities
+                yield ntou("Hello,")
+                yield ntou("world")
+                yield europoundUnicode
+            euro.exposed = True
+            
+            # Bare hooks
+            def pipe(self):
+                return cherrypy.request.body
+            pipe.exposed = True
+            pipe._cp_config = {'hooks.before_request_body': pipe_body}
+            
+            # Multiple decorators; include kwargs just for fun.
+            # Note that rotator must run before gzip.
+            def decorated_euro(self, *vpath):
+                yield ntou("Hello,")
+                yield ntou("world")
+                yield europoundUnicode
+            decorated_euro.exposed = True
+            decorated_euro = tools.gzip(compress_level=6)(decorated_euro)
+            decorated_euro = tools.rotator(scale=3)(decorated_euro)
+        
+        root = Root()
+        
+        
+        class TestType(type):
+            """Metaclass which automatically exposes all functions in each subclass,
+            and adds an instance of the subclass as an attribute of root.
+            """
+            def __init__(cls, name, bases, dct):
+                type.__init__(cls, name, bases, dct)
+                for value in itervalues(dct):
+                    if isinstance(value, types.FunctionType):
+                        value.exposed = True
+                setattr(root, name.lower(), cls())
+        class Test(object):
+            __metaclass__ = TestType
+        
+        
+        # METHOD ONE:
+        # Declare Tools in _cp_config
+        class Demo(Test):
+            
+            _cp_config = {"tools.nadsat.on": True}
+            
+            def index(self, id=None):
+                return "A good piece of cherry pie"
+            
+            def ended(self, id):
+                return repr(tools.nadsat.ended[id])
+            
+            def err(self, id=None):
+                raise ValueError()
+            
+            def errinstream(self, id=None):
+                yield "nonconfidential"
+                raise ValueError()
+                yield "confidential"
+            
+            # METHOD TWO: decorator using Tool()
+            # We support Python 2.3, but the @-deco syntax would look like this:
+            # @tools.check_access()
+            def restricted(self):
+                return "Welcome!"
+            restricted = myauthtools.check_access()(restricted)
+            userid = restricted
+            
+            def err_in_onstart(self):
+                return "success!"
+            
+            def stream(self, id=None):
+                for x in xrange(100000000):
+                    yield str(x)
+            stream._cp_config = {'response.stream': True}
+        
+        
+        conf = {
+            # METHOD THREE:
+            # Declare Tools in detached config
+            '/demo': {
+                'tools.numerify.on': True,
+                'tools.numerify.map': {ntob("pie"): ntob("3.14159")},
+            },
+            '/demo/restricted': {
+                'request.show_tracebacks': False,
+            },
+            '/demo/userid': {
+                'request.show_tracebacks': False,
+                'myauth.check_access.default': True,
+            },
+            '/demo/errinstream': {
+                'response.stream': True,
+            },
+            '/demo/err_in_onstart': {
+                # Because this isn't a dict, on_start_resource will error.
+                'tools.numerify.map': "pie->3.14159"
+            },
+            # Combined tools
+            '/euro': {
+                'tools.gzip.on': True,
+                'tools.encode.on': True,
+            },
+            # Priority specified in config
+            '/decorated_euro/subpath': {
+                'tools.gzip.priority': 10,
+            },
+            # Handler wrappers
+            '/tarfile': {'tools.streamer.on': True}
+        }
+        app = cherrypy.tree.mount(root, config=conf)
+        app.request_class.namespaces['myauth'] = myauthtools
+        
+        if sys.version_info >= (2, 5):
+            from cherrypy.test import _test_decorators
+            root.tooldecs = _test_decorators.ToolExamples()
+    setup_server = staticmethod(setup_server)
+
+    def testHookErrors(self):
+        self.getPage("/demo/?id=1")
+        # If body is "razdrez", then on_end_request is being called too early.
+        self.assertBody("A horrorshow lomtick of cherry 3.14159")
+        # If this fails, then on_end_request isn't being called at all.
+        time.sleep(0.1)
+        self.getPage("/demo/ended/1")
+        self.assertBody("True")
+        
+        valerr = '\n    raise ValueError()\nValueError'
+        self.getPage("/demo/err?id=3")
+        # If body is "razdrez", then on_end_request is being called too early.
+        self.assertErrorPage(502, pattern=valerr)
+        # If this fails, then on_end_request isn't being called at all.
+        time.sleep(0.1)
+        self.getPage("/demo/ended/3")
+        self.assertBody("True")
+        
+        # If body is "razdrez", then on_end_request is being called too early.
+        if (cherrypy.server.protocol_version == "HTTP/1.0" or
+            getattr(cherrypy.server, "using_apache", False)):
+            self.getPage("/demo/errinstream?id=5")
+            # Because this error is raised after the response body has
+            # started, the status should not change to an error status.
+            self.assertStatus("200 OK")
+            self.assertBody("nonconfidential")
+        else:
+            # Because this error is raised after the response body has
+            # started, and because it's chunked output, an error is raised by
+            # the HTTP client when it encounters incomplete output.
+            self.assertRaises((ValueError, IncompleteRead), self.getPage,
+                              "/demo/errinstream?id=5")
+        # If this fails, then on_end_request isn't being called at all.
+        time.sleep(0.1)
+        self.getPage("/demo/ended/5")
+        self.assertBody("True")
+        
+        # Test the "__call__" technique (compile-time decorator).
+        self.getPage("/demo/restricted")
+        self.assertErrorPage(401)
+        
+        # Test compile-time decorator with kwargs from config.
+        self.getPage("/demo/userid")
+        self.assertBody("Welcome!")
+    
+    def testEndRequestOnDrop(self):
+        old_timeout = None
+        try:
+            httpserver = cherrypy.server.httpserver
+            old_timeout = httpserver.timeout
+        except (AttributeError, IndexError):
+            return self.skip()
+        
+        try:
+            httpserver.timeout = timeout
+            
+            # Test that on_end_request is called even if the client drops.
+            self.persistent = True
+            try:
+                conn = self.HTTP_CONN
+                conn.putrequest("GET", "/demo/stream?id=9", skip_host=True)
+                conn.putheader("Host", self.HOST)
+                conn.endheaders()
+                # Skip the rest of the request and close the conn. This will
+                # cause the server's active socket to error, which *should*
+                # result in the request being aborted, and request.close being
+                # called all the way up the stack (including WSGI middleware),
+                # eventually calling our on_end_request hook.
+            finally:
+                self.persistent = False
+            time.sleep(timeout * 2)
+            # Test that the on_end_request hook was called.
+            self.getPage("/demo/ended/9")
+            self.assertBody("True")
+        finally:
+            if old_timeout is not None:
+                httpserver.timeout = old_timeout
+    
+    def testGuaranteedHooks(self):
+        # The 'critical' on_start_resource hook is 'failsafe' (guaranteed
+        # to run even if there are failures in other on_start methods).
+        # This is NOT true of the other hooks.
+        # Here, we have set up a failure in NumerifyTool.numerify_map,
+        # but our 'critical' hook should run and set the error to 502.
+        self.getPage("/demo/err_in_onstart")
+        self.assertErrorPage(502)
+        self.assertInBody("AttributeError: 'str' object has no attribute 'items'")
+    
+    def testCombinedTools(self):
+        expectedResult = (ntou("Hello,world") + europoundUnicode).encode('utf-8')
+        zbuf = BytesIO()
+        zfile = gzip.GzipFile(mode='wb', fileobj=zbuf, compresslevel=9)
+        zfile.write(expectedResult)
+        zfile.close()
+        
+        self.getPage("/euro", headers=[("Accept-Encoding", "gzip"),
+                                        ("Accept-Charset", "ISO-8859-1,utf-8;q=0.7,*;q=0.7")])
+        self.assertInBody(zbuf.getvalue()[:3])
+        
+        zbuf = BytesIO()
+        zfile = gzip.GzipFile(mode='wb', fileobj=zbuf, compresslevel=6)
+        zfile.write(expectedResult)
+        zfile.close()
+        
+        self.getPage("/decorated_euro", headers=[("Accept-Encoding", "gzip")])
+        self.assertInBody(zbuf.getvalue()[:3])
+        
+        # This returns a different value because gzip's priority was
+        # lowered in conf, allowing the rotator to run after gzip.
+        # Of course, we don't want breakage in production apps,
+        # but it proves the priority was changed.
+        self.getPage("/decorated_euro/subpath",
+                     headers=[("Accept-Encoding", "gzip")])
+        self.assertInBody(''.join([chr((ord(x) + 3) % 256) for x in zbuf.getvalue()]))
+    
+    def testBareHooks(self):
+        content = "bit of a pain in me gulliver"
+        self.getPage("/pipe",
+                     headers=[("Content-Length", str(len(content))),
+                              ("Content-Type", "text/plain")],
+                     method="POST", body=content)
+        self.assertBody(content)
+    
+    def testHandlerWrapperTool(self):
+        self.getPage("/tarfile")
+        self.assertBody("I am a tarfile")
+    
+    def testToolWithConfig(self):
+        if not sys.version_info >= (2, 5):
+            return self.skip("skipped (Python 2.5+ only)")
+        
+        self.getPage('/tooldecs/blah')
+        self.assertHeader('Content-Type', 'application/data')
+    
+    def testWarnToolOn(self):
+        # get
+        try:
+            numon = cherrypy.tools.numerify.on
+        except AttributeError:
+            pass
+        else:
+            raise AssertionError("Tool.on did not error as it should have.")
+        
+        # set
+        try:
+            cherrypy.tools.numerify.on = True
+        except AttributeError:
+            pass
+        else:
+            raise AssertionError("Tool.on did not error as it should have.")
+
diff --git a/cherrypy/test/test_tutorials.py b/cherrypy/test/test_tutorials.py
new file mode 100644
index 00000000..aab27861
--- /dev/null
+++ b/cherrypy/test/test_tutorials.py
@@ -0,0 +1,201 @@
+import sys
+
+import cherrypy
+from cherrypy.test import helper
+
+
+class TutorialTest(helper.CPWebCase):
+
+    def setup_server(cls):
+        
+        conf = cherrypy.config.copy()
+        
+        def load_tut_module(name):
+            """Import or reload tutorial module as needed."""
+            cherrypy.config.reset()
+            cherrypy.config.update(conf)
+            
+            target = "cherrypy.tutorial." + name
+            if target in sys.modules:
+                module = reload(sys.modules[target])
+            else:
+                module = __import__(target, globals(), locals(), [''])
+            # The above import will probably mount a new app at "".
+            app = cherrypy.tree.apps[""]
+            
+            app.root.load_tut_module = load_tut_module
+            app.root.sessions = sessions
+            app.root.traceback_setting = traceback_setting
+            
+            cls.supervisor.sync_apps()
+        load_tut_module.exposed = True
+        
+        def sessions():
+            cherrypy.config.update({"tools.sessions.on": True})
+        sessions.exposed = True
+        
+        def traceback_setting():
+            return repr(cherrypy.request.show_tracebacks)
+        traceback_setting.exposed = True
+        
+        class Dummy:
+            pass
+        root = Dummy()
+        root.load_tut_module = load_tut_module
+        cherrypy.tree.mount(root)
+    setup_server = classmethod(setup_server)
+
+    
+    def test01HelloWorld(self):
+        self.getPage("/load_tut_module/tut01_helloworld")
+        self.getPage("/")
+        self.assertBody('Hello world!')
+    
+    def test02ExposeMethods(self):
+        self.getPage("/load_tut_module/tut02_expose_methods")
+        self.getPage("/showMessage")
+        self.assertBody('Hello world!')
+    
+    def test03GetAndPost(self):
+        self.getPage("/load_tut_module/tut03_get_and_post")
+        
+        # Try different GET queries
+        self.getPage("/greetUser?name=Bob")
+        self.assertBody("Hey Bob, what's up?")
+        
+        self.getPage("/greetUser")
+        self.assertBody('Please enter your name here.')
+        
+        self.getPage("/greetUser?name=")
+        self.assertBody('No, really, enter your name here.')
+        
+        # Try the same with POST
+        self.getPage("/greetUser", method="POST", body="name=Bob")
+        self.assertBody("Hey Bob, what's up?")
+        
+        self.getPage("/greetUser", method="POST", body="name=")
+        self.assertBody('No, really, enter your name here.')
+    
+    def test04ComplexSite(self):
+        self.getPage("/load_tut_module/tut04_complex_site")
+        msg = '''
+            
Here are some extra useful links:

+            
+            
+            
+            
[Return to links page]
'''
+        self.getPage("/links/extra/")
+        self.assertBody(msg)
+    
+    def test05DerivedObjects(self):
+        self.getPage("/load_tut_module/tut05_derived_objects")
+        msg = '''
+            
+            
+                Another Page
+            
+            
+            
Another Page

+        
+            

+            And this is the amazing second page!
+            

+        
+            
+            
+        '''
+        self.getPage("/another/")
+        self.assertBody(msg)
+    
+    def test06DefaultMethod(self):
+        self.getPage("/load_tut_module/tut06_default_method")
+        self.getPage('/hendrik')
+        self.assertBody('Hendrik Mans, CherryPy co-developer & crazy German '
+                        '(back)')
+    
+    def test07Sessions(self):
+        self.getPage("/load_tut_module/tut07_sessions")
+        self.getPage("/sessions")
+        
+        self.getPage('/')
+        self.assertBody("\n            During your current session, you've viewed this"
+                         "\n            page 1 times! Your life is a patio of fun!"
+                         "\n        ")
+        
+        self.getPage('/', self.cookies)
+        self.assertBody("\n            During your current session, you've viewed this"
+                         "\n            page 2 times! Your life is a patio of fun!"
+                         "\n        ")
+    
+    def test08GeneratorsAndYield(self):
+        self.getPage("/load_tut_module/tut08_generators_and_yield")
+        self.getPage('/')
+        self.assertBody('
Generators rule!
'
+                         '
List of users:
'
+                         'Remi
Carlos
Hendrik
Lorenzo Lamas
'
+                         '')
+    
+    def test09Files(self):
+        self.getPage("/load_tut_module/tut09_files")
+        
+        # Test upload
+        filesize = 5
+        h = [("Content-type", "multipart/form-data; boundary=x"),
+             ("Content-Length", str(105 + filesize))]
+        b = '--x\n' + \
+            'Content-Disposition: form-data; name="myFile"; filename="hello.txt"\r\n' + \
+            'Content-Type: text/plain\r\n' + \
+            '\r\n' + \
+            'a' * filesize + '\n' + \
+            '--x--\n'
+        self.getPage('/upload', h, "POST", b)
+        self.assertBody('''
+        
+            myFile length: %d

+            myFile filename: hello.txt

+            myFile mime-type: text/plain
+        
+        ''' % filesize)
+    
+        # Test download
+        self.getPage('/download')
+        self.assertStatus("200 OK")
+        self.assertHeader("Content-Type", "application/x-download")
+        self.assertHeader("Content-Disposition",
+                          # Make sure the filename is quoted.
+                          'attachment; filename="pdf_file.pdf"')
+        self.assertEqual(len(self.body), 85698)
+    
+    def test10HTTPErrors(self):
+        self.getPage("/load_tut_module/tut10_http_errors")
+        
+        self.getPage("/")
+        self.assertInBody("""""")
+        self.assertInBody("""""")
+        self.assertInBody("""""")
+        self.assertInBody("""""")
+        self.assertInBody("""""")
+        
+        self.getPage("/traceback_setting")
+        setting = self.body
+        self.getPage("/toggleTracebacks")
+        self.assertStatus((302, 303))
+        self.getPage("/traceback_setting")
+        self.assertBody(str(not eval(setting)))
+        
+        self.getPage("/error?code=500")
+        self.assertStatus(500)
+        self.assertInBody("The server encountered an unexpected condition "
+                          "which prevented it from fulfilling the request.")
+        
+        self.getPage("/error?code=403")
+        self.assertStatus(403)
+        self.assertInBody("
You can't do that!
")
+        
+        self.getPage("/messageArg")
+        self.assertStatus(500)
+        self.assertInBody("If you construct an HTTPError with a 'message'")
+
diff --git a/cherrypy/test/test_virtualhost.py b/cherrypy/test/test_virtualhost.py
new file mode 100644
index 00000000..d6eed0ea
--- /dev/null
+++ b/cherrypy/test/test_virtualhost.py
@@ -0,0 +1,107 @@
+import os
+curdir = os.path.join(os.getcwd(), os.path.dirname(__file__))
+
+import cherrypy
+from cherrypy.test import helper
+
+
+class VirtualHostTest(helper.CPWebCase):
+
+    def setup_server():
+        class Root:
+            def index(self):
+                return "Hello, world"
+            index.exposed = True
+            
+            def dom4(self):
+                return "Under construction"
+            dom4.exposed = True
+            
+            def method(self, value):
+                return "You sent %s" % repr(value)
+            method.exposed = True
+        
+        class VHost:
+            def __init__(self, sitename):
+                self.sitename = sitename
+            
+            def index(self):
+                return "Welcome to %s" % self.sitename
+            index.exposed = True
+            
+            def vmethod(self, value):
+                return "You sent %s" % repr(value)
+            vmethod.exposed = True
+            
+            def url(self):
+                return cherrypy.url("nextpage")
+            url.exposed = True
+            
+            # Test static as a handler (section must NOT include vhost prefix)
+            static = cherrypy.tools.staticdir.handler(section='/static', dir=curdir)
+        
+        root = Root()
+        root.mydom2 = VHost("Domain 2")
+        root.mydom3 = VHost("Domain 3")
+        hostmap = {'www.mydom2.com': '/mydom2',
+                   'www.mydom3.com': '/mydom3',
+                   'www.mydom4.com': '/dom4',
+                   }
+        cherrypy.tree.mount(root, config={
+            '/': {'request.dispatch': cherrypy.dispatch.VirtualHost(**hostmap)},
+            # Test static in config (section must include vhost prefix)
+            '/mydom2/static2': {'tools.staticdir.on': True,
+                                'tools.staticdir.root': curdir,
+                                'tools.staticdir.dir': 'static',
+                                'tools.staticdir.index': 'index.html',
+                                },
+            })
+    setup_server = staticmethod(setup_server)
+    
+    def testVirtualHost(self):
+        self.getPage("/", [('Host', 'www.mydom1.com')])
+        self.assertBody('Hello, world')
+        self.getPage("/mydom2/", [('Host', 'www.mydom1.com')])
+        self.assertBody('Welcome to Domain 2')
+        
+        self.getPage("/", [('Host', 'www.mydom2.com')])
+        self.assertBody('Welcome to Domain 2')
+        self.getPage("/", [('Host', 'www.mydom3.com')])
+        self.assertBody('Welcome to Domain 3')
+        self.getPage("/", [('Host', 'www.mydom4.com')])
+        self.assertBody('Under construction')
+        
+        # Test GET, POST, and positional params
+        self.getPage("/method?value=root")
+        self.assertBody("You sent u'root'")
+        self.getPage("/vmethod?value=dom2+GET", [('Host', 'www.mydom2.com')])
+        self.assertBody("You sent u'dom2 GET'")
+        self.getPage("/vmethod", [('Host', 'www.mydom3.com')], method="POST",
+                     body="value=dom3+POST")
+        self.assertBody("You sent u'dom3 POST'")
+        self.getPage("/vmethod/pos", [('Host', 'www.mydom3.com')])
+        self.assertBody("You sent 'pos'")
+        
+        # Test that cherrypy.url uses the browser url, not the virtual url
+        self.getPage("/url", [('Host', 'www.mydom2.com')])
+        self.assertBody("%s://www.mydom2.com/nextpage" % self.scheme)
+    
+    def test_VHost_plus_Static(self):
+        # Test static as a handler
+        self.getPage("/static/style.css", [('Host', 'www.mydom2.com')])
+        self.assertStatus('200 OK')
+        self.assertHeader('Content-Type', 'text/css;charset=utf-8')
+        
+        # Test static in config
+        self.getPage("/static2/dirback.jpg", [('Host', 'www.mydom2.com')])
+        self.assertStatus('200 OK')
+        self.assertHeader('Content-Type', 'image/jpeg')
+        
+        # Test static config with "index" arg
+        self.getPage("/static2/", [('Host', 'www.mydom2.com')])
+        self.assertStatus('200 OK')
+        self.assertBody('Hello, world\r\n')
+        # Since tools.trailing_slash is on by default, this should redirect
+        self.getPage("/static2", [('Host', 'www.mydom2.com')])
+        self.assertStatus(301)
+
diff --git a/cherrypy/test/test_wsgi_ns.py b/cherrypy/test/test_wsgi_ns.py
new file mode 100644
index 00000000..d57013c3
--- /dev/null
+++ b/cherrypy/test/test_wsgi_ns.py
@@ -0,0 +1,80 @@
+import cherrypy
+from cherrypy.test import helper
+
+
+class WSGI_Namespace_Test(helper.CPWebCase):
+
+    def setup_server():
+        
+        class WSGIResponse(object):
+            
+            def __init__(self, appresults):
+                self.appresults = appresults
+                self.iter = iter(appresults)
+            
+            def __iter__(self):
+                return self
+            
+            def next(self):
+                return self.iter.next()
+            
+            def close(self):
+                if hasattr(self.appresults, "close"):
+                    self.appresults.close()
+        
+        
+        class ChangeCase(object):
+            
+            def __init__(self, app, to=None):
+                self.app = app
+                self.to = to
+            
+            def __call__(self, environ, start_response):
+                res = self.app(environ, start_response)
+                class CaseResults(WSGIResponse):
+                    def next(this):
+                        return getattr(this.iter.next(), self.to)()
+                return CaseResults(res)
+        
+        class Replacer(object):
+            
+            def __init__(self, app, map={}):
+                self.app = app
+                self.map = map
+            
+            def __call__(self, environ, start_response):
+                res = self.app(environ, start_response)
+                class ReplaceResults(WSGIResponse):
+                    def next(this):
+                        line = this.iter.next()
+                        for k, v in self.map.iteritems():
+                            line = line.replace(k, v)
+                        return line
+                return ReplaceResults(res)
+        
+        class Root(object):
+            
+            def index(self):
+                return "HellO WoRlD!"
+            index.exposed = True
+        
+        
+        root_conf = {'wsgi.pipeline': [('replace', Replacer)],
+                     'wsgi.replace.map': {'L': 'X', 'l': 'r'},
+                     }
+        
+        app = cherrypy.Application(Root())
+        app.wsgiapp.pipeline.append(('changecase', ChangeCase))
+        app.wsgiapp.config['changecase'] = {'to': 'upper'}
+        cherrypy.tree.mount(app, config={'/': root_conf})
+    setup_server = staticmethod(setup_server)
+
+    
+    def test_pipeline(self):
+        if not cherrypy.server.httpserver:
+            return self.skip()
+        
+        self.getPage("/")
+        # If body is "HEXXO WORXD!", the middleware was applied out of order.
+        self.assertBody("HERRO WORRD!")
+
diff --git a/cherrypy/test/test_wsgi_vhost.py b/cherrypy/test/test_wsgi_vhost.py
new file mode 100644
index 00000000..abb1a917
--- /dev/null
+++ b/cherrypy/test/test_wsgi_vhost.py
@@ -0,0 +1,36 @@
+import cherrypy
+from cherrypy.test import helper
+
+
+class WSGI_VirtualHost_Test(helper.CPWebCase):
+
+    def setup_server():
+        
+        class ClassOfRoot(object):
+            
+            def __init__(self, name):
+                self.name = name
+            
+            def index(self):
+                return "Welcome to the %s website!" % self.name
+            index.exposed = True
+        
+        
+        default = cherrypy.Application(None)
+        
+        domains = {}
+        for year in range(1997, 2008):
+            app = cherrypy.Application(ClassOfRoot('Class of %s' % year))
+            domains['www.classof%s.example' % year] = app
+        
+        cherrypy.tree.graft(cherrypy._cpwsgi.VirtualHost(default, domains))
+    setup_server = staticmethod(setup_server)
+    
+    def test_welcome(self):
+        if not cherrypy.server.using_wsgi:
+            return self.skip("skipped (not using WSGI)... ")
+        
+        for year in range(1997, 2008):
+            self.getPage("/", headers=[('Host', 'www.classof%s.example' % year)])
+            self.assertBody("Welcome to the Class of %s website!" % year)
+
diff --git a/cherrypy/test/test_wsgiapps.py b/cherrypy/test/test_wsgiapps.py
new file mode 100644
index 00000000..fa5420c5
--- /dev/null
+++ b/cherrypy/test/test_wsgiapps.py
@@ -0,0 +1,111 @@
+from cherrypy.test import helper
+
+
+class WSGIGraftTests(helper.CPWebCase):
+
+    def setup_server():
+        import os
+        curdir = os.path.join(os.getcwd(), os.path.dirname(__file__))
+        
+        import cherrypy
+        
+        def test_app(environ, start_response):
+            status = '200 OK'
+            response_headers = [('Content-type', 'text/plain')]
+            start_response(status, response_headers)
+            output = ['Hello, world!\n',
+                      'This is a wsgi app running within CherryPy!\n\n']
+            keys = list(environ.keys())
+            keys.sort()
+            for k in keys:
+                output.append('%s: %s\n' % (k,environ[k]))
+            return output
+        
+        def test_empty_string_app(environ, start_response):
+            status = '200 OK'
+            response_headers = [('Content-type', 'text/plain')]
+            start_response(status, response_headers)
+            return ['Hello', '', ' ', '', 'world']
+        
+        
+        class WSGIResponse(object):
+            
+            def __init__(self, appresults):
+                self.appresults = appresults
+                self.iter = iter(appresults)
+            
+            def __iter__(self):
+                return self
+            
+            def next(self):
+                return self.iter.next()
+            
+            def close(self):
+                if hasattr(self.appresults, "close"):
+                    self.appresults.close()
+        
+        
+        class ReversingMiddleware(object):
+            
+            def __init__(self, app):
+                self.app = app
+            
+            def __call__(self, environ, start_response):
+                results = app(environ, start_response)
+                class Reverser(WSGIResponse):
+                    def next(this):
+                        line = list(this.iter.next())
+                        line.reverse()
+                        return "".join(line)
+                return Reverser(results)
+        
+        class Root:
+            def index(self):
+                return "I'm a regular CherryPy page handler!"
+            index.exposed = True
+        
+        
+        cherrypy.tree.mount(Root())
+        
+        cherrypy.tree.graft(test_app, '/hosted/app1')
+        cherrypy.tree.graft(test_empty_string_app, '/hosted/app3')
+        
+        # Set script_name explicitly to None to signal CP that it should
+        # be pulled from the WSGI environ each time.
+        app = cherrypy.Application(Root(), script_name=None)
+        cherrypy.tree.graft(ReversingMiddleware(app), '/hosted/app2')
+    setup_server = staticmethod(setup_server)
+
+    wsgi_output = '''Hello, world!
+This is a wsgi app running within CherryPy!'''
+
+    def test_01_standard_app(self):
+        self.getPage("/")
+        self.assertBody("I'm a regular CherryPy page handler!")
+    
+    def test_04_pure_wsgi(self):
+        import cherrypy
+        if not cherrypy.server.using_wsgi:
+            return self.skip("skipped (not using WSGI)... ")
+        self.getPage("/hosted/app1")
+        self.assertHeader("Content-Type", "text/plain")
+        self.assertInBody(self.wsgi_output)
+
+    def test_05_wrapped_cp_app(self):
+        import cherrypy
+        if not cherrypy.server.using_wsgi:
+            return self.skip("skipped (not using WSGI)... ")
+        self.getPage("/hosted/app2/")
+        body = list("I'm a regular CherryPy page handler!")
+        body.reverse()
+        body = "".join(body)
+        self.assertInBody(body)
+
+    def test_06_empty_string_app(self):
+        import cherrypy
+        if not cherrypy.server.using_wsgi:
+            return self.skip("skipped (not using WSGI)... ")
+        self.getPage("/hosted/app3")
+        self.assertHeader("Content-Type", "text/plain")
+        self.assertInBody('Hello world')
+
diff --git a/cherrypy/test/test_xmlrpc.py b/cherrypy/test/test_xmlrpc.py
new file mode 100644
index 00000000..c4bf61e0
--- /dev/null
+++ b/cherrypy/test/test_xmlrpc.py
@@ -0,0 +1,172 @@
+import sys
+from xmlrpclib import DateTime, Fault, ServerProxy, SafeTransport
+
+class HTTPSTransport(SafeTransport):
+    """Subclass of SafeTransport to fix sock.recv errors (by using file)."""
+    
+    def request(self, host, handler, request_body, verbose=0):
+        # issue XML-RPC request
+        h = self.make_connection(host)
+        if verbose:
+            h.set_debuglevel(1)
+        
+        self.send_request(h, handler, request_body)
+        self.send_host(h, host)
+        self.send_user_agent(h)
+        self.send_content(h, request_body)
+        
+        errcode, errmsg, headers = h.getreply()
+        if errcode != 200:
+            raise xmlrpclib.ProtocolError(host + handler, errcode, errmsg,
+                                          headers)
+        
+        self.verbose = verbose
+        
+        # Here's where we differ from the superclass. It says:
+        # try:
+        #     sock = h._conn.sock
+        # except AttributeError:
+        #     sock = None
+        # return self._parse_response(h.getfile(), sock)
+        
+        return self.parse_response(h.getfile())
+
+import cherrypy
+
+
+def setup_server():
+    from cherrypy import _cptools
+    
+    class Root:
+        def index(self):
+            return "I'm a standard index!"
+        index.exposed = True
+
+
+    class XmlRpc(_cptools.XMLRPCController):
+        
+        def foo(self):
+            return "Hello world!"
+        foo.exposed = True
+        
+        def return_single_item_list(self):
+            return [42]
+        return_single_item_list.exposed = True
+        
+        def return_string(self):
+            return "here is a string"
+        return_string.exposed = True
+        
+        def return_tuple(self):
+            return ('here', 'is', 1, 'tuple')
+        return_tuple.exposed = True
+        
+        def return_dict(self):
+            return dict(a=1, b=2, c=3)
+        return_dict.exposed = True
+        
+        def return_composite(self):
+            return dict(a=1,z=26), 'hi', ['welcome', 'friend']
+        return_composite.exposed = True
+
+        def return_int(self):
+            return 42
+        return_int.exposed = True
+
+        def return_float(self):
+            return 3.14
+        return_float.exposed = True
+
+        def return_datetime(self):
+            return DateTime((2003, 10, 7, 8, 1, 0, 1, 280, -1))
+        return_datetime.exposed = True
+
+        def return_boolean(self):
+            return True
+        return_boolean.exposed = True
+
+        def test_argument_passing(self, num):
+            return num * 2
+        test_argument_passing.exposed = True
+
+        def test_returning_Fault(self):
+            return Fault(1, "custom Fault response")
+        test_returning_Fault.exposed = True
+
+    root = Root()
+    root.xmlrpc = XmlRpc()
+    cherrypy.tree.mount(root, config={'/': {
+        'request.dispatch': cherrypy.dispatch.XMLRPCDispatcher(),
+        'tools.xmlrpc.allow_none': 0,
+        }})
+
+
+from cherrypy.test import helper
+
+class XmlRpcTest(helper.CPWebCase):
+    setup_server = staticmethod(setup_server)
+    def testXmlRpc(self):
+        
+        scheme = "http"
+        try:
+            scheme = self.harness.scheme
+        except AttributeError:
+            pass
+        
+        if scheme == "https":
+            url = 'https://%s:%s/xmlrpc/' % (self.interface(), self.PORT)
+            proxy = ServerProxy(url, transport=HTTPSTransport())
+        else:
+            url = 'http://%s:%s/xmlrpc/' % (self.interface(), self.PORT)
+            proxy = ServerProxy(url)
+        
+        # begin the tests ...
+        self.getPage("/xmlrpc/foo")
+        self.assertBody("Hello world!")
+        
+        self.assertEqual(proxy.return_single_item_list(), [42])
+        self.assertNotEqual(proxy.return_single_item_list(), 'one bazillion')
+        self.assertEqual(proxy.return_string(), "here is a string")
+        self.assertEqual(proxy.return_tuple(), list(('here', 'is', 1, 'tuple')))
+        self.assertEqual(proxy.return_dict(), {'a': 1, 'c': 3, 'b': 2})
+        self.assertEqual(proxy.return_composite(),
+                         [{'a': 1, 'z': 26}, 'hi', ['welcome', 'friend']])
+        self.assertEqual(proxy.return_int(), 42)
+        self.assertEqual(proxy.return_float(), 3.14)
+        self.assertEqual(proxy.return_datetime(),
+                         DateTime((2003, 10, 7, 8, 1, 0, 1, 280, -1)))
+        self.assertEqual(proxy.return_boolean(), True)
+        self.assertEqual(proxy.test_argument_passing(22), 22 * 2)
+        
+        # Test an error in the page handler (should raise an xmlrpclib.Fault)
+        try:
+            proxy.test_argument_passing({})
+        except Exception:
+            x = sys.exc_info()[1]
+            self.assertEqual(x.__class__, Fault)
+            self.assertEqual(x.faultString, ("unsupported operand type(s) "
+                                             "for *: 'dict' and 'int'"))
+        else:
+            self.fail("Expected xmlrpclib.Fault")
+        
+        # http://www.cherrypy.org/ticket/533
+        # if a method is not found, an xmlrpclib.Fault should be raised
+        try:
+            proxy.non_method()
+        except Exception:
+            x = sys.exc_info()[1]
+            self.assertEqual(x.__class__, Fault)
+            self.assertEqual(x.faultString, 'method "non_method" is not supported')
+        else:
+            self.fail("Expected xmlrpclib.Fault")
+        
+        # Test returning a Fault from the page handler.
+        try:
+            proxy.test_returning_Fault()
+        except Exception:
+            x = sys.exc_info()[1]
+            self.assertEqual(x.__class__, Fault)
+            self.assertEqual(x.faultString, ("custom Fault response"))
+        else:
+            self.fail("Expected xmlrpclib.Fault")
+
diff --git a/cherrypy/test/webtest.py b/cherrypy/test/webtest.py
new file mode 100644
index 00000000..969eab0e
--- /dev/null
+++ b/cherrypy/test/webtest.py
@@ -0,0 +1,535 @@
+"""Extensions to unittest for web frameworks.
+
+Use the WebCase.getPage method to request a page from your HTTP server.
+
+Framework Integration
+=====================
+
+If you have control over your server process, you can handle errors
+in the server-side of the HTTP conversation a bit better. You must run
+both the client (your WebCase tests) and the server in the same process
+(but in separate threads, obviously).
+
+When an error occurs in the framework, call server_error. It will print
+the traceback to stdout, and keep any assertions you have from running
+(the assumption is that, if the server errors, the page output will not
+be of further significance to your tests).
+"""
+
+import os
+import pprint
+import re
+import socket
+import sys
+import time
+import traceback
+import types
+
+from unittest import *
+from unittest import _TextTestResult
+
+from cherrypy._cpcompat import basestring, HTTPConnection, HTTPSConnection, unicodestr
+
+
+
+def interface(host):
+    """Return an IP address for a client connection given the server host.
+
+    If the server is listening on '0.0.0.0' (INADDR_ANY)
+    or '::' (IN6ADDR_ANY), this will return the proper localhost."""
+    if host == '0.0.0.0':
+        # INADDR_ANY, which should respond on localhost.
+        return "127.0.0.1"
+    if host == '::':
+        # IN6ADDR_ANY, which should respond on localhost.
+        return "::1"
+    return host
+
+
+class TerseTestResult(_TextTestResult):
+
+    def printErrors(self):
+        # Overridden to avoid unnecessary empty line
+        if self.errors or self.failures:
+            if self.dots or self.showAll:
+                self.stream.writeln()
+            self.printErrorList('ERROR', self.errors)
+            self.printErrorList('FAIL', self.failures)
+
+
+class TerseTestRunner(TextTestRunner):
+    """A test runner class that displays results in textual form."""
+
+    def _makeResult(self):
+        return TerseTestResult(self.stream, self.descriptions, self.verbosity)
+
+    def run(self, test):
+        "Run the given test case or test suite."
+        # Overridden to remove unnecessary empty lines and separators
+        result = self._makeResult()
+        test(result)
+        result.printErrors()
+        if not result.wasSuccessful():
+            self.stream.write("FAILED (")
+            failed, errored = list(map(len, (result.failures, result.errors)))
+            if failed:
+                self.stream.write("failures=%d" % failed)
+            if errored:
+                if failed: self.stream.write(", ")
+                self.stream.write("errors=%d" % errored)
+            self.stream.writeln(")")
+        return result
+
+
+class ReloadingTestLoader(TestLoader):
+
+    def loadTestsFromName(self, name, module=None):
+        """Return a suite of all tests cases given a string specifier.
+
+        The name may resolve either to a module, a test case class, a
+        test method within a test case class, or a callable object which
+        returns a TestCase or TestSuite instance.
+
+        The method optionally resolves the names relative to a given module.
+        """
+        parts = name.split('.')
+        unused_parts = []
+        if module is None:
+            if not parts:
+                raise ValueError("incomplete test name: %s" % name)
+            else:
+                parts_copy = parts[:]
+                while parts_copy:
+                    target = ".".join(parts_copy)
+                    if target in sys.modules:
+                        module = reload(sys.modules[target])
+                        parts = unused_parts
+                        break
+                    else:
+                        try:
+                            module = __import__(target)
+                            parts = unused_parts
+                            break
+                        except ImportError:
+                            unused_parts.insert(0,parts_copy[-1])
+                            del parts_copy[-1]
+                            if not parts_copy:
+                                raise
+                parts = parts[1:]
+        obj = module
+        for part in parts:
+            obj = getattr(obj, part)
+
+        if type(obj) == types.ModuleType:
+            return self.loadTestsFromModule(obj)
+        elif (isinstance(obj, (type, types.ClassType)) and
+              issubclass(obj, TestCase)):
+            return self.loadTestsFromTestCase(obj)
+        elif type(obj) == types.UnboundMethodType:
+            return obj.im_class(obj.__name__)
+        elif hasattr(obj, '__call__'):
+            test = obj()
+            if not isinstance(test, TestCase) and \
+               not isinstance(test, TestSuite):
+                raise ValueError("calling %s returned %s, "
+                                 "not a test" % (obj,test))
+            return test
+        else:
+            raise ValueError("do not know how to make test from: %s" % obj)
+
+
+try:
+    # Jython support
+    if sys.platform[:4] == 'java':
+        def getchar():
+            # Hopefully this is enough
+            return sys.stdin.read(1)
+    else:
+        # On Windows, msvcrt.getch reads a single char without output.
+        import msvcrt
+        def getchar():
+            return msvcrt.getch()
+except ImportError:
+    # Unix getchr
+    import tty, termios
+    def getchar():
+        fd = sys.stdin.fileno()
+        old_settings = termios.tcgetattr(fd)
+        try:
+            tty.setraw(sys.stdin.fileno())
+            ch = sys.stdin.read(1)
+        finally:
+            termios.tcsetattr(fd, termios.TCSADRAIN, old_settings)
+        return ch
+
+
+class WebCase(TestCase):
+    HOST = "127.0.0.1"
+    PORT = 8000
+    HTTP_CONN = HTTPConnection
+    PROTOCOL = "HTTP/1.1"
+
+    scheme = "http"
+    url = None
+
+    status = None
+    headers = None
+    body = None
+    
+    encoding = 'utf-8'
+    
+    time = None
+
+    def get_conn(self, auto_open=False):
+        """Return a connection to our HTTP server."""
+        if self.scheme == "https":
+            cls = HTTPSConnection
+        else:
+            cls = HTTPConnection
+        conn = cls(self.interface(), self.PORT)
+        # Automatically re-connect?
+        conn.auto_open = auto_open
+        conn.connect()
+        return conn
+
+    def set_persistent(self, on=True, auto_open=False):
+        """Make our HTTP_CONN persistent (or not).
+
+        If the 'on' argument is True (the default), then self.HTTP_CONN
+        will be set to an instance of HTTPConnection (or HTTPS
+        if self.scheme is "https"). This will then persist across requests.
+
+        We only allow for a single open connection, so if you call this
+        and we currently have an open connection, it will be closed.
+        """
+        try:
+            self.HTTP_CONN.close()
+        except (TypeError, AttributeError):
+            pass
+
+        if on:
+            self.HTTP_CONN = self.get_conn(auto_open=auto_open)
+        else:
+            if self.scheme == "https":
+                self.HTTP_CONN = HTTPSConnection
+            else:
+                self.HTTP_CONN = HTTPConnection
+
+    def _get_persistent(self):
+        return hasattr(self.HTTP_CONN, "__class__")
+    def _set_persistent(self, on):
+        self.set_persistent(on)
+    persistent = property(_get_persistent, _set_persistent)
+
+    def interface(self):
+        """Return an IP address for a client connection.
+
+        If the server is listening on '0.0.0.0' (INADDR_ANY)
+        or '::' (IN6ADDR_ANY), this will return the proper localhost."""
+        return interface(self.HOST)
+
+    def getPage(self, url, headers=None, method="GET", body=None, protocol=None):
+        """Open the url with debugging support. Return status, headers, body."""
+        ServerError.on = False
+        
+        if isinstance(url, unicodestr):
+            url = url.encode('utf-8')
+        if isinstance(body, unicodestr):
+            body = body.encode('utf-8')
+        
+        self.url = url
+        self.time = None
+        start = time.time()
+        result = openURL(url, headers, method, body, self.HOST, self.PORT,
+                         self.HTTP_CONN, protocol or self.PROTOCOL)
+        self.time = time.time() - start
+        self.status, self.headers, self.body = result
+
+        # Build a list of request cookies from the previous response cookies.
+        self.cookies = [('Cookie', v) for k, v in self.headers
+                        if k.lower() == 'set-cookie']
+
+        if ServerError.on:
+            raise ServerError()
+        return result
+
+    interactive = True
+    console_height = 30
+
+    def _handlewebError(self, msg):
+        print("")
+        print("    ERROR: %s" % msg)
+
+        if not self.interactive:
+            raise self.failureException(msg)
+
+        p = "    Show: [B]ody [H]eaders [S]tatus [U]RL; [I]gnore, [R]aise, or sys.e[X]it >> "
+        sys.stdout.write(p)
+        sys.stdout.flush()
+        while True:
+            i = getchar().upper()
+            if i not in "BHSUIRX":
+                continue
+            print(i.upper())  # Also prints new line
+            if i == "B":
+                for x, line in enumerate(self.body.splitlines()):
+                    if (x + 1) % self.console_height == 0:
+                        # The \r and comma should make the next line overwrite
+                        sys.stdout.write("<-- More -->\r")
+                        m = getchar().lower()
+                        # Erase our "More" prompt
+                        sys.stdout.write("            \r")
+                        if m == "q":
+                            break
+                    print(line)
+            elif i == "H":
+                pprint.pprint(self.headers)
+            elif i == "S":
+                print(self.status)
+            elif i == "U":
+                print(self.url)
+            elif i == "I":
+                # return without raising the normal exception
+                return
+            elif i == "R":
+                raise self.failureException(msg)
+            elif i == "X":
+                self.exit()
+            sys.stdout.write(p)
+            sys.stdout.flush()
+
+    def exit(self):
+        sys.exit()
+
+    def assertStatus(self, status, msg=None):
+        """Fail if self.status != status."""
+        if isinstance(status, basestring):
+            if not self.status == status:
+                if msg is None:
+                    msg = 'Status (%r) != %r' % (self.status, status)
+                self._handlewebError(msg)
+        elif isinstance(status, int):
+            code = int(self.status[:3])
+            if code != status:
+                if msg is None:
+                    msg = 'Status (%r) != %r' % (self.status, status)
+                self._handlewebError(msg)
+        else:
+            # status is a tuple or list.
+            match = False
+            for s in status:
+                if isinstance(s, basestring):
+                    if self.status == s:
+                        match = True
+                        break
+                elif int(self.status[:3]) == s:
+                    match = True
+                    break
+            if not match:
+                if msg is None:
+                    msg = 'Status (%r) not in %r' % (self.status, status)
+                self._handlewebError(msg)
+
+    def assertHeader(self, key, value=None, msg=None):
+        """Fail if (key, [value]) not in self.headers."""
+        lowkey = key.lower()
+        for k, v in self.headers:
+            if k.lower() == lowkey:
+                if value is None or str(value) == v:
+                    return v
+
+        if msg is None:
+            if value is None:
+                msg = '%r not in headers' % key
+            else:
+                msg = '%r:%r not in headers' % (key, value)
+        self._handlewebError(msg)
+
+    def assertHeaderItemValue(self, key, value, msg=None):
+        """Fail if the header does not contain the specified value"""
+        actual_value = self.assertHeader(key, msg=msg)
+        header_values = map(str.strip, actual_value.split(','))
+        if value in header_values:
+            return value
+
+        if msg is None:
+            msg = "%r not in %r" % (value, header_values)
+        self._handlewebError(msg)
+
+    def assertNoHeader(self, key, msg=None):
+        """Fail if key in self.headers."""
+        lowkey = key.lower()
+        matches = [k for k, v in self.headers if k.lower() == lowkey]
+        if matches:
+            if msg is None:
+                msg = '%r in headers' % key
+            self._handlewebError(msg)
+
+    def assertBody(self, value, msg=None):
+        """Fail if value != self.body."""
+        if value != self.body:
+            if msg is None:
+                msg = 'expected body:\n%r\n\nactual body:\n%r' % (value, self.body)
+            self._handlewebError(msg)
+
+    def assertInBody(self, value, msg=None):
+        """Fail if value not in self.body."""
+        if value not in self.body:
+            if msg is None:
+                msg = '%r not in body: %s' % (value, self.body)
+            self._handlewebError(msg)
+
+    def assertNotInBody(self, value, msg=None):
+        """Fail if value in self.body."""
+        if value in self.body:
+            if msg is None:
+                msg = '%r found in body' % value
+            self._handlewebError(msg)
+
+    def assertMatchesBody(self, pattern, msg=None, flags=0):
+        """Fail if value (a regex pattern) is not in self.body."""
+        if re.search(pattern, self.body, flags) is None:
+            if msg is None:
+                msg = 'No match for %r in body' % pattern
+            self._handlewebError(msg)
+
+
+methods_with_bodies = ("POST", "PUT")
+
+def cleanHeaders(headers, method, body, host, port):
+    """Return request headers, with required headers added (if missing)."""
+    if headers is None:
+        headers = []
+
+    # Add the required Host request header if not present.
+    # [This specifies the host:port of the server, not the client.]
+    found = False
+    for k, v in headers:
+        if k.lower() == 'host':
+            found = True
+            break
+    if not found:
+        if port == 80:
+            headers.append(("Host", host))
+        else:
+            headers.append(("Host", "%s:%s" % (host, port)))
+
+    if method in methods_with_bodies:
+        # Stick in default type and length headers if not present
+        found = False
+        for k, v in headers:
+            if k.lower() == 'content-type':
+                found = True
+                break
+        if not found:
+            headers.append(("Content-Type", "application/x-www-form-urlencoded"))
+            headers.append(("Content-Length", str(len(body or ""))))
+
+    return headers
+
+
+def shb(response):
+    """Return status, headers, body the way we like from a response."""
+    h = []
+    key, value = None, None
+    for line in response.msg.headers:
+        if line:
+            if line[0] in " \t":
+                value += line.strip()
+            else:
+                if key and value:
+                    h.append((key, value))
+                key, value = line.split(":", 1)
+                key = key.strip()
+                value = value.strip()
+    if key and value:
+        h.append((key, value))
+
+    return "%s %s" % (response.status, response.reason), h, response.read()
+
+
+def openURL(url, headers=None, method="GET", body=None,
+            host="127.0.0.1", port=8000, http_conn=HTTPConnection,
+            protocol="HTTP/1.1"):
+    """Open the given HTTP resource and return status, headers, and body."""
+
+    headers = cleanHeaders(headers, method, body, host, port)
+
+    # Trying 10 times is simply in case of socket errors.
+    # Normal case--it should run once.
+    for trial in range(10):
+        try:
+            # Allow http_conn to be a class or an instance
+            if hasattr(http_conn, "host"):
+                conn = http_conn
+            else:
+                conn = http_conn(interface(host), port)
+
+            conn._http_vsn_str = protocol
+            conn._http_vsn = int("".join([x for x in protocol if x.isdigit()]))
+
+            # skip_accept_encoding argument added in python version 2.4
+            if sys.version_info < (2, 4):
+                def putheader(self, header, value):
+                    if header == 'Accept-Encoding' and value == 'identity':
+                        return
+                    self.__class__.putheader(self, header, value)
+                import new
+                conn.putheader = new.instancemethod(putheader, conn, conn.__class__)
+                conn.putrequest(method.upper(), url, skip_host=True)
+            else:
+                conn.putrequest(method.upper(), url, skip_host=True,
+                                skip_accept_encoding=True)
+
+            for key, value in headers:
+                conn.putheader(key, value)
+            conn.endheaders()
+
+            if body is not None:
+                conn.send(body)
+
+            # Handle response
+            response = conn.getresponse()
+
+            s, h, b = shb(response)
+
+            if not hasattr(http_conn, "host"):
+                # We made our own conn instance. Close it.
+                conn.close()
+
+            return s, h, b
+        except socket.error:
+            time.sleep(0.5)
+    raise
+
+
+# Add any exceptions which your web framework handles
+# normally (that you don't want server_error to trap).
+ignored_exceptions = []
+
+# You'll want set this to True when you can't guarantee
+# that each response will immediately follow each request;
+# for example, when handling requests via multiple threads.
+ignore_all = False
+
+class ServerError(Exception):
+    on = False
+
+
+def server_error(exc=None):
+    """Server debug hook. Return True if exception handled, False if ignored.
+
+    You probably want to wrap this, so you can still handle an error using
+    your framework when it's ignored.
+    """
+    if exc is None:
+        exc = sys.exc_info()
+
+    if ignore_all or exc[0] in ignored_exceptions:
+        return False
+    else:
+        ServerError.on = True
+        print("")
+        print("".join(traceback.format_exception(*exc)))
+        return True
+
diff --git a/cherrypy/tutorial/README.txt b/cherrypy/tutorial/README.txt
new file mode 100644
index 00000000..2b877e1f
--- /dev/null
+++ b/cherrypy/tutorial/README.txt
@@ -0,0 +1,16 @@
+CherryPy Tutorials
+------------------------------------------------------------------------
+
+This is a series of tutorials explaining how to develop dynamic web
+applications using CherryPy. A couple of notes:
+
+  - Each of these tutorials builds on the ones before it. If you're
+    new to CherryPy, we recommend you start with 01_helloworld.py and
+    work your way upwards. :)
+
+  - In most of these tutorials, you will notice that all output is done
+    by returning normal Python strings, often using simple Python
+    variable substitution. In most real-world applications, you will
+    probably want to use a separate template package (like Cheetah,
+    CherryTemplate or XML/XSL).
+
diff --git a/cherrypy/tutorial/__init__.py b/cherrypy/tutorial/__init__.py
new file mode 100644
index 00000000..c4e2c558
--- /dev/null
+++ b/cherrypy/tutorial/__init__.py
@@ -0,0 +1,3 @@
+
+# This is used in test_config to test unrepr of "from A import B"
+thing2 = object()
\ No newline at end of file
diff --git a/cherrypy/tutorial/bonus-sqlobject.py b/cherrypy/tutorial/bonus-sqlobject.py
new file mode 100644
index 00000000..c43feb45
--- /dev/null
+++ b/cherrypy/tutorial/bonus-sqlobject.py
@@ -0,0 +1,168 @@
+'''
+Bonus Tutorial: Using SQLObject
+
+This is a silly little contacts manager application intended to
+demonstrate how to use SQLObject from within a CherryPy2 project. It
+also shows how to use inline Cheetah templates.
+
+SQLObject is an Object/Relational Mapper that allows you to access
+data stored in an RDBMS in a pythonic fashion. You create data objects
+as Python classes and let SQLObject take care of all the nasty details.
+
+This code depends on the latest development version (0.6+) of SQLObject.
+You can get it from the SQLObject Subversion server. You can find all
+necessary information at . This code will NOT
+work with the 0.5.x version advertised on their website!
+
+This code also depends on a recent version of Cheetah. You can find
+Cheetah at .
+
+After starting this application for the first time, you will need to
+access the /reset URI in order to create the database table and some
+sample data. Accessing /reset again will drop and re-create the table,
+so you may want to be careful. :-)
+
+This application isn't supposed to be fool-proof, it's not even supposed
+to be very GOOD. Play around with it some, browse the source code, smile.
+
+:)
+
+-- Hendrik Mans 
+'''
+
+import cherrypy
+from Cheetah.Template import Template
+from sqlobject import *
+
+# configure your database connection here
+__connection__ = 'mysql://root:@localhost/test'
+
+# this is our (only) data class.
+class Contact(SQLObject):
+    lastName = StringCol(length = 50, notNone = True)
+    firstName = StringCol(length = 50, notNone = True)
+    phone = StringCol(length = 30, notNone = True, default = '')
+    email = StringCol(length = 30, notNone = True, default = '')
+    url = StringCol(length = 100, notNone = True, default = '')
+
+
+class ContactManager:
+    def index(self):
+        # Let's display a list of all stored contacts.
+        contacts = Contact.select()
+
+        template = Template('''
+            
All Contacts

+
+            #for $contact in $contacts
+                $contact.lastName, $contact.firstName
+                [Edit]
+                [Delete]
+                

+            #end for
+
+            
[Add new contact]

+        ''', [locals(), globals()])
+
+        return template.respond()
+
+    index.exposed = True
+
+
+    def edit(self, id = 0):
+        # we really want id as an integer. Since GET/POST parameters
+        # are always passed as strings, let's convert it.
+        id = int(id)
+
+        if id > 0:
+            # if an id is specified, we're editing an existing contact.
+            contact = Contact.get(id)
+            title = "Edit Contact"
+        else:
+            # if no id is specified, we're entering a new contact.
+            contact = None
+            title = "New Contact"
+
+
+        # In the following template code, please note that we use
+        # Cheetah's $getVar() construct for the form values. We have
+        # to do this because contact may be set to None (see above).
+        template = Template('''
+            
$title

+
+            
+                
+                Last Name: 

+                First Name: 

+                Phone: 

+                Email: 

+                URL: 

+                
+            

+        ''', [locals(), globals()])
+
+        return template.respond()
+
+    edit.exposed = True
+
+
+    def delete(self, id):
+        # Delete the specified contact
+        contact = Contact.get(int(id))
+        contact.destroySelf()
+        return 'Deleted. Return to Index'
+
+    delete.exposed = True
+
+
+    def store(self, lastName, firstName, phone, email, url, id = None):
+        if id and int(id) > 0:
+            # If an id was specified, update an existing contact.
+            contact = Contact.get(int(id))
+
+            # We could set one field after another, but that would
+            # cause multiple UPDATE clauses. So we'll just do it all
+            # in a single pass through the set() method.
+            contact.set(
+                lastName = lastName,
+                firstName = firstName,
+                phone = phone,
+                email = email,
+                url = url)
+        else:
+            # Otherwise, add a new contact.
+            contact = Contact(
+                lastName = lastName,
+                firstName = firstName,
+                phone = phone,
+                email = email,
+                url = url)
+
+        return 'Stored. Return to Index'
+
+    store.exposed = True
+
+
+    def reset(self):
+        # Drop existing table
+        Contact.dropTable(True)
+
+        # Create new table
+        Contact.createTable()
+
+        # Create some sample data
+        Contact(
+            firstName = 'Hendrik',
+            lastName = 'Mans',
+            email = 'hendrik@mans.de',
+            phone = '++49 89 12345678',
+            url = 'http://www.mornography.de')
+
+        return "reset completed!"
+
+    reset.exposed = True
+
+
+print("If you're running this application for the first time, please go to http://localhost:8080/reset once in order to create the database!")
+
+cherrypy.quickstart(ContactManager())
diff --git a/cherrypy/tutorial/custom_error.html b/cherrypy/tutorial/custom_error.html
new file mode 100644
index 00000000..d0f30c8a
--- /dev/null
+++ b/cherrypy/tutorial/custom_error.html
@@ -0,0 +1,14 @@
+
+
+
+
+    403 Unauthorized
+
+    
+        
You can't do that!

+        
%(message)s

+        
This is a custom error page that is read from a file.

+        
%(traceback)s

+    
+
diff --git a/cherrypy/tutorial/pdf_file.pdf b/cherrypy/tutorial/pdf_file.pdf
new file mode 100644
index 0000000000000000000000000000000000000000..38b4f15eabdd65d4a674cb32034361245aa7b97e
GIT binary patch
literal 85698
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 message for you!'
+    index.exposed = True
+    
+    def showMessage(self):
+        # Here's the important message!
+        return "Hello world!"
+    showMessage.exposed = True
+
+import os.path
+tutconf = os.path.join(os.path.dirname(__file__), 'tutorial.conf')
+
+if __name__ == '__main__':
+    # CherryPy always starts with app.root when trying to map request URIs
+    # to objects, so we need to mount a request handler root. A request
+    # to '/' will be mapped to HelloWorld().index().
+    cherrypy.quickstart(HelloWorld(), config=tutconf)
+else:
+    # This branch is for the test suite; you can ignore it.
+    cherrypy.tree.mount(HelloWorld(), config=tutconf)
diff --git a/cherrypy/tutorial/tut03_get_and_post.py b/cherrypy/tutorial/tut03_get_and_post.py
new file mode 100644
index 00000000..283477d5
--- /dev/null
+++ b/cherrypy/tutorial/tut03_get_and_post.py
@@ -0,0 +1,53 @@
+"""
+Tutorial - Passing variables
+
+This tutorial shows you how to pass GET/POST variables to methods.
+"""
+
+import cherrypy
+
+
+class WelcomePage:
+
+    def index(self):
+        # Ask for the user's name.
+        return '''
+            

+            What is your name?
+            
+            
+            
'''
+    index.exposed = True
+    
+    def greetUser(self, name = None):
+        # CherryPy passes all GET and POST variables as method parameters.
+        # It doesn't make a difference where the variables come from, how
+        # large their contents are, and so on.
+        #
+        # You can define default parameter values as usual. In this
+        # example, the "name" parameter defaults to None so we can check
+        # if a name was actually specified.
+        
+        if name:
+            # Greet the user!
+            return "Hey %s, what's up?" % name
+        else:
+            if name is None:
+                # No name was specified
+                return 'Please enter your name here.'
+            else:
+                return 'No, really, enter your name here.'
+    greetUser.exposed = True
+
+
+import os.path
+tutconf = os.path.join(os.path.dirname(__file__), 'tutorial.conf')
+
+if __name__ == '__main__':
+    # CherryPy always starts with app.root when trying to map request URIs
+    # to objects, so we need to mount a request handler root. A request
+    # to '/' will be mapped to HelloWorld().index().
+    cherrypy.quickstart(WelcomePage(), config=tutconf)
+else:
+    # This branch is for the test suite; you can ignore it.
+    cherrypy.tree.mount(WelcomePage(), config=tutconf)
diff --git a/cherrypy/tutorial/tut04_complex_site.py b/cherrypy/tutorial/tut04_complex_site.py
new file mode 100644
index 00000000..b4d820ed
--- /dev/null
+++ b/cherrypy/tutorial/tut04_complex_site.py
@@ -0,0 +1,98 @@
+"""
+Tutorial - Multiple objects
+
+This tutorial shows you how to create a site structure through multiple
+possibly nested request handler objects.
+"""
+
+import cherrypy
+
+
+class HomePage:
+    def index(self):
+        return '''
+            
Hi, this is the home page! Check out the other
+            fun stuff on this site:

+            
+            '''
+    index.exposed = True
+
+
+class JokePage:
+    def index(self):
+        return '''
+            
"In Python, how do you create a string of random
+            characters?" -- "Read a Perl file!"

+            
[Return]
'''
+    index.exposed = True
+
+
+class LinksPage:
+    def __init__(self):
+        # Request handler objects can create their own nested request
+        # handler objects. Simply create them inside their __init__
+        # methods!
+        self.extra = ExtraLinksPage()
+    
+    def index(self):
+        # Note the way we link to the extra links page (and back).
+        # As you can see, this object doesn't really care about its
+        # absolute position in the site tree, since we use relative
+        # links exclusively.
+        return '''
+            
Here are some useful links:

+            
+            
+            
+            
You can check out some extra useful
+            links here.

+            
+            
[Return]

+        '''
+    index.exposed = True
+
+
+class ExtraLinksPage:
+    def index(self):
+        # Note the relative link back to the Links page!
+        return '''
+            
Here are some extra useful links:

+            
+            
+            
+            
[Return to links page]
'''
+    index.exposed = True
+
+
+# Of course we can also mount request handler objects right here!
+root = HomePage()
+root.joke = JokePage()
+root.links = LinksPage()
+
+# Remember, we don't need to mount ExtraLinksPage here, because
+# LinksPage does that itself on initialization. In fact, there is
+# no reason why you shouldn't let your root object take care of
+# creating all contained request handler objects.
+
+
+import os.path
+tutconf = os.path.join(os.path.dirname(__file__), 'tutorial.conf')
+
+if __name__ == '__main__':
+    # CherryPy always starts with app.root when trying to map request URIs
+    # to objects, so we need to mount a request handler root. A request
+    # to '/' will be mapped to HelloWorld().index().
+    cherrypy.quickstart(root, config=tutconf)
+else:
+    # This branch is for the test suite; you can ignore it.
+    cherrypy.tree.mount(root, config=tutconf)
+
diff --git a/cherrypy/tutorial/tut05_derived_objects.py b/cherrypy/tutorial/tut05_derived_objects.py
new file mode 100644
index 00000000..3d4ec9b1
--- /dev/null
+++ b/cherrypy/tutorial/tut05_derived_objects.py
@@ -0,0 +1,83 @@
+"""
+Tutorial - Object inheritance
+
+You are free to derive your request handler classes from any base
+class you wish. In most real-world applications, you will probably
+want to create a central base class used for all your pages, which takes
+care of things like printing a common page header and footer.
+"""
+
+import cherrypy
+
+
+class Page:
+    # Store the page title in a class attribute
+    title = 'Untitled Page'
+    
+    def header(self):
+        return '''
+            
+            
+                %s
+            
+            
+            
%s

+        ''' % (self.title, self.title)
+    
+    def footer(self):
+        return '''
+            
+            
+        '''
+    
+    # Note that header and footer don't get their exposed attributes
+    # set to True. This isn't necessary since the user isn't supposed
+    # to call header or footer directly; instead, we'll call them from
+    # within the actually exposed handler methods defined in this
+    # class' subclasses.
+
+
+class HomePage(Page):
+    # Different title for this page
+    title = 'Tutorial 5'
+    
+    def __init__(self):
+        # create a subpage
+        self.another = AnotherPage()
+    
+    def index(self):
+        # Note that we call the header and footer methods inherited
+        # from the Page class!
+        return self.header() + '''
+            

+            Isn't this exciting? There's
+            another page, too!
+            

+        ''' + self.footer()
+    index.exposed = True
+
+
+class AnotherPage(Page):
+    title = 'Another Page'
+    
+    def index(self):
+        return self.header() + '''
+            

+            And this is the amazing second page!
+            

+        ''' + self.footer()
+    index.exposed = True
+
+
+import os.path
+tutconf = os.path.join(os.path.dirname(__file__), 'tutorial.conf')
+
+if __name__ == '__main__':
+    # CherryPy always starts with app.root when trying to map request URIs
+    # to objects, so we need to mount a request handler root. A request
+    # to '/' will be mapped to HelloWorld().index().
+    cherrypy.quickstart(HomePage(), config=tutconf)
+else:
+    # This branch is for the test suite; you can ignore it.
+    cherrypy.tree.mount(HomePage(), config=tutconf)
+
diff --git a/cherrypy/tutorial/tut06_default_method.py b/cherrypy/tutorial/tut06_default_method.py
new file mode 100644
index 00000000..fe24f380
--- /dev/null
+++ b/cherrypy/tutorial/tut06_default_method.py
@@ -0,0 +1,64 @@
+"""
+Tutorial - The default method
+
+Request handler objects can implement a method called "default" that
+is called when no other suitable method/object could be found.
+Essentially, if CherryPy2 can't find a matching request handler object
+for the given request URI, it will use the default method of the object
+located deepest on the URI path.
+
+Using this mechanism you can easily simulate virtual URI structures
+by parsing the extra URI string, which you can access through
+cherrypy.request.virtualPath.
+
+The application in this tutorial simulates an URI structure looking
+like /users/. Since the  bit will not be found (as
+there are no matching methods), it is handled by the default method.
+"""
+
+import cherrypy
+
+
+class UsersPage:
+    
+    def index(self):
+        # Since this is just a stupid little example, we'll simply
+        # display a list of links to random, made-up users. In a real
+        # application, this could be generated from a database result set.
+        return '''
+            Remi Delon

+            Hendrik Mans

+            Lorenzo Lamas

+        '''
+    index.exposed = True
+    
+    def default(self, user):
+        # Here we react depending on the virtualPath -- the part of the
+        # path that could not be mapped to an object method. In a real
+        # application, we would probably do some database lookups here
+        # instead of the silly if/elif/else construct.
+        if user == 'remi':
+            out = "Remi Delon, CherryPy lead developer"
+        elif user == 'hendrik':
+            out = "Hendrik Mans, CherryPy co-developer & crazy German"
+        elif user == 'lorenzo':
+            out = "Lorenzo Lamas, famous actor and singer!"
+        else:
+            out = "Unknown user. :-("
+        
+        return '%s (back)' % out
+    default.exposed = True
+
+
+import os.path
+tutconf = os.path.join(os.path.dirname(__file__), 'tutorial.conf')
+
+if __name__ == '__main__':
+    # CherryPy always starts with app.root when trying to map request URIs
+    # to objects, so we need to mount a request handler root. A request
+    # to '/' will be mapped to HelloWorld().index().
+    cherrypy.quickstart(UsersPage(), config=tutconf)
+else:
+    # This branch is for the test suite; you can ignore it.
+    cherrypy.tree.mount(UsersPage(), config=tutconf)
+
diff --git a/cherrypy/tutorial/tut07_sessions.py b/cherrypy/tutorial/tut07_sessions.py
new file mode 100644
index 00000000..4b1386b4
--- /dev/null
+++ b/cherrypy/tutorial/tut07_sessions.py
@@ -0,0 +1,44 @@
+"""
+Tutorial - Sessions
+
+Storing session data in CherryPy applications is very easy: cherrypy
+provides a dictionary called "session" that represents the session
+data for the current user. If you use RAM based sessions, you can store
+any kind of object into that dictionary; otherwise, you are limited to
+objects that can be pickled.
+"""
+
+import cherrypy
+
+
+class HitCounter:
+    
+    _cp_config = {'tools.sessions.on': True}
+    
+    def index(self):
+        # Increase the silly hit counter
+        count = cherrypy.session.get('count', 0) + 1
+        
+        # Store the new value in the session dictionary
+        cherrypy.session['count'] = count
+        
+        # And display a silly hit count message!
+        return '''
+            During your current session, you've viewed this
+            page %s times! Your life is a patio of fun!
+        ''' % count
+    index.exposed = True
+
+
+import os.path
+tutconf = os.path.join(os.path.dirname(__file__), 'tutorial.conf')
+
+if __name__ == '__main__':
+    # CherryPy always starts with app.root when trying to map request URIs
+    # to objects, so we need to mount a request handler root. A request
+    # to '/' will be mapped to HelloWorld().index().
+    cherrypy.quickstart(HitCounter(), config=tutconf)
+else:
+    # This branch is for the test suite; you can ignore it.
+    cherrypy.tree.mount(HitCounter(), config=tutconf)
+
diff --git a/cherrypy/tutorial/tut08_generators_and_yield.py b/cherrypy/tutorial/tut08_generators_and_yield.py
new file mode 100644
index 00000000..a6fbdc24
--- /dev/null
+++ b/cherrypy/tutorial/tut08_generators_and_yield.py
@@ -0,0 +1,47 @@
+"""
+Bonus Tutorial: Using generators to return result bodies
+
+Instead of returning a complete result string, you can use the yield
+statement to return one result part after another. This may be convenient
+in situations where using a template package like CherryPy or Cheetah
+would be overkill, and messy string concatenation too uncool. ;-)
+"""
+
+import cherrypy
+
+
+class GeneratorDemo:
+    
+    def header(self):
+        return "
Generators rule!
"
+    
+    def footer(self):
+        return ""
+    
+    def index(self):
+        # Let's make up a list of users for presentation purposes
+        users = ['Remi', 'Carlos', 'Hendrik', 'Lorenzo Lamas']
+        
+        # Every yield line adds one part to the total result body.
+        yield self.header()
+        yield "
List of users:
"
+        
+        for user in users:
+            yield "%s
" % user
+            
+        yield self.footer()
+    index.exposed = True
+
+
+import os.path
+tutconf = os.path.join(os.path.dirname(__file__), 'tutorial.conf')
+
+if __name__ == '__main__':
+    # CherryPy always starts with app.root when trying to map request URIs
+    # to objects, so we need to mount a request handler root. A request
+    # to '/' will be mapped to HelloWorld().index().
+    cherrypy.quickstart(GeneratorDemo(), config=tutconf)
+else:
+    # This branch is for the test suite; you can ignore it.
+    cherrypy.tree.mount(GeneratorDemo(), config=tutconf)
+
diff --git a/cherrypy/tutorial/tut09_files.py b/cherrypy/tutorial/tut09_files.py
new file mode 100644
index 00000000..4c8e5815
--- /dev/null
+++ b/cherrypy/tutorial/tut09_files.py
@@ -0,0 +1,107 @@
+"""
+
+Tutorial: File upload and download
+
+Uploads
+-------
+
+When a client uploads a file to a CherryPy application, it's placed
+on disk immediately. CherryPy will pass it to your exposed method
+as an argument (see "myFile" below); that arg will have a "file"
+attribute, which is a handle to the temporary uploaded file.
+If you wish to permanently save the file, you need to read()
+from myFile.file and write() somewhere else.
+
+Note the use of 'enctype="multipart/form-data"' and 'input type="file"'
+in the HTML which the client uses to upload the file.
+
+
+Downloads
+---------
+
+If you wish to send a file to the client, you have two options:
+First, you can simply return a file-like object from your page handler.
+CherryPy will read the file and serve it as the content (HTTP body)
+of the response. However, that doesn't tell the client that
+the response is a file to be saved, rather than displayed.
+Use cherrypy.lib.static.serve_file for that; it takes four
+arguments:
+
+serve_file(path, content_type=None, disposition=None, name=None)
+
+Set "name" to the filename that you expect clients to use when they save
+your file. Note that the "name" argument is ignored if you don't also
+provide a "disposition" (usually "attachement"). You can manually set
+"content_type", but be aware that if you also use the encoding tool, it
+may choke if the file extension is not recognized as belonging to a known
+Content-Type. Setting the content_type to "application/x-download" works
+in most cases, and should prompt the user with an Open/Save dialog in
+popular browsers.
+
+"""
+
+import os
+localDir = os.path.dirname(__file__)
+absDir = os.path.join(os.getcwd(), localDir)
+
+import cherrypy
+from cherrypy.lib import static
+
+
+class FileDemo(object):
+    
+    def index(self):
+        return """
+        
+            
Upload a file

+            

+            filename: 

+            
+            

+            
Download a file

+            This one
+        
+        """
+    index.exposed = True
+    
+    def upload(self, myFile):
+        out = """
+        
+            myFile length: %s

+            myFile filename: %s

+            myFile mime-type: %s
+        
+        """
+        
+        # Although this just counts the file length, it demonstrates
+        # how to read large files in chunks instead of all at once.
+        # CherryPy reads the uploaded file into a temporary file;
+        # myFile.file.read reads from that.
+        size = 0
+        while True:
+            data = myFile.file.read(8192)
+            if not data:
+                break
+            size += len(data)
+        
+        return out % (size, myFile.filename, myFile.content_type)
+    upload.exposed = True
+    
+    def download(self):
+        path = os.path.join(absDir, "pdf_file.pdf")
+        return static.serve_file(path, "application/x-download",
+                                 "attachment", os.path.basename(path))
+    download.exposed = True
+
+
+import os.path
+tutconf = os.path.join(os.path.dirname(__file__), 'tutorial.conf')
+
+if __name__ == '__main__':
+    # CherryPy always starts with app.root when trying to map request URIs
+    # to objects, so we need to mount a request handler root. A request
+    # to '/' will be mapped to HelloWorld().index().
+    cherrypy.quickstart(FileDemo(), config=tutconf)
+else:
+    # This branch is for the test suite; you can ignore it.
+    cherrypy.tree.mount(FileDemo(), config=tutconf)
diff --git a/cherrypy/tutorial/tut10_http_errors.py b/cherrypy/tutorial/tut10_http_errors.py
new file mode 100644
index 00000000..dfa57331
--- /dev/null
+++ b/cherrypy/tutorial/tut10_http_errors.py
@@ -0,0 +1,81 @@
+"""
+
+Tutorial: HTTP errors
+
+HTTPError is used to return an error response to the client.
+CherryPy has lots of options regarding how such errors are
+logged, displayed, and formatted.
+
+"""
+
+import os
+localDir = os.path.dirname(__file__)
+curpath = os.path.normpath(os.path.join(os.getcwd(), localDir))
+
+import cherrypy
+
+
+class HTTPErrorDemo(object):
+    
+    # Set a custom response for 403 errors.
+    _cp_config = {'error_page.403' : os.path.join(curpath, "custom_error.html")}
+    
+    def index(self):
+        # display some links that will result in errors
+        tracebacks = cherrypy.request.show_tracebacks
+        if tracebacks:
+            trace = 'off'
+        else:
+            trace = 'on'
+            
+        return """
+        
+            
Toggle tracebacks %s

+            
Click me; I'm a broken link!

+            
Use a custom error page from a file.

+            
These errors are explicitly raised by the application:

+            
+            
You can also set the response body
+            when you raise an error.

+        
+        """ % trace
+    index.exposed = True
+    
+    def toggleTracebacks(self):
+        # simple function to toggle tracebacks on and off 
+        tracebacks = cherrypy.request.show_tracebacks
+        cherrypy.config.update({'request.show_tracebacks': not tracebacks})
+        
+        # redirect back to the index
+        raise cherrypy.HTTPRedirect('/')
+    toggleTracebacks.exposed = True
+    
+    def error(self, code):
+        # raise an error based on the get query
+        raise cherrypy.HTTPError(status = code)
+    error.exposed = True
+    
+    def messageArg(self):
+        message = ("If you construct an HTTPError with a 'message' "
+                   "argument, it wil be placed on the error page "
+                   "(underneath the status line by default).")
+        raise cherrypy.HTTPError(500, message=message)
+    messageArg.exposed = True
+
+
+import os.path
+tutconf = os.path.join(os.path.dirname(__file__), 'tutorial.conf')
+
+if __name__ == '__main__':
+    # CherryPy always starts with app.root when trying to map request URIs
+    # to objects, so we need to mount a request handler root. A request
+    # to '/' will be mapped to HelloWorld().index().
+    cherrypy.quickstart(HTTPErrorDemo(), config=tutconf)
+else:
+    # This branch is for the test suite; you can ignore it.
+    cherrypy.tree.mount(HTTPErrorDemo(), config=tutconf)
diff --git a/cherrypy/tutorial/tutorial.conf b/cherrypy/tutorial/tutorial.conf
new file mode 100644
index 00000000..b978408c
--- /dev/null
+++ b/cherrypy/tutorial/tutorial.conf
@@ -0,0 +1,4 @@
+[global]
+server.socket_host = "127.0.0.1"
+server.socket_port = 8181
+server.thread_pool = 10
diff --git a/cherrypy/wsgiserver/__init__.py b/cherrypy/wsgiserver/__init__.py
new file mode 100644
index 00000000..55d1dd90
--- /dev/null
+++ b/cherrypy/wsgiserver/__init__.py
@@ -0,0 +1,2219 @@
+"""A high-speed, production ready, thread pooled, generic HTTP server.
+
+Simplest example on how to use this module directly
+(without using CherryPy's application machinery)::
+
+    from cherrypy import wsgiserver
+    
+    def my_crazy_app(environ, start_response):
+        status = '200 OK'
+        response_headers = [('Content-type','text/plain')]
+        start_response(status, response_headers)
+        return ['Hello world!']
+    
+    server = wsgiserver.CherryPyWSGIServer(
+                ('0.0.0.0', 8070), my_crazy_app,
+                server_name='www.cherrypy.example')
+    server.start()
+    
+The CherryPy WSGI server can serve as many WSGI applications 
+as you want in one instance by using a WSGIPathInfoDispatcher::
+    
+    d = WSGIPathInfoDispatcher({'/': my_crazy_app, '/blog': my_blog_app})
+    server = wsgiserver.CherryPyWSGIServer(('0.0.0.0', 80), d)
+    
+Want SSL support? Just set server.ssl_adapter to an SSLAdapter instance.
+
+This won't call the CherryPy engine (application side) at all, only the
+HTTP server, which is independent from the rest of CherryPy. Don't
+let the name "CherryPyWSGIServer" throw you; the name merely reflects
+its origin, not its coupling.
+
+For those of you wanting to understand internals of this module, here's the
+basic call flow. The server's listening thread runs a very tight loop,
+sticking incoming connections onto a Queue::
+
+    server = CherryPyWSGIServer(...)
+    server.start()
+    while True:
+        tick()
+        # This blocks until a request comes in:
+        child = socket.accept()
+        conn = HTTPConnection(child, ...)
+        server.requests.put(conn)
+
+Worker threads are kept in a pool and poll the Queue, popping off and then
+handling each connection in turn. Each connection can consist of an arbitrary
+number of requests and their responses, so we run a nested loop::
+
+    while True:
+        conn = server.requests.get()
+        conn.communicate()
+        ->  while True:
+                req = HTTPRequest(...)
+                req.parse_request()
+                ->  # Read the Request-Line, e.g. "GET /page HTTP/1.1"
+                    req.rfile.readline()
+                    read_headers(req.rfile, req.inheaders)
+                req.respond()
+                ->  response = app(...)
+                    try:
+                        for chunk in response:
+                            if chunk:
+                                req.write(chunk)
+                    finally:
+                        if hasattr(response, "close"):
+                            response.close()
+                if req.close_connection:
+                    return
+"""
+
+CRLF = '\r\n'
+import os
+import Queue
+import re
+quoted_slash = re.compile("(?i)%2F")
+import rfc822
+import socket
+import sys
+if 'win' in sys.platform and not hasattr(socket, 'IPPROTO_IPV6'):
+    socket.IPPROTO_IPV6 = 41
+try:
+    import cStringIO as StringIO
+except ImportError:
+    import StringIO
+DEFAULT_BUFFER_SIZE = -1
+
+_fileobject_uses_str_type = isinstance(socket._fileobject(None)._rbuf, basestring)
+
+import threading
+import time
+import traceback
+def format_exc(limit=None):
+    """Like print_exc() but return a string. Backport for Python 2.3."""
+    try:
+        etype, value, tb = sys.exc_info()
+        return ''.join(traceback.format_exception(etype, value, tb, limit))
+    finally:
+        etype = value = tb = None
+
+
+from urllib import unquote
+from urlparse import urlparse
+import warnings
+
+import errno
+
+def plat_specific_errors(*errnames):
+    """Return error numbers for all errors in errnames on this platform.
+    
+    The 'errno' module contains different global constants depending on
+    the specific platform (OS). This function will return the list of
+    numeric values for a given list of potential names.
+    """
+    errno_names = dir(errno)
+    nums = [getattr(errno, k) for k in errnames if k in errno_names]
+    # de-dupe the list
+    return dict.fromkeys(nums).keys()
+
+socket_error_eintr = plat_specific_errors("EINTR", "WSAEINTR")
+
+socket_errors_to_ignore = plat_specific_errors(
+    "EPIPE",
+    "EBADF", "WSAEBADF",
+    "ENOTSOCK", "WSAENOTSOCK",
+    "ETIMEDOUT", "WSAETIMEDOUT",
+    "ECONNREFUSED", "WSAECONNREFUSED",
+    "ECONNRESET", "WSAECONNRESET",
+    "ECONNABORTED", "WSAECONNABORTED",
+    "ENETRESET", "WSAENETRESET",
+    "EHOSTDOWN", "EHOSTUNREACH",
+    )
+socket_errors_to_ignore.append("timed out")
+socket_errors_to_ignore.append("The read operation timed out")
+
+socket_errors_nonblocking = plat_specific_errors(
+    'EAGAIN', 'EWOULDBLOCK', 'WSAEWOULDBLOCK')
+
+comma_separated_headers = ['Accept', 'Accept-Charset', 'Accept-Encoding',
+    'Accept-Language', 'Accept-Ranges', 'Allow', 'Cache-Control',
+    'Connection', 'Content-Encoding', 'Content-Language', 'Expect',
+    'If-Match', 'If-None-Match', 'Pragma', 'Proxy-Authenticate', 'TE',
+    'Trailer', 'Transfer-Encoding', 'Upgrade', 'Vary', 'Via', 'Warning',
+    'WWW-Authenticate']
+
+
+import logging
+if not hasattr(logging, 'statistics'): logging.statistics = {}
+
+
+def read_headers(rfile, hdict=None):
+    """Read headers from the given stream into the given header dict.
+    
+    If hdict is None, a new header dict is created. Returns the populated
+    header dict.
+    
+    Headers which are repeated are folded together using a comma if their
+    specification so dictates.
+    
+    This function raises ValueError when the read bytes violate the HTTP spec.
+    You should probably return "400 Bad Request" if this happens.
+    """
+    if hdict is None:
+        hdict = {}
+    
+    while True:
+        line = rfile.readline()
+        if not line:
+            # No more data--illegal end of headers
+            raise ValueError("Illegal end of headers.")
+        
+        if line == CRLF:
+            # Normal end of headers
+            break
+        if not line.endswith(CRLF):
+            raise ValueError("HTTP requires CRLF terminators")
+        
+        if line[0] in ' \t':
+            # It's a continuation line.
+            v = line.strip()
+        else:
+            try:
+                k, v = line.split(":", 1)
+            except ValueError:
+                raise ValueError("Illegal header line.")
+            # TODO: what about TE and WWW-Authenticate?
+            k = k.strip().title()
+            v = v.strip()
+            hname = k
+        
+        if k in comma_separated_headers:
+            existing = hdict.get(hname)
+            if existing:
+                v = ", ".join((existing, v))
+        hdict[hname] = v
+    
+    return hdict
+
+
+class MaxSizeExceeded(Exception):
+    pass
+
+class SizeCheckWrapper(object):
+    """Wraps a file-like object, raising MaxSizeExceeded if too large."""
+    
+    def __init__(self, rfile, maxlen):
+        self.rfile = rfile
+        self.maxlen = maxlen
+        self.bytes_read = 0
+    
+    def _check_length(self):
+        if self.maxlen and self.bytes_read > self.maxlen:
+            raise MaxSizeExceeded()
+    
+    def read(self, size=None):
+        data = self.rfile.read(size)
+        self.bytes_read += len(data)
+        self._check_length()
+        return data
+    
+    def readline(self, size=None):
+        if size is not None:
+            data = self.rfile.readline(size)
+            self.bytes_read += len(data)
+            self._check_length()
+            return data
+        
+        # User didn't specify a size ...
+        # We read the line in chunks to make sure it's not a 100MB line !
+        res = []
+        while True:
+            data = self.rfile.readline(256)
+            self.bytes_read += len(data)
+            self._check_length()
+            res.append(data)
+            # See http://www.cherrypy.org/ticket/421
+            if len(data) < 256 or data[-1:] == "\n":
+                return ''.join(res)
+    
+    def readlines(self, sizehint=0):
+        # Shamelessly stolen from StringIO
+        total = 0
+        lines = []
+        line = self.readline()
+        while line:
+            lines.append(line)
+            total += len(line)
+            if 0 < sizehint <= total:
+                break
+            line = self.readline()
+        return lines
+    
+    def close(self):
+        self.rfile.close()
+    
+    def __iter__(self):
+        return self
+    
+    def next(self):
+        data = self.rfile.next()
+        self.bytes_read += len(data)
+        self._check_length()
+        return data
+
+
+class KnownLengthRFile(object):
+    """Wraps a file-like object, returning an empty string when exhausted."""
+    
+    def __init__(self, rfile, content_length):
+        self.rfile = rfile
+        self.remaining = content_length
+    
+    def read(self, size=None):
+        if self.remaining == 0:
+            return ''
+        if size is None:
+            size = self.remaining
+        else:
+            size = min(size, self.remaining)
+        
+        data = self.rfile.read(size)
+        self.remaining -= len(data)
+        return data
+    
+    def readline(self, size=None):
+        if self.remaining == 0:
+            return ''
+        if size is None:
+            size = self.remaining
+        else:
+            size = min(size, self.remaining)
+        
+        data = self.rfile.readline(size)
+        self.remaining -= len(data)
+        return data
+    
+    def readlines(self, sizehint=0):
+        # Shamelessly stolen from StringIO
+        total = 0
+        lines = []
+        line = self.readline(sizehint)
+        while line:
+            lines.append(line)
+            total += len(line)
+            if 0 < sizehint <= total:
+                break
+            line = self.readline(sizehint)
+        return lines
+    
+    def close(self):
+        self.rfile.close()
+    
+    def __iter__(self):
+        return self
+    
+    def __next__(self):
+        data = next(self.rfile)
+        self.remaining -= len(data)
+        return data
+
+
+class ChunkedRFile(object):
+    """Wraps a file-like object, returning an empty string when exhausted.
+    
+    This class is intended to provide a conforming wsgi.input value for
+    request entities that have been encoded with the 'chunked' transfer
+    encoding.
+    """
+    
+    def __init__(self, rfile, maxlen, bufsize=8192):
+        self.rfile = rfile
+        self.maxlen = maxlen
+        self.bytes_read = 0
+        self.buffer = ''
+        self.bufsize = bufsize
+        self.closed = False
+    
+    def _fetch(self):
+        if self.closed:
+            return
+        
+        line = self.rfile.readline()
+        self.bytes_read += len(line)
+        
+        if self.maxlen and self.bytes_read > self.maxlen:
+            raise MaxSizeExceeded("Request Entity Too Large", self.maxlen)
+        
+        line = line.strip().split(";", 1)
+        
+        try:
+            chunk_size = line.pop(0)
+            chunk_size = int(chunk_size, 16)
+        except ValueError:
+            raise ValueError("Bad chunked transfer size: " + repr(chunk_size))
+        
+        if chunk_size <= 0:
+            self.closed = True
+            return
+        
+##            if line: chunk_extension = line[0]
+        
+        if self.maxlen and self.bytes_read + chunk_size > self.maxlen:
+            raise IOError("Request Entity Too Large")
+        
+        chunk = self.rfile.read(chunk_size)
+        self.bytes_read += len(chunk)
+        self.buffer += chunk
+        
+        crlf = self.rfile.read(2)
+        if crlf != CRLF:
+            raise ValueError(
+                 "Bad chunked transfer coding (expected '\\r\\n', "
+                 "got " + repr(crlf) + ")")
+    
+    def read(self, size=None):
+        data = ''
+        while True:
+            if size and len(data) >= size:
+                return data
+            
+            if not self.buffer:
+                self._fetch()
+                if not self.buffer:
+                    # EOF
+                    return data
+            
+            if size:
+                remaining = size - len(data)
+                data += self.buffer[:remaining]
+                self.buffer = self.buffer[remaining:]
+            else:
+                data += self.buffer
+    
+    def readline(self, size=None):
+        data = ''
+        while True:
+            if size and len(data) >= size:
+                return data
+            
+            if not self.buffer:
+                self._fetch()
+                if not self.buffer:
+                    # EOF
+                    return data
+            
+            newline_pos = self.buffer.find('\n')
+            if size:
+                if newline_pos == -1:
+                    remaining = size - len(data)
+                    data += self.buffer[:remaining]
+                    self.buffer = self.buffer[remaining:]
+                else:
+                    remaining = min(size - len(data), newline_pos)
+                    data += self.buffer[:remaining]
+                    self.buffer = self.buffer[remaining:]
+            else:
+                if newline_pos == -1:
+                    data += self.buffer
+                else:
+                    data += self.buffer[:newline_pos]
+                    self.buffer = self.buffer[newline_pos:]
+    
+    def readlines(self, sizehint=0):
+        # Shamelessly stolen from StringIO
+        total = 0
+        lines = []
+        line = self.readline(sizehint)
+        while line:
+            lines.append(line)
+            total += len(line)
+            if 0 < sizehint <= total:
+                break
+            line = self.readline(sizehint)
+        return lines
+    
+    def read_trailer_lines(self):
+        if not self.closed:
+            raise ValueError(
+                "Cannot read trailers until the request body has been read.")
+        
+        while True:
+            line = self.rfile.readline()
+            if not line:
+                # No more data--illegal end of headers
+                raise ValueError("Illegal end of headers.")
+            
+            self.bytes_read += len(line)
+            if self.maxlen and self.bytes_read > self.maxlen:
+                raise IOError("Request Entity Too Large")
+            
+            if line == CRLF:
+                # Normal end of headers
+                break
+            if not line.endswith(CRLF):
+                raise ValueError("HTTP requires CRLF terminators")
+            
+            yield line
+    
+    def close(self):
+        self.rfile.close()
+    
+    def __iter__(self):
+        # Shamelessly stolen from StringIO
+        total = 0
+        line = self.readline(sizehint)
+        while line:
+            yield line
+            total += len(line)
+            if 0 < sizehint <= total:
+                break
+            line = self.readline(sizehint)
+
+
+class HTTPRequest(object):
+    """An HTTP Request (and response).
+    
+    A single HTTP connection may consist of multiple request/response pairs.
+    """
+    
+    server = None
+    """The HTTPServer object which is receiving this request."""
+    
+    conn = None
+    """The HTTPConnection object on which this request connected."""
+    
+    inheaders = {}
+    """A dict of request headers."""
+    
+    outheaders = []
+    """A list of header tuples to write in the response."""
+    
+    ready = False
+    """When True, the request has been parsed and is ready to begin generating
+    the response. When False, signals the calling Connection that the response
+    should not be generated and the connection should close."""
+    
+    close_connection = False
+    """Signals the calling Connection that the request should close. This does
+    not imply an error! The client and/or server may each request that the
+    connection be closed."""
+    
+    chunked_write = False
+    """If True, output will be encoded with the "chunked" transfer-coding.
+    
+    This value is set automatically inside send_headers."""
+    
+    def __init__(self, server, conn):
+        self.server= server
+        self.conn = conn
+        
+        self.ready = False
+        self.started_request = False
+        self.scheme = "http"
+        if self.server.ssl_adapter is not None:
+            self.scheme = "https"
+        # Use the lowest-common protocol in case read_request_line errors.
+        self.response_protocol = 'HTTP/1.0'
+        self.inheaders = {}
+        
+        self.status = ""
+        self.outheaders = []
+        self.sent_headers = False
+        self.close_connection = self.__class__.close_connection
+        self.chunked_read = False
+        self.chunked_write = self.__class__.chunked_write
+    
+    def parse_request(self):
+        """Parse the next HTTP request start-line and message-headers."""
+        self.rfile = SizeCheckWrapper(self.conn.rfile,
+                                      self.server.max_request_header_size)
+        try:
+            self.read_request_line()
+        except MaxSizeExceeded:
+            self.simple_response("414 Request-URI Too Long",
+                "The Request-URI sent with the request exceeds the maximum "
+                "allowed bytes.")
+            return
+        
+        try:
+            success = self.read_request_headers()
+        except MaxSizeExceeded:
+            self.simple_response("413 Request Entity Too Large",
+                "The headers sent with the request exceed the maximum "
+                "allowed bytes.")
+            return
+        else:
+            if not success:
+                return
+        
+        self.ready = True
+    
+    def read_request_line(self):
+        # HTTP/1.1 connections are persistent by default. If a client
+        # requests a page, then idles (leaves the connection open),
+        # then rfile.readline() will raise socket.error("timed out").
+        # Note that it does this based on the value given to settimeout(),
+        # and doesn't need the client to request or acknowledge the close
+        # (although your TCP stack might suffer for it: cf Apache's history
+        # with FIN_WAIT_2).
+        request_line = self.rfile.readline()
+        
+        # Set started_request to True so communicate() knows to send 408
+        # from here on out.
+        self.started_request = True
+        if not request_line:
+            # Force self.ready = False so the connection will close.
+            self.ready = False
+            return
+        
+        if request_line == CRLF:
+            # RFC 2616 sec 4.1: "...if the server is reading the protocol
+            # stream at the beginning of a message and receives a CRLF
+            # first, it should ignore the CRLF."
+            # But only ignore one leading line! else we enable a DoS.
+            request_line = self.rfile.readline()
+            if not request_line:
+                self.ready = False
+                return
+        
+        if not request_line.endswith(CRLF):
+            self.simple_response("400 Bad Request", "HTTP requires CRLF terminators")
+            return
+        
+        try:
+            method, uri, req_protocol = request_line.strip().split(" ", 2)
+            rp = int(req_protocol[5]), int(req_protocol[7])
+        except (ValueError, IndexError):
+            self.simple_response("400 Bad Request", "Malformed Request-Line")
+            return
+        
+        self.uri = uri
+        self.method = method
+        
+        # uri may be an abs_path (including "http://host.domain.tld");
+        scheme, authority, path = self.parse_request_uri(uri)
+        if '#' in path:
+            self.simple_response("400 Bad Request",
+                                 "Illegal #fragment in Request-URI.")
+            return
+        
+        if scheme:
+            self.scheme = scheme
+        
+        qs = ''
+        if '?' in path:
+            path, qs = path.split('?', 1)
+        
+        # Unquote the path+params (e.g. "/this%20path" -> "/this path").
+        # http://www.w3.org/Protocols/rfc2616/rfc2616-sec5.html#sec5.1.2
+        #
+        # But note that "...a URI must be separated into its components
+        # before the escaped characters within those components can be
+        # safely decoded." http://www.ietf.org/rfc/rfc2396.txt, sec 2.4.2
+        # Therefore, "/this%2Fpath" becomes "/this%2Fpath", not "/this/path".
+        try:
+            atoms = [unquote(x) for x in quoted_slash.split(path)]
+        except ValueError, ex:
+            self.simple_response("400 Bad Request", ex.args[0])
+            return
+        path = "%2F".join(atoms)
+        self.path = path
+        
+        # Note that, like wsgiref and most other HTTP servers,
+        # we "% HEX HEX"-unquote the path but not the query string.
+        self.qs = qs
+        
+        # Compare request and server HTTP protocol versions, in case our
+        # server does not support the requested protocol. Limit our output
+        # to min(req, server). We want the following output:
+        #     request    server     actual written   supported response
+        #     protocol   protocol  response protocol    feature set
+        # a     1.0        1.0           1.0                1.0
+        # b     1.0        1.1           1.1                1.0
+        # c     1.1        1.0           1.0                1.0
+        # d     1.1        1.1           1.1                1.1
+        # Notice that, in (b), the response will be "HTTP/1.1" even though
+        # the client only understands 1.0. RFC 2616 10.5.6 says we should
+        # only return 505 if the _major_ version is different.
+        sp = int(self.server.protocol[5]), int(self.server.protocol[7])
+        
+        if sp[0] != rp[0]:
+            self.simple_response("505 HTTP Version Not Supported")
+            return
+        self.request_protocol = req_protocol
+        self.response_protocol = "HTTP/%s.%s" % min(rp, sp)
+    
+    def read_request_headers(self):
+        """Read self.rfile into self.inheaders. Return success."""
+        
+        # then all the http headers
+        try:
+            read_headers(self.rfile, self.inheaders)
+        except ValueError, ex:
+            self.simple_response("400 Bad Request", ex.args[0])
+            return False
+        
+        mrbs = self.server.max_request_body_size
+        if mrbs and int(self.inheaders.get("Content-Length", 0)) > mrbs:
+            self.simple_response("413 Request Entity Too Large",
+                "The entity sent with the request exceeds the maximum "
+                "allowed bytes.")
+            return False
+        
+        # Persistent connection support
+        if self.response_protocol == "HTTP/1.1":
+            # Both server and client are HTTP/1.1
+            if self.inheaders.get("Connection", "") == "close":
+                self.close_connection = True
+        else:
+            # Either the server or client (or both) are HTTP/1.0
+            if self.inheaders.get("Connection", "") != "Keep-Alive":
+                self.close_connection = True
+        
+        # Transfer-Encoding support
+        te = None
+        if self.response_protocol == "HTTP/1.1":
+            te = self.inheaders.get("Transfer-Encoding")
+            if te:
+                te = [x.strip().lower() for x in te.split(",") if x.strip()]
+        
+        self.chunked_read = False
+        
+        if te:
+            for enc in te:
+                if enc == "chunked":
+                    self.chunked_read = True
+                else:
+                    # Note that, even if we see "chunked", we must reject
+                    # if there is an extension we don't recognize.
+                    self.simple_response("501 Unimplemented")
+                    self.close_connection = True
+                    return False
+        
+        # From PEP 333:
+        # "Servers and gateways that implement HTTP 1.1 must provide
+        # transparent support for HTTP 1.1's "expect/continue" mechanism.
+        # This may be done in any of several ways:
+        #   1. Respond to requests containing an Expect: 100-continue request
+        #      with an immediate "100 Continue" response, and proceed normally.
+        #   2. Proceed with the request normally, but provide the application
+        #      with a wsgi.input stream that will send the "100 Continue"
+        #      response if/when the application first attempts to read from
+        #      the input stream. The read request must then remain blocked
+        #      until the client responds.
+        #   3. Wait until the client decides that the server does not support
+        #      expect/continue, and sends the request body on its own.
+        #      (This is suboptimal, and is not recommended.)
+        #
+        # We used to do 3, but are now doing 1. Maybe we'll do 2 someday,
+        # but it seems like it would be a big slowdown for such a rare case.
+        if self.inheaders.get("Expect", "") == "100-continue":
+            # Don't use simple_response here, because it emits headers
+            # we don't want. See http://www.cherrypy.org/ticket/951
+            msg = self.server.protocol + " 100 Continue\r\n\r\n"
+            try:
+                self.conn.wfile.sendall(msg)
+            except socket.error, x:
+                if x.args[0] not in socket_errors_to_ignore:
+                    raise
+        return True
+    
+    def parse_request_uri(self, uri):
+        """Parse a Request-URI into (scheme, authority, path).
+        
+        Note that Request-URI's must be one of::
+            
+            Request-URI    = "*" | absoluteURI | abs_path | authority
+        
+        Therefore, a Request-URI which starts with a double forward-slash
+        cannot be a "net_path"::
+        
+            net_path      = "//" authority [ abs_path ]
+        
+        Instead, it must be interpreted as an "abs_path" with an empty first
+        path segment::
+        
+            abs_path      = "/"  path_segments
+            path_segments = segment *( "/" segment )
+            segment       = *pchar *( ";" param )
+            param         = *pchar
+        """
+        if uri == "*":
+            return None, None, uri
+        
+        i = uri.find('://')
+        if i > 0 and '?' not in uri[:i]:
+            # An absoluteURI.
+            # If there's a scheme (and it must be http or https), then:
+            # http_URL = "http:" "//" host [ ":" port ] [ abs_path [ "?" query ]]
+            scheme, remainder = uri[:i].lower(), uri[i + 3:]
+            authority, path = remainder.split("/", 1)
+            return scheme, authority, path
+        
+        if uri.startswith('/'):
+            # An abs_path.
+            return None, None, uri
+        else:
+            # An authority.
+            return None, uri, None
+    
+    def respond(self):
+        """Call the gateway and write its iterable output."""
+        mrbs = self.server.max_request_body_size
+        if self.chunked_read:
+            self.rfile = ChunkedRFile(self.conn.rfile, mrbs)
+        else:
+            cl = int(self.inheaders.get("Content-Length", 0))
+            if mrbs and mrbs < cl:
+                if not self.sent_headers:
+                    self.simple_response("413 Request Entity Too Large",
+                        "The entity sent with the request exceeds the maximum "
+                        "allowed bytes.")
+                return
+            self.rfile = KnownLengthRFile(self.conn.rfile, cl)
+        
+        self.server.gateway(self).respond()
+        
+        if (self.ready and not self.sent_headers):
+            self.sent_headers = True
+            self.send_headers()
+        if self.chunked_write:
+            self.conn.wfile.sendall("0\r\n\r\n")
+    
+    def simple_response(self, status, msg=""):
+        """Write a simple response back to the client."""
+        status = str(status)
+        buf = [self.server.protocol + " " +
+               status + CRLF,
+               "Content-Length: %s\r\n" % len(msg),
+               "Content-Type: text/plain\r\n"]
+        
+        if status[:3] in ("413", "414"):
+            # Request Entity Too Large / Request-URI Too Long
+            self.close_connection = True
+            if self.response_protocol == 'HTTP/1.1':
+                # This will not be true for 414, since read_request_line
+                # usually raises 414 before reading the whole line, and we
+                # therefore cannot know the proper response_protocol.
+                buf.append("Connection: close\r\n")
+            else:
+                # HTTP/1.0 had no 413/414 status nor Connection header.
+                # Emit 400 instead and trust the message body is enough.
+                status = "400 Bad Request"
+        
+        buf.append(CRLF)
+        if msg:
+            if isinstance(msg, unicode):
+                msg = msg.encode("ISO-8859-1")
+            buf.append(msg)
+        
+        try:
+            self.conn.wfile.sendall("".join(buf))
+        except socket.error, x:
+            if x.args[0] not in socket_errors_to_ignore:
+                raise
+    
+    def write(self, chunk):
+        """Write unbuffered data to the client."""
+        if self.chunked_write and chunk:
+            buf = [hex(len(chunk))[2:], CRLF, chunk, CRLF]
+            self.conn.wfile.sendall("".join(buf))
+        else:
+            self.conn.wfile.sendall(chunk)
+    
+    def send_headers(self):
+        """Assert, process, and send the HTTP response message-headers.
+        
+        You must set self.status, and self.outheaders before calling this.
+        """
+        hkeys = [key.lower() for key, value in self.outheaders]
+        status = int(self.status[:3])
+        
+        if status == 413:
+            # Request Entity Too Large. Close conn to avoid garbage.
+            self.close_connection = True
+        elif "content-length" not in hkeys:
+            # "All 1xx (informational), 204 (no content),
+            # and 304 (not modified) responses MUST NOT
+            # include a message-body." So no point chunking.
+            if status < 200 or status in (204, 205, 304):
+                pass
+            else:
+                if (self.response_protocol == 'HTTP/1.1'
+                    and self.method != 'HEAD'):
+                    # Use the chunked transfer-coding
+                    self.chunked_write = True
+                    self.outheaders.append(("Transfer-Encoding", "chunked"))
+                else:
+                    # Closing the conn is the only way to determine len.
+                    self.close_connection = True
+        
+        if "connection" not in hkeys:
+            if self.response_protocol == 'HTTP/1.1':
+                # Both server and client are HTTP/1.1 or better
+                if self.close_connection:
+                    self.outheaders.append(("Connection", "close"))
+            else:
+                # Server and/or client are HTTP/1.0
+                if not self.close_connection:
+                    self.outheaders.append(("Connection", "Keep-Alive"))
+        
+        if (not self.close_connection) and (not self.chunked_read):
+            # Read any remaining request body data on the socket.
+            # "If an origin server receives a request that does not include an
+            # Expect request-header field with the "100-continue" expectation,
+            # the request includes a request body, and the server responds
+            # with a final status code before reading the entire request body
+            # from the transport connection, then the server SHOULD NOT close
+            # the transport connection until it has read the entire request,
+            # or until the client closes the connection. Otherwise, the client
+            # might not reliably receive the response message. However, this
+            # requirement is not be construed as preventing a server from
+            # defending itself against denial-of-service attacks, or from
+            # badly broken client implementations."
+            remaining = getattr(self.rfile, 'remaining', 0)
+            if remaining > 0:
+                self.rfile.read(remaining)
+        
+        if "date" not in hkeys:
+            self.outheaders.append(("Date", rfc822.formatdate()))
+        
+        if "server" not in hkeys:
+            self.outheaders.append(("Server", self.server.server_name))
+        
+        buf = [self.server.protocol + " " + self.status + CRLF]
+        for k, v in self.outheaders:
+            buf.append(k + ": " + v + CRLF)
+        buf.append(CRLF)
+        self.conn.wfile.sendall("".join(buf))
+
+
+class NoSSLError(Exception):
+    """Exception raised when a client speaks HTTP to an HTTPS socket."""
+    pass
+
+
+class FatalSSLAlert(Exception):
+    """Exception raised when the SSL implementation signals a fatal alert."""
+    pass
+
+
+class CP_fileobject(socket._fileobject):
+    """Faux file object attached to a socket object."""
+
+    def __init__(self, *args, **kwargs):
+        self.bytes_read = 0
+        self.bytes_written = 0
+        socket._fileobject.__init__(self, *args, **kwargs)
+    
+    def sendall(self, data):
+        """Sendall for non-blocking sockets."""
+        while data:
+            try:
+                bytes_sent = self.send(data)
+                data = data[bytes_sent:]
+            except socket.error, e:
+                if e.args[0] not in socket_errors_nonblocking:
+                    raise
+
+    def send(self, data):
+        bytes_sent = self._sock.send(data)
+        self.bytes_written += bytes_sent
+        return bytes_sent
+
+    def flush(self):
+        if self._wbuf:
+            buffer = "".join(self._wbuf)
+            self._wbuf = []
+            self.sendall(buffer)
+
+    def recv(self, size):
+        while True:
+            try:
+                data = self._sock.recv(size)
+                self.bytes_read += len(data)
+                return data
+            except socket.error, e:
+                if (e.args[0] not in socket_errors_nonblocking
+                    and e.args[0] not in socket_error_eintr):
+                    raise
+
+    if not _fileobject_uses_str_type:
+        def read(self, size=-1):
+            # Use max, disallow tiny reads in a loop as they are very inefficient.
+            # We never leave read() with any leftover data from a new recv() call
+            # in our internal buffer.
+            rbufsize = max(self._rbufsize, self.default_bufsize)
+            # Our use of StringIO rather than lists of string objects returned by
+            # recv() minimizes memory usage and fragmentation that occurs when
+            # rbufsize is large compared to the typical return value of recv().
+            buf = self._rbuf
+            buf.seek(0, 2)  # seek end
+            if size < 0:
+                # Read until EOF
+                self._rbuf = StringIO.StringIO()  # reset _rbuf.  we consume it via buf.
+                while True:
+                    data = self.recv(rbufsize)
+                    if not data:
+                        break
+                    buf.write(data)
+                return buf.getvalue()
+            else:
+                # Read until size bytes or EOF seen, whichever comes first
+                buf_len = buf.tell()
+                if buf_len >= size:
+                    # Already have size bytes in our buffer?  Extract and return.
+                    buf.seek(0)
+                    rv = buf.read(size)
+                    self._rbuf = StringIO.StringIO()
+                    self._rbuf.write(buf.read())
+                    return rv
+
+                self._rbuf = StringIO.StringIO()  # reset _rbuf.  we consume it via buf.
+                while True:
+                    left = size - buf_len
+                    # recv() will malloc the amount of memory given as its
+                    # parameter even though it often returns much less data
+                    # than that.  The returned data string is short lived
+                    # as we copy it into a StringIO and free it.  This avoids
+                    # fragmentation issues on many platforms.
+                    data = self.recv(left)
+                    if not data:
+                        break
+                    n = len(data)
+                    if n == size and not buf_len:
+                        # Shortcut.  Avoid buffer data copies when:
+                        # - We have no data in our buffer.
+                        # AND
+                        # - Our call to recv returned exactly the
+                        #   number of bytes we were asked to read.
+                        return data
+                    if n == left:
+                        buf.write(data)
+                        del data  # explicit free
+                        break
+                    assert n <= left, "recv(%d) returned %d bytes" % (left, n)
+                    buf.write(data)
+                    buf_len += n
+                    del data  # explicit free
+                    #assert buf_len == buf.tell()
+                return buf.getvalue()
+
+        def readline(self, size=-1):
+            buf = self._rbuf
+            buf.seek(0, 2)  # seek end
+            if buf.tell() > 0:
+                # check if we already have it in our buffer
+                buf.seek(0)
+                bline = buf.readline(size)
+                if bline.endswith('\n') or len(bline) == size:
+                    self._rbuf = StringIO.StringIO()
+                    self._rbuf.write(buf.read())
+                    return bline
+                del bline
+            if size < 0:
+                # Read until \n or EOF, whichever comes first
+                if self._rbufsize <= 1:
+                    # Speed up unbuffered case
+                    buf.seek(0)
+                    buffers = [buf.read()]
+                    self._rbuf = StringIO.StringIO()  # reset _rbuf.  we consume it via buf.
+                    data = None
+                    recv = self.recv
+                    while data != "\n":
+                        data = recv(1)
+                        if not data:
+                            break
+                        buffers.append(data)
+                    return "".join(buffers)
+
+                buf.seek(0, 2)  # seek end
+                self._rbuf = StringIO.StringIO()  # reset _rbuf.  we consume it via buf.
+                while True:
+                    data = self.recv(self._rbufsize)
+                    if not data:
+                        break
+                    nl = data.find('\n')
+                    if nl >= 0:
+                        nl += 1
+                        buf.write(data[:nl])
+                        self._rbuf.write(data[nl:])
+                        del data
+                        break
+                    buf.write(data)
+                return buf.getvalue()
+            else:
+                # Read until size bytes or \n or EOF seen, whichever comes first
+                buf.seek(0, 2)  # seek end
+                buf_len = buf.tell()
+                if buf_len >= size:
+                    buf.seek(0)
+                    rv = buf.read(size)
+                    self._rbuf = StringIO.StringIO()
+                    self._rbuf.write(buf.read())
+                    return rv
+                self._rbuf = StringIO.StringIO()  # reset _rbuf.  we consume it via buf.
+                while True:
+                    data = self.recv(self._rbufsize)
+                    if not data:
+                        break
+                    left = size - buf_len
+                    # did we just receive a newline?
+                    nl = data.find('\n', 0, left)
+                    if nl >= 0:
+                        nl += 1
+                        # save the excess data to _rbuf
+                        self._rbuf.write(data[nl:])
+                        if buf_len:
+                            buf.write(data[:nl])
+                            break
+                        else:
+                            # Shortcut.  Avoid data copy through buf when returning
+                            # a substring of our first recv().
+                            return data[:nl]
+                    n = len(data)
+                    if n == size and not buf_len:
+                        # Shortcut.  Avoid data copy through buf when
+                        # returning exactly all of our first recv().
+                        return data
+                    if n >= left:
+                        buf.write(data[:left])
+                        self._rbuf.write(data[left:])
+                        break
+                    buf.write(data)
+                    buf_len += n
+                    #assert buf_len == buf.tell()
+                return buf.getvalue()
+    else:
+        def read(self, size=-1):
+            if size < 0:
+                # Read until EOF
+                buffers = [self._rbuf]
+                self._rbuf = ""
+                if self._rbufsize <= 1:
+                    recv_size = self.default_bufsize
+                else:
+                    recv_size = self._rbufsize
+
+                while True:
+                    data = self.recv(recv_size)
+                    if not data:
+                        break
+                    buffers.append(data)
+                return "".join(buffers)
+            else:
+                # Read until size bytes or EOF seen, whichever comes first
+                data = self._rbuf
+                buf_len = len(data)
+                if buf_len >= size:
+                    self._rbuf = data[size:]
+                    return data[:size]
+                buffers = []
+                if data:
+                    buffers.append(data)
+                self._rbuf = ""
+                while True:
+                    left = size - buf_len
+                    recv_size = max(self._rbufsize, left)
+                    data = self.recv(recv_size)
+                    if not data:
+                        break
+                    buffers.append(data)
+                    n = len(data)
+                    if n >= left:
+                        self._rbuf = data[left:]
+                        buffers[-1] = data[:left]
+                        break
+                    buf_len += n
+                return "".join(buffers)
+
+        def readline(self, size=-1):
+            data = self._rbuf
+            if size < 0:
+                # Read until \n or EOF, whichever comes first
+                if self._rbufsize <= 1:
+                    # Speed up unbuffered case
+                    assert data == ""
+                    buffers = []
+                    while data != "\n":
+                        data = self.recv(1)
+                        if not data:
+                            break
+                        buffers.append(data)
+                    return "".join(buffers)
+                nl = data.find('\n')
+                if nl >= 0:
+                    nl += 1
+                    self._rbuf = data[nl:]
+                    return data[:nl]
+                buffers = []
+                if data:
+                    buffers.append(data)
+                self._rbuf = ""
+                while True:
+                    data = self.recv(self._rbufsize)
+                    if not data:
+                        break
+                    buffers.append(data)
+                    nl = data.find('\n')
+                    if nl >= 0:
+                        nl += 1
+                        self._rbuf = data[nl:]
+                        buffers[-1] = data[:nl]
+                        break
+                return "".join(buffers)
+            else:
+                # Read until size bytes or \n or EOF seen, whichever comes first
+                nl = data.find('\n', 0, size)
+                if nl >= 0:
+                    nl += 1
+                    self._rbuf = data[nl:]
+                    return data[:nl]
+                buf_len = len(data)
+                if buf_len >= size:
+                    self._rbuf = data[size:]
+                    return data[:size]
+                buffers = []
+                if data:
+                    buffers.append(data)
+                self._rbuf = ""
+                while True:
+                    data = self.recv(self._rbufsize)
+                    if not data:
+                        break
+                    buffers.append(data)
+                    left = size - buf_len
+                    nl = data.find('\n', 0, left)
+                    if nl >= 0:
+                        nl += 1
+                        self._rbuf = data[nl:]
+                        buffers[-1] = data[:nl]
+                        break
+                    n = len(data)
+                    if n >= left:
+                        self._rbuf = data[left:]
+                        buffers[-1] = data[:left]
+                        break
+                    buf_len += n
+                return "".join(buffers)
+
+
+class HTTPConnection(object):
+    """An HTTP connection (active socket).
+    
+    server: the Server object which received this connection.
+    socket: the raw socket object (usually TCP) for this connection.
+    makefile: a fileobject class for reading from the socket.
+    """
+    
+    remote_addr = None
+    remote_port = None
+    ssl_env = None
+    rbufsize = DEFAULT_BUFFER_SIZE
+    wbufsize = DEFAULT_BUFFER_SIZE
+    RequestHandlerClass = HTTPRequest
+    
+    def __init__(self, server, sock, makefile=CP_fileobject):
+        self.server = server
+        self.socket = sock
+        self.rfile = makefile(sock, "rb", self.rbufsize)
+        self.wfile = makefile(sock, "wb", self.wbufsize)
+        self.requests_seen = 0
+    
+    def communicate(self):
+        """Read each request and respond appropriately."""
+        request_seen = False
+        try:
+            while True:
+                # (re)set req to None so that if something goes wrong in
+                # the RequestHandlerClass constructor, the error doesn't
+                # get written to the previous request.
+                req = None
+                req = self.RequestHandlerClass(self.server, self)
+                
+                # This order of operations should guarantee correct pipelining.
+                req.parse_request()
+                if self.server.stats['Enabled']:
+                    self.requests_seen += 1
+                if not req.ready:
+                    # Something went wrong in the parsing (and the server has
+                    # probably already made a simple_response). Return and
+                    # let the conn close.
+                    return
+                
+                request_seen = True
+                req.respond()
+                if req.close_connection:
+                    return
+        except socket.error, e:
+            errnum = e.args[0]
+            # sadly SSL sockets return a different (longer) time out string
+            if errnum == 'timed out' or errnum == 'The read operation timed out':
+                # Don't error if we're between requests; only error
+                # if 1) no request has been started at all, or 2) we're
+                # in the middle of a request.
+                # See http://www.cherrypy.org/ticket/853
+                if (not request_seen) or (req and req.started_request):
+                    # Don't bother writing the 408 if the response
+                    # has already started being written.
+                    if req and not req.sent_headers:
+                        try:
+                            req.simple_response("408 Request Timeout")
+                        except FatalSSLAlert:
+                            # Close the connection.
+                            return
+            elif errnum not in socket_errors_to_ignore:
+                if req and not req.sent_headers:
+                    try:
+                        req.simple_response("500 Internal Server Error",
+                                            format_exc())
+                    except FatalSSLAlert:
+                        # Close the connection.
+                        return
+            return
+        except (KeyboardInterrupt, SystemExit):
+            raise
+        except FatalSSLAlert:
+            # Close the connection.
+            return
+        except NoSSLError:
+            if req and not req.sent_headers:
+                # Unwrap our wfile
+                self.wfile = CP_fileobject(self.socket._sock, "wb", self.wbufsize)
+                req.simple_response("400 Bad Request",
+                    "The client sent a plain HTTP request, but "
+                    "this server only speaks HTTPS on this port.")
+                self.linger = True
+        except Exception:
+            if req and not req.sent_headers:
+                try:
+                    req.simple_response("500 Internal Server Error", format_exc())
+                except FatalSSLAlert:
+                    # Close the connection.
+                    return
+    
+    linger = False
+    
+    def close(self):
+        """Close the socket underlying this connection."""
+        self.rfile.close()
+        
+        if not self.linger:
+            # Python's socket module does NOT call close on the kernel socket
+            # when you call socket.close(). We do so manually here because we
+            # want this server to send a FIN TCP segment immediately. Note this
+            # must be called *before* calling socket.close(), because the latter
+            # drops its reference to the kernel socket.
+            if hasattr(self.socket, '_sock'):
+                self.socket._sock.close()
+            self.socket.close()
+        else:
+            # On the other hand, sometimes we want to hang around for a bit
+            # to make sure the client has a chance to read our entire
+            # response. Skipping the close() calls here delays the FIN
+            # packet until the socket object is garbage-collected later.
+            # Someday, perhaps, we'll do the full lingering_close that
+            # Apache does, but not today.
+            pass
+
+
+_SHUTDOWNREQUEST = None
+
+class WorkerThread(threading.Thread):
+    """Thread which continuously polls a Queue for Connection objects.
+    
+    Due to the timing issues of polling a Queue, a WorkerThread does not
+    check its own 'ready' flag after it has started. To stop the thread,
+    it is necessary to stick a _SHUTDOWNREQUEST object onto the Queue
+    (one for each running WorkerThread).
+    """
+    
+    conn = None
+    """The current connection pulled off the Queue, or None."""
+    
+    server = None
+    """The HTTP Server which spawned this thread, and which owns the
+    Queue and is placing active connections into it."""
+    
+    ready = False
+    """A simple flag for the calling server to know when this thread
+    has begun polling the Queue."""
+    
+    
+    def __init__(self, server):
+        self.ready = False
+        self.server = server
+        
+        self.requests_seen = 0
+        self.bytes_read = 0
+        self.bytes_written = 0
+        self.start_time = None
+        self.work_time = 0
+        self.stats = {
+            'Requests': lambda s: self.requests_seen + ((self.start_time is None) and 0 or self.conn.requests_seen),
+            'Bytes Read': lambda s: self.bytes_read + ((self.start_time is None) and 0 or self.conn.rfile.bytes_read),
+            'Bytes Written': lambda s: self.bytes_written + ((self.start_time is None) and 0 or self.conn.wfile.bytes_written),
+            'Work Time': lambda s: self.work_time + ((self.start_time is None) and 0 or time.time() - self.start_time),
+            'Read Throughput': lambda s: s['Bytes Read'](s) / (s['Work Time'](s) or 1e-6),
+            'Write Throughput': lambda s: s['Bytes Written'](s) / (s['Work Time'](s) or 1e-6),
+        }
+        threading.Thread.__init__(self)
+    
+    def run(self):
+        self.server.stats['Worker Threads'][self.getName()] = self.stats
+        try:
+            self.ready = True
+            while True:
+                conn = self.server.requests.get()
+                if conn is _SHUTDOWNREQUEST:
+                    return
+                
+                self.conn = conn
+                if self.server.stats['Enabled']:
+                    self.start_time = time.time()
+                try:
+                    conn.communicate()
+                finally:
+                    conn.close()
+                    if self.server.stats['Enabled']:
+                        self.requests_seen += self.conn.requests_seen
+                        self.bytes_read += self.conn.rfile.bytes_read
+                        self.bytes_written += self.conn.wfile.bytes_written
+                        self.work_time += time.time() - self.start_time
+                        self.start_time = None
+                    self.conn = None
+        except (KeyboardInterrupt, SystemExit), exc:
+            self.server.interrupt = exc
+
+
+class ThreadPool(object):
+    """A Request Queue for the CherryPyWSGIServer which pools threads.
+    
+    ThreadPool objects must provide min, get(), put(obj), start()
+    and stop(timeout) attributes.
+    """
+    
+    def __init__(self, server, min=10, max=-1):
+        self.server = server
+        self.min = min
+        self.max = max
+        self._threads = []
+        self._queue = Queue.Queue()
+        self.get = self._queue.get
+    
+    def start(self):
+        """Start the pool of threads."""
+        for i in range(self.min):
+            self._threads.append(WorkerThread(self.server))
+        for worker in self._threads:
+            worker.setName("CP Server " + worker.getName())
+            worker.start()
+        for worker in self._threads:
+            while not worker.ready:
+                time.sleep(.1)
+    
+    def _get_idle(self):
+        """Number of worker threads which are idle. Read-only."""
+        return len([t for t in self._threads if t.conn is None])
+    idle = property(_get_idle, doc=_get_idle.__doc__)
+    
+    def put(self, obj):
+        self._queue.put(obj)
+        if obj is _SHUTDOWNREQUEST:
+            return
+    
+    def grow(self, amount):
+        """Spawn new worker threads (not above self.max)."""
+        for i in range(amount):
+            if self.max > 0 and len(self._threads) >= self.max:
+                break
+            worker = WorkerThread(self.server)
+            worker.setName("CP Server " + worker.getName())
+            self._threads.append(worker)
+            worker.start()
+    
+    def shrink(self, amount):
+        """Kill off worker threads (not below self.min)."""
+        # Grow/shrink the pool if necessary.
+        # Remove any dead threads from our list
+        for t in self._threads:
+            if not t.isAlive():
+                self._threads.remove(t)
+                amount -= 1
+        
+        if amount > 0:
+            for i in range(min(amount, len(self._threads) - self.min)):
+                # Put a number of shutdown requests on the queue equal
+                # to 'amount'. Once each of those is processed by a worker,
+                # that worker will terminate and be culled from our list
+                # in self.put.
+                self._queue.put(_SHUTDOWNREQUEST)
+    
+    def stop(self, timeout=5):
+        # Must shut down threads here so the code that calls
+        # this method can know when all threads are stopped.
+        for worker in self._threads:
+            self._queue.put(_SHUTDOWNREQUEST)
+        
+        # Don't join currentThread (when stop is called inside a request).
+        current = threading.currentThread()
+        if timeout and timeout >= 0:
+            endtime = time.time() + timeout
+        while self._threads:
+            worker = self._threads.pop()
+            if worker is not current and worker.isAlive():
+                try:
+                    if timeout is None or timeout < 0:
+                        worker.join()
+                    else:
+                        remaining_time = endtime - time.time()
+                        if remaining_time > 0:
+                            worker.join(remaining_time)
+                        if worker.isAlive():
+                            # We exhausted the timeout.
+                            # Forcibly shut down the socket.
+                            c = worker.conn
+                            if c and not c.rfile.closed:
+                                try:
+                                    c.socket.shutdown(socket.SHUT_RD)
+                                except TypeError:
+                                    # pyOpenSSL sockets don't take an arg
+                                    c.socket.shutdown()
+                            worker.join()
+                except (AssertionError,
+                        # Ignore repeated Ctrl-C.
+                        # See http://www.cherrypy.org/ticket/691.
+                        KeyboardInterrupt), exc1:
+                    pass
+    
+    def _get_qsize(self):
+        return self._queue.qsize()
+    qsize = property(_get_qsize)
+
+
+
+try:
+    import fcntl
+except ImportError:
+    try:
+        from ctypes import windll, WinError
+    except ImportError:
+        def prevent_socket_inheritance(sock):
+            """Dummy function, since neither fcntl nor ctypes are available."""
+            pass
+    else:
+        def prevent_socket_inheritance(sock):
+            """Mark the given socket fd as non-inheritable (Windows)."""
+            if not windll.kernel32.SetHandleInformation(sock.fileno(), 1, 0):
+                raise WinError()
+else:
+    def prevent_socket_inheritance(sock):
+        """Mark the given socket fd as non-inheritable (POSIX)."""
+        fd = sock.fileno()
+        old_flags = fcntl.fcntl(fd, fcntl.F_GETFD)
+        fcntl.fcntl(fd, fcntl.F_SETFD, old_flags | fcntl.FD_CLOEXEC)
+
+
+class SSLAdapter(object):
+    """Base class for SSL driver library adapters.
+    
+    Required methods:
+    
+        * ``wrap(sock) -> (wrapped socket, ssl environ dict)``
+        * ``makefile(sock, mode='r', bufsize=DEFAULT_BUFFER_SIZE) -> socket file object``
+    """
+    
+    def __init__(self, certificate, private_key, certificate_chain=None):
+        self.certificate = certificate
+        self.private_key = private_key
+        self.certificate_chain = certificate_chain
+    
+    def wrap(self, sock):
+        raise NotImplemented
+    
+    def makefile(self, sock, mode='r', bufsize=DEFAULT_BUFFER_SIZE):
+        raise NotImplemented
+
+
+class HTTPServer(object):
+    """An HTTP server."""
+    
+    _bind_addr = "127.0.0.1"
+    _interrupt = None
+    
+    gateway = None
+    """A Gateway instance."""
+    
+    minthreads = None
+    """The minimum number of worker threads to create (default 10)."""
+    
+    maxthreads = None
+    """The maximum number of worker threads to create (default -1 = no limit)."""
+    
+    server_name = None
+    """The name of the server; defaults to socket.gethostname()."""
+    
+    protocol = "HTTP/1.1"
+    """The version string to write in the Status-Line of all HTTP responses.
+    
+    For example, "HTTP/1.1" is the default. This also limits the supported
+    features used in the response."""
+    
+    request_queue_size = 5
+    """The 'backlog' arg to socket.listen(); max queued connections (default 5)."""
+    
+    shutdown_timeout = 5
+    """The total time, in seconds, to wait for worker threads to cleanly exit."""
+    
+    timeout = 10
+    """The timeout in seconds for accepted connections (default 10)."""
+    
+    version = "CherryPy/3.2.0"
+    """A version string for the HTTPServer."""
+    
+    software = None
+    """The value to set for the SERVER_SOFTWARE entry in the WSGI environ.
+    
+    If None, this defaults to ``'%s Server' % self.version``."""
+    
+    ready = False
+    """An internal flag which marks whether the socket is accepting connections."""
+    
+    max_request_header_size = 0
+    """The maximum size, in bytes, for request headers, or 0 for no limit."""
+    
+    max_request_body_size = 0
+    """The maximum size, in bytes, for request bodies, or 0 for no limit."""
+    
+    nodelay = True
+    """If True (the default since 3.1), sets the TCP_NODELAY socket option."""
+    
+    ConnectionClass = HTTPConnection
+    """The class to use for handling HTTP connections."""
+    
+    ssl_adapter = None
+    """An instance of SSLAdapter (or a subclass).
+    
+    You must have the corresponding SSL driver library installed."""
+    
+    def __init__(self, bind_addr, gateway, minthreads=10, maxthreads=-1,
+                 server_name=None):
+        self.bind_addr = bind_addr
+        self.gateway = gateway
+        
+        self.requests = ThreadPool(self, min=minthreads or 1, max=maxthreads)
+        
+        if not server_name:
+            server_name = socket.gethostname()
+        self.server_name = server_name
+        self.clear_stats()
+    
+    def clear_stats(self):
+        self._start_time = None
+        self._run_time = 0
+        self.stats = {
+            'Enabled': False,
+            'Bind Address': lambda s: repr(self.bind_addr),
+            'Run time': lambda s: (not s['Enabled']) and 0 or self.runtime(),
+            'Accepts': 0,
+            'Accepts/sec': lambda s: s['Accepts'] / self.runtime(),
+            'Queue': lambda s: getattr(self.requests, "qsize", None),
+            'Threads': lambda s: len(getattr(self.requests, "_threads", [])),
+            'Threads Idle': lambda s: getattr(self.requests, "idle", None),
+            'Socket Errors': 0,
+            'Requests': lambda s: (not s['Enabled']) and 0 or sum([w['Requests'](w) for w
+                                       in s['Worker Threads'].values()], 0),
+            'Bytes Read': lambda s: (not s['Enabled']) and 0 or sum([w['Bytes Read'](w) for w
+                                         in s['Worker Threads'].values()], 0),
+            'Bytes Written': lambda s: (not s['Enabled']) and 0 or sum([w['Bytes Written'](w) for w
+                                            in s['Worker Threads'].values()], 0),
+            'Work Time': lambda s: (not s['Enabled']) and 0 or sum([w['Work Time'](w) for w
+                                         in s['Worker Threads'].values()], 0),
+            'Read Throughput': lambda s: (not s['Enabled']) and 0 or sum(
+                [w['Bytes Read'](w) / (w['Work Time'](w) or 1e-6)
+                 for w in s['Worker Threads'].values()], 0),
+            'Write Throughput': lambda s: (not s['Enabled']) and 0 or sum(
+                [w['Bytes Written'](w) / (w['Work Time'](w) or 1e-6)
+                 for w in s['Worker Threads'].values()], 0),
+            'Worker Threads': {},
+            }
+        logging.statistics["CherryPy HTTPServer %d" % id(self)] = self.stats
+    
+    def runtime(self):
+        if self._start_time is None:
+            return self._run_time
+        else:
+            return self._run_time + (time.time() - self._start_time)
+    
+    def __str__(self):
+        return "%s.%s(%r)" % (self.__module__, self.__class__.__name__,
+                              self.bind_addr)
+    
+    def _get_bind_addr(self):
+        return self._bind_addr
+    def _set_bind_addr(self, value):
+        if isinstance(value, tuple) and value[0] in ('', None):
+            # Despite the socket module docs, using '' does not
+            # allow AI_PASSIVE to work. Passing None instead
+            # returns '0.0.0.0' like we want. In other words:
+            #     host    AI_PASSIVE     result
+            #      ''         Y         192.168.x.y
+            #      ''         N         192.168.x.y
+            #     None        Y         0.0.0.0
+            #     None        N         127.0.0.1
+            # But since you can get the same effect with an explicit
+            # '0.0.0.0', we deny both the empty string and None as values.
+            raise ValueError("Host values of '' or None are not allowed. "
+                             "Use '0.0.0.0' (IPv4) or '::' (IPv6) instead "
+                             "to listen on all active interfaces.")
+        self._bind_addr = value
+    bind_addr = property(_get_bind_addr, _set_bind_addr,
+        doc="""The interface on which to listen for connections.
+        
+        For TCP sockets, a (host, port) tuple. Host values may be any IPv4
+        or IPv6 address, or any valid hostname. The string 'localhost' is a
+        synonym for '127.0.0.1' (or '::1', if your hosts file prefers IPv6).
+        The string '0.0.0.0' is a special IPv4 entry meaning "any active
+        interface" (INADDR_ANY), and '::' is the similar IN6ADDR_ANY for
+        IPv6. The empty string or None are not allowed.
+        
+        For UNIX sockets, supply the filename as a string.""")
+    
+    def start(self):
+        """Run the server forever."""
+        # We don't have to trap KeyboardInterrupt or SystemExit here,
+        # because cherrpy.server already does so, calling self.stop() for us.
+        # If you're using this server with another framework, you should
+        # trap those exceptions in whatever code block calls start().
+        self._interrupt = None
+        
+        if self.software is None:
+            self.software = "%s Server" % self.version
+        
+        # SSL backward compatibility
+        if (self.ssl_adapter is None and
+            getattr(self, 'ssl_certificate', None) and
+            getattr(self, 'ssl_private_key', None)):
+            warnings.warn(
+                    "SSL attributes are deprecated in CherryPy 3.2, and will "
+                    "be removed in CherryPy 3.3. Use an ssl_adapter attribute "
+                    "instead.",
+                    DeprecationWarning
+                )
+            try:
+                from cherrypy.wsgiserver.ssl_pyopenssl import pyOpenSSLAdapter
+            except ImportError:
+                pass
+            else:
+                self.ssl_adapter = pyOpenSSLAdapter(
+                    self.ssl_certificate, self.ssl_private_key,
+                    getattr(self, 'ssl_certificate_chain', None))
+        
+        # Select the appropriate socket
+        if isinstance(self.bind_addr, basestring):
+            # AF_UNIX socket
+            
+            # So we can reuse the socket...
+            try: os.unlink(self.bind_addr)
+            except: pass
+            
+            # So everyone can access the socket...
+            try: os.chmod(self.bind_addr, 0777)
+            except: pass
+            
+            info = [(socket.AF_UNIX, socket.SOCK_STREAM, 0, "", self.bind_addr)]
+        else:
+            # AF_INET or AF_INET6 socket
+            # Get the correct address family for our host (allows IPv6 addresses)
+            host, port = self.bind_addr
+            try:
+                info = socket.getaddrinfo(host, port, socket.AF_UNSPEC,
+                                          socket.SOCK_STREAM, 0, socket.AI_PASSIVE)
+            except socket.gaierror:
+                if ':' in self.bind_addr[0]:
+                    info = [(socket.AF_INET6, socket.SOCK_STREAM,
+                             0, "", self.bind_addr + (0, 0))]
+                else:
+                    info = [(socket.AF_INET, socket.SOCK_STREAM,
+                             0, "", self.bind_addr)]
+        
+        self.socket = None
+        msg = "No socket could be created"
+        for res in info:
+            af, socktype, proto, canonname, sa = res
+            try:
+                self.bind(af, socktype, proto)
+            except socket.error:
+                if self.socket:
+                    self.socket.close()
+                self.socket = None
+                continue
+            break
+        if not self.socket:
+            raise socket.error(msg)
+        
+        # Timeout so KeyboardInterrupt can be caught on Win32
+        self.socket.settimeout(1)
+        self.socket.listen(self.request_queue_size)
+        
+        # Create worker threads
+        self.requests.start()
+        
+        self.ready = True
+        self._start_time = time.time()
+        while self.ready:
+            self.tick()
+            if self.interrupt:
+                while self.interrupt is True:
+                    # Wait for self.stop() to complete. See _set_interrupt.
+                    time.sleep(0.1)
+                if self.interrupt:
+                    raise self.interrupt
+    
+    def bind(self, family, type, proto=0):
+        """Create (or recreate) the actual socket object."""
+        self.socket = socket.socket(family, type, proto)
+        prevent_socket_inheritance(self.socket)
+        self.socket.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        if self.nodelay and not isinstance(self.bind_addr, str):
+            self.socket.setsockopt(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)
+        
+        if self.ssl_adapter is not None:
+            self.socket = self.ssl_adapter.bind(self.socket)
+        
+        # If listening on the IPV6 any address ('::' = IN6ADDR_ANY),
+        # activate dual-stack. See http://www.cherrypy.org/ticket/871.
+        if (hasattr(socket, 'AF_INET6') and family == socket.AF_INET6
+            and self.bind_addr[0] in ('::', '::0', '::0.0.0.0')):
+            try:
+                self.socket.setsockopt(socket.IPPROTO_IPV6, socket.IPV6_V6ONLY, 0)
+            except (AttributeError, socket.error):
+                # Apparently, the socket option is not available in
+                # this machine's TCP stack
+                pass
+        
+        self.socket.bind(self.bind_addr)
+    
+    def tick(self):
+        """Accept a new connection and put it on the Queue."""
+        try:
+            s, addr = self.socket.accept()
+            if self.stats['Enabled']:
+                self.stats['Accepts'] += 1
+            if not self.ready:
+                return
+            
+            prevent_socket_inheritance(s)
+            if hasattr(s, 'settimeout'):
+                s.settimeout(self.timeout)
+            
+            makefile = CP_fileobject
+            ssl_env = {}
+            # if ssl cert and key are set, we try to be a secure HTTP server
+            if self.ssl_adapter is not None:
+                try:
+                    s, ssl_env = self.ssl_adapter.wrap(s)
+                except NoSSLError:
+                    msg = ("The client sent a plain HTTP request, but "
+                           "this server only speaks HTTPS on this port.")
+                    buf = ["%s 400 Bad Request\r\n" % self.protocol,
+                           "Content-Length: %s\r\n" % len(msg),
+                           "Content-Type: text/plain\r\n\r\n",
+                           msg]
+                    
+                    wfile = CP_fileobject(s, "wb", DEFAULT_BUFFER_SIZE)
+                    try:
+                        wfile.sendall("".join(buf))
+                    except socket.error, x:
+                        if x.args[0] not in socket_errors_to_ignore:
+                            raise
+                    return
+                if not s:
+                    return
+                makefile = self.ssl_adapter.makefile
+                # Re-apply our timeout since we may have a new socket object
+                if hasattr(s, 'settimeout'):
+                    s.settimeout(self.timeout)
+            
+            conn = self.ConnectionClass(self, s, makefile)
+            
+            if not isinstance(self.bind_addr, basestring):
+                # optional values
+                # Until we do DNS lookups, omit REMOTE_HOST
+                if addr is None: # sometimes this can happen
+                    # figure out if AF_INET or AF_INET6.
+                    if len(s.getsockname()) == 2:
+                        # AF_INET
+                        addr = ('0.0.0.0', 0)
+                    else:
+                        # AF_INET6
+                        addr = ('::', 0)
+                conn.remote_addr = addr[0]
+                conn.remote_port = addr[1]
+            
+            conn.ssl_env = ssl_env
+            
+            self.requests.put(conn)
+        except socket.timeout:
+            # The only reason for the timeout in start() is so we can
+            # notice keyboard interrupts on Win32, which don't interrupt
+            # accept() by default
+            return
+        except socket.error, x:
+            if self.stats['Enabled']:
+                self.stats['Socket Errors'] += 1
+            if x.args[0] in socket_error_eintr:
+                # I *think* this is right. EINTR should occur when a signal
+                # is received during the accept() call; all docs say retry
+                # the call, and I *think* I'm reading it right that Python
+                # will then go ahead and poll for and handle the signal
+                # elsewhere. See http://www.cherrypy.org/ticket/707.
+                return
+            if x.args[0] in socket_errors_nonblocking:
+                # Just try again. See http://www.cherrypy.org/ticket/479.
+                return
+            if x.args[0] in socket_errors_to_ignore:
+                # Our socket was closed.
+                # See http://www.cherrypy.org/ticket/686.
+                return
+            raise
+    
+    def _get_interrupt(self):
+        return self._interrupt
+    def _set_interrupt(self, interrupt):
+        self._interrupt = True
+        self.stop()
+        self._interrupt = interrupt
+    interrupt = property(_get_interrupt, _set_interrupt,
+                         doc="Set this to an Exception instance to "
+                             "interrupt the server.")
+    
+    def stop(self):
+        """Gracefully shutdown a server that is serving forever."""
+        self.ready = False
+        if self._start_time is not None:
+            self._run_time += (time.time() - self._start_time)
+        self._start_time = None
+        
+        sock = getattr(self, "socket", None)
+        if sock:
+            if not isinstance(self.bind_addr, basestring):
+                # Touch our own socket to make accept() return immediately.
+                try:
+                    host, port = sock.getsockname()[:2]
+                except socket.error, x:
+                    if x.args[0] not in socket_errors_to_ignore:
+                        # Changed to use error code and not message
+                        # See http://www.cherrypy.org/ticket/860.
+                        raise
+                else:
+                    # Note that we're explicitly NOT using AI_PASSIVE,
+                    # here, because we want an actual IP to touch.
+                    # localhost won't work if we've bound to a public IP,
+                    # but it will if we bound to '0.0.0.0' (INADDR_ANY).
+                    for res in socket.getaddrinfo(host, port, socket.AF_UNSPEC,
+                                                  socket.SOCK_STREAM):
+                        af, socktype, proto, canonname, sa = res
+                        s = None
+                        try:
+                            s = socket.socket(af, socktype, proto)
+                            # See http://groups.google.com/group/cherrypy-users/
+                            #        browse_frm/thread/bbfe5eb39c904fe0
+                            s.settimeout(1.0)
+                            s.connect((host, port))
+                            s.close()
+                        except socket.error:
+                            if s:
+                                s.close()
+            if hasattr(sock, "close"):
+                sock.close()
+            self.socket = None
+        
+        self.requests.stop(self.shutdown_timeout)
+
+
+class Gateway(object):
+    
+    def __init__(self, req):
+        self.req = req
+    
+    def respond(self):
+        raise NotImplemented
+
+
+# These may either be wsgiserver.SSLAdapter subclasses or the string names
+# of such classes (in which case they will be lazily loaded).
+ssl_adapters = {
+    'builtin': 'cherrypy.wsgiserver.ssl_builtin.BuiltinSSLAdapter',
+    'pyopenssl': 'cherrypy.wsgiserver.ssl_pyopenssl.pyOpenSSLAdapter',
+    }
+
+def get_ssl_adapter_class(name='pyopenssl'):
+    adapter = ssl_adapters[name.lower()]
+    if isinstance(adapter, basestring):
+        last_dot = adapter.rfind(".")
+        attr_name = adapter[last_dot + 1:]
+        mod_path = adapter[:last_dot]
+        
+        try:
+            mod = sys.modules[mod_path]
+            if mod is None:
+                raise KeyError()
+        except KeyError:
+            # The last [''] is important.
+            mod = __import__(mod_path, globals(), locals(), [''])
+        
+        # Let an AttributeError propagate outward.
+        try:
+            adapter = getattr(mod, attr_name)
+        except AttributeError:
+            raise AttributeError("'%s' object has no attribute '%s'"
+                                 % (mod_path, attr_name))
+    
+    return adapter
+
+# -------------------------------- WSGI Stuff -------------------------------- #
+
+
+class CherryPyWSGIServer(HTTPServer):
+    
+    wsgi_version = (1, 0)
+    
+    def __init__(self, bind_addr, wsgi_app, numthreads=10, server_name=None,
+                 max=-1, request_queue_size=5, timeout=10, shutdown_timeout=5):
+        self.requests = ThreadPool(self, min=numthreads or 1, max=max)
+        self.wsgi_app = wsgi_app
+        self.gateway = wsgi_gateways[self.wsgi_version]
+        
+        self.bind_addr = bind_addr
+        if not server_name:
+            server_name = socket.gethostname()
+        self.server_name = server_name
+        self.request_queue_size = request_queue_size
+        
+        self.timeout = timeout
+        self.shutdown_timeout = shutdown_timeout
+        self.clear_stats()
+    
+    def _get_numthreads(self):
+        return self.requests.min
+    def _set_numthreads(self, value):
+        self.requests.min = value
+    numthreads = property(_get_numthreads, _set_numthreads)
+
+
+class WSGIGateway(Gateway):
+    
+    def __init__(self, req):
+        self.req = req
+        self.started_response = False
+        self.env = self.get_environ()
+        self.remaining_bytes_out = None
+    
+    def get_environ(self):
+        """Return a new environ dict targeting the given wsgi.version"""
+        raise NotImplemented
+    
+    def respond(self):
+        response = self.req.server.wsgi_app(self.env, self.start_response)
+        try:
+            for chunk in response:
+                # "The start_response callable must not actually transmit
+                # the response headers. Instead, it must store them for the
+                # server or gateway to transmit only after the first
+                # iteration of the application return value that yields
+                # a NON-EMPTY string, or upon the application's first
+                # invocation of the write() callable." (PEP 333)
+                if chunk:
+                    if isinstance(chunk, unicode):
+                        chunk = chunk.encode('ISO-8859-1')
+                    self.write(chunk)
+        finally:
+            if hasattr(response, "close"):
+                response.close()
+    
+    def start_response(self, status, headers, exc_info = None):
+        """WSGI callable to begin the HTTP response."""
+        # "The application may call start_response more than once,
+        # if and only if the exc_info argument is provided."
+        if self.started_response and not exc_info:
+            raise AssertionError("WSGI start_response called a second "
+                                 "time with no exc_info.")
+        self.started_response = True
+        
+        # "if exc_info is provided, and the HTTP headers have already been
+        # sent, start_response must raise an error, and should raise the
+        # exc_info tuple."
+        if self.req.sent_headers:
+            try:
+                raise exc_info[0], exc_info[1], exc_info[2]
+            finally:
+                exc_info = None
+        
+        self.req.status = status
+        for k, v in headers:
+            if not isinstance(k, str):
+                raise TypeError("WSGI response header key %r is not a byte string." % k)
+            if not isinstance(v, str):
+                raise TypeError("WSGI response header value %r is not a byte string." % v)
+            if k.lower() == 'content-length':
+                self.remaining_bytes_out = int(v)
+        self.req.outheaders.extend(headers)
+        
+        return self.write
+    
+    def write(self, chunk):
+        """WSGI callable to write unbuffered data to the client.
+        
+        This method is also used internally by start_response (to write
+        data from the iterable returned by the WSGI application).
+        """
+        if not self.started_response:
+            raise AssertionError("WSGI write called before start_response.")
+        
+        chunklen = len(chunk)
+        rbo = self.remaining_bytes_out
+        if rbo is not None and chunklen > rbo:
+            if not self.req.sent_headers:
+                # Whew. We can send a 500 to the client.
+                self.req.simple_response("500 Internal Server Error",
+                    "The requested resource returned more bytes than the "
+                    "declared Content-Length.")
+            else:
+                # Dang. We have probably already sent data. Truncate the chunk
+                # to fit (so the client doesn't hang) and raise an error later.
+                chunk = chunk[:rbo]
+        
+        if not self.req.sent_headers:
+            self.req.sent_headers = True
+            self.req.send_headers()
+        
+        self.req.write(chunk)
+        
+        if rbo is not None:
+            rbo -= chunklen
+            if rbo < 0:
+                raise ValueError(
+                    "Response body exceeds the declared Content-Length.")
+
+
+class WSGIGateway_10(WSGIGateway):
+    
+    def get_environ(self):
+        """Return a new environ dict targeting the given wsgi.version"""
+        req = self.req
+        env = {
+            # set a non-standard environ entry so the WSGI app can know what
+            # the *real* server protocol is (and what features to support).
+            # See http://www.faqs.org/rfcs/rfc2145.html.
+            'ACTUAL_SERVER_PROTOCOL': req.server.protocol,
+            'PATH_INFO': req.path,
+            'QUERY_STRING': req.qs,
+            'REMOTE_ADDR': req.conn.remote_addr or '',
+            'REMOTE_PORT': str(req.conn.remote_port or ''),
+            'REQUEST_METHOD': req.method,
+            'REQUEST_URI': req.uri,
+            'SCRIPT_NAME': '',
+            'SERVER_NAME': req.server.server_name,
+            # Bah. "SERVER_PROTOCOL" is actually the REQUEST protocol.
+            'SERVER_PROTOCOL': req.request_protocol,
+            'SERVER_SOFTWARE': req.server.software,
+            'wsgi.errors': sys.stderr,
+            'wsgi.input': req.rfile,
+            'wsgi.multiprocess': False,
+            'wsgi.multithread': True,
+            'wsgi.run_once': False,
+            'wsgi.url_scheme': req.scheme,
+            'wsgi.version': (1, 0),
+            }
+        
+        if isinstance(req.server.bind_addr, basestring):
+            # AF_UNIX. This isn't really allowed by WSGI, which doesn't
+            # address unix domain sockets. But it's better than nothing.
+            env["SERVER_PORT"] = ""
+        else:
+            env["SERVER_PORT"] = str(req.server.bind_addr[1])
+        
+        # Request headers
+        for k, v in req.inheaders.iteritems():
+            env["HTTP_" + k.upper().replace("-", "_")] = v
+        
+        # CONTENT_TYPE/CONTENT_LENGTH
+        ct = env.pop("HTTP_CONTENT_TYPE", None)
+        if ct is not None:
+            env["CONTENT_TYPE"] = ct
+        cl = env.pop("HTTP_CONTENT_LENGTH", None)
+        if cl is not None:
+            env["CONTENT_LENGTH"] = cl
+        
+        if req.conn.ssl_env:
+            env.update(req.conn.ssl_env)
+        
+        return env
+
+
+class WSGIGateway_u0(WSGIGateway_10):
+    
+    def get_environ(self):
+        """Return a new environ dict targeting the given wsgi.version"""
+        req = self.req
+        env_10 = WSGIGateway_10.get_environ(self)
+        env = dict([(k.decode('ISO-8859-1'), v) for k, v in env_10.iteritems()])
+        env[u'wsgi.version'] = ('u', 0)
+        
+        # Request-URI
+        env.setdefault(u'wsgi.url_encoding', u'utf-8')
+        try:
+            for key in [u"PATH_INFO", u"SCRIPT_NAME", u"QUERY_STRING"]:
+                env[key] = env_10[str(key)].decode(env[u'wsgi.url_encoding'])
+        except UnicodeDecodeError:
+            # Fall back to latin 1 so apps can transcode if needed.
+            env[u'wsgi.url_encoding'] = u'ISO-8859-1'
+            for key in [u"PATH_INFO", u"SCRIPT_NAME", u"QUERY_STRING"]:
+                env[key] = env_10[str(key)].decode(env[u'wsgi.url_encoding'])
+        
+        for k, v in sorted(env.items()):
+            if isinstance(v, str) and k not in ('REQUEST_URI', 'wsgi.input'):
+                env[k] = v.decode('ISO-8859-1')
+        
+        return env
+
+wsgi_gateways = {
+    (1, 0): WSGIGateway_10,
+    ('u', 0): WSGIGateway_u0,
+}
+
+class WSGIPathInfoDispatcher(object):
+    """A WSGI dispatcher for dispatch based on the PATH_INFO.
+    
+    apps: a dict or list of (path_prefix, app) pairs.
+    """
+    
+    def __init__(self, apps):
+        try:
+            apps = apps.items()
+        except AttributeError:
+            pass
+        
+        # Sort the apps by len(path), descending
+        apps.sort(cmp=lambda x,y: cmp(len(x[0]), len(y[0])))
+        apps.reverse()
+        
+        # The path_prefix strings must start, but not end, with a slash.
+        # Use "" instead of "/".
+        self.apps = [(p.rstrip("/"), a) for p, a in apps]
+    
+    def __call__(self, environ, start_response):
+        path = environ["PATH_INFO"] or "/"
+        for p, app in self.apps:
+            # The apps list should be sorted by length, descending.
+            if path.startswith(p + "/") or path == p:
+                environ = environ.copy()
+                environ["SCRIPT_NAME"] = environ["SCRIPT_NAME"] + p
+                environ["PATH_INFO"] = path[len(p):]
+                return app(environ, start_response)
+        
+        start_response('404 Not Found', [('Content-Type', 'text/plain'),
+                                         ('Content-Length', '0')])
+        return ['']
+
diff --git a/cherrypy/wsgiserver/ssl_builtin.py b/cherrypy/wsgiserver/ssl_builtin.py
new file mode 100644
index 00000000..64c0eeb0
--- /dev/null
+++ b/cherrypy/wsgiserver/ssl_builtin.py
@@ -0,0 +1,72 @@
+"""A library for integrating Python's builtin ``ssl`` library with CherryPy.
+
+The ssl module must be importable for SSL functionality.
+
+To use this module, set ``CherryPyWSGIServer.ssl_adapter`` to an instance of
+``BuiltinSSLAdapter``.
+"""
+
+try:
+    import ssl
+except ImportError:
+    ssl = None
+
+from cherrypy import wsgiserver
+
+
+class BuiltinSSLAdapter(wsgiserver.SSLAdapter):
+    """A wrapper for integrating Python's builtin ssl module with CherryPy."""
+    
+    certificate = None
+    """The filename of the server SSL certificate."""
+    
+    private_key = None
+    """The filename of the server's private key file."""
+    
+    def __init__(self, certificate, private_key, certificate_chain=None):
+        if ssl is None:
+            raise ImportError("You must install the ssl module to use HTTPS.")
+        self.certificate = certificate
+        self.private_key = private_key
+        self.certificate_chain = certificate_chain
+    
+    def bind(self, sock):
+        """Wrap and return the given socket."""
+        return sock
+    
+    def wrap(self, sock):
+        """Wrap and return the given socket, plus WSGI environ entries."""
+        try:
+            s = ssl.wrap_socket(sock, do_handshake_on_connect=True,
+                    server_side=True, certfile=self.certificate,
+                    keyfile=self.private_key, ssl_version=ssl.PROTOCOL_SSLv23)
+        except ssl.SSLError, e:
+            if e.errno == ssl.SSL_ERROR_EOF:
+                # This is almost certainly due to the cherrypy engine
+                # 'pinging' the socket to assert it's connectable;
+                # the 'ping' isn't SSL.
+                return None, {}
+            elif e.errno == ssl.SSL_ERROR_SSL:
+                if e.args[1].endswith('http request'):
+                    # The client is speaking HTTP to an HTTPS server.
+                    raise wsgiserver.NoSSLError
+            raise
+        return s, self.get_environ(s)
+    
+    # TODO: fill this out more with mod ssl env
+    def get_environ(self, sock):
+        """Create WSGI environ entries to be merged into each request."""
+        cipher = sock.cipher()
+        ssl_environ = {
+            "wsgi.url_scheme": "https",
+            "HTTPS": "on",
+            'SSL_PROTOCOL': cipher[1],
+            'SSL_CIPHER': cipher[0]
+##            SSL_VERSION_INTERFACE 	string 	The mod_ssl program version
+##            SSL_VERSION_LIBRARY 	string 	The OpenSSL program version
+            }
+        return ssl_environ
+    
+    def makefile(self, sock, mode='r', bufsize=-1):
+        return wsgiserver.CP_fileobject(sock, mode, bufsize)
+
diff --git a/cherrypy/wsgiserver/ssl_pyopenssl.py b/cherrypy/wsgiserver/ssl_pyopenssl.py
new file mode 100644
index 00000000..f3d9bf54
--- /dev/null
+++ b/cherrypy/wsgiserver/ssl_pyopenssl.py
@@ -0,0 +1,256 @@
+"""A library for integrating pyOpenSSL with CherryPy.
+
+The OpenSSL module must be importable for SSL functionality.
+You can obtain it from http://pyopenssl.sourceforge.net/
+
+To use this module, set CherryPyWSGIServer.ssl_adapter to an instance of
+SSLAdapter. There are two ways to use SSL:
+
+Method One
+----------
+
+ * ``ssl_adapter.context``: an instance of SSL.Context.
+
+If this is not None, it is assumed to be an SSL.Context instance,
+and will be passed to SSL.Connection on bind(). The developer is
+responsible for forming a valid Context object. This approach is
+to be preferred for more flexibility, e.g. if the cert and key are
+streams instead of files, or need decryption, or SSL.SSLv3_METHOD
+is desired instead of the default SSL.SSLv23_METHOD, etc. Consult
+the pyOpenSSL documentation for complete options.
+
+Method Two (shortcut)
+---------------------
+
+ * ``ssl_adapter.certificate``: the filename of the server SSL certificate.
+ * ``ssl_adapter.private_key``: the filename of the server's private key file.
+
+Both are None by default. If ssl_adapter.context is None, but .private_key
+and .certificate are both given and valid, they will be read, and the
+context will be automatically created from them.
+"""
+
+import socket
+import threading
+import time
+
+from cherrypy import wsgiserver
+
+try:
+    from OpenSSL import SSL
+    from OpenSSL import crypto
+except ImportError:
+    SSL = None
+
+
+class SSL_fileobject(wsgiserver.CP_fileobject):
+    """SSL file object attached to a socket object."""
+    
+    ssl_timeout = 3
+    ssl_retry = .01
+    
+    def _safe_call(self, is_reader, call, *args, **kwargs):
+        """Wrap the given call with SSL error-trapping.
+        
+        is_reader: if False EOF errors will be raised. If True, EOF errors
+        will return "" (to emulate normal sockets).
+        """
+        start = time.time()
+        while True:
+            try:
+                return call(*args, **kwargs)
+            except SSL.WantReadError:
+                # Sleep and try again. This is dangerous, because it means
+                # the rest of the stack has no way of differentiating
+                # between a "new handshake" error and "client dropped".
+                # Note this isn't an endless loop: there's a timeout below.
+                time.sleep(self.ssl_retry)
+            except SSL.WantWriteError:
+                time.sleep(self.ssl_retry)
+            except SSL.SysCallError, e:
+                if is_reader and e.args == (-1, 'Unexpected EOF'):
+                    return ""
+                
+                errnum = e.args[0]
+                if is_reader and errnum in wsgiserver.socket_errors_to_ignore:
+                    return ""
+                raise socket.error(errnum)
+            except SSL.Error, e:
+                if is_reader and e.args == (-1, 'Unexpected EOF'):
+                    return ""
+                
+                thirdarg = None
+                try:
+                    thirdarg = e.args[0][0][2]
+                except IndexError:
+                    pass
+                
+                if thirdarg == 'http request':
+                    # The client is talking HTTP to an HTTPS server.
+                    raise wsgiserver.NoSSLError()
+                
+                raise wsgiserver.FatalSSLAlert(*e.args)
+            except:
+                raise
+            
+            if time.time() - start > self.ssl_timeout:
+                raise socket.timeout("timed out")
+    
+    def recv(self, *args, **kwargs):
+        buf = []
+        r = super(SSL_fileobject, self).recv
+        while True:
+            data = self._safe_call(True, r, *args, **kwargs)
+            buf.append(data)
+            p = self._sock.pending()
+            if not p:
+                return "".join(buf)
+    
+    def sendall(self, *args, **kwargs):
+        return self._safe_call(False, super(SSL_fileobject, self).sendall,
+                               *args, **kwargs)
+
+    def send(self, *args, **kwargs):
+        return self._safe_call(False, super(SSL_fileobject, self).send,
+                               *args, **kwargs)
+
+
+class SSLConnection:
+    """A thread-safe wrapper for an SSL.Connection.
+    
+    ``*args``: the arguments to create the wrapped ``SSL.Connection(*args)``.
+    """
+    
+    def __init__(self, *args):
+        self._ssl_conn = SSL.Connection(*args)
+        self._lock = threading.RLock()
+    
+    for f in ('get_context', 'pending', 'send', 'write', 'recv', 'read',
+              'renegotiate', 'bind', 'listen', 'connect', 'accept',
+              'setblocking', 'fileno', 'close', 'get_cipher_list',
+              'getpeername', 'getsockname', 'getsockopt', 'setsockopt',
+              'makefile', 'get_app_data', 'set_app_data', 'state_string',
+              'sock_shutdown', 'get_peer_certificate', 'want_read',
+              'want_write', 'set_connect_state', 'set_accept_state',
+              'connect_ex', 'sendall', 'settimeout', 'gettimeout'):
+        exec("""def %s(self, *args):
+        self._lock.acquire()
+        try:
+            return self._ssl_conn.%s(*args)
+        finally:
+            self._lock.release()
+""" % (f, f))
+    
+    def shutdown(self, *args):
+        self._lock.acquire()
+        try:
+            # pyOpenSSL.socket.shutdown takes no args
+            return self._ssl_conn.shutdown()
+        finally:
+            self._lock.release()
+
+
+class pyOpenSSLAdapter(wsgiserver.SSLAdapter):
+    """A wrapper for integrating pyOpenSSL with CherryPy."""
+    
+    context = None
+    """An instance of SSL.Context."""
+    
+    certificate = None
+    """The filename of the server SSL certificate."""
+    
+    private_key = None
+    """The filename of the server's private key file."""
+    
+    certificate_chain = None
+    """Optional. The filename of CA's intermediate certificate bundle.
+    
+    This is needed for cheaper "chained root" SSL certificates, and should be
+    left as None if not required."""
+    
+    def __init__(self, certificate, private_key, certificate_chain=None):
+        if SSL is None:
+            raise ImportError("You must install pyOpenSSL to use HTTPS.")
+        
+        self.context = None
+        self.certificate = certificate
+        self.private_key = private_key
+        self.certificate_chain = certificate_chain
+        self._environ = None
+    
+    def bind(self, sock):
+        """Wrap and return the given socket."""
+        if self.context is None:
+            self.context = self.get_context()
+        conn = SSLConnection(self.context, sock)
+        self._environ = self.get_environ()
+        return conn
+    
+    def wrap(self, sock):
+        """Wrap and return the given socket, plus WSGI environ entries."""
+        return sock, self._environ.copy()
+    
+    def get_context(self):
+        """Return an SSL.Context from self attributes."""
+        # See http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/442473
+        c = SSL.Context(SSL.SSLv23_METHOD)
+        c.use_privatekey_file(self.private_key)
+        if self.certificate_chain:
+            c.load_verify_locations(self.certificate_chain)
+        c.use_certificate_file(self.certificate)
+        return c
+    
+    def get_environ(self):
+        """Return WSGI environ entries to be merged into each request."""
+        ssl_environ = {
+            "HTTPS": "on",
+            # pyOpenSSL doesn't provide access to any of these AFAICT
+##            'SSL_PROTOCOL': 'SSLv2',
+##            SSL_CIPHER 	string 	The cipher specification name
+##            SSL_VERSION_INTERFACE 	string 	The mod_ssl program version
+##            SSL_VERSION_LIBRARY 	string 	The OpenSSL program version
+            }
+        
+        if self.certificate:
+            # Server certificate attributes
+            cert = open(self.certificate, 'rb').read()
+            cert = crypto.load_certificate(crypto.FILETYPE_PEM, cert)
+            ssl_environ.update({
+                'SSL_SERVER_M_VERSION': cert.get_version(),
+                'SSL_SERVER_M_SERIAL': cert.get_serial_number(),
+##                'SSL_SERVER_V_START': Validity of server's certificate (start time),
+##                'SSL_SERVER_V_END': Validity of server's certificate (end time),
+                })
+            
+            for prefix, dn in [("I", cert.get_issuer()),
+                               ("S", cert.get_subject())]:
+                # X509Name objects don't seem to have a way to get the
+                # complete DN string. Use str() and slice it instead,
+                # because str(dn) == ""
+                dnstr = str(dn)[18:-2]
+                
+                wsgikey = 'SSL_SERVER_%s_DN' % prefix
+                ssl_environ[wsgikey] = dnstr
+                
+                # The DN should be of the form: /k1=v1/k2=v2, but we must allow
+                # for any value to contain slashes itself (in a URL).
+                while dnstr:
+                    pos = dnstr.rfind("=")
+                    dnstr, value = dnstr[:pos], dnstr[pos + 1:]
+                    pos = dnstr.rfind("/")
+                    dnstr, key = dnstr[:pos], dnstr[pos + 1:]
+                    if key and value:
+                        wsgikey = 'SSL_SERVER_%s_DN_%s' % (prefix, key)
+                        ssl_environ[wsgikey] = value
+        
+        return ssl_environ
+    
+    def makefile(self, sock, mode='r', bufsize=-1):
+        if SSL and isinstance(sock, SSL.ConnectionType):
+            timeout = sock.gettimeout()
+            f = SSL_fileobject(sock, mode, bufsize)
+            f.ssl_timeout = timeout
+            return f
+        else:
+            return wsgiserver.CP_fileobject(sock, mode, bufsize)
+
diff --git a/config.ini b/config.ini
new file mode 100644
index 00000000..8bc40be7
--- /dev/null
+++ b/config.ini
@@ -0,0 +1,25 @@
+[General]
+http_host = 0.0.0.0
+http_port = 8181
+http_username =
+http_password =
+usenet_retention =
+include_lossless = 0
+launch_browser = 0
+path_to_itunes = 
+music_download_dir = 
+move_to_itunes = 0
+rename_mp3s = 0
+add_album_art = 0
+
+[NZBMatrix]
+nzbmatrix = 0
+nzbmatrix_username =
+nzbmatrix_apikey =
+
+[SABnzbd]
+sab_username =
+sab_password =
+sab_apikey =
+sab_category =
+sab_host =
diff --git a/config.py b/config.py
new file mode 100644
index 00000000..39480787
--- /dev/null
+++ b/config.py
@@ -0,0 +1,91 @@
+import os
+from configobj import ConfigObj
+
+config = ConfigObj(os.path.join(os.path.dirname(__file__), 'config.ini'))
+
+General = config['General']
+http_host = General['http_host']
+http_port = General['http_port']
+http_username = General['http_username']
+http_password = General['http_password']
+launch_browser = General['launch_browser']
+usenet_retention = General['usenet_retention']
+include_lossless = General['include_lossless']
+move_to_itunes = General['move_to_itunes']
+path_to_itunes = General['path_to_itunes']
+rename_mp3s = General['rename_mp3s']
+add_album_art = General['add_album_art']
+music_download_dir = General['music_download_dir']
+NZBMatrix = config['NZBMatrix']
+nzbmatrix = NZBMatrix['nzbmatrix']
+nzbmatrix_username = NZBMatrix['nzbmatrix_username']
+nzbmatrix_apikey = NZBMatrix['nzbmatrix_apikey']
+SABnzbd = config['SABnzbd']
+sab_username = SABnzbd['sab_username']
+sab_password = SABnzbd['sab_password']
+sab_apikey = SABnzbd['sab_apikey']
+sab_category = SABnzbd['sab_category']
+sab_host = SABnzbd['sab_host']
+
+def var_to_chk(variable):
+	if variable == '1':
+		return 'Checked'
+	else:
+		return ''
+
+form = '''

+	

+	
Web Interface

+	
+	
+		
+	
+	
HTTP Host:

+	

+	
i.e. localhost or 0.0.0.0
HTTP Username:

+	

HTTP Port:

+	
HTTP Password:

+	

Launch Browser on Startup:

+    Enabled

+	
Download Settings

+    
+    
+    
+    
+    
+    
+    
SABnzbd Host:

+    

+    
usually localhost:8080
SABnzbd Username:

+    

SABnzbd API:

+    
SABnzbd Password:

+    

SABnzbd Category:

+    
Music Download Directory:

+    

+    
Absolute or relative path to the dir where SAB downloads your music

+    i.e. Downloads/music or /Users/name/Downloads/music

Usenet Retention:

+    

+	
Search Providers

+	
+    
+    
Enable NZBMatrix:

+    Enabled
NZBMatrix Username:

+    
NZBMatrix API:

+    

+    
Quality & Post Processing

+    
+    
+    
+    
+    
Album Quality:

+    Include lossless
iTunes:

+    Move downloads to iTunes

Path to iTunes folder:

+    

+    
i.e. Music/iTunes or /Users/name/Music/iTunes
Renaming & Metadata:

+    Rename & add metadata

Album Art:

+    Add album art

+    
''' % (http_host, http_username, 
+    http_port, http_password, var_to_chk(launch_browser), sab_host, sab_username, sab_apikey, sab_password,
+    sab_category, music_download_dir, usenet_retention, var_to_chk(nzbmatrix), nzbmatrix_username, nzbmatrix_apikey,
+    var_to_chk(include_lossless), var_to_chk(move_to_itunes), path_to_itunes, var_to_chk(rename_mp3s),
+    var_to_chk(add_album_art))
\ No newline at end of file
diff --git a/configobj.py b/configobj.py
new file mode 100644
index 00000000..c1f6e6df
--- /dev/null
+++ b/configobj.py
@@ -0,0 +1,2468 @@
+# configobj.py
+# A config file reader/writer that supports nested sections in config files.
+# Copyright (C) 2005-2010 Michael Foord, Nicola Larosa
+# E-mail: fuzzyman AT voidspace DOT org DOT uk
+#         nico AT tekNico DOT net
+
+# ConfigObj 4
+# http://www.voidspace.org.uk/python/configobj.html
+
+# Released subject to the BSD License
+# Please see http://www.voidspace.org.uk/python/license.shtml
+
+# Scripts maintained at http://www.voidspace.org.uk/python/index.shtml
+# For information about bugfixes, updates and support, please join the
+# ConfigObj mailing list:
+# http://lists.sourceforge.net/lists/listinfo/configobj-develop
+# Comments, suggestions and bug reports welcome.
+
+from __future__ import generators
+
+import os
+import re
+import sys
+
+from codecs import BOM_UTF8, BOM_UTF16, BOM_UTF16_BE, BOM_UTF16_LE
+
+
+# imported lazily to avoid startup performance hit if it isn't used
+compiler = None
+
+# A dictionary mapping BOM to
+# the encoding to decode with, and what to set the
+# encoding attribute to.
+BOMS = {
+    BOM_UTF8: ('utf_8', None),
+    BOM_UTF16_BE: ('utf16_be', 'utf_16'),
+    BOM_UTF16_LE: ('utf16_le', 'utf_16'),
+    BOM_UTF16: ('utf_16', 'utf_16'),
+    }
+# All legal variants of the BOM codecs.
+# TODO: the list of aliases is not meant to be exhaustive, is there a
+#   better way ?
+BOM_LIST = {
+    'utf_16': 'utf_16',
+    'u16': 'utf_16',
+    'utf16': 'utf_16',
+    'utf-16': 'utf_16',
+    'utf16_be': 'utf16_be',
+    'utf_16_be': 'utf16_be',
+    'utf-16be': 'utf16_be',
+    'utf16_le': 'utf16_le',
+    'utf_16_le': 'utf16_le',
+    'utf-16le': 'utf16_le',
+    'utf_8': 'utf_8',
+    'u8': 'utf_8',
+    'utf': 'utf_8',
+    'utf8': 'utf_8',
+    'utf-8': 'utf_8',
+    }
+
+# Map of encodings to the BOM to write.
+BOM_SET = {
+    'utf_8': BOM_UTF8,
+    'utf_16': BOM_UTF16,
+    'utf16_be': BOM_UTF16_BE,
+    'utf16_le': BOM_UTF16_LE,
+    None: BOM_UTF8
+    }
+
+
+def match_utf8(encoding):
+    return BOM_LIST.get(encoding.lower()) == 'utf_8'
+
+
+# Quote strings used for writing values
+squot = "'%s'"
+dquot = '"%s"'
+noquot = "%s"
+wspace_plus = ' \r\n\v\t\'"'
+tsquot = '"""%s"""'
+tdquot = "'''%s'''"
+
+# Sentinel for use in getattr calls to replace hasattr
+MISSING = object()
+
+__version__ = '4.7.2'
+
+try:
+    any
+except NameError:
+    def any(iterable):
+        for entry in iterable:
+            if entry:
+                return True
+        return False
+
+
+__all__ = (
+    '__version__',
+    'DEFAULT_INDENT_TYPE',
+    'DEFAULT_INTERPOLATION',
+    'ConfigObjError',
+    'NestingError',
+    'ParseError',
+    'DuplicateError',
+    'ConfigspecError',
+    'ConfigObj',
+    'SimpleVal',
+    'InterpolationError',
+    'InterpolationLoopError',
+    'MissingInterpolationOption',
+    'RepeatSectionError',
+    'ReloadError',
+    'UnreprError',
+    'UnknownType',
+    'flatten_errors',
+    'get_extra_values'
+)
+
+DEFAULT_INTERPOLATION = 'configparser'
+DEFAULT_INDENT_TYPE = '    '
+MAX_INTERPOL_DEPTH = 10
+
+OPTION_DEFAULTS = {
+    'interpolation': True,
+    'raise_errors': False,
+    'list_values': True,
+    'create_empty': False,
+    'file_error': False,
+    'configspec': None,
+    'stringify': True,
+    # option may be set to one of ('', ' ', '\t')
+    'indent_type': None,
+    'encoding': None,
+    'default_encoding': None,
+    'unrepr': False,
+    'write_empty_values': False,
+}
+
+
+
+def getObj(s):
+    global compiler
+    if compiler is None:
+        import compiler
+    s = "a=" + s
+    p = compiler.parse(s)
+    return p.getChildren()[1].getChildren()[0].getChildren()[1]
+
+
+class UnknownType(Exception):
+    pass
+
+
+class Builder(object):
+    
+    def build(self, o):
+        m = getattr(self, 'build_' + o.__class__.__name__, None)
+        if m is None:
+            raise UnknownType(o.__class__.__name__)
+        return m(o)
+    
+    def build_List(self, o):
+        return map(self.build, o.getChildren())
+    
+    def build_Const(self, o):
+        return o.value
+    
+    def build_Dict(self, o):
+        d = {}
+        i = iter(map(self.build, o.getChildren()))
+        for el in i:
+            d[el] = i.next()
+        return d
+    
+    def build_Tuple(self, o):
+        return tuple(self.build_List(o))
+    
+    def build_Name(self, o):
+        if o.name == 'None':
+            return None
+        if o.name == 'True':
+            return True
+        if o.name == 'False':
+            return False
+        
+        # An undefined Name
+        raise UnknownType('Undefined Name')
+    
+    def build_Add(self, o):
+        real, imag = map(self.build_Const, o.getChildren())
+        try:
+            real = float(real)
+        except TypeError:
+            raise UnknownType('Add')
+        if not isinstance(imag, complex) or imag.real != 0.0:
+            raise UnknownType('Add')
+        return real+imag
+    
+    def build_Getattr(self, o):
+        parent = self.build(o.expr)
+        return getattr(parent, o.attrname)
+    
+    def build_UnarySub(self, o):
+        return -self.build_Const(o.getChildren()[0])
+    
+    def build_UnaryAdd(self, o):
+        return self.build_Const(o.getChildren()[0])
+
+
+_builder = Builder()
+
+
+def unrepr(s):
+    if not s:
+        return s
+    return _builder.build(getObj(s))
+
+
+
+class ConfigObjError(SyntaxError):
+    """
+    This is the base class for all errors that ConfigObj raises.
+    It is a subclass of SyntaxError.
+    """
+    def __init__(self, message='', line_number=None, line=''):
+        self.line = line
+        self.line_number = line_number
+        SyntaxError.__init__(self, message)
+
+
+class NestingError(ConfigObjError):
+    """
+    This error indicates a level of nesting that doesn't match.
+    """
+
+
+class ParseError(ConfigObjError):
+    """
+    This error indicates that a line is badly written.
+    It is neither a valid ``key = value`` line,
+    nor a valid section marker line.
+    """
+
+
+class ReloadError(IOError):
+    """
+    A 'reload' operation failed.
+    This exception is a subclass of ``IOError``.
+    """
+    def __init__(self):
+        IOError.__init__(self, 'reload failed, filename is not set.')
+
+
+class DuplicateError(ConfigObjError):
+    """
+    The keyword or section specified already exists.
+    """
+
+
+class ConfigspecError(ConfigObjError):
+    """
+    An error occured whilst parsing a configspec.
+    """
+
+
+class InterpolationError(ConfigObjError):
+    """Base class for the two interpolation errors."""
+
+
+class InterpolationLoopError(InterpolationError):
+    """Maximum interpolation depth exceeded in string interpolation."""
+
+    def __init__(self, option):
+        InterpolationError.__init__(
+            self,
+            'interpolation loop detected in value "%s".' % option)
+
+
+class RepeatSectionError(ConfigObjError):
+    """
+    This error indicates additional sections in a section with a
+    ``__many__`` (repeated) section.
+    """
+
+
+class MissingInterpolationOption(InterpolationError):
+    """A value specified for interpolation was missing."""
+    def __init__(self, option):
+        msg = 'missing option "%s" in interpolation.' % option
+        InterpolationError.__init__(self, msg)
+
+
+class UnreprError(ConfigObjError):
+    """An error parsing in unrepr mode."""
+
+
+
+class InterpolationEngine(object):
+    """
+    A helper class to help perform string interpolation.
+
+    This class is an abstract base class; its descendants perform
+    the actual work.
+    """
+
+    # compiled regexp to use in self.interpolate()
+    _KEYCRE = re.compile(r"%\(([^)]*)\)s")
+    _cookie = '%'
+
+    def __init__(self, section):
+        # the Section instance that "owns" this engine
+        self.section = section
+
+
+    def interpolate(self, key, value):
+        # short-cut
+        if not self._cookie in value:
+            return value
+        
+        def recursive_interpolate(key, value, section, backtrail):
+            """The function that does the actual work.
+
+            ``value``: the string we're trying to interpolate.
+            ``section``: the section in which that string was found
+            ``backtrail``: a dict to keep track of where we've been,
+            to detect and prevent infinite recursion loops
+
+            This is similar to a depth-first-search algorithm.
+            """
+            # Have we been here already?
+            if (key, section.name) in backtrail:
+                # Yes - infinite loop detected
+                raise InterpolationLoopError(key)
+            # Place a marker on our backtrail so we won't come back here again
+            backtrail[(key, section.name)] = 1
+
+            # Now start the actual work
+            match = self._KEYCRE.search(value)
+            while match:
+                # The actual parsing of the match is implementation-dependent,
+                # so delegate to our helper function
+                k, v, s = self._parse_match(match)
+                if k is None:
+                    # That's the signal that no further interpolation is needed
+                    replacement = v
+                else:
+                    # Further interpolation may be needed to obtain final value
+                    replacement = recursive_interpolate(k, v, s, backtrail)
+                # Replace the matched string with its final value
+                start, end = match.span()
+                value = ''.join((value[:start], replacement, value[end:]))
+                new_search_start = start + len(replacement)
+                # Pick up the next interpolation key, if any, for next time
+                # through the while loop
+                match = self._KEYCRE.search(value, new_search_start)
+
+            # Now safe to come back here again; remove marker from backtrail
+            del backtrail[(key, section.name)]
+
+            return value
+
+        # Back in interpolate(), all we have to do is kick off the recursive
+        # function with appropriate starting values
+        value = recursive_interpolate(key, value, self.section, {})
+        return value
+
+
+    def _fetch(self, key):
+        """Helper function to fetch values from owning section.
+
+        Returns a 2-tuple: the value, and the section where it was found.
+        """
+        # switch off interpolation before we try and fetch anything !
+        save_interp = self.section.main.interpolation
+        self.section.main.interpolation = False
+
+        # Start at section that "owns" this InterpolationEngine
+        current_section = self.section
+        while True:
+            # try the current section first
+            val = current_section.get(key)
+            if val is not None and not isinstance(val, Section):
+                break
+            # try "DEFAULT" next
+            val = current_section.get('DEFAULT', {}).get(key)
+            if val is not None and not isinstance(val, Section):
+                break
+            # move up to parent and try again
+            # top-level's parent is itself
+            if current_section.parent is current_section:
+                # reached top level, time to give up
+                break
+            current_section = current_section.parent
+
+        # restore interpolation to previous value before returning
+        self.section.main.interpolation = save_interp
+        if val is None:
+            raise MissingInterpolationOption(key)
+        return val, current_section
+
+
+    def _parse_match(self, match):
+        """Implementation-dependent helper function.
+
+        Will be passed a match object corresponding to the interpolation
+        key we just found (e.g., "%(foo)s" or "$foo"). Should look up that
+        key in the appropriate config file section (using the ``_fetch()``
+        helper function) and return a 3-tuple: (key, value, section)
+
+        ``key`` is the name of the key we're looking for
+        ``value`` is the value found for that key
+        ``section`` is a reference to the section where it was found
+
+        ``key`` and ``section`` should be None if no further
+        interpolation should be performed on the resulting value
+        (e.g., if we interpolated "$$" and returned "$").
+        """
+        raise NotImplementedError()
+    
+
+
+class ConfigParserInterpolation(InterpolationEngine):
+    """Behaves like ConfigParser."""
+    _cookie = '%'
+    _KEYCRE = re.compile(r"%\(([^)]*)\)s")
+
+    def _parse_match(self, match):
+        key = match.group(1)
+        value, section = self._fetch(key)
+        return key, value, section
+
+
+
+class TemplateInterpolation(InterpolationEngine):
+    """Behaves like string.Template."""
+    _cookie = '$'
+    _delimiter = '$'
+    _KEYCRE = re.compile(r"""
+        \$(?:
+          (?P\$)              |   # Two $ signs
+          (?P[_a-z][_a-z0-9]*)  |   # $name format
+          {(?P[^}]*)}              # ${name} format
+        )
+        """, re.IGNORECASE | re.VERBOSE)
+
+    def _parse_match(self, match):
+        # Valid name (in or out of braces): fetch value from section
+        key = match.group('named') or match.group('braced')
+        if key is not None:
+            value, section = self._fetch(key)
+            return key, value, section
+        # Escaped delimiter (e.g., $$): return single delimiter
+        if match.group('escaped') is not None:
+            # Return None for key and section to indicate it's time to stop
+            return None, self._delimiter, None
+        # Anything else: ignore completely, just return it unchanged
+        return None, match.group(), None
+
+
+interpolation_engines = {
+    'configparser': ConfigParserInterpolation,
+    'template': TemplateInterpolation,
+}
+
+
+def __newobj__(cls, *args):
+    # Hack for pickle
+    return cls.__new__(cls, *args) 
+
+class Section(dict):
+    """
+    A dictionary-like object that represents a section in a config file.
+    
+    It does string interpolation if the 'interpolation' attribute
+    of the 'main' object is set to True.
+    
+    Interpolation is tried first from this object, then from the 'DEFAULT'
+    section of this object, next from the parent and its 'DEFAULT' section,
+    and so on until the main object is reached.
+    
+    A Section will behave like an ordered dictionary - following the
+    order of the ``scalars`` and ``sections`` attributes.
+    You can use this to change the order of members.
+    
+    Iteration follows the order: scalars, then sections.
+    """
+
+    
+    def __setstate__(self, state):
+        dict.update(self, state[0])
+        self.__dict__.update(state[1])
+
+    def __reduce__(self):
+        state = (dict(self), self.__dict__)
+        return (__newobj__, (self.__class__,), state)
+    
+    
+    def __init__(self, parent, depth, main, indict=None, name=None):
+        """
+        * parent is the section above
+        * depth is the depth level of this section
+        * main is the main ConfigObj
+        * indict is a dictionary to initialise the section with
+        """
+        if indict is None:
+            indict = {}
+        dict.__init__(self)
+        # used for nesting level *and* interpolation
+        self.parent = parent
+        # used for the interpolation attribute
+        self.main = main
+        # level of nesting depth of this Section
+        self.depth = depth
+        # purely for information
+        self.name = name
+        #
+        self._initialise()
+        # we do this explicitly so that __setitem__ is used properly
+        # (rather than just passing to ``dict.__init__``)
+        for entry, value in indict.iteritems():
+            self[entry] = value
+            
+            
+    def _initialise(self):
+        # the sequence of scalar values in this Section
+        self.scalars = []
+        # the sequence of sections in this Section
+        self.sections = []
+        # for comments :-)
+        self.comments = {}
+        self.inline_comments = {}
+        # the configspec
+        self.configspec = None
+        # for defaults
+        self.defaults = []
+        self.default_values = {}
+        self.extra_values = []
+        self._created = False
+
+
+    def _interpolate(self, key, value):
+        try:
+            # do we already have an interpolation engine?
+            engine = self._interpolation_engine
+        except AttributeError:
+            # not yet: first time running _interpolate(), so pick the engine
+            name = self.main.interpolation
+            if name == True:  # note that "if name:" would be incorrect here
+                # backwards-compatibility: interpolation=True means use default
+                name = DEFAULT_INTERPOLATION
+            name = name.lower()  # so that "Template", "template", etc. all work
+            class_ = interpolation_engines.get(name, None)
+            if class_ is None:
+                # invalid value for self.main.interpolation
+                self.main.interpolation = False
+                return value
+            else:
+                # save reference to engine so we don't have to do this again
+                engine = self._interpolation_engine = class_(self)
+        # let the engine do the actual work
+        return engine.interpolate(key, value)
+
+
+    def __getitem__(self, key):
+        """Fetch the item and do string interpolation."""
+        val = dict.__getitem__(self, key)
+        if self.main.interpolation: 
+            if isinstance(val, basestring):
+                return self._interpolate(key, val)
+            if isinstance(val, list):
+                def _check(entry):
+                    if isinstance(entry, basestring):
+                        return self._interpolate(key, entry)
+                    return entry
+                new = [_check(entry) for entry in val]
+                if new != val:
+                    return new
+        return val
+
+
+    def __setitem__(self, key, value, unrepr=False):
+        """
+        Correctly set a value.
+        
+        Making dictionary values Section instances.
+        (We have to special case 'Section' instances - which are also dicts)
+        
+        Keys must be strings.
+        Values need only be strings (or lists of strings) if
+        ``main.stringify`` is set.
+        
+        ``unrepr`` must be set when setting a value to a dictionary, without
+        creating a new sub-section.
+        """
+        if not isinstance(key, basestring):
+            raise ValueError('The key "%s" is not a string.' % key)
+        
+        # add the comment
+        if key not in self.comments:
+            self.comments[key] = []
+            self.inline_comments[key] = ''
+        # remove the entry from defaults
+        if key in self.defaults:
+            self.defaults.remove(key)
+        #
+        if isinstance(value, Section):
+            if key not in self:
+                self.sections.append(key)
+            dict.__setitem__(self, key, value)
+        elif isinstance(value, dict) and not unrepr:
+            # First create the new depth level,
+            # then create the section
+            if key not in self:
+                self.sections.append(key)
+            new_depth = self.depth + 1
+            dict.__setitem__(
+                self,
+                key,
+                Section(
+                    self,
+                    new_depth,
+                    self.main,
+                    indict=value,
+                    name=key))
+        else:
+            if key not in self:
+                self.scalars.append(key)
+            if not self.main.stringify:
+                if isinstance(value, basestring):
+                    pass
+                elif isinstance(value, (list, tuple)):
+                    for entry in value:
+                        if not isinstance(entry, basestring):
+                            raise TypeError('Value is not a string "%s".' % entry)
+                else:
+                    raise TypeError('Value is not a string "%s".' % value)
+            dict.__setitem__(self, key, value)
+
+
+    def __delitem__(self, key):
+        """Remove items from the sequence when deleting."""
+        dict. __delitem__(self, key)
+        if key in self.scalars:
+            self.scalars.remove(key)
+        else:
+            self.sections.remove(key)
+        del self.comments[key]
+        del self.inline_comments[key]
+
+
+    def get(self, key, default=None):
+        """A version of ``get`` that doesn't bypass string interpolation."""
+        try:
+            return self[key]
+        except KeyError:
+            return default
+
+
+    def update(self, indict):
+        """
+        A version of update that uses our ``__setitem__``.
+        """
+        for entry in indict:
+            self[entry] = indict[entry]
+
+
+    def pop(self, key, default=MISSING):
+        """
+        'D.pop(k[,d]) -> v, remove specified key and return the corresponding value.
+        If key is not found, d is returned if given, otherwise KeyError is raised'
+        """
+        try:
+            val = self[key]
+        except KeyError:
+            if default is MISSING:
+                raise
+            val = default
+        else:
+            del self[key]
+        return val
+
+
+    def popitem(self):
+        """Pops the first (key,val)"""
+        sequence = (self.scalars + self.sections)
+        if not sequence:
+            raise KeyError(": 'popitem(): dictionary is empty'")
+        key = sequence[0]
+        val =  self[key]
+        del self[key]
+        return key, val
+
+
+    def clear(self):
+        """
+        A version of clear that also affects scalars/sections
+        Also clears comments and configspec.
+        
+        Leaves other attributes alone :
+            depth/main/parent are not affected
+        """
+        dict.clear(self)
+        self.scalars = []
+        self.sections = []
+        self.comments = {}
+        self.inline_comments = {}
+        self.configspec = None
+        self.defaults = []
+        self.extra_values = []
+
+
+    def setdefault(self, key, default=None):
+        """A version of setdefault that sets sequence if appropriate."""
+        try:
+            return self[key]
+        except KeyError:
+            self[key] = default
+            return self[key]
+
+
+    def items(self):
+        """D.items() -> list of D's (key, value) pairs, as 2-tuples"""
+        return zip((self.scalars + self.sections), self.values())
+
+
+    def keys(self):
+        """D.keys() -> list of D's keys"""
+        return (self.scalars + self.sections)
+
+
+    def values(self):
+        """D.values() -> list of D's values"""
+        return [self[key] for key in (self.scalars + self.sections)]
+
+
+    def iteritems(self):
+        """D.iteritems() -> an iterator over the (key, value) items of D"""
+        return iter(self.items())
+
+
+    def iterkeys(self):
+        """D.iterkeys() -> an iterator over the keys of D"""
+        return iter((self.scalars + self.sections))
+
+    __iter__ = iterkeys
+
+
+    def itervalues(self):
+        """D.itervalues() -> an iterator over the values of D"""
+        return iter(self.values())
+
+
+    def __repr__(self):
+        """x.__repr__() <==> repr(x)"""
+        def _getval(key):
+            try:
+                return self[key]
+            except MissingInterpolationOption:
+                return dict.__getitem__(self, key)
+        return '{%s}' % ', '.join([('%s: %s' % (repr(key), repr(_getval(key))))
+            for key in (self.scalars + self.sections)])
+
+    __str__ = __repr__
+    __str__.__doc__ = "x.__str__() <==> str(x)"
+
+
+    # Extra methods - not in a normal dictionary
+
+    def dict(self):
+        """
+        Return a deepcopy of self as a dictionary.
+        
+        All members that are ``Section`` instances are recursively turned to
+        ordinary dictionaries - by calling their ``dict`` method.
+        
+        >>> n = a.dict()
+        >>> n == a
+        1
+        >>> n is a
+        0
+        """
+        newdict = {}
+        for entry in self:
+            this_entry = self[entry]
+            if isinstance(this_entry, Section):
+                this_entry = this_entry.dict()
+            elif isinstance(this_entry, list):
+                # create a copy rather than a reference
+                this_entry = list(this_entry)
+            elif isinstance(this_entry, tuple):
+                # create a copy rather than a reference
+                this_entry = tuple(this_entry)
+            newdict[entry] = this_entry
+        return newdict
+
+
+    def merge(self, indict):
+        """
+        A recursive update - useful for merging config files.
+        
+        >>> a = '''[section1]
+        ...     option1 = True
+        ...     [[subsection]]
+        ...     more_options = False
+        ...     # end of file'''.splitlines()
+        >>> b = '''# File is user.ini
+        ...     [section1]
+        ...     option1 = False
+        ...     # end of file'''.splitlines()
+        >>> c1 = ConfigObj(b)
+        >>> c2 = ConfigObj(a)
+        >>> c2.merge(c1)
+        >>> c2
+        ConfigObj({'section1': {'option1': 'False', 'subsection': {'more_options': 'False'}}})
+        """
+        for key, val in indict.items():
+            if (key in self and isinstance(self[key], dict) and
+                                isinstance(val, dict)):
+                self[key].merge(val)
+            else:   
+                self[key] = val
+
+
+    def rename(self, oldkey, newkey):
+        """
+        Change a keyname to another, without changing position in sequence.
+        
+        Implemented so that transformations can be made on keys,
+        as well as on values. (used by encode and decode)
+        
+        Also renames comments.
+        """
+        if oldkey in self.scalars:
+            the_list = self.scalars
+        elif oldkey in self.sections:
+            the_list = self.sections
+        else:
+            raise KeyError('Key "%s" not found.' % oldkey)
+        pos = the_list.index(oldkey)
+        #
+        val = self[oldkey]
+        dict.__delitem__(self, oldkey)
+        dict.__setitem__(self, newkey, val)
+        the_list.remove(oldkey)
+        the_list.insert(pos, newkey)
+        comm = self.comments[oldkey]
+        inline_comment = self.inline_comments[oldkey]
+        del self.comments[oldkey]
+        del self.inline_comments[oldkey]
+        self.comments[newkey] = comm
+        self.inline_comments[newkey] = inline_comment
+
+
+    def walk(self, function, raise_errors=True,
+            call_on_sections=False, **keywargs):
+        """
+        Walk every member and call a function on the keyword and value.
+        
+        Return a dictionary of the return values
+        
+        If the function raises an exception, raise the errror
+        unless ``raise_errors=False``, in which case set the return value to
+        ``False``.
+        
+        Any unrecognised keyword arguments you pass to walk, will be pased on
+        to the function you pass in.
+        
+        Note: if ``call_on_sections`` is ``True`` then - on encountering a
+        subsection, *first* the function is called for the *whole* subsection,
+        and then recurses into it's members. This means your function must be
+        able to handle strings, dictionaries and lists. This allows you
+        to change the key of subsections as well as for ordinary members. The
+        return value when called on the whole subsection has to be discarded.
+        
+        See  the encode and decode methods for examples, including functions.
+        
+        .. admonition:: caution
+        
+            You can use ``walk`` to transform the names of members of a section
+            but you mustn't add or delete members.
+        
+        >>> config = '''[XXXXsection]
+        ... XXXXkey = XXXXvalue'''.splitlines()
+        >>> cfg = ConfigObj(config)
+        >>> cfg
+        ConfigObj({'XXXXsection': {'XXXXkey': 'XXXXvalue'}})
+        >>> def transform(section, key):
+        ...     val = section[key]
+        ...     newkey = key.replace('XXXX', 'CLIENT1')
+        ...     section.rename(key, newkey)
+        ...     if isinstance(val, (tuple, list, dict)):
+        ...         pass
+        ...     else:
+        ...         val = val.replace('XXXX', 'CLIENT1')
+        ...         section[newkey] = val
+        >>> cfg.walk(transform, call_on_sections=True)
+        {'CLIENT1section': {'CLIENT1key': None}}
+        >>> cfg
+        ConfigObj({'CLIENT1section': {'CLIENT1key': 'CLIENT1value'}})
+        """
+        out = {}
+        # scalars first
+        for i in range(len(self.scalars)):
+            entry = self.scalars[i]
+            try:
+                val = function(self, entry, **keywargs)
+                # bound again in case name has changed
+                entry = self.scalars[i]
+                out[entry] = val
+            except Exception:
+                if raise_errors:
+                    raise
+                else:
+                    entry = self.scalars[i]
+                    out[entry] = False
+        # then sections
+        for i in range(len(self.sections)):
+            entry = self.sections[i]
+            if call_on_sections:
+                try:
+                    function(self, entry, **keywargs)
+                except Exception:
+                    if raise_errors:
+                        raise
+                    else:
+                        entry = self.sections[i]
+                        out[entry] = False
+                # bound again in case name has changed
+                entry = self.sections[i]
+            # previous result is discarded
+            out[entry] = self[entry].walk(
+                function,
+                raise_errors=raise_errors,
+                call_on_sections=call_on_sections,
+                **keywargs)
+        return out
+
+
+    def as_bool(self, key):
+        """
+        Accepts a key as input. The corresponding value must be a string or
+        the objects (``True`` or 1) or (``False`` or 0). We allow 0 and 1 to
+        retain compatibility with Python 2.2.
+        
+        If the string is one of  ``True``, ``On``, ``Yes``, or ``1`` it returns 
+        ``True``.
+        
+        If the string is one of  ``False``, ``Off``, ``No``, or ``0`` it returns 
+        ``False``.
+        
+        ``as_bool`` is not case sensitive.
+        
+        Any other input will raise a ``ValueError``.
+        
+        >>> a = ConfigObj()
+        >>> a['a'] = 'fish'
+        >>> a.as_bool('a')
+        Traceback (most recent call last):
+        ValueError: Value "fish" is neither True nor False
+        >>> a['b'] = 'True'
+        >>> a.as_bool('b')
+        1
+        >>> a['b'] = 'off'
+        >>> a.as_bool('b')
+        0
+        """
+        val = self[key]
+        if val == True:
+            return True
+        elif val == False:
+            return False
+        else:
+            try:
+                if not isinstance(val, basestring):
+                    # TODO: Why do we raise a KeyError here?
+                    raise KeyError()
+                else:
+                    return self.main._bools[val.lower()]
+            except KeyError:
+                raise ValueError('Value "%s" is neither True nor False' % val)
+
+
+    def as_int(self, key):
+        """
+        A convenience method which coerces the specified value to an integer.
+        
+        If the value is an invalid literal for ``int``, a ``ValueError`` will
+        be raised.
+        
+        >>> a = ConfigObj()
+        >>> a['a'] = 'fish'
+        >>> a.as_int('a')
+        Traceback (most recent call last):
+        ValueError: invalid literal for int() with base 10: 'fish'
+        >>> a['b'] = '1'
+        >>> a.as_int('b')
+        1
+        >>> a['b'] = '3.2'
+        >>> a.as_int('b')
+        Traceback (most recent call last):
+        ValueError: invalid literal for int() with base 10: '3.2'
+        """
+        return int(self[key])
+
+
+    def as_float(self, key):
+        """
+        A convenience method which coerces the specified value to a float.
+        
+        If the value is an invalid literal for ``float``, a ``ValueError`` will
+        be raised.
+        
+        >>> a = ConfigObj()
+        >>> a['a'] = 'fish'
+        >>> a.as_float('a')
+        Traceback (most recent call last):
+        ValueError: invalid literal for float(): fish
+        >>> a['b'] = '1'
+        >>> a.as_float('b')
+        1.0
+        >>> a['b'] = '3.2'
+        >>> a.as_float('b')
+        3.2000000000000002
+        """
+        return float(self[key])
+    
+    
+    def as_list(self, key):
+        """
+        A convenience method which fetches the specified value, guaranteeing
+        that it is a list.
+        
+        >>> a = ConfigObj()
+        >>> a['a'] = 1
+        >>> a.as_list('a')
+        [1]
+        >>> a['a'] = (1,)
+        >>> a.as_list('a')
+        [1]
+        >>> a['a'] = [1]
+        >>> a.as_list('a')
+        [1]
+        """
+        result = self[key]
+        if isinstance(result, (tuple, list)):
+            return list(result)
+        return [result]
+        
+
+    def restore_default(self, key):
+        """
+        Restore (and return) default value for the specified key.
+        
+        This method will only work for a ConfigObj that was created
+        with a configspec and has been validated.
+        
+        If there is no default value for this key, ``KeyError`` is raised.
+        """
+        default = self.default_values[key]
+        dict.__setitem__(self, key, default)
+        if key not in self.defaults:
+            self.defaults.append(key)
+        return default
+
+    
+    def restore_defaults(self):
+        """
+        Recursively restore default values to all members
+        that have them.
+        
+        This method will only work for a ConfigObj that was created
+        with a configspec and has been validated.
+        
+        It doesn't delete or modify entries without default values.
+        """
+        for key in self.default_values:
+            self.restore_default(key)
+            
+        for section in self.sections:
+            self[section].restore_defaults()
+
+
+class ConfigObj(Section):
+    """An object to read, create, and write config files."""
+
+    _keyword = re.compile(r'''^ # line start
+        (\s*)                   # indentation
+        (                       # keyword
+            (?:".*?")|          # double quotes
+            (?:'.*?')|          # single quotes
+            (?:[^'"=].*?)       # no quotes
+        )
+        \s*=\s*                 # divider
+        (.*)                    # value (including list values and comments)
+        $   # line end
+        ''',
+        re.VERBOSE)
+
+    _sectionmarker = re.compile(r'''^
+        (\s*)                     # 1: indentation
+        ((?:\[\s*)+)              # 2: section marker open
+        (                         # 3: section name open
+            (?:"\s*\S.*?\s*")|    # at least one non-space with double quotes
+            (?:'\s*\S.*?\s*')|    # at least one non-space with single quotes
+            (?:[^'"\s].*?)        # at least one non-space unquoted
+        )                         # section name close
+        ((?:\s*\])+)              # 4: section marker close
+        \s*(\#.*)?                # 5: optional comment
+        $''',
+        re.VERBOSE)
+
+    # this regexp pulls list values out as a single string
+    # or single values and comments
+    # FIXME: this regex adds a '' to the end of comma terminated lists
+    #   workaround in ``_handle_value``
+    _valueexp = re.compile(r'''^
+        (?:
+            (?:
+                (
+                    (?:
+                        (?:
+                            (?:".*?")|              # double quotes
+                            (?:'.*?')|              # single quotes
+                            (?:[^'",\#][^,\#]*?)    # unquoted
+                        )
+                        \s*,\s*                     # comma
+                    )*      # match all list items ending in a comma (if any)
+                )
+                (
+                    (?:".*?")|                      # double quotes
+                    (?:'.*?')|                      # single quotes
+                    (?:[^'",\#\s][^,]*?)|           # unquoted
+                    (?:(? 1:
+                msg = "Parsing failed with several errors.\nFirst error %s" % info
+                error = ConfigObjError(msg)
+            else:
+                error = self._errors[0]
+            # set the errors attribute; it's a list of tuples:
+            # (error_type, message, line_number)
+            error.errors = self._errors
+            # set the config attribute
+            error.config = self
+            raise error
+        # delete private attributes
+        del self._errors
+        
+        if configspec is None:
+            self.configspec = None
+        else:
+            self._handle_configspec(configspec)
+    
+    
+    def _initialise(self, options=None):
+        if options is None:
+            options = OPTION_DEFAULTS
+            
+        # initialise a few variables
+        self.filename = None
+        self._errors = []
+        self.raise_errors = options['raise_errors']
+        self.interpolation = options['interpolation']
+        self.list_values = options['list_values']
+        self.create_empty = options['create_empty']
+        self.file_error = options['file_error']
+        self.stringify = options['stringify']
+        self.indent_type = options['indent_type']
+        self.encoding = options['encoding']
+        self.default_encoding = options['default_encoding']
+        self.BOM = False
+        self.newlines = None
+        self.write_empty_values = options['write_empty_values']
+        self.unrepr = options['unrepr']
+        
+        self.initial_comment = []
+        self.final_comment = []
+        self.configspec = None
+        
+        if self._inspec:
+            self.list_values = False
+        
+        # Clear section attributes as well
+        Section._initialise(self)
+        
+        
+    def __repr__(self):
+        def _getval(key):
+            try:
+                return self[key]
+            except MissingInterpolationOption:
+                return dict.__getitem__(self, key)
+        return ('ConfigObj({%s})' % 
+                ', '.join([('%s: %s' % (repr(key), repr(_getval(key)))) 
+                for key in (self.scalars + self.sections)]))
+    
+    
+    def _handle_bom(self, infile):
+        """
+        Handle any BOM, and decode if necessary.
+        
+        If an encoding is specified, that *must* be used - but the BOM should
+        still be removed (and the BOM attribute set).
+        
+        (If the encoding is wrongly specified, then a BOM for an alternative
+        encoding won't be discovered or removed.)
+        
+        If an encoding is not specified, UTF8 or UTF16 BOM will be detected and
+        removed. The BOM attribute will be set. UTF16 will be decoded to
+        unicode.
+        
+        NOTE: This method must not be called with an empty ``infile``.
+        
+        Specifying the *wrong* encoding is likely to cause a
+        ``UnicodeDecodeError``.
+        
+        ``infile`` must always be returned as a list of lines, but may be
+        passed in as a single string.
+        """
+        if ((self.encoding is not None) and
+            (self.encoding.lower() not in BOM_LIST)):
+            # No need to check for a BOM
+            # the encoding specified doesn't have one
+            # just decode
+            return self._decode(infile, self.encoding)
+        
+        if isinstance(infile, (list, tuple)):
+            line = infile[0]
+        else:
+            line = infile
+        if self.encoding is not None:
+            # encoding explicitly supplied
+            # And it could have an associated BOM
+            # TODO: if encoding is just UTF16 - we ought to check for both
+            # TODO: big endian and little endian versions.
+            enc = BOM_LIST[self.encoding.lower()]
+            if enc == 'utf_16':
+                # For UTF16 we try big endian and little endian
+                for BOM, (encoding, final_encoding) in BOMS.items():
+                    if not final_encoding:
+                        # skip UTF8
+                        continue
+                    if infile.startswith(BOM):
+                        ### BOM discovered
+                        ##self.BOM = True
+                        # Don't need to remove BOM
+                        return self._decode(infile, encoding)
+                    
+                # If we get this far, will *probably* raise a DecodeError
+                # As it doesn't appear to start with a BOM
+                return self._decode(infile, self.encoding)
+            
+            # Must be UTF8
+            BOM = BOM_SET[enc]
+            if not line.startswith(BOM):
+                return self._decode(infile, self.encoding)
+            
+            newline = line[len(BOM):]
+            
+            # BOM removed
+            if isinstance(infile, (list, tuple)):
+                infile[0] = newline
+            else:
+                infile = newline
+            self.BOM = True
+            return self._decode(infile, self.encoding)
+        
+        # No encoding specified - so we need to check for UTF8/UTF16
+        for BOM, (encoding, final_encoding) in BOMS.items():
+            if not line.startswith(BOM):
+                continue
+            else:
+                # BOM discovered
+                self.encoding = final_encoding
+                if not final_encoding:
+                    self.BOM = True
+                    # UTF8
+                    # remove BOM
+                    newline = line[len(BOM):]
+                    if isinstance(infile, (list, tuple)):
+                        infile[0] = newline
+                    else:
+                        infile = newline
+                    # UTF8 - don't decode
+                    if isinstance(infile, basestring):
+                        return infile.splitlines(True)
+                    else:
+                        return infile
+                # UTF16 - have to decode
+                return self._decode(infile, encoding)
+            
+        # No BOM discovered and no encoding specified, just return
+        if isinstance(infile, basestring):
+            # infile read from a file will be a single string
+            return infile.splitlines(True)
+        return infile
+
+
+    def _a_to_u(self, aString):
+        """Decode ASCII strings to unicode if a self.encoding is specified."""
+        if self.encoding:
+            return aString.decode('ascii')
+        else:
+            return aString
+
+
+    def _decode(self, infile, encoding):
+        """
+        Decode infile to unicode. Using the specified encoding.
+        
+        if is a string, it also needs converting to a list.
+        """
+        if isinstance(infile, basestring):
+            # can't be unicode
+            # NOTE: Could raise a ``UnicodeDecodeError``
+            return infile.decode(encoding).splitlines(True)
+        for i, line in enumerate(infile):
+            if not isinstance(line, unicode):
+                # NOTE: The isinstance test here handles mixed lists of unicode/string
+                # NOTE: But the decode will break on any non-string values
+                # NOTE: Or could raise a ``UnicodeDecodeError``
+                infile[i] = line.decode(encoding)
+        return infile
+
+
+    def _decode_element(self, line):
+        """Decode element to unicode if necessary."""
+        if not self.encoding:
+            return line
+        if isinstance(line, str) and self.default_encoding:
+            return line.decode(self.default_encoding)
+        return line
+
+
+    def _str(self, value):
+        """
+        Used by ``stringify`` within validate, to turn non-string values
+        into strings.
+        """
+        if not isinstance(value, basestring):
+            return str(value)
+        else:
+            return value
+
+
+    def _parse(self, infile):
+        """Actually parse the config file."""
+        temp_list_values = self.list_values
+        if self.unrepr:
+            self.list_values = False
+            
+        comment_list = []
+        done_start = False
+        this_section = self
+        maxline = len(infile) - 1
+        cur_index = -1
+        reset_comment = False
+        
+        while cur_index < maxline:
+            if reset_comment:
+                comment_list = []
+            cur_index += 1
+            line = infile[cur_index]
+            sline = line.strip()
+            # do we have anything on the line ?
+            if not sline or sline.startswith('#'):
+                reset_comment = False
+                comment_list.append(line)
+                continue
+            
+            if not done_start:
+                # preserve initial comment
+                self.initial_comment = comment_list
+                comment_list = []
+                done_start = True
+                
+            reset_comment = True
+            # first we check if it's a section marker
+            mat = self._sectionmarker.match(line)
+            if mat is not None:
+                # is a section line
+                (indent, sect_open, sect_name, sect_close, comment) = mat.groups()
+                if indent and (self.indent_type is None):
+                    self.indent_type = indent
+                cur_depth = sect_open.count('[')
+                if cur_depth != sect_close.count(']'):
+                    self._handle_error("Cannot compute the section depth at line %s.",
+                                       NestingError, infile, cur_index)
+                    continue
+                
+                if cur_depth < this_section.depth:
+                    # the new section is dropping back to a previous level
+                    try:
+                        parent = self._match_depth(this_section,
+                                                   cur_depth).parent
+                    except SyntaxError:
+                        self._handle_error("Cannot compute nesting level at line %s.",
+                                           NestingError, infile, cur_index)
+                        continue
+                elif cur_depth == this_section.depth:
+                    # the new section is a sibling of the current section
+                    parent = this_section.parent
+                elif cur_depth == this_section.depth + 1:
+                    # the new section is a child the current section
+                    parent = this_section
+                else:
+                    self._handle_error("Section too nested at line %s.",
+                                       NestingError, infile, cur_index)
+                    
+                sect_name = self._unquote(sect_name)
+                if sect_name in parent:
+                    self._handle_error('Duplicate section name at line %s.',
+                                       DuplicateError, infile, cur_index)
+                    continue
+                
+                # create the new section
+                this_section = Section(
+                    parent,
+                    cur_depth,
+                    self,
+                    name=sect_name)
+                parent[sect_name] = this_section
+                parent.inline_comments[sect_name] = comment
+                parent.comments[sect_name] = comment_list
+                continue
+            #
+            # it's not a section marker,
+            # so it should be a valid ``key = value`` line
+            mat = self._keyword.match(line)
+            if mat is None:
+                # it neither matched as a keyword
+                # or a section marker
+                self._handle_error(
+                    'Invalid line at line "%s".',
+                    ParseError, infile, cur_index)
+            else:
+                # is a keyword value
+                # value will include any inline comment
+                (indent, key, value) = mat.groups()
+                if indent and (self.indent_type is None):
+                    self.indent_type = indent
+                # check for a multiline value
+                if value[:3] in ['"""', "'''"]:
+                    try:
+                        value, comment, cur_index = self._multiline(
+                            value, infile, cur_index, maxline)
+                    except SyntaxError:
+                        self._handle_error(
+                            'Parse error in value at line %s.',
+                            ParseError, infile, cur_index)
+                        continue
+                    else:
+                        if self.unrepr:
+                            comment = ''
+                            try:
+                                value = unrepr(value)
+                            except Exception, e:
+                                if type(e) == UnknownType:
+                                    msg = 'Unknown name or type in value at line %s.'
+                                else:
+                                    msg = 'Parse error in value at line %s.'
+                                self._handle_error(msg, UnreprError, infile,
+                                    cur_index)
+                                continue
+                else:
+                    if self.unrepr:
+                        comment = ''
+                        try:
+                            value = unrepr(value)
+                        except Exception, e:
+                            if isinstance(e, UnknownType):
+                                msg = 'Unknown name or type in value at line %s.'
+                            else:
+                                msg = 'Parse error in value at line %s.'
+                            self._handle_error(msg, UnreprError, infile,
+                                cur_index)
+                            continue
+                    else:
+                        # extract comment and lists
+                        try:
+                            (value, comment) = self._handle_value(value)
+                        except SyntaxError:
+                            self._handle_error(
+                                'Parse error in value at line %s.',
+                                ParseError, infile, cur_index)
+                            continue
+                #
+                key = self._unquote(key)
+                if key in this_section:
+                    self._handle_error(
+                        'Duplicate keyword name at line %s.',
+                        DuplicateError, infile, cur_index)
+                    continue
+                # add the key.
+                # we set unrepr because if we have got this far we will never
+                # be creating a new section
+                this_section.__setitem__(key, value, unrepr=True)
+                this_section.inline_comments[key] = comment
+                this_section.comments[key] = comment_list
+                continue
+        #
+        if self.indent_type is None:
+            # no indentation used, set the type accordingly
+            self.indent_type = ''
+
+        # preserve the final comment
+        if not self and not self.initial_comment:
+            self.initial_comment = comment_list
+        elif not reset_comment:
+            self.final_comment = comment_list
+        self.list_values = temp_list_values
+
+
+    def _match_depth(self, sect, depth):
+        """
+        Given a section and a depth level, walk back through the sections
+        parents to see if the depth level matches a previous section.
+        
+        Return a reference to the right section,
+        or raise a SyntaxError.
+        """
+        while depth < sect.depth:
+            if sect is sect.parent:
+                # we've reached the top level already
+                raise SyntaxError()
+            sect = sect.parent
+        if sect.depth == depth:
+            return sect
+        # shouldn't get here
+        raise SyntaxError()
+
+
+    def _handle_error(self, text, ErrorClass, infile, cur_index):
+        """
+        Handle an error according to the error settings.
+        
+        Either raise the error or store it.
+        The error will have occured at ``cur_index``
+        """
+        line = infile[cur_index]
+        cur_index += 1
+        message = text % cur_index
+        error = ErrorClass(message, cur_index, line)
+        if self.raise_errors:
+            # raise the error - parsing stops here
+            raise error
+        # store the error
+        # reraise when parsing has finished
+        self._errors.append(error)
+
+
+    def _unquote(self, value):
+        """Return an unquoted version of a value"""
+        if not value:
+            # should only happen during parsing of lists
+            raise SyntaxError
+        if (value[0] == value[-1]) and (value[0] in ('"', "'")):
+            value = value[1:-1]
+        return value
+
+
+    def _quote(self, value, multiline=True):
+        """
+        Return a safely quoted version of a value.
+        
+        Raise a ConfigObjError if the value cannot be safely quoted.
+        If multiline is ``True`` (default) then use triple quotes
+        if necessary.
+        
+        * Don't quote values that don't need it.
+        * Recursively quote members of a list and return a comma joined list.
+        * Multiline is ``False`` for lists.
+        * Obey list syntax for empty and single member lists.
+        
+        If ``list_values=False`` then the value is only quoted if it contains
+        a ``\\n`` (is multiline) or '#'.
+        
+        If ``write_empty_values`` is set, and the value is an empty string, it
+        won't be quoted.
+        """
+        if multiline and self.write_empty_values and value == '':
+            # Only if multiline is set, so that it is used for values not
+            # keys, and not values that are part of a list
+            return ''
+        
+        if multiline and isinstance(value, (list, tuple)):
+            if not value:
+                return ','
+            elif len(value) == 1:
+                return self._quote(value[0], multiline=False) + ','
+            return ', '.join([self._quote(val, multiline=False)
+                for val in value])
+        if not isinstance(value, basestring):
+            if self.stringify:
+                value = str(value)
+            else:
+                raise TypeError('Value "%s" is not a string.' % value)
+
+        if not value:
+            return '""'
+        
+        no_lists_no_quotes = not self.list_values and '\n' not in value and '#' not in value
+        need_triple = multiline and ((("'" in value) and ('"' in value)) or ('\n' in value ))
+        hash_triple_quote = multiline and not need_triple and ("'" in value) and ('"' in value) and ('#' in value)
+        check_for_single = (no_lists_no_quotes or not need_triple) and not hash_triple_quote
+        
+        if check_for_single:
+            if not self.list_values:
+                # we don't quote if ``list_values=False``
+                quot = noquot
+            # for normal values either single or double quotes will do
+            elif '\n' in value:
+                # will only happen if multiline is off - e.g. '\n' in key
+                raise ConfigObjError('Value "%s" cannot be safely quoted.' % value)
+            elif ((value[0] not in wspace_plus) and
+                    (value[-1] not in wspace_plus) and
+                    (',' not in value)):
+                quot = noquot
+            else:
+                quot = self._get_single_quote(value)
+        else:
+            # if value has '\n' or "'" *and* '"', it will need triple quotes
+            quot = self._get_triple_quote(value)
+        
+        if quot == noquot and '#' in value and self.list_values:
+            quot = self._get_single_quote(value)
+                
+        return quot % value
+    
+    
+    def _get_single_quote(self, value):
+        if ("'" in value) and ('"' in value):
+            raise ConfigObjError('Value "%s" cannot be safely quoted.' % value)
+        elif '"' in value:
+            quot = squot
+        else:
+            quot = dquot
+        return quot
+    
+    
+    def _get_triple_quote(self, value):
+        if (value.find('"""') != -1) and (value.find("'''") != -1):
+            raise ConfigObjError('Value "%s" cannot be safely quoted.' % value)
+        if value.find('"""') == -1:
+            quot = tdquot
+        else:
+            quot = tsquot 
+        return quot
+
+
+    def _handle_value(self, value):
+        """
+        Given a value string, unquote, remove comment,
+        handle lists. (including empty and single member lists)
+        """
+        if self._inspec:
+            # Parsing a configspec so don't handle comments
+            return (value, '')
+        # do we look for lists in values ?
+        if not self.list_values:
+            mat = self._nolistvalue.match(value)
+            if mat is None:
+                raise SyntaxError()
+            # NOTE: we don't unquote here
+            return mat.groups()
+        #
+        mat = self._valueexp.match(value)
+        if mat is None:
+            # the value is badly constructed, probably badly quoted,
+            # or an invalid list
+            raise SyntaxError()
+        (list_values, single, empty_list, comment) = mat.groups()
+        if (list_values == '') and (single is None):
+            # change this if you want to accept empty values
+            raise SyntaxError()
+        # NOTE: note there is no error handling from here if the regex
+        # is wrong: then incorrect values will slip through
+        if empty_list is not None:
+            # the single comma - meaning an empty list
+            return ([], comment)
+        if single is not None:
+            # handle empty values
+            if list_values and not single:
+                # FIXME: the '' is a workaround because our regex now matches
+                #   '' at the end of a list if it has a trailing comma
+                single = None
+            else:
+                single = single or '""'
+                single = self._unquote(single)
+        if list_values == '':
+            # not a list value
+            return (single, comment)
+        the_list = self._listvalueexp.findall(list_values)
+        the_list = [self._unquote(val) for val in the_list]
+        if single is not None:
+            the_list += [single]
+        return (the_list, comment)
+
+
+    def _multiline(self, value, infile, cur_index, maxline):
+        """Extract the value, where we are in a multiline situation."""
+        quot = value[:3]
+        newvalue = value[3:]
+        single_line = self._triple_quote[quot][0]
+        multi_line = self._triple_quote[quot][1]
+        mat = single_line.match(value)
+        if mat is not None:
+            retval = list(mat.groups())
+            retval.append(cur_index)
+            return retval
+        elif newvalue.find(quot) != -1:
+            # somehow the triple quote is missing
+            raise SyntaxError()
+        #
+        while cur_index < maxline:
+            cur_index += 1
+            newvalue += '\n'
+            line = infile[cur_index]
+            if line.find(quot) == -1:
+                newvalue += line
+            else:
+                # end of multiline, process it
+                break
+        else:
+            # we've got to the end of the config, oops...
+            raise SyntaxError()
+        mat = multi_line.match(line)
+        if mat is None:
+            # a badly formed line
+            raise SyntaxError()
+        (value, comment) = mat.groups()
+        return (newvalue + value, comment, cur_index)
+
+
+    def _handle_configspec(self, configspec):
+        """Parse the configspec."""
+        # FIXME: Should we check that the configspec was created with the 
+        #        correct settings ? (i.e. ``list_values=False``)
+        if not isinstance(configspec, ConfigObj):
+            try:
+                configspec = ConfigObj(configspec,
+                                       raise_errors=True,
+                                       file_error=True,
+                                       _inspec=True)
+            except ConfigObjError, e:
+                # FIXME: Should these errors have a reference
+                #        to the already parsed ConfigObj ?
+                raise ConfigspecError('Parsing configspec failed: %s' % e)
+            except IOError, e:
+                raise IOError('Reading configspec failed: %s' % e)
+        
+        self.configspec = configspec
+            
+
+        
+    def _set_configspec(self, section, copy):
+        """
+        Called by validate. Handles setting the configspec on subsections
+        including sections to be validated by __many__
+        """
+        configspec = section.configspec
+        many = configspec.get('__many__')
+        if isinstance(many, dict):
+            for entry in section.sections:
+                if entry not in configspec:
+                    section[entry].configspec = many
+                    
+        for entry in configspec.sections:
+            if entry == '__many__':
+                continue
+            if entry not in section:
+                section[entry] = {}
+                section[entry]._created = True
+                if copy:
+                    # copy comments
+                    section.comments[entry] = configspec.comments.get(entry, [])
+                    section.inline_comments[entry] = configspec.inline_comments.get(entry, '')
+                
+            # Could be a scalar when we expect a section
+            if isinstance(section[entry], Section):
+                section[entry].configspec = configspec[entry]
+                        
+
+    def _write_line(self, indent_string, entry, this_entry, comment):
+        """Write an individual line, for the write method"""
+        # NOTE: the calls to self._quote here handles non-StringType values.
+        if not self.unrepr:
+            val = self._decode_element(self._quote(this_entry))
+        else:
+            val = repr(this_entry)
+        return '%s%s%s%s%s' % (indent_string,
+                               self._decode_element(self._quote(entry, multiline=False)),
+                               self._a_to_u(' = '),
+                               val,
+                               self._decode_element(comment))
+
+
+    def _write_marker(self, indent_string, depth, entry, comment):
+        """Write a section marker line"""
+        return '%s%s%s%s%s' % (indent_string,
+                               self._a_to_u('[' * depth),
+                               self._quote(self._decode_element(entry), multiline=False),
+                               self._a_to_u(']' * depth),
+                               self._decode_element(comment))
+
+
+    def _handle_comment(self, comment):
+        """Deal with a comment."""
+        if not comment:
+            return ''
+        start = self.indent_type
+        if not comment.startswith('#'):
+            start += self._a_to_u(' # ')
+        return (start + comment)
+
+
+    # Public methods
+
+    def write(self, outfile=None, section=None):
+        """
+        Write the current ConfigObj as a file
+        
+        tekNico: FIXME: use StringIO instead of real files
+        
+        >>> filename = a.filename
+        >>> a.filename = 'test.ini'
+        >>> a.write()
+        >>> a.filename = filename
+        >>> a == ConfigObj('test.ini', raise_errors=True)
+        1
+        >>> import os
+        >>> os.remove('test.ini')
+        """
+        if self.indent_type is None:
+            # this can be true if initialised from a dictionary
+            self.indent_type = DEFAULT_INDENT_TYPE
+            
+        out = []
+        cs = self._a_to_u('#')
+        csp = self._a_to_u('# ')
+        if section is None:
+            int_val = self.interpolation
+            self.interpolation = False
+            section = self
+            for line in self.initial_comment:
+                line = self._decode_element(line)
+                stripped_line = line.strip()
+                if stripped_line and not stripped_line.startswith(cs):
+                    line = csp + line
+                out.append(line)
+                
+        indent_string = self.indent_type * section.depth
+        for entry in (section.scalars + section.sections):
+            if entry in section.defaults:
+                # don't write out default values
+                continue
+            for comment_line in section.comments[entry]:
+                comment_line = self._decode_element(comment_line.lstrip())
+                if comment_line and not comment_line.startswith(cs):
+                    comment_line = csp + comment_line
+                out.append(indent_string + comment_line)
+            this_entry = section[entry]
+            comment = self._handle_comment(section.inline_comments[entry])
+            
+            if isinstance(this_entry, dict):
+                # a section
+                out.append(self._write_marker(
+                    indent_string,
+                    this_entry.depth,
+                    entry,
+                    comment))
+                out.extend(self.write(section=this_entry))
+            else:
+                out.append(self._write_line(
+                    indent_string,
+                    entry,
+                    this_entry,
+                    comment))
+                
+        if section is self:
+            for line in self.final_comment:
+                line = self._decode_element(line)
+                stripped_line = line.strip()
+                if stripped_line and not stripped_line.startswith(cs):
+                    line = csp + line
+                out.append(line)
+            self.interpolation = int_val
+            
+        if section is not self:
+            return out
+        
+        if (self.filename is None) and (outfile is None):
+            # output a list of lines
+            # might need to encode
+            # NOTE: This will *screw* UTF16, each line will start with the BOM
+            if self.encoding:
+                out = [l.encode(self.encoding) for l in out]
+            if (self.BOM and ((self.encoding is None) or
+                (BOM_LIST.get(self.encoding.lower()) == 'utf_8'))):
+                # Add the UTF8 BOM
+                if not out:
+                    out.append('')
+                out[0] = BOM_UTF8 + out[0]
+            return out
+        
+        # Turn the list to a string, joined with correct newlines
+        newline = self.newlines or os.linesep
+        if (getattr(outfile, 'mode', None) is not None and outfile.mode == 'w'
+            and sys.platform == 'win32' and newline == '\r\n'):
+            # Windows specific hack to avoid writing '\r\r\n'
+            newline = '\n'
+        output = self._a_to_u(newline).join(out)
+        if self.encoding:
+            output = output.encode(self.encoding)
+        if self.BOM and ((self.encoding is None) or match_utf8(self.encoding)):
+            # Add the UTF8 BOM
+            output = BOM_UTF8 + output
+            
+        if not output.endswith(newline):
+            output += newline
+        if outfile is not None:
+            outfile.write(output)
+        else:
+            h = open(self.filename, 'wb')
+            h.write(output)
+            h.close()
+
+
+    def validate(self, validator, preserve_errors=False, copy=False,
+                 section=None):
+        """
+        Test the ConfigObj against a configspec.
+        
+        It uses the ``validator`` object from *validate.py*.
+        
+        To run ``validate`` on the current ConfigObj, call: ::
+        
+            test = config.validate(validator)
+        
+        (Normally having previously passed in the configspec when the ConfigObj
+        was created - you can dynamically assign a dictionary of checks to the
+        ``configspec`` attribute of a section though).
+        
+        It returns ``True`` if everything passes, or a dictionary of
+        pass/fails (True/False). If every member of a subsection passes, it
+        will just have the value ``True``. (It also returns ``False`` if all
+        members fail).
+        
+        In addition, it converts the values from strings to their native
+        types if their checks pass (and ``stringify`` is set).
+        
+        If ``preserve_errors`` is ``True`` (``False`` is default) then instead
+        of a marking a fail with a ``False``, it will preserve the actual
+        exception object. This can contain info about the reason for failure.
+        For example the ``VdtValueTooSmallError`` indicates that the value
+        supplied was too small. If a value (or section) is missing it will
+        still be marked as ``False``.
+        
+        You must have the validate module to use ``preserve_errors=True``.
+        
+        You can then use the ``flatten_errors`` function to turn your nested
+        results dictionary into a flattened list of failures - useful for
+        displaying meaningful error messages.
+        """
+        if section is None:
+            if self.configspec is None:
+                raise ValueError('No configspec supplied.')
+            if preserve_errors:
+                # We do this once to remove a top level dependency on the validate module
+                # Which makes importing configobj faster
+                from validate import VdtMissingValue
+                self._vdtMissingValue = VdtMissingValue
+                
+            section = self
+
+            if copy:
+                section.initial_comment = section.configspec.initial_comment
+                section.final_comment = section.configspec.final_comment
+                section.encoding = section.configspec.encoding
+                section.BOM = section.configspec.BOM
+                section.newlines = section.configspec.newlines
+                section.indent_type = section.configspec.indent_type
+            
+        #
+        # section.default_values.clear() #??
+        configspec = section.configspec
+        self._set_configspec(section, copy)
+
+        
+        def validate_entry(entry, spec, val, missing, ret_true, ret_false):
+            section.default_values.pop(entry, None)
+                
+            try:
+                section.default_values[entry] = validator.get_default_value(configspec[entry])
+            except (KeyError, AttributeError, validator.baseErrorClass):
+                # No default, bad default or validator has no 'get_default_value'
+                # (e.g. SimpleVal)
+                pass
+            
+            try:
+                check = validator.check(spec,
+                                        val,
+                                        missing=missing
+                                        )
+            except validator.baseErrorClass, e:
+                if not preserve_errors or isinstance(e, self._vdtMissingValue):
+                    out[entry] = False
+                else:
+                    # preserve the error
+                    out[entry] = e
+                    ret_false = False
+                ret_true = False
+            else:
+                ret_false = False
+                out[entry] = True
+                if self.stringify or missing:
+                    # if we are doing type conversion
+                    # or the value is a supplied default
+                    if not self.stringify:
+                        if isinstance(check, (list, tuple)):
+                            # preserve lists
+                            check = [self._str(item) for item in check]
+                        elif missing and check is None:
+                            # convert the None from a default to a ''
+                            check = ''
+                        else:
+                            check = self._str(check)
+                    if (check != val) or missing:
+                        section[entry] = check
+                if not copy and missing and entry not in section.defaults:
+                    section.defaults.append(entry)
+            return ret_true, ret_false
+        
+        #
+        out = {}
+        ret_true = True
+        ret_false = True
+        
+        unvalidated = [k for k in section.scalars if k not in configspec]
+        incorrect_sections = [k for k in configspec.sections if k in section.scalars]        
+        incorrect_scalars = [k for k in configspec.scalars if k in section.sections]
+        
+        for entry in configspec.scalars:
+            if entry in ('__many__', '___many___'):
+                # reserved names
+                continue
+            if (not entry in section.scalars) or (entry in section.defaults):
+                # missing entries
+                # or entries from defaults
+                missing = True
+                val = None
+                if copy and entry not in section.scalars:
+                    # copy comments
+                    section.comments[entry] = (
+                        configspec.comments.get(entry, []))
+                    section.inline_comments[entry] = (
+                        configspec.inline_comments.get(entry, ''))
+                #
+            else:
+                missing = False
+                val = section[entry]
+            
+            ret_true, ret_false = validate_entry(entry, configspec[entry], val, 
+                                                 missing, ret_true, ret_false)
+        
+        many = None
+        if '__many__' in configspec.scalars:
+            many = configspec['__many__']
+        elif '___many___' in configspec.scalars:
+            many = configspec['___many___']
+        
+        if many is not None:
+            for entry in unvalidated:
+                val = section[entry]
+                ret_true, ret_false = validate_entry(entry, many, val, False,
+                                                     ret_true, ret_false)
+            unvalidated = []
+
+        for entry in incorrect_scalars:
+            ret_true = False
+            if not preserve_errors:
+                out[entry] = False
+            else:
+                ret_false = False
+                msg = 'Value %r was provided as a section' % entry
+                out[entry] = validator.baseErrorClass(msg)
+        for entry in incorrect_sections:
+            ret_true = False
+            if not preserve_errors:
+                out[entry] = False
+            else:
+                ret_false = False
+                msg = 'Section %r was provided as a single value' % entry
+                out[entry] = validator.baseErrorClass(msg)
+                
+        # Missing sections will have been created as empty ones when the
+        # configspec was read.
+        for entry in section.sections:
+            # FIXME: this means DEFAULT is not copied in copy mode
+            if section is self and entry == 'DEFAULT':
+                continue
+            if section[entry].configspec is None:
+                unvalidated.append(entry)
+                continue
+            if copy:
+                section.comments[entry] = configspec.comments.get(entry, [])
+                section.inline_comments[entry] = configspec.inline_comments.get(entry, '')
+            check = self.validate(validator, preserve_errors=preserve_errors, copy=copy, section=section[entry])
+            out[entry] = check
+            if check == False:
+                ret_true = False
+            elif check == True:
+                ret_false = False
+            else:
+                ret_true = False
+        
+        section.extra_values = unvalidated
+        if preserve_errors and not section._created:
+            # If the section wasn't created (i.e. it wasn't missing)
+            # then we can't return False, we need to preserve errors
+            ret_false = False
+        #
+        if ret_false and preserve_errors and out:
+            # If we are preserving errors, but all
+            # the failures are from missing sections / values
+            # then we can return False. Otherwise there is a
+            # real failure that we need to preserve.
+            ret_false = not any(out.values())
+        if ret_true:
+            return True
+        elif ret_false:
+            return False
+        return out
+
+
+    def reset(self):
+        """Clear ConfigObj instance and restore to 'freshly created' state."""
+        self.clear()
+        self._initialise()
+        # FIXME: Should be done by '_initialise', but ConfigObj constructor (and reload)
+        #        requires an empty dictionary
+        self.configspec = None
+        # Just to be sure ;-)
+        self._original_configspec = None
+        
+        
+    def reload(self):
+        """
+        Reload a ConfigObj from file.
+        
+        This method raises a ``ReloadError`` if the ConfigObj doesn't have
+        a filename attribute pointing to a file.
+        """
+        if not isinstance(self.filename, basestring):
+            raise ReloadError()
+
+        filename = self.filename
+        current_options = {}
+        for entry in OPTION_DEFAULTS:
+            if entry == 'configspec':
+                continue
+            current_options[entry] = getattr(self, entry)
+            
+        configspec = self._original_configspec
+        current_options['configspec'] = configspec
+            
+        self.clear()
+        self._initialise(current_options)
+        self._load(filename, configspec)
+        
+
+
+class SimpleVal(object):
+    """
+    A simple validator.
+    Can be used to check that all members expected are present.
+    
+    To use it, provide a configspec with all your members in (the value given
+    will be ignored). Pass an instance of ``SimpleVal`` to the ``validate``
+    method of your ``ConfigObj``. ``validate`` will return ``True`` if all
+    members are present, or a dictionary with True/False meaning
+    present/missing. (Whole missing sections will be replaced with ``False``)
+    """
+    
+    def __init__(self):
+        self.baseErrorClass = ConfigObjError
+    
+    def check(self, check, member, missing=False):
+        """A dummy check method, always returns the value unchanged."""
+        if missing:
+            raise self.baseErrorClass()
+        return member
+
+
+def flatten_errors(cfg, res, levels=None, results=None):
+    """
+    An example function that will turn a nested dictionary of results
+    (as returned by ``ConfigObj.validate``) into a flat list.
+    
+    ``cfg`` is the ConfigObj instance being checked, ``res`` is the results
+    dictionary returned by ``validate``.
+    
+    (This is a recursive function, so you shouldn't use the ``levels`` or
+    ``results`` arguments - they are used by the function.)
+    
+    Returns a list of keys that failed. Each member of the list is a tuple::
+    
+        ([list of sections...], key, result)
+    
+    If ``validate`` was called with ``preserve_errors=False`` (the default)
+    then ``result`` will always be ``False``.
+
+    *list of sections* is a flattened list of sections that the key was found
+    in.
+    
+    If the section was missing (or a section was expected and a scalar provided
+    - or vice-versa) then key will be ``None``.
+    
+    If the value (or section) was missing then ``result`` will be ``False``.
+    
+    If ``validate`` was called with ``preserve_errors=True`` and a value
+    was present, but failed the check, then ``result`` will be the exception
+    object returned. You can use this as a string that describes the failure.
+    
+    For example *The value "3" is of the wrong type*.
+    """
+    if levels is None:
+        # first time called
+        levels = []
+        results = []
+    if res == True:
+        return results
+    if res == False or isinstance(res, Exception):
+        results.append((levels[:], None, res))
+        if levels:
+            levels.pop()
+        return results
+    for (key, val) in res.items():
+        if val == True:
+            continue
+        if isinstance(cfg.get(key), dict):
+            # Go down one level
+            levels.append(key)
+            flatten_errors(cfg[key], val, levels, results)
+            continue
+        results.append((levels[:], key, val))
+    #
+    # Go up one level
+    if levels:
+        levels.pop()
+    #
+    return results
+
+
+def get_extra_values(conf, _prepend=()):
+    """
+    Find all the values and sections not in the configspec from a validated
+    ConfigObj.
+    
+    ``get_extra_values`` returns a list of tuples where each tuple represents
+    either an extra section, or an extra value.
+    
+    The tuples contain two values, a tuple representing the section the value 
+    is in and the name of the extra values. For extra values in the top level
+    section the first member will be an empty tuple. For values in the 'foo'
+    section the first member will be ``('foo',)``. For members in the 'bar'
+    subsection of the 'foo' section the first member will be ``('foo', 'bar')``.
+    
+    NOTE: If you call ``get_extra_values`` on a ConfigObj instance that hasn't
+    been validated it will return an empty list.
+    """
+    out = []
+    
+    out.extend([(_prepend, name) for name in conf.extra_values])
+    for name in conf.sections:
+        if name not in conf.extra_values:
+            out.extend(get_extra_values(conf[name], _prepend + (name,)))
+    return out
+
+
+"""*A programming language is a medium of expression.* - Paul Graham"""
diff --git a/data/css/style.css b/data/css/style.css
new file mode 100644
index 00000000..81d9832e
--- /dev/null
+++ b/data/css/style.css
@@ -0,0 +1,114 @@
+body{
+	font-family:"Lucida Grande", "Lucida Sans Unicode", Verdana, Arial,
+	Helvetica, sans-serif;
+	font-size:16px;
+	background-color: #ebf4fb;
+	padding: 5px;
+	}
+	
+h1{
+	font-family:"Lucida Grande", "Lucida Sans Unicode", Verdana, Arial,
+	Helvetica, sans-serif;
+	size:30px;
+	color: #8B8989;
+	}
+.container{
+	width: 95%;
+	}	
+.header{
+	background-color: #EEB4B4;
+	width: 80%;
+	}
+.config{
+	font-size:14px;
+	margin-left: 30px;
+	}
+.configtable{
+	background-color: #eeeeee;
+	width: 95%;
+	padding: 15px;
+	line-height: 12px;
+	-moz-border-radius: 10px;
+	border-radius: 10px;
+	}
+.logo{
+	font-family:"Lucida Grande", "Lucida Sans Unicode", Verdana, Arial,
+	Helvetica, sans-serif;
+	font-size:20px;
+	color: #8B8989;
+	margin-left: 30px;
+	margin-top: 0px;
+	}
+.search{
+	margin-top: -40px;
+	margin-right: 30px;
+	}
+.data{
+	background-color: #ebf4fb;
+	font-size:24px;
+	}
+.datanil{
+	background-color: #ebf4fb;
+	font-size:36px;
+	text-align: center;
+	position: relative;
+	top:150px;
+	}
+.table{
+	padding: 10px;
+	font-size:24px;
+	background-color: #ffffff;
+	width: 95%;
+	margin-top: 25px;
+	margin-left: auto;
+	margin-right: 0px;
+	-moz-border-radius: 20px;
+	border-radius: 20px;
+	}
+.nav{
+	padding: 2px;
+	font-size:20px;
+	color: grey;
+	background-color: #bbbbbb;
+	width: 95%;
+	text-align: center;
+	margin-left: auto;
+	margin-right: 10px;
+	-moz-border-radius: 20px;
+	border-radius: 20px;
+	word-spacing: 18px;
+	}
+.center{
+	text-align: center;
+	font-size: 28px;
+	}
+.smalltext{
+	font-size: 11px;
+	}
+a:link {
+	color: #5E2612; 
+  	text-decoration: none; 
+  	}
+a:visited {
+  	color: #5E2612; 
+	text-decoration: none; 
+	}
+a:hover { /*this effect is not shown in NN4.xx*/
+  	color: #999999; 
+	text-decoration: underline;
+  	}
+a:active {/*colour in NN4.xx is red*/ 
+  	color: #5E2612; 
+  	text-decoration: underline; 
+	}
+a.external {
+	color: blue;
+	font-size:12px;
+	}
+a.blue {
+	color: blue;
+	}
+a.externalred {
+	color: red;
+	font-size:12px;
+	}
\ No newline at end of file
diff --git a/data/css/view.css b/data/css/view.css
new file mode 100755
index 00000000..86c6efd4
--- /dev/null
+++ b/data/css/view.css
@@ -0,0 +1,827 @@
+#form_container
+{
+	background:#fff;
+	border:1px solid #ccc;
+	margin:0 auto;
+	text-align:left;
+	width:640px;
+}
+
+#top
+{
+	display:block;
+	height:10px;
+	margin:10px auto 0;
+	width:650px;
+}
+
+#footer
+{
+	width:640px;
+	clear:both;
+	color:#999999;
+	text-align:center;
+	width:640px;
+	padding-bottom: 15px;
+	font-size: 85%;
+}
+
+#footer a{
+	color:#999999;
+	text-decoration: none;
+	border-bottom: 1px dotted #999999;
+}
+
+#bottom
+{
+	display:block;
+	height:10px;
+	margin:0 auto;
+	width:650px;
+}
+
+form.appnitro
+{
+	margin:20px 20px 0;
+	padding:0 0 20px;
+}
+
+/**** Form Section ****/
+.appnitro
+{
+	font-family:Lucida Grande, Tahoma, Arial, Verdana, sans-serif;
+	font-size:small;
+}
+
+.appnitro li
+{
+	width:61%;
+}
+
+form ul
+{
+	font-size:100%;
+	list-style-type:none;
+	margin:0;
+	padding:0;
+	width:100%;
+}
+
+form li
+{
+	display:block;
+	margin:0;
+	padding:4px 5px 2px 9px;
+	position:relative;
+}
+
+form li:after
+{
+	clear:both;
+	content:".";
+	display:block;
+	height:0;
+	visibility:hidden;
+}
+
+.buttons:after
+{
+	clear:both;
+	content:".";
+	display:block;
+	height:0;
+	visibility:hidden;
+}
+
+.buttons
+{
+	clear:both;
+	display:block;
+	margin-top:10px;
+}
+
+* html form li
+{
+	height:1%;
+}
+
+* html .buttons
+{
+	height:1%;
+}
+
+* html form li div
+{
+	display:inline-block;
+}
+
+form li div
+{
+	color:#444;
+	margin:0 4px 0 0;
+	padding:0 0 8px;
+}
+
+form li span
+{
+	color:#444;
+	float:left;
+	margin:0 4px 0 0;
+	padding:0 0 8px;
+}
+
+form li div.left
+{
+	display:inline;
+	float:left;
+	width:48%;
+}
+
+form li div.right
+{
+	display:inline;
+	float:right;
+	width:48%;
+}
+
+form li div.left .medium
+{
+	width:100%;
+}
+
+form li div.right .medium
+{
+	width:100%;
+}
+
+.clear
+{
+	clear:both;
+}
+
+form li div label
+{
+	clear:both;
+	color:#444;
+	display:block;
+	font-size:9px;
+	line-height:9px;
+	margin:0;
+	padding-top:3px;
+}
+
+form li span label
+{
+	clear:both;
+	color:#444;
+	display:block;
+	font-size:9px;
+	line-height:9px;
+	margin:0;
+	padding-top:3px;
+}
+
+form li .datepicker
+{
+	cursor:pointer !important;
+	float:left;
+	height:16px;
+	margin:.1em 5px 0 0;
+	padding:0;
+	width:16px;
+}
+
+.form_description
+{
+	border-bottom:1px dotted #ccc;
+	clear:both;
+	display:inline-block;
+	margin:0 0 1em;
+}
+
+.form_description[class]
+{
+	display:block;
+}
+
+.form_description h2
+{
+	clear:left;
+	font-size:160%;
+	font-weight:400;
+	margin:0 0 3px;
+}
+
+.form_description p
+{
+	font-size:95%;
+	line-height:130%;
+	margin:0 0 12px;
+}
+
+form hr
+{
+	display:none;
+}
+
+form li.section_break
+{
+	border-top:1px dotted #ccc;
+	margin-top:9px;
+	padding-bottom:0;
+	padding-left:9px;
+	padding-top:13px;
+	width:97% !important;
+}
+
+form ul li.first
+{
+	border-top:none !important;
+	margin-top:0 !important;
+	padding-top:0 !important;
+}
+
+form .section_break h3
+{
+	font-size:110%;
+	font-weight:400;
+	line-height:130%;
+	margin:0 0 2px;
+}
+
+form .section_break p
+{
+	font-size:85%;
+
+	margin:0 0 10px;
+}
+
+/**** Buttons ****/
+input.button_text
+{
+	overflow:visible;
+	padding:0 7px;
+	width:auto;
+}
+
+.buttons input
+{
+	font-size:120%;
+	margin-right:5px;
+}
+
+/**** Inputs and Labels ****/
+label.description
+{
+	border:none;
+	color:#222;
+	display:block;
+	font-size:95%;
+	font-weight:700;
+	line-height:150%;
+	padding:0 0 1px;
+}
+
+span.symbol
+{
+	font-size:115%;
+	line-height:130%;
+}
+
+input.text
+{
+	background:#fff url(../../../images/shadow.gif) repeat-x top;
+	border-bottom:1px solid #ddd;
+	border-left:1px solid #c3c3c3;
+	border-right:1px solid #c3c3c3;
+	border-top:1px solid #7c7c7c;
+	color:#333;
+	font-size:100%;
+	margin:0;
+	padding:2px 0;
+}
+
+input.file
+{
+	color:#333;
+	font-size:100%;
+	margin:0;
+	padding:2px 0;
+}
+
+textarea.textarea
+{
+	background:#fff url(../../../images/shadow.gif) repeat-x top;
+	border-bottom:1px solid #ddd;
+	border-left:1px solid #c3c3c3;
+	border-right:1px solid #c3c3c3;
+	border-top:1px solid #7c7c7c;
+	color:#333;
+	font-family:"Lucida Grande", Tahoma, Arial, Verdana, sans-serif;
+	font-size:100%;
+	margin:0;
+	width:99%;
+}
+
+select.select
+{
+	color:#333;
+	font-size:100%;
+	margin:1px 0;
+	padding:1px 0 0;
+	background:#fff url(../../../images/shadow.gif) repeat-x top;
+	border-bottom:1px solid #ddd;
+	border-left:1px solid #c3c3c3;
+	border-right:1px solid #c3c3c3;
+	border-top:1px solid #7c7c7c;
+}
+
+
+input.currency
+{
+	text-align:right;
+}
+
+input.checkbox
+{
+	display:block;
+	height:13px;
+	line-height:1.4em;
+	margin:6px 0 0 3px;
+	width:13px;
+}
+
+input.radio
+{
+	display:block;
+	height:13px;
+	line-height:1.4em;
+	margin:6px 0 0 3px;
+	width:13px;
+}
+
+label.choice
+{
+	color:#444;
+	display:block;
+	font-size:100%;
+	line-height:1.4em;
+	margin:-1.55em 0 0 25px;
+	padding:4px 0 5px;
+	width:90%;
+}
+
+select.select[class]
+{
+	margin:0;
+	padding:1px 0;
+}
+
+*:first-child+html select.select[class]
+{
+	margin:1px 0;
+}
+
+.safari select.select
+{
+	font-size:120% !important;
+	margin-bottom:1px;
+}
+
+input.small
+{
+	width:25%;
+}
+
+select.small
+{
+	width:25%;
+}
+
+input.medium
+{
+	width:50%;
+}
+
+select.medium
+{
+	width:50%;
+}
+
+input.large
+{
+	width:99%;
+}
+
+select.large
+{
+	width:100%;
+}
+
+textarea.small
+{
+	height:5.5em;
+}
+
+textarea.medium
+{
+	height:10em;
+}
+
+textarea.large
+{
+	height:20em;
+}
+
+/**** Errors ****/
+#error_message
+{
+	background:#fff;
+	border:1px dotted red;
+	margin-bottom:1em;
+	padding-left:0;
+	padding-right:0;
+	padding-top:4px;
+	text-align:center;
+	width:99%;
+}
+
+#error_message_title
+{
+	color:#DF0000;
+	font-size:125%;
+	margin:7px 0 5px;
+	padding:0;
+}
+
+#error_message_desc
+{
+	color:#000;
+	font-size:100%;
+	margin:0 0 .8em;
+}
+
+#error_message_desc strong
+{
+	background-color:#FFDFDF;
+	color:red;
+	padding:2px 3px;
+}
+
+form li.error
+{
+	background-color:#FFDFDF !important;
+	border-bottom:1px solid #EACBCC;
+	border-right:1px solid #EACBCC;
+	margin:3px 0;
+}
+
+form li.error label
+{
+	color:#DF0000 !important;
+}
+
+form p.error
+{
+	clear:both;
+	color:red;
+	font-size:10px;
+	font-weight:700;
+	margin:0 0 5px;
+}
+
+form .required
+{
+	color:red;
+	float:none;
+	font-weight:700;
+}
+
+/**** Guidelines and Error Highlight ****/
+form li.highlighted
+{
+	background-color:#fff7c0;
+}
+
+form .guidelines
+{
+	background:#f5f5f5;
+	border:1px solid #e6e6e6;
+	color:#444;
+	font-size:80%;
+	left:100%;
+	line-height:130%;
+	margin:0 0 0 8px;
+	padding:8px 10px 9px;
+	position:absolute;
+	top:0;
+	visibility:hidden;
+	width:42%;
+	z-index:1000;
+}
+
+form .guidelines small
+{
+	font-size:105%;
+}
+
+form li.highlighted .guidelines
+{
+	visibility:visible;
+}
+
+form li:hover .guidelines
+{
+	visibility:visible;
+}
+
+.no_guidelines .guidelines
+{
+	display:none !important;
+}
+
+.no_guidelines form li
+{
+	width:97%;
+}
+
+.no_guidelines li.section
+{
+	padding-left:9px;
+}
+
+/*** Success Message ****/
+.form_success 
+{
+	clear: both;
+	margin: 0;
+	padding: 90px 0pt 100px;
+	text-align: center
+}
+
+.form_success h2 {
+    clear:left;
+    font-size:160%;
+    font-weight:normal;
+    margin:0pt 0pt 3px;
+}
+
+/*** Password ****/
+ul.password{
+    margin-top:60px;
+    margin-bottom: 60px;
+    text-align: center;
+}
+.password h2{
+    color:#DF0000;
+    font-weight:bold;
+    margin:0pt auto 10px;
+}
+
+.password input.text {
+   font-size:170% !important;
+   width:380px;
+   text-align: center;
+}
+.password label{
+   display:block;
+   font-size:120% !important;
+   padding-top:10px;
+   font-weight:bold;
+}
+
+#li_captcha{
+   padding-left: 5px;
+}
+
+
+#li_captcha span{
+	float:none;
+}
+
+/** Embedded Form **/
+
+.embed #form_container{
+	border: none;
+}
+
+.embed #top, .embed #bottom, .embed h1{
+	display: none;
+}
+
+.embed #form_container{
+	width: 100%;
+}
+
+.embed #footer{
+	text-align: left;
+	padding-left: 10px;
+	width: 99%;
+}
+
+.embed #footer.success{
+	text-align: center;
+}
+
+.embed form.appnitro
+{
+	margin:0px 0px 0;
+	
+}
+
+
+
+/*** Calendar **********************/
+div.calendar { position: relative; }
+
+.calendar table {
+cursor:pointer;
+border:1px solid #ccc;
+font-size: 11px;
+color: #000;
+background: #fff;
+font-family:"Lucida Grande", Tahoma, Arial, Verdana, sans-serif;
+}
+
+.calendar .button { 
+text-align: center;    
+padding: 2px;          
+}
+
+.calendar .nav {
+background:#f5f5f5;
+}
+
+.calendar thead .title { 
+font-weight: bold;      
+text-align: center;
+background: #dedede;
+color: #000;
+padding: 2px 0 3px 0;
+}
+
+.calendar thead .headrow { 
+background: #f5f5f5;
+color: #444;
+font-weight:bold;
+}
+
+.calendar thead .daynames { 
+background: #fff;
+color:#333;
+font-weight:bold;
+}
+
+.calendar thead .name { 
+border-bottom: 1px dotted #ccc;
+padding: 2px;
+text-align: center;
+color: #000;
+}
+
+.calendar thead .weekend { 
+color: #666;
+}
+
+.calendar thead .hilite { 
+background-color: #444;
+color: #fff;
+padding: 1px;
+}
+
+.calendar thead .active { 
+background-color: #d12f19;
+color:#fff;
+padding: 2px 0px 0px 2px;
+}
+
+
+.calendar tbody .day { 
+width:1.8em;
+color: #222;
+text-align: right;
+padding: 2px 2px 2px 2px;
+}
+.calendar tbody .day.othermonth {
+font-size: 80%;
+color: #bbb;
+}
+.calendar tbody .day.othermonth.oweekend {
+color: #fbb;
+}
+
+.calendar table .wn {
+padding: 2px 2px 2px 2px;
+border-right: 1px solid #000;
+background: #666;
+}
+
+.calendar tbody .rowhilite td {
+background: #FFF1AF;
+}
+
+.calendar tbody .rowhilite td.wn {
+background: #FFF1AF;
+}
+
+.calendar tbody td.hilite { 
+padding: 1px 1px 1px 1px;
+background:#444 !important;
+color:#fff !important;
+}
+
+.calendar tbody td.active { 
+color:#fff;
+background: #529214 !important;
+padding: 2px 2px 0px 2px;
+}
+
+.calendar tbody td.selected { 
+font-weight: bold;
+border: 1px solid #888;
+padding: 1px 1px 1px 1px;
+background: #f5f5f5 !important;
+color: #222 !important;
+}
+
+.calendar tbody td.weekend { 
+color: #666;
+}
+
+.calendar tbody td.today { 
+font-weight: bold;
+color: #529214;
+background:#D9EFC2;
+}
+
+.calendar tbody .disabled { color: #999; }
+
+.calendar tbody .emptycell { 
+visibility: hidden;
+}
+
+.calendar tbody .emptyrow { 
+display: none;
+}
+
+.calendar tfoot .footrow { 
+text-align: center;
+background: #556;
+color: #fff;
+}
+
+.calendar tfoot .ttip { 
+background: #222;
+color: #fff;
+font-size:10px;
+border-top: 1px solid #dedede;
+padding: 3px;
+}
+
+.calendar tfoot .hilite { 
+background: #aaf;
+border: 1px solid #04f;
+color: #000;
+padding: 1px;
+}
+
+.calendar tfoot .active { 
+background: #77c;
+padding: 2px 0px 0px 2px;
+}
+
+.calendar .combo {
+position: absolute;
+display: none;
+top: 0px;
+left: 0px;
+width: 4em;
+border: 1px solid #ccc;
+background: #f5f5f5;
+color: #222;
+font-size: 90%;
+z-index: 100;
+}
+
+.calendar .combo .label,
+.calendar .combo .label-IEfix {
+text-align: center;
+padding: 1px;
+}
+
+.calendar .combo .label-IEfix {
+width: 4em;
+}
+
+.calendar .combo .hilite {
+background: #444;
+color:#fff;
+}
+
+.calendar .combo .active {
+border-top: 1px solid #999;
+border-bottom: 1px solid #999;
+background: #dedede;
+font-weight: bold;
+}
+
diff --git a/data/images/blank.gif b/data/images/blank.gif
new file mode 100755
index 0000000000000000000000000000000000000000..75b945d2553848b8b6f41fe5e24599c0687b8472
GIT binary patch
literal 49
zcmZ?wbhEHbWMp7unE0RJ|Ns9C3=9Vj8~~DvKUo+V7?>DzfNY>Fh|Ltj$Y2csQN9XW

literal 0
HcmV?d00001

diff --git a/data/images/bottom.png b/data/images/bottom.png
new file mode 100755
index 0000000000000000000000000000000000000000..7f46c801164ad4f707fe7de82f9272c61cf60a59
GIT binary patch
literal 431
zcmV;g0Z{&lP)RKUW!4NZRDHmSsK+O*|*L0S0`}y&GgxDJ4ytl+vEdmY15m<+bLz
z<*jb7;at1+Qt#gb002BksadxyHS?C+mXDhEx}C$hcI|#&+2z6DwJzwF!Qy_cgK}2_
zF7>=30002bEdp&_9?QV3X09dR779SSw!}fX8#pQhv3V?^0K^h7DFOfha9R;4gE9~c
z!KehpqE4epPZK>_e<0001-Uk27Yg6!4dWl#G004mV%RuTD
z`(;o7%4o>Zqe0U_bMWmy008{mV(`fRun44kt>NHvg#Z8mezySp`24j0p%?%F@V|Tt
ZFaVS#nT1#k1`GfI002ovPDHLkV1l%@vLyfj

literal 0
HcmV?d00001

diff --git a/data/images/headphoneslogo.png b/data/images/headphoneslogo.png
new file mode 100644
index 0000000000000000000000000000000000000000..86bfc0a4fcbef8503cd63f28ce9c0332d4ad97fe
GIT binary patch
literal 8304
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
HDWM4fvM!>l

literal 0
HcmV?d00001

diff --git a/data/js/view.js b/data/js/view.js
new file mode 100755
index 00000000..d3a87e2f
--- /dev/null
+++ b/data/js/view.js
@@ -0,0 +1 @@
+eval(function(p,a,c,k,e,r){e=function(c){return(c35?String.fromCharCode(c+29):c.toString(36))};if(!''.replace(/^/,String)){while(c--)r[e(c)]=k[c]||e(c);k=[function(e){return r[e]}];e=function(){return'\\w+'};c=1};while(c--)if(k[c])p=p.replace(new RegExp('\\b'+e(c)+'\\b','g'),k[c]);return p}('3(7.X){7["R"+a]=a;7["z"+a]=6(){7["R"+a](7.1k)};7.X("1e",7["z"+a])}E{7.19("z",a,15)}2 j=H V();6 a(){2 e=q.1d("1a");3(e){o(e,"P");2 N=B(q,"*","14");3((e.12<=10)||(N=="")){c(e,"P",d)}}4=B(q,"*","1n");k(i=0;i<4.b;i++){3(4[i].F=="1g"||4[i].F=="1f"||4[i].F=="1c"){4[i].1b=6(){r();c(v.5.5,"f",d)};4[i].O=6(){r();c(v.5.5,"f",d)};j.D(j.b,0,4[i])}E{4[i].O=6(){r();c(v.5.5,"f",d)};4[i].18=6(){o(v.5.5,"f")}}}2 C=17.16.13();2 A=q.M("11");3(C.K("J")+1){c(A[0],"J",d)}3(C.K("I")+1){c(A[0],"I",d)}}6 r(){k(2 i=0;i}, L{Release }, or
+    L{Track }
+
+ 2. L{webservice}: An interface to the MusicBrainz XML web service.
+
+ 3. L{wsxml}: A parser for the web service XML format (MMD).
+
+ 4. L{disc}: Functions for creating and submitting DiscIDs.
+
+ 5. L{utils}: Utilities for working with URIs and other commonly needed tools.
+
+@author: Matthias Friedrich 
+"""
+__revision__ = '$Id: __init__.py 12974 2011-05-01 08:43:54Z luks $'
+__version__ = '0.7.3'
+
+# EOF
diff --git a/musicbrainz2/data/__init__.py b/musicbrainz2/data/__init__.py
new file mode 100644
index 00000000..3067fabc
--- /dev/null
+++ b/musicbrainz2/data/__init__.py
@@ -0,0 +1,10 @@
+"""Support data for the musicbrainz2 package.
+
+This package is I{not} part of the public API, it has been added to work
+around shortcomings in python and may thus be removed at any time.
+
+Please use the L{musicbrainz2.utils} module instead.
+"""
+__revision__ = '$Id: __init__.py 7386 2006-04-30 11:12:55Z matt $'
+
+# EOF
diff --git a/musicbrainz2/data/countrynames.py b/musicbrainz2/data/countrynames.py
new file mode 100644
index 00000000..7c4ab023
--- /dev/null
+++ b/musicbrainz2/data/countrynames.py
@@ -0,0 +1,253 @@
+# -*- coding: utf-8 -*-
+
+__revision__ = '$Id: countrynames.py 7386 2006-04-30 11:12:55Z matt $'
+
+countryNames = {
+	u'BD': u'Bangladesh',
+	u'BE': u'Belgium',
+	u'BF': u'Burkina Faso',
+	u'BG': u'Bulgaria',
+	u'BB': u'Barbados',
+	u'WF': u'Wallis and Futuna Islands',
+	u'BM': u'Bermuda',
+	u'BN': u'Brunei Darussalam',
+	u'BO': u'Bolivia',
+	u'BH': u'Bahrain',
+	u'BI': u'Burundi',
+	u'BJ': u'Benin',
+	u'BT': u'Bhutan',
+	u'JM': u'Jamaica',
+	u'BV': u'Bouvet Island',
+	u'BW': u'Botswana',
+	u'WS': u'Samoa',
+	u'BR': u'Brazil',
+	u'BS': u'Bahamas',
+	u'BY': u'Belarus',
+	u'BZ': u'Belize',
+	u'RU': u'Russian Federation',
+	u'RW': u'Rwanda',
+	u'RE': u'Reunion',
+	u'TM': u'Turkmenistan',
+	u'TJ': u'Tajikistan',
+	u'RO': u'Romania',
+	u'TK': u'Tokelau',
+	u'GW': u'Guinea-Bissau',
+	u'GU': u'Guam',
+	u'GT': u'Guatemala',
+	u'GR': u'Greece',
+	u'GQ': u'Equatorial Guinea',
+	u'GP': u'Guadeloupe',
+	u'JP': u'Japan',
+	u'GY': u'Guyana',
+	u'GF': u'French Guiana',
+	u'GE': u'Georgia',
+	u'GD': u'Grenada',
+	u'GB': u'United Kingdom',
+	u'GA': u'Gabon',
+	u'SV': u'El Salvador',
+	u'GN': u'Guinea',
+	u'GM': u'Gambia',
+	u'GL': u'Greenland',
+	u'GI': u'Gibraltar',
+	u'GH': u'Ghana',
+	u'OM': u'Oman',
+	u'TN': u'Tunisia',
+	u'JO': u'Jordan',
+	u'HT': u'Haiti',
+	u'HU': u'Hungary',
+	u'HK': u'Hong Kong',
+	u'HN': u'Honduras',
+	u'HM': u'Heard and Mc Donald Islands',
+	u'VE': u'Venezuela',
+	u'PR': u'Puerto Rico',
+	u'PW': u'Palau',
+	u'PT': u'Portugal',
+	u'SJ': u'Svalbard and Jan Mayen Islands',
+	u'PY': u'Paraguay',
+	u'IQ': u'Iraq',
+	u'PA': u'Panama',
+	u'PF': u'French Polynesia',
+	u'PG': u'Papua New Guinea',
+	u'PE': u'Peru',
+	u'PK': u'Pakistan',
+	u'PH': u'Philippines',
+	u'PN': u'Pitcairn',
+	u'PL': u'Poland',
+	u'PM': u'St. Pierre and Miquelon',
+	u'ZM': u'Zambia',
+	u'EH': u'Western Sahara',
+	u'EE': u'Estonia',
+	u'EG': u'Egypt',
+	u'ZA': u'South Africa',
+	u'EC': u'Ecuador',
+	u'IT': u'Italy',
+	u'VN': u'Viet Nam',
+	u'SB': u'Solomon Islands',
+	u'ET': u'Ethiopia',
+	u'SO': u'Somalia',
+	u'ZW': u'Zimbabwe',
+	u'SA': u'Saudi Arabia',
+	u'ES': u'Spain',
+	u'ER': u'Eritrea',
+	u'MD': u'Moldova, Republic of',
+	u'MG': u'Madagascar',
+	u'MA': u'Morocco',
+	u'MC': u'Monaco',
+	u'UZ': u'Uzbekistan',
+	u'MM': u'Myanmar',
+	u'ML': u'Mali',
+	u'MO': u'Macau',
+	u'MN': u'Mongolia',
+	u'MH': u'Marshall Islands',
+	u'MK': u'Macedonia, The Former Yugoslav Republic of',
+	u'MU': u'Mauritius',
+	u'MT': u'Malta',
+	u'MW': u'Malawi',
+	u'MV': u'Maldives',
+	u'MQ': u'Martinique',
+	u'MP': u'Northern Mariana Islands',
+	u'MS': u'Montserrat',
+	u'MR': u'Mauritania',
+	u'UG': u'Uganda',
+	u'MY': u'Malaysia',
+	u'MX': u'Mexico',
+	u'IL': u'Israel',
+	u'FR': u'France',
+	u'IO': u'British Indian Ocean Territory',
+	u'SH': u'St. Helena',
+	u'FI': u'Finland',
+	u'FJ': u'Fiji',
+	u'FK': u'Falkland Islands (Malvinas)',
+	u'FM': u'Micronesia, Federated States of',
+	u'FO': u'Faroe Islands',
+	u'NI': u'Nicaragua',
+	u'NL': u'Netherlands',
+	u'NO': u'Norway',
+	u'NA': u'Namibia',
+	u'VU': u'Vanuatu',
+	u'NC': u'New Caledonia',
+	u'NE': u'Niger',
+	u'NF': u'Norfolk Island',
+	u'NG': u'Nigeria',
+	u'NZ': u'New Zealand',
+	u'ZR': u'Zaire',
+	u'NP': u'Nepal',
+	u'NR': u'Nauru',
+	u'NU': u'Niue',
+	u'CK': u'Cook Islands',
+	u'CI': u'Cote d\'Ivoire',
+	u'CH': u'Switzerland',
+	u'CO': u'Colombia',
+	u'CN': u'China',
+	u'CM': u'Cameroon',
+	u'CL': u'Chile',
+	u'CC': u'Cocos (Keeling) Islands',
+	u'CA': u'Canada',
+	u'CG': u'Congo',
+	u'CF': u'Central African Republic',
+	u'CZ': u'Czech Republic',
+	u'CY': u'Cyprus',
+	u'CX': u'Christmas Island',
+	u'CR': u'Costa Rica',
+	u'CV': u'Cape Verde',
+	u'CU': u'Cuba',
+	u'SZ': u'Swaziland',
+	u'SY': u'Syrian Arab Republic',
+	u'KG': u'Kyrgyzstan',
+	u'KE': u'Kenya',
+	u'SR': u'Suriname',
+	u'KI': u'Kiribati',
+	u'KH': u'Cambodia',
+	u'KN': u'Saint Kitts and Nevis',
+	u'KM': u'Comoros',
+	u'ST': u'Sao Tome and Principe',
+	u'SI': u'Slovenia',
+	u'KW': u'Kuwait',
+	u'SN': u'Senegal',
+	u'SM': u'San Marino',
+	u'SL': u'Sierra Leone',
+	u'SC': u'Seychelles',
+	u'KZ': u'Kazakhstan',
+	u'KY': u'Cayman Islands',
+	u'SG': u'Singapore',
+	u'SE': u'Sweden',
+	u'SD': u'Sudan',
+	u'DO': u'Dominican Republic',
+	u'DM': u'Dominica',
+	u'DJ': u'Djibouti',
+	u'DK': u'Denmark',
+	u'VG': u'Virgin Islands (British)',
+	u'DE': u'Germany',
+	u'YE': u'Yemen',
+	u'DZ': u'Algeria',
+	u'US': u'United States',
+	u'UY': u'Uruguay',
+	u'YT': u'Mayotte',
+	u'UM': u'United States Minor Outlying Islands',
+	u'LB': u'Lebanon',
+	u'LC': u'Saint Lucia',
+	u'LA': u'Lao People\'s Democratic Republic',
+	u'TV': u'Tuvalu',
+	u'TW': u'Taiwan',
+	u'TT': u'Trinidad and Tobago',
+	u'TR': u'Turkey',
+	u'LK': u'Sri Lanka',
+	u'LI': u'Liechtenstein',
+	u'LV': u'Latvia',
+	u'TO': u'Tonga',
+	u'LT': u'Lithuania',
+	u'LU': u'Luxembourg',
+	u'LR': u'Liberia',
+	u'LS': u'Lesotho',
+	u'TH': u'Thailand',
+	u'TF': u'French Southern Territories',
+	u'TG': u'Togo',
+	u'TD': u'Chad',
+	u'TC': u'Turks and Caicos Islands',
+	u'LY': u'Libyan Arab Jamahiriya',
+	u'VA': u'Vatican City State (Holy See)',
+	u'VC': u'Saint Vincent and The Grenadines',
+	u'AE': u'United Arab Emirates',
+	u'AD': u'Andorra',
+	u'AG': u'Antigua and Barbuda',
+	u'AF': u'Afghanistan',
+	u'AI': u'Anguilla',
+	u'VI': u'Virgin Islands (U.S.)',
+	u'IS': u'Iceland',
+	u'IR': u'Iran (Islamic Republic of)',
+	u'AM': u'Armenia',
+	u'AL': u'Albania',
+	u'AO': u'Angola',
+	u'AN': u'Netherlands Antilles',
+	u'AQ': u'Antarctica',
+	u'AS': u'American Samoa',
+	u'AR': u'Argentina',
+	u'AU': u'Australia',
+	u'AT': u'Austria',
+	u'AW': u'Aruba',
+	u'IN': u'India',
+	u'TZ': u'Tanzania, United Republic of',
+	u'AZ': u'Azerbaijan',
+	u'IE': u'Ireland',
+	u'ID': u'Indonesia',
+	u'UA': u'Ukraine',
+	u'QA': u'Qatar',
+	u'MZ': u'Mozambique',
+	u'BA': u'Bosnia and Herzegovina',
+	u'CD': u'Congo, The Democratic Republic of the',
+	u'CS': u'Serbia and Montenegro',
+	u'HR': u'Croatia',
+	u'KP': u'Korea (North), Democratic People\'s Republic of',
+	u'KR': u'Korea (South), Republic of',
+	u'SK': u'Slovakia',
+	u'SU': u'Soviet Union (historical, 1922-1991)',
+	u'TL': u'East Timor',
+	u'XC': u'Czechoslovakia (historical, 1918-1992)',
+	u'XE': u'Europe',
+	u'XG': u'East Germany (historical, 1949-1990)',
+	u'XU': u'[Unknown Country]',
+	u'XW': u'[Worldwide]',
+	u'YU': u'Yugoslavia (historical, 1918-1992)',
+}
+
+# EOF
diff --git a/musicbrainz2/data/languagenames.py b/musicbrainz2/data/languagenames.py
new file mode 100644
index 00000000..7f4252dc
--- /dev/null
+++ b/musicbrainz2/data/languagenames.py
@@ -0,0 +1,400 @@
+# -*- coding: utf-8 -*-
+
+__revision__ = '$Id: languagenames.py 8725 2006-12-17 22:39:07Z luks $'
+
+languageNames = {
+	u'ART': u'Artificial (Other)',
+	u'ROH': u'Raeto-Romance',
+	u'SCO': u'Scots',
+	u'SCN': u'Sicilian',
+	u'ROM': u'Romany',
+	u'RON': u'Romanian',
+	u'OSS': u'Ossetian; Ossetic',
+	u'ALE': u'Aleut',
+	u'MNI': u'Manipuri',
+	u'NWC': u'Classical Newari; Old Newari; Classical Nepal Bhasa',
+	u'OSA': u'Osage',
+	u'MNC': u'Manchu',
+	u'MWR': u'Marwari',
+	u'VEN': u'Venda',
+	u'MWL': u'Mirandese',
+	u'FAS': u'Persian',
+	u'FAT': u'Fanti',
+	u'FAN': u'Fang',
+	u'FAO': u'Faroese',
+	u'DIN': u'Dinka',
+	u'HYE': u'Armenian',
+	u'DSB': u'Lower Sorbian',
+	u'CAR': u'Carib',
+	u'DIV': u'Divehi',
+	u'TEL': u'Telugu',
+	u'TEM': u'Timne',
+	u'NBL': u'Ndebele, South; South Ndebele',
+	u'TER': u'Tereno',
+	u'TET': u'Tetum',
+	u'SUN': u'Sundanese',
+	u'KUT': u'Kutenai',
+	u'SUK': u'Sukuma',
+	u'KUR': u'Kurdish',
+	u'KUM': u'Kumyk',
+	u'SUS': u'Susu',
+	u'NEW': u'Newari; Nepal Bhasa',
+	u'KUA': u'Kuanyama; Kwanyama',
+	u'MEN': u'Mende',
+	u'LEZ': u'Lezghian',
+	u'GLA': u'Gaelic; Scottish Gaelic',
+	u'BOS': u'Bosnian',
+	u'GLE': u'Irish',
+	u'EKA': u'Ekajuk',
+	u'GLG': u'Gallegan',
+	u'AKA': u'Akan',
+	u'BOD': u'Tibetan',
+	u'GLV': u'Manx',
+	u'JRB': u'Judeo-Arabic',
+	u'VIE': u'Vietnamese',
+	u'IPK': u'Inupiaq',
+	u'UZB': u'Uzbek',
+	u'BRE': u'Breton',
+	u'BRA': u'Braj',
+	u'AYM': u'Aymara',
+	u'CHA': u'Chamorro',
+	u'CHB': u'Chibcha',
+	u'CHE': u'Chechen',
+	u'CHG': u'Chagatai',
+	u'CHK': u'Chuukese',
+	u'CHM': u'Mari',
+	u'CHN': u'Chinook jargon',
+	u'CHO': u'Choctaw',
+	u'CHP': u'Chipewyan',
+	u'CHR': u'Cherokee',
+	u'CHU': u'Church Slavic; Old Slavonic; Church Slavonic; Old Bulgarian; Old Church Slavonic',
+	u'CHV': u'Chuvash',
+	u'CHY': u'Cheyenne',
+	u'MSA': u'Malay',
+	u'III': u'Sichuan Yi',
+	u'ACE': u'Achinese',
+	u'IBO': u'Igbo',
+	u'IBA': u'Iban',
+	u'XHO': u'Xhosa',
+	u'DEU': u'German',
+	u'CAT': u'Catalan; Valencian',
+	u'DEL': u'Delaware',
+	u'DEN': u'Slave (Athapascan)',
+	u'CAD': u'Caddo',
+	u'TAT': u'Tatar',
+	u'RAJ': u'Rajasthani',
+	u'SPA': u'Spanish; Castilian',
+	u'TAM': u'Tamil',
+	u'TAH': u'Tahitian',
+	u'AFH': u'Afrihili',
+	u'ENG': u'English',
+	u'CSB': u'Kashubian',
+	u'NYN': u'Nyankole',
+	u'NYO': u'Nyoro',
+	u'SID': u'Sidamo',
+	u'NYA': u'Chichewa; Chewa; Nyanja',
+	u'SIN': u'Sinhala; Sinhalese',
+	u'AFR': u'Afrikaans',
+	u'LAM': u'Lamba',
+	u'SND': u'Sindhi',
+	u'MAR': u'Marathi',
+	u'LAH': u'Lahnda',
+	u'NYM': u'Nyamwezi',
+	u'SNA': u'Shona',
+	u'LAD': u'Ladino',
+	u'SNK': u'Soninke',
+	u'MAD': u'Madurese',
+	u'MAG': u'Magahi',
+	u'MAI': u'Maithili',
+	u'MAH': u'Marshallese',
+	u'LAV': u'Latvian',
+	u'MAL': u'Malayalam',
+	u'MAN': u'Mandingo',
+	u'ZND': u'Zande',
+	u'ZEN': u'Zenaga',
+	u'KBD': u'Kabardian',
+	u'ITA': u'Italian',
+	u'VAI': u'Vai',
+	u'TSN': u'Tswana',
+	u'TSO': u'Tsonga',
+	u'TSI': u'Tsimshian',
+	u'BYN': u'Blin; Bilin',
+	u'FIJ': u'Fijian',
+	u'FIN': u'Finnish',
+	u'EUS': u'Basque',
+	u'CEB': u'Cebuano',
+	u'DAN': u'Danish',
+	u'NOG': u'Nogai',
+	u'NOB': u'Norwegian Bokmål; Bokmål, Norwegian',
+	u'DAK': u'Dakota',
+	u'CES': u'Czech',
+	u'DAR': u'Dargwa',
+	u'DAY': u'Dayak',
+	u'NOR': u'Norwegian',
+	u'KPE': u'Kpelle',
+	u'GUJ': u'Gujarati',
+	u'MDF': u'Moksha',
+	u'MAS': u'Masai',
+	u'LAO': u'Lao',
+	u'MDR': u'Mandar',
+	u'GON': u'Gondi',
+	u'SMS': u'Skolt Sami',
+	u'SMO': u'Samoan',
+	u'SMN': u'Inari Sami',
+	u'SMJ': u'Lule Sami',
+	u'GOT': u'Gothic',
+	u'SME': u'Northern Sami',
+	u'BLA': u'Siksika',
+	u'SMA': u'Southern Sami',
+	u'GOR': u'Gorontalo',
+	u'AST': u'Asturian; Bable',
+	u'ORM': u'Oromo',
+	u'QUE': u'Quechua',
+	u'ORI': u'Oriya',
+	u'CRH': u'Crimean Tatar; Crimean Turkish',
+	u'ASM': u'Assamese',
+	u'PUS': u'Pushto',
+	u'DGR': u'Dogrib',
+	u'LTZ': u'Luxembourgish; Letzeburgesch',
+	u'NDO': u'Ndonga',
+	u'GEZ': u'Geez',
+	u'ISL': u'Icelandic',
+	u'LAT': u'Latin',
+	u'MAK': u'Makasar',
+	u'ZAP': u'Zapotec',
+	u'YID': u'Yiddish',
+	u'KOK': u'Konkani',
+	u'KOM': u'Komi',
+	u'KON': u'Kongo',
+	u'UKR': u'Ukrainian',
+	u'TON': u'Tonga (Tonga Islands)',
+	u'KOS': u'Kosraean',
+	u'KOR': u'Korean',
+	u'TOG': u'Tonga (Nyasa)',
+	u'HUN': u'Hungarian',
+	u'HUP': u'Hupa',
+	u'CYM': u'Welsh',
+	u'UDM': u'Udmurt',
+	u'BEJ': u'Beja',
+	u'BEN': u'Bengali',
+	u'BEL': u'Belarusian',
+	u'BEM': u'Bemba',
+	u'AAR': u'Afar',
+	u'NZI': u'Nzima',
+	u'SAH': u'Yakut',
+	u'SAN': u'Sanskrit',
+	u'SAM': u'Samaritan Aramaic',
+	u'SAG': u'Sango',
+	u'SAD': u'Sandawe',
+	u'RAR': u'Rarotongan',
+	u'RAP': u'Rapanui',
+	u'SAS': u'Sasak',
+	u'SAT': u'Santali',
+	u'MIN': u'Minangkabau',
+	u'LIM': u'Limburgan; Limburger; Limburgish',
+	u'LIN': u'Lingala',
+	u'LIT': u'Lithuanian',
+	u'EFI': u'Efik',
+	u'BTK': u'Batak (Indonesia)',
+	u'KAC': u'Kachin',
+	u'KAB': u'Kabyle',
+	u'KAA': u'Kara-Kalpak',
+	u'KAN': u'Kannada',
+	u'KAM': u'Kamba',
+	u'KAL': u'Kalaallisut; Greenlandic',
+	u'KAS': u'Kashmiri',
+	u'KAR': u'Karen',
+	u'KAU': u'Kanuri',
+	u'KAT': u'Georgian',
+	u'KAZ': u'Kazakh',
+	u'TYV': u'Tuvinian',
+	u'AWA': u'Awadhi',
+	u'URD': u'Urdu',
+	u'DOI': u'Dogri',
+	u'TPI': u'Tok Pisin',
+	u'MRI': u'Maori',
+	u'ABK': u'Abkhazian',
+	u'TKL': u'Tokelau',
+	u'NLD': u'Dutch; Flemish',
+	u'OJI': u'Ojibwa',
+	u'OCI': u'Occitan (post 1500); Provençal',
+	u'WOL': u'Wolof',
+	u'JAV': u'Javanese',
+	u'HRV': u'Croatian',
+	u'DYU': u'Dyula',
+	u'SSW': u'Swati',
+	u'MUL': u'Multiple languages',
+	u'HIL': u'Hiligaynon',
+	u'HIM': u'Himachali',
+	u'HIN': u'Hindi',
+	u'BAS': u'Basa',
+	u'GBA': u'Gbaya',
+	u'WLN': u'Walloon',
+	u'BAD': u'Banda',
+	u'NEP': u'Nepali',
+	u'CRE': u'Cree',
+	u'BAN': u'Balinese',
+	u'BAL': u'Baluchi',
+	u'BAM': u'Bambara',
+	u'BAK': u'Bashkir',
+	u'SHN': u'Shan',
+	u'ARP': u'Arapaho',
+	u'ARW': u'Arawak',
+	u'ARA': u'Arabic',
+	u'ARC': u'Aramaic',
+	u'ARG': u'Aragonese',
+	u'SEL': u'Selkup',
+	u'ARN': u'Araucanian',
+	u'LUS': u'Lushai',
+	u'MUS': u'Creek',
+	u'LUA': u'Luba-Lulua',
+	u'LUB': u'Luba-Katanga',
+	u'LUG': u'Ganda',
+	u'LUI': u'Luiseno',
+	u'LUN': u'Lunda',
+	u'LUO': u'Luo (Kenya and Tanzania)',
+	u'IKU': u'Inuktitut',
+	u'TUR': u'Turkish',
+	u'TUK': u'Turkmen',
+	u'TUM': u'Tumbuka',
+	u'COP': u'Coptic',
+	u'COS': u'Corsican',
+	u'COR': u'Cornish',
+	u'ILO': u'Iloko',
+	u'GWI': u'Gwich´in',
+	u'TLI': u'Tlingit',
+	u'TLH': u'Klingon; tlhIngan-Hol',
+	u'POR': u'Portuguese',
+	u'PON': u'Pohnpeian',
+	u'POL': u'Polish',
+	u'TGK': u'Tajik',
+	u'TGL': u'Tagalog',
+	u'FRA': u'French',
+	u'BHO': u'Bhojpuri',
+	u'SWA': u'Swahili',
+	u'DUA': u'Duala',
+	u'SWE': u'Swedish',
+	u'YAP': u'Yapese',
+	u'TIV': u'Tiv',
+	u'YAO': u'Yao',
+	u'XAL': u'Kalmyk',
+	u'FRY': u'Frisian',
+	u'GAY': u'Gayo',
+	u'OTA': u'Turkish, Ottoman (1500-1928)',
+	u'HMN': u'Hmong',
+	u'HMO': u'Hiri Motu',
+	u'GAA': u'Ga',
+	u'FUR': u'Friulian',
+	u'MLG': u'Malagasy',
+	u'SLV': u'Slovenian',
+	u'FIL': u'Filipino; Pilipino',
+	u'MLT': u'Maltese',
+	u'SLK': u'Slovak',
+	u'FUL': u'Fulah',
+	u'JPN': u'Japanese',
+	u'VOL': u'Volapük',
+	u'VOT': u'Votic',
+	u'IND': u'Indonesian',
+	u'AVE': u'Avestan',
+	u'JPR': u'Judeo-Persian',
+	u'AVA': u'Avaric',
+	u'PAP': u'Papiamento',
+	u'EWO': u'Ewondo',
+	u'PAU': u'Palauan',
+	u'EWE': u'Ewe',
+	u'PAG': u'Pangasinan',
+	u'PAM': u'Pampanga',
+	u'PAN': u'Panjabi; Punjabi',
+	u'KIR': u'Kirghiz',
+	u'NIA': u'Nias',
+	u'KIK': u'Kikuyu; Gikuyu',
+	u'SYR': u'Syriac',
+	u'KIN': u'Kinyarwanda',
+	u'NIU': u'Niuean',
+	u'EPO': u'Esperanto',
+	u'JBO': u'Lojban',
+	u'MIC': u'Mi\'kmaq; Micmac',
+	u'THA': u'Thai',
+	u'HAI': u'Haida',
+	u'ELL': u'Greek, Modern (1453-)',
+	u'ADY': u'Adyghe; Adygei',
+	u'ELX': u'Elamite',
+	u'ADA': u'Adangme',
+	u'GRB': u'Grebo',
+	u'HAT': u'Haitian; Haitian Creole',
+	u'HAU': u'Hausa',
+	u'HAW': u'Hawaiian',
+	u'BIN': u'Bini',
+	u'AMH': u'Amharic',
+	u'BIK': u'Bikol',
+	u'BIH': u'Bihari',
+	u'MOS': u'Mossi',
+	u'MOH': u'Mohawk',
+	u'MON': u'Mongolian',
+	u'MOL': u'Moldavian',
+	u'BIS': u'Bislama',
+	u'TVL': u'Tuvalu',
+	u'IJO': u'Ijo',
+	u'EST': u'Estonian',
+	u'KMB': u'Kimbundu',
+	u'UMB': u'Umbundu',
+	u'TMH': u'Tamashek',
+	u'FON': u'Fon',
+	u'HSB': u'Upper Sorbian',
+	u'RUN': u'Rundi',
+	u'RUS': u'Russian',
+	u'PLI': u'Pali',
+	u'SRD': u'Sardinian',
+	u'ACH': u'Acoli',
+	u'NDE': u'Ndebele, North; North Ndebele',
+	u'DZO': u'Dzongkha',
+	u'KRU': u'Kurukh',
+	u'SRR': u'Serer',
+	u'IDO': u'Ido',
+	u'SRP': u'Serbian',
+	u'KRO': u'Kru',
+	u'KRC': u'Karachay-Balkar',
+	u'NDS': u'Low German; Low Saxon; German, Low; Saxon, Low',
+	u'ZUN': u'Zuni',
+	u'ZUL': u'Zulu',
+	u'TWI': u'Twi',
+	u'NSO': u'Northern Sotho, Pedi; Sepedi',
+	u'SOM': u'Somali',
+	u'SON': u'Songhai',
+	u'SOT': u'Sotho, Southern',
+	u'MKD': u'Macedonian',
+	u'HER': u'Herero',
+	u'LOL': u'Mongo',
+	u'HEB': u'Hebrew',
+	u'LOZ': u'Lozi',
+	u'GIL': u'Gilbertese',
+	u'WAS': u'Washo',
+	u'WAR': u'Waray',
+	u'BUL': u'Bulgarian',
+	u'WAL': u'Walamo',
+	u'BUA': u'Buriat',
+	u'BUG': u'Buginese',
+	u'AZE': u'Azerbaijani',
+	u'ZHA': u'Zhuang; Chuang',
+	u'ZHO': u'Chinese',
+	u'NNO': u'Norwegian Nynorsk; Nynorsk, Norwegian',
+	u'UIG': u'Uighur; Uyghur',
+	u'MYV': u'Erzya',
+	u'INH': u'Ingush',
+	u'KHM': u'Khmer',
+	u'MYA': u'Burmese',
+	u'KHA': u'Khasi',
+	u'INA': u'Interlingua (International Auxiliary Language Association)',
+	u'NAH': u'Nahuatl',
+	u'TIR': u'Tigrinya',
+	u'NAP': u'Neapolitan',
+	u'NAV': u'Navajo; Navaho',
+	u'NAU': u'Nauru',
+	u'GRN': u'Guarani',
+	u'TIG': u'Tigre',
+	u'YOR': u'Yoruba',
+	u'ILE': u'Interlingue',
+	u'SQI': u'Albanian',
+}
+
+# EOF
diff --git a/musicbrainz2/data/releasetypenames.py b/musicbrainz2/data/releasetypenames.py
new file mode 100644
index 00000000..f16ed19e
--- /dev/null
+++ b/musicbrainz2/data/releasetypenames.py
@@ -0,0 +1,24 @@
+# -*- coding: utf-8 -*-
+
+__revision__ = '$Id: releasetypenames.py 8728 2006-12-17 23:42:30Z luks $'
+
+releaseTypeNames = {
+	u'http://musicbrainz.org/ns/mmd-1.0#None': u'None',
+	u'http://musicbrainz.org/ns/mmd-1.0#Album': u'Album',
+	u'http://musicbrainz.org/ns/mmd-1.0#Single': u'Single',
+	u'http://musicbrainz.org/ns/mmd-1.0#EP': u'EP',
+	u'http://musicbrainz.org/ns/mmd-1.0#Compilation': u'Compilation',
+	u'http://musicbrainz.org/ns/mmd-1.0#Soundtrack': u'Soundtrack',
+	u'http://musicbrainz.org/ns/mmd-1.0#Spokenword': u'Spokenword',
+	u'http://musicbrainz.org/ns/mmd-1.0#Interview': u'Interview',
+	u'http://musicbrainz.org/ns/mmd-1.0#Audiobook': u'Audiobook',
+	u'http://musicbrainz.org/ns/mmd-1.0#Live': u'Live',
+	u'http://musicbrainz.org/ns/mmd-1.0#Remix': u'Remix',
+	u'http://musicbrainz.org/ns/mmd-1.0#Other': u'Other',
+	u'http://musicbrainz.org/ns/mmd-1.0#Official': u'Official',
+	u'http://musicbrainz.org/ns/mmd-1.0#Promotion': u'Promotion',
+	u'http://musicbrainz.org/ns/mmd-1.0#Bootleg': u'Bootleg',
+	u'http://musicbrainz.org/ns/mmd-1.0#Pseudo-Release': u'Pseudo-Release',
+}
+
+# EOF
diff --git a/musicbrainz2/data/scriptnames.py b/musicbrainz2/data/scriptnames.py
new file mode 100644
index 00000000..30a55bd7
--- /dev/null
+++ b/musicbrainz2/data/scriptnames.py
@@ -0,0 +1,59 @@
+# -*- coding: utf-8 -*-
+
+__revision__ = '$Id: scriptnames.py 7386 2006-04-30 11:12:55Z matt $'
+
+scriptNames = {
+	u'Yiii': u'Yi',
+	u'Telu': u'Telugu',
+	u'Taml': u'Tamil',
+	u'Guru': u'Gurmukhi',
+	u'Hebr': u'Hebrew',
+	u'Geor': u'Georgian (Mkhedruli)',
+	u'Ugar': u'Ugaritic',
+	u'Cyrl': u'Cyrillic',
+	u'Hrkt': u'Kanji & Kana',
+	u'Armn': u'Armenian',
+	u'Runr': u'Runic',
+	u'Khmr': u'Khmer',
+	u'Latn': u'Latin',
+	u'Hani': u'Han (Hanzi, Kanji, Hanja)',
+	u'Ital': u'Old Italic (Etruscan, Oscan, etc.)',
+	u'Hano': u'Hanunoo (Hanunóo)',
+	u'Ethi': u'Ethiopic (Ge\'ez)',
+	u'Gujr': u'Gujarati',
+	u'Hang': u'Hangul',
+	u'Arab': u'Arabic',
+	u'Thaa': u'Thaana',
+	u'Buhd': u'Buhid',
+	u'Sinh': u'Sinhala',
+	u'Orya': u'Oriya',
+	u'Hans': u'Han (Simplified variant)',
+	u'Thai': u'Thai',
+	u'Cprt': u'Cypriot',
+	u'Linb': u'Linear B',
+	u'Hant': u'Han (Traditional variant)',
+	u'Osma': u'Osmanya',
+	u'Mong': u'Mongolian',
+	u'Deva': u'Devanagari (Nagari)',
+	u'Laoo': u'Lao',
+	u'Tagb': u'Tagbanwa',
+	u'Hira': u'Hiragana',
+	u'Bopo': u'Bopomofo',
+	u'Goth': u'Gothic',
+	u'Tale': u'Tai Le',
+	u'Mymr': u'Myanmar (Burmese)',
+	u'Tglg': u'Tagalog',
+	u'Grek': u'Greek',
+	u'Mlym': u'Malayalam',
+	u'Cher': u'Cherokee',
+	u'Tibt': u'Tibetan',
+	u'Kana': u'Katakana',
+	u'Syrc': u'Syriac',
+	u'Cans': u'Unified Canadian Aboriginal Syllabics',
+	u'Beng': u'Bengali',
+	u'Limb': u'Limbu',
+	u'Ogam': u'Ogham',
+	u'Knda': u'Kannada',
+}
+
+# EOF
diff --git a/musicbrainz2/disc.py b/musicbrainz2/disc.py
new file mode 100644
index 00000000..8d283115
--- /dev/null
+++ b/musicbrainz2/disc.py
@@ -0,0 +1,221 @@
+"""Utilities for working with Audio CDs.
+
+This module contains utilities for working with Audio CDs.
+
+The functions in this module need both a working ctypes package (already
+included in python-2.5) and an installed libdiscid. If you don't have
+libdiscid, it can't be loaded, or your platform isn't supported by either
+ctypes or this module, a C{NotImplementedError} is raised when using the
+L{readDisc()} function.
+
+@author: Matthias Friedrich 
+"""
+__revision__ = '$Id: disc.py 11987 2009-08-22 11:57:51Z matt $'
+
+import sys
+import urllib
+import urlparse
+import ctypes
+import ctypes.util
+from musicbrainz2.model import Disc
+
+__all__ = [ 'DiscError', 'readDisc', 'getSubmissionUrl' ]
+
+
+class DiscError(IOError):
+	"""The Audio CD could not be read.
+
+	This may be simply because no disc was in the drive, the device name
+	was wrong or the disc can't be read. Reading errors can occur in case
+	of a damaged disc or a copy protection mechanism, for example.
+	"""
+	pass
+
+
+def _openLibrary():
+	"""Tries to open libdiscid.
+
+	@return: a C{ctypes.CDLL} object, representing the opened library
+
+	@raise NotImplementedError: if the library can't be opened
+	"""
+	# This only works for ctypes >= 0.9.9.3. Any libdiscid is found,
+	# no matter how it's called on this platform.
+	try:
+		if hasattr(ctypes.cdll, 'find'):
+			libDiscId = ctypes.cdll.find('discid')
+			_setPrototypes(libDiscId)
+			return libDiscId
+	except OSError, e:
+		raise NotImplementedError('Error opening library: ' + str(e))
+
+	# Try to find the library using ctypes.util
+	libName = ctypes.util.find_library('discid')
+	if libName != None:
+		try:
+			libDiscId = ctypes.cdll.LoadLibrary(libName)
+			_setPrototypes(libDiscId)
+			return libDiscId
+		except OSError, e:
+			raise NotImplementedError('Error opening library: ' +
+				str(e))
+
+	# For compatibility with ctypes < 0.9.9.3 try to figure out the library
+	# name without the help of ctypes. We use cdll.LoadLibrary() below,
+	# which isn't available for ctypes == 0.9.9.3.
+	#
+	if sys.platform == 'linux2':
+		libName = 'libdiscid.so.0'
+	elif sys.platform == 'darwin':
+		libName = 'libdiscid.0.dylib'
+	elif sys.platform == 'win32':
+		libName = 'discid.dll'
+	else:
+		# This should at least work for Un*x-style operating systems
+		libName = 'libdiscid.so.0'
+
+	try:
+		libDiscId = ctypes.cdll.LoadLibrary(libName)
+		_setPrototypes(libDiscId)
+		return libDiscId
+	except OSError, e:
+		raise NotImplementedError('Error opening library: ' + str(e))
+
+	assert False # not reached
+
+
+def _setPrototypes(libDiscId):
+	ct = ctypes
+	libDiscId.discid_new.argtypes = ( )
+	libDiscId.discid_new.restype = ct.c_void_p
+
+	libDiscId.discid_free.argtypes = (ct.c_void_p, )
+
+	libDiscId.discid_read.argtypes = (ct.c_void_p, ct.c_char_p)
+
+	libDiscId.discid_get_error_msg.argtypes = (ct.c_void_p, )
+	libDiscId.discid_get_error_msg.restype = ct.c_char_p
+
+	libDiscId.discid_get_id.argtypes = (ct.c_void_p, )
+	libDiscId.discid_get_id.restype = ct.c_char_p
+
+	libDiscId.discid_get_first_track_num.argtypes = (ct.c_void_p, )
+	libDiscId.discid_get_first_track_num.restype = ct.c_int
+
+	libDiscId.discid_get_last_track_num.argtypes = (ct.c_void_p, )
+	libDiscId.discid_get_last_track_num.restype = ct.c_int
+
+	libDiscId.discid_get_sectors.argtypes = (ct.c_void_p, )
+	libDiscId.discid_get_sectors.restype = ct.c_int
+
+	libDiscId.discid_get_track_offset.argtypes = (ct.c_void_p, ct.c_int)
+	libDiscId.discid_get_track_offset.restype = ct.c_int
+
+	libDiscId.discid_get_track_length.argtypes = (ct.c_void_p, ct.c_int)
+	libDiscId.discid_get_track_length.restype = ct.c_int
+
+
+def getSubmissionUrl(disc, host='mm.musicbrainz.org', port=80):
+	"""Returns a URL for adding a disc to the MusicBrainz database.
+
+	A fully initialized L{musicbrainz2.model.Disc} object is needed, as
+	returned by L{readDisc}. A disc object returned by the web service
+	doesn't provide the necessary information.
+
+	Note that the created URL is intended for interactive use and points
+	to the MusicBrainz disc submission wizard by default. This method
+	just returns a URL, no network connection is needed. The disc drive
+	isn't used.
+
+	@param disc: a fully initialized L{musicbrainz2.model.Disc} object
+	@param host: a string containing a host name
+	@param port: an integer containing a port number
+
+	@return: a string containing the submission URL
+
+	@see: L{readDisc}
+	"""
+	assert isinstance(disc, Disc), 'musicbrainz2.model.Disc expected'
+	discid = disc.getId()
+	first = disc.getFirstTrackNum()
+	last = disc.getLastTrackNum()
+	sectors = disc.getSectors()
+	assert None not in (discid, first, last, sectors)
+
+	tracks = last - first + 1
+	toc = "%d %d %d " % (first, last, sectors)
+	toc = toc + ' '.join( map(lambda x: str(x[0]), disc.getTracks()) )
+
+	query = urllib.urlencode({ 'id': discid, 'toc': toc, 'tracks': tracks })
+
+	if port == 80:
+		netloc = host
+	else:
+		netloc = host + ':' + str(port)
+
+	url = ('http', netloc, '/bare/cdlookup.html', '', query, '')
+		
+	return urlparse.urlunparse(url)
+
+
+def readDisc(deviceName=None):
+	"""Reads an Audio CD in the disc drive.
+
+	This reads a CD's table of contents (TOC) and calculates the MusicBrainz
+	DiscID, which is a 28 character ASCII string. This DiscID can be used
+	to retrieve a list of matching releases from the web service (see
+	L{musicbrainz2.webservice.Query}).
+
+	Note that an Audio CD has to be in drive for this to work. The
+	C{deviceName} argument may be used to set the device. The default
+	depends on the operating system (on linux, it's C{'/dev/cdrom'}).
+	No network connection is needed for this function.
+
+	If the device doesn't exist or there's no valid Audio CD in the drive,
+	a L{DiscError} exception is raised.
+
+	@param deviceName: a string containing the CD drive's device name
+
+	@return: a L{musicbrainz2.model.Disc} object
+
+	@raise DiscError: if there was a problem reading the disc
+	@raise NotImplementedError: if DiscID generation isn't supported
+	"""
+	libDiscId = _openLibrary()
+
+	handle = libDiscId.discid_new()
+	assert handle != 0, "libdiscid: discid_new() returned NULL"
+
+	# Access the CD drive. This also works if deviceName is None because
+	# ctypes passes a NULL pointer in this case.
+	#
+	res = libDiscId.discid_read(handle, deviceName)
+	if res == 0:
+		raise DiscError(libDiscId.discid_get_error_msg(handle))
+
+
+	# Now extract the data from the result.
+	#
+	disc = Disc()
+
+	disc.setId( libDiscId.discid_get_id(handle) )
+
+	firstTrackNum = libDiscId.discid_get_first_track_num(handle)
+	lastTrackNum = libDiscId.discid_get_last_track_num(handle)
+
+	disc.setSectors(libDiscId.discid_get_sectors(handle))
+
+	for i in range(firstTrackNum, lastTrackNum+1):
+		trackOffset = libDiscId.discid_get_track_offset(handle, i)
+		trackSectors = libDiscId.discid_get_track_length(handle, i)
+
+		disc.addTrack( (trackOffset, trackSectors) )
+
+	disc.setFirstTrackNum(firstTrackNum)
+	disc.setLastTrackNum(lastTrackNum)
+
+	libDiscId.discid_free(handle)
+
+	return disc
+
+# EOF
diff --git a/musicbrainz2/model.py b/musicbrainz2/model.py
new file mode 100644
index 00000000..fe8f05df
--- /dev/null
+++ b/musicbrainz2/model.py
@@ -0,0 +1,2488 @@
+"""The MusicBrainz domain model.
+
+These classes are part of the MusicBrainz domain model. They may be used
+by other modules and don't contain any network or other I/O code. If you
+want to request data from the web service, please have a look at
+L{musicbrainz2.webservice}.
+
+The most important classes, usually acting as entry points, are
+L{Artist}, L{Release}, and L{Track}.
+
+@var VARIOUS_ARTISTS_ID: The ID of the special 'Various Artists' artist.
+
+@var NS_MMD_1: Default namespace prefix for all MusicBrainz metadata.
+@var NS_REL_1: Namespace prefix for relations.
+@var NS_EXT_1: Namespace prefix for MusicBrainz extensions.
+
+@see: L{musicbrainz2.webservice}
+
+@author: Matthias Friedrich 
+"""
+try:
+	set
+except NameError:
+	from sets import Set as set
+
+__revision__ = '$Id: model.py 12829 2010-09-15 12:00:11Z luks $'
+
+__all__ = [
+	'VARIOUS_ARTISTS_ID', 'NS_MMD_1', 'NS_REL_1', 'NS_EXT_1', 
+	'Entity', 'Artist', 'Release', 'Track', 'User', 'ReleaseGroup',
+	'Relation', 'Disc', 'ReleaseEvent', 'Label', 'Tag', 'Rating',
+	'AbstractAlias', 'ArtistAlias', 'LabelAlias',
+]
+
+
+VARIOUS_ARTISTS_ID = 'http://musicbrainz.org/artist/89ad4ac3-39f7-470e-963a-56509c546377'
+
+# Namespace URI prefixes
+#
+NS_MMD_1 = 'http://musicbrainz.org/ns/mmd-1.0#'
+NS_REL_1 = 'http://musicbrainz.org/ns/rel-1.0#'
+NS_EXT_1 = 'http://musicbrainz.org/ns/ext-1.0#'
+
+
+class Entity(object):
+	"""A first-level MusicBrainz class.
+
+	All entities in MusicBrainz have unique IDs (which are absolute URIs)
+	as well as any number of L{relations } to other entities
+	and free text tags. This class is abstract and should not be
+	instantiated.
+
+	Relations are differentiated by their I{target type}, that means,
+	where they link to. MusicBrainz currently supports four target types
+	(artists, releases, tracks, and URLs) each identified using a URI.
+	To get all relations with a specific target type, you can use
+	L{getRelations} and pass one of the following constants as the
+	parameter:
+
+	 - L{Relation.TO_ARTIST}
+	 - L{Relation.TO_RELEASE}
+	 - L{Relation.TO_TRACK}
+	 - L{Relation.TO_URL}
+
+	@see: L{Relation}
+	"""
+
+	def __init__(self, id_=None):
+		"""Constructor.
+
+		This should only used by derived classes.
+
+		@param id_: a string containing an absolute URI
+		"""
+		self._id = id_
+		self._relations = { }
+		self._tags = { }
+		self._rating = Rating()
+
+	def getId(self):
+		"""Returns a MusicBrainz ID.
+
+		@return: a string containing a URI, or None
+		"""
+		return self._id
+
+	def setId(self, value):
+		"""Sets a MusicBrainz ID.
+
+		@param value: a string containing an absolute URI 
+		"""
+		self._id = value
+
+	id = property(getId, setId, doc='The MusicBrainz ID.')
+
+	def getRelations(self, targetType=None, relationType=None,
+			requiredAttributes=(), direction=None):
+		"""Returns a list of relations.
+
+		If C{targetType} is given, only relations of that target
+		type are returned. For MusicBrainz, the following target
+		types are defined:
+		 - L{Relation.TO_ARTIST}
+		 - L{Relation.TO_RELEASE}
+		 - L{Relation.TO_TRACK}
+		 - L{Relation.TO_URL}
+
+		If C{targetType} is L{Relation.TO_ARTIST}, for example,
+		this method returns all relations between this Entity and
+		artists.
+
+		You may use the C{relationType} parameter to further restrict
+		the selection. If it is set, only relations with the given
+		relation type are returned. The C{requiredAttributes} sequence
+		lists attributes that have to be part of all returned relations.
+
+		If C{direction} is set, only relations with the given reading
+		direction are returned. You can use the L{Relation.DIR_FORWARD},
+		L{Relation.DIR_BACKWARD}, and L{Relation.DIR_NONE} constants
+		for this.
+
+		@param targetType: a string containing an absolute URI, or None
+		@param relationType: a string containing an absolute URI, or None
+		@param requiredAttributes: a sequence containing absolute URIs
+		@param direction: one of L{Relation}'s direction constants
+		@return: a list of L{Relation} objects
+
+		@see: L{Entity}
+		"""
+		allRels = [ ]
+		if targetType is not None:
+			allRels = self._relations.setdefault(targetType, [ ])
+		else:
+			for (k, relList) in self._relations.items():
+				for rel in relList:
+					allRels.append(rel)
+
+		# Filter for direction.
+		#
+		if direction is not None:
+			allRels = [r for r in allRels if r.getDirection() == direction]
+
+		# Filter for relation type.
+		#
+		if relationType is None:
+			return allRels
+		else:
+			allRels = [r for r in allRels if r.getType() == relationType]
+
+		# Now filer for attribute type.
+		#
+		tmp = []
+		required = set(iter(requiredAttributes))
+
+		for r in allRels:
+			attrs = set(iter(r.getAttributes()))
+			if required.issubset(attrs):
+				tmp.append(r)
+		return tmp
+
+
+	def getRelationTargets(self, targetType=None, relationType=None,
+			requiredAttributes=(), direction=None):
+		"""Returns a list of relation targets.
+
+		The arguments work exactly like in L{getRelations}, but
+		instead of L{Relation} objects, the matching relation
+		targets are returned. This can be L{Artist}, L{Release},
+		or L{Track} objects, depending on the relations.
+
+		As a special case, URL strings are returned if the target
+		is an URL.
+
+		@param targetType: a string containing an absolute URI, or None
+		@param relationType: a string containing an absolute URI, or None
+		@param requiredAttributes: a sequence containing absolute URIs
+		@param direction: one of L{Relation}'s direction constants
+		@return: a list of objects, depending on the relation
+
+		@see: L{getRelations}
+		"""
+		ret = [ ]
+		rels =  self.getRelations(targetType, relationType,
+			requiredAttributes, direction)
+
+		for r in rels:
+			if r.getTargetType() == Relation.TO_URL:
+				ret.append(r.getTargetId())
+			else:
+				ret.append(r.getTarget())
+
+		return ret
+
+
+	def addRelation(self, relation):
+		"""Adds a relation.
+
+		This method adds C{relation} to the list of relations. The
+		given relation has to be initialized, at least the target
+		type has to be set.
+
+		@param relation: the L{Relation} object to add
+
+		@see: L{Entity}
+		"""
+		assert relation.getType is not None
+		assert relation.getTargetType is not None
+		assert relation.getTargetId is not None
+		l = self._relations.setdefault(relation.getTargetType(), [ ])
+		l.append(relation)
+
+
+	def getRelationTargetTypes(self):
+		"""Returns a list of target types available for this entity.
+
+		Use this to find out to which types of targets this entity
+		has relations. If the entity only has relations to tracks and
+		artists, for example, then a list containg the strings
+		L{Relation.TO_TRACK} and L{Relation.TO_ARTIST} is returned.
+
+		@return: a list of strings containing URIs
+
+		@see: L{getRelations}
+		"""
+		return self._relations.keys()
+
+	def getTag(self, value):
+		"""Return the tag with the given value (aka the tag's name).
+
+		@return: the L{Tag} with the given name or raises a KeyError
+		"""
+		return self._tags[value]
+
+	def getTags(self):
+		"""Return all tags attached to this Entity.
+
+		@return: a list of L{Tag} objects
+		"""
+		return self._tags.values()
+
+	tags = property(getTags, doc='The tags for this entity.')
+
+	def addTag(self, tag):
+		"""Add a new tag.
+
+		This merges an existing tag with the same name.
+
+		@param tag: the L{Tag} object to add
+
+		@see: L{getTags}
+		"""
+		if self._tags.has_key(tag.value):
+			existing = self._tags[tag.value]
+			existing.count += tag.count
+		else:
+			self._tags[tag.value] = tag
+
+	def getRating(self):
+		"""Return the rating of this Entity.
+		0 = Unrated
+		1 - 5 = Rating
+
+		@return: rating
+		"""
+		return self._rating
+
+	rating = property(getRating, doc='The rating for this entity.')
+
+	def setRating(self, value):
+		self._rating = value
+		
+
+class Artist(Entity):
+	"""Represents an artist.
+
+	Artists in MusicBrainz can have a type. Currently, this type can
+	be either Person or Group for which the following URIs are assigned:
+
+	 - C{http://musicbrainz.org/ns/mmd-1.0#Person}
+	 - C{http://musicbrainz.org/ns/mmd-1.0#Group}
+
+	Use the L{TYPE_PERSON} and L{TYPE_GROUP} constants for comparison.
+	"""
+	TYPE_PERSON = NS_MMD_1 + 'Person'
+	TYPE_GROUP = NS_MMD_1 + 'Group'
+
+	def __init__(self, id_=None, type_=None, name=None, sortName=None):
+		"""Constructor.
+
+		@param id_: a string containing an absolute URI
+		@param type_: a string containing an absolute URI
+		@param name: a string containing the artist's name
+		@param sortName: a string containing the artist's sort name
+		"""
+		Entity.__init__(self, id_)
+		self._type = type_
+		self._name = name
+		self._sortName = sortName
+		self._disambiguation = None
+		self._beginDate = None
+		self._endDate = None
+		self._aliases = [ ]
+		self._releases = [ ]
+		self._releasesCount = None
+		self._releasesOffset = None
+		self._releaseGroups = [ ]
+		self._releaseGroupsCount = None
+		self._releaseGroupsOffset = None
+
+	def getType(self):
+		"""Returns the artist's type.
+
+		@return: a string containing an absolute URI, or None 
+		"""
+		return self._type
+
+	def setType(self, type_):
+		"""Sets the artist's type.
+
+		@param type_: a string containing an absolute URI
+		"""
+		self._type = type_
+
+	type = property(getType, setType, doc="The artist's type.")
+
+	def getName(self):
+		"""Returns the artist's name.
+
+		@return: a string containing the artist's name, or None
+		"""
+		return self._name
+
+	def setName(self, name):
+		"""Sets the artist's name.
+
+		@param name: a string containing the artist's name
+		"""
+		self._name = name
+
+	name = property(getName, setName, doc="The artist's name.")
+
+	def getSortName(self):
+		"""Returns the artist's sort name.
+
+		The sort name is the artist's name in a special format which
+		is better suited for lexicographic sorting. The MusicBrainz
+		style guide specifies this format.
+
+		@see: U{The MusicBrainz Style Guidelines
+			}
+		"""
+		return self._sortName
+
+	def setSortName(self, sortName):
+		"""Sets the artist's sort name.
+
+		@param sortName: a string containing the artist's sort name
+
+		@see: L{getSortName}
+		"""
+		self._sortName = sortName
+
+	sortName = property(getSortName, setSortName,
+		doc="The artist's sort name.")
+
+	def getDisambiguation(self):
+		"""Returns the disambiguation attribute.
+
+		This attribute may be used if there is more than one artist
+		with the same name. In this case, disambiguation attributes
+		are added to the artists' names to keep them apart.
+
+		For example, there are at least three bands named 'Vixen'.
+		Each band has a different disambiguation in the MusicBrainz
+		database, like 'Hip-hop' or 'all-female rock/glam band'.
+
+		@return: a disambiguation string, or None
+
+		@see: L{getUniqueName}
+		"""
+		return self._disambiguation
+
+	def setDisambiguation(self, disambiguation):
+		"""Sets the disambiguation attribute.
+
+		@param disambiguation: a disambiguation string
+
+		@see: L{getDisambiguation}, L{getUniqueName}
+		"""
+		self._disambiguation = disambiguation
+
+	disambiguation = property(getDisambiguation, setDisambiguation,
+		doc="The disambiguation comment.")
+
+	def getUniqueName(self):
+		"""Returns a unique artist name (using disambiguation).
+
+		This method returns the artist name together with the
+		disambiguation attribute in parenthesis if it exists.
+		Example: 'Vixen (Hip-hop)'.
+
+		@return: a string containing the unique name
+
+		@see: L{getDisambiguation}
+		"""
+		d = self.getDisambiguation() 
+		if d is not None and d.strip() != '':
+			return '%s (%s)' % (self.getName(), d)
+		else: 
+			return self.getName()
+
+	def getBeginDate(self):
+		"""Returns the birth/foundation date.
+
+		The definition of the I{begin date} depends on the artist's
+		type. For persons, this is the day of birth, for groups it
+		is the day the group was founded.
+
+		The returned date has the format 'YYYY', 'YYYY-MM', or 
+		'YYYY-MM-DD', depending on how much detail is known.
+
+		@return: a string containing the date, or None
+
+		@see: L{getType}
+		"""
+		return self._beginDate
+
+	def setBeginDate(self, dateStr):
+		"""Sets the begin/foundation date.
+
+		@param dateStr: a date string
+
+		@see: L{getBeginDate}
+		"""
+		self._beginDate = dateStr
+
+	beginDate = property(getBeginDate, setBeginDate,
+		doc="The begin/foundation date.")
+
+	def getEndDate(self):
+		"""Returns the death/dissolving date.
+
+		The definition of the I{end date} depends on the artist's
+		type. For persons, this is the day of death, for groups it
+		is the day the group was dissolved.
+
+		@return: a string containing a date, or None
+
+		@see: L{getBeginDate}
+		"""
+		return self._endDate
+
+	def setEndDate(self, dateStr):
+		"""Sets the death/dissolving date.
+
+		@param dateStr: a string containing a date
+
+		@see: L{setEndDate}, L{getBeginDate}
+		"""
+		self._endDate = dateStr
+
+	endDate = property(getEndDate, setEndDate,
+		doc="The death/dissolving date.")
+
+	def getAliases(self):
+		"""Returns the list of aliases for this artist.
+
+		@return: a list of L{ArtistAlias} objects
+		"""
+		return self._aliases
+
+	aliases = property(getAliases, doc='The list of aliases.')
+
+	def addAlias(self, alias):
+		"""Adds an alias for this artist.
+		
+		@param alias: an L{ArtistAlias} object
+		"""
+		self._aliases.append(alias)
+
+	def getReleases(self):
+		"""Returns a list of releases from this artist.
+
+		This may also include releases where this artist isn't the
+		I{main} artist but has just contributed one or more tracks
+		(aka VA-Releases).
+
+		@return: a list of L{Release} objects
+		"""
+		return self._releases
+
+	releases = property(getReleases, doc='The list of releases')
+
+	def addRelease(self, release):
+		"""Adds a release to this artist's list of releases.
+
+		@param release: a L{Release} object
+		"""
+		self._releases.append(release)
+
+	def getReleasesOffset(self):
+		"""Returns the offset of the release list.
+
+		This is used if the release list is incomplete (ie. the web
+		service only returned part of the release for this artist).
+		Note that the offset value is zero-based, which means release
+		C{0} is the first release.
+
+		@return: an integer containing the offset, or None
+
+		@see: L{getReleases}, L{getReleasesCount}
+		"""
+		return self._releasesOffset
+
+	def setReleasesOffset(self, offset):
+		"""Sets the offset of the release list.
+
+		@param offset: an integer containing the offset, or None
+
+		@see: L{getReleasesOffset}
+		"""
+		self._releasesOffset = offset
+
+	releasesOffset = property(getReleasesOffset, setReleasesOffset,
+		doc='The offset of the release list.')
+
+	def getReleasesCount(self):
+		"""Returns the number of existing releases.
+	
+		This may or may not match with the number of elements that
+		L{getReleases} returns. If the count is higher than
+		the list, it indicates that the list is incomplete.
+
+		@return: an integer containing the count, or None
+
+		@see: L{setReleasesCount}, L{getReleasesOffset}
+		"""
+		return self._releasesCount
+
+	def setReleasesCount(self, value):
+		"""Sets the number of existing releases.
+
+		@param value: an integer containing the count, or None
+
+		@see: L{getReleasesCount}, L{setReleasesOffset}
+		"""
+		self._releasesCount = value
+
+	releasesCount = property(getReleasesCount, setReleasesCount,
+		doc='The total number of releases')
+
+	def getReleaseGroups(self):
+		"""Returns a list of release groups from this artist.
+		
+		@return: a list of L{ReleaseGroup} objects
+		"""
+		return self._releaseGroups
+	
+	releaseGroups = property(getReleaseGroups, doc='The list of release groups')
+	
+	def addReleaseGroup(self, releaseGroup):
+		"""Adds a release group to this artist's list of release groups.
+		
+		@param releaseGroup: a L{ReleaseGroup} object
+		"""
+		self._releaseGroups.append(releaseGroup)
+
+	def getReleaseGroupsOffset(self):
+		"""Returns the offset of the release group list.
+
+		This is used if the release group list is incomplete (ie. the
+		web service only returned part of the result for this artist).
+		Note that the offset value is zero-based, which means release
+		group C{0} is the first release group.
+
+		@return: an integer containing the offset, or None
+
+		@see: L{getReleaseGroups}, L{getReleaseGroupsCount}
+		"""
+		return self._releaseGroupsOffset
+
+	def setReleaseGroupsOffset(self, offset):
+		"""Sets the offset of the release group list.
+
+		@param offset: an integer containing the offset, or None
+
+		@see: L{getReleaseGroupsOffset}
+		"""
+		self._releaseGroupsOffset = offset
+
+	releaseGroupsOffset = property(getReleaseGroupsOffset, setReleaseGroupsOffset,
+		doc='The offset of the release group list.')
+
+	def getReleaseGroupsCount(self):
+		"""Returns the number of existing release groups.
+
+		This may or may not match with the number of elements that
+		L{getReleaseGroups} returns. If the count is higher than
+		the list, it indicates that the list is incomplete.
+
+		@return: an integer containing the count, or None
+
+		@see: L{setReleaseGroupsCount}, L{getReleaseGroupsOffset}
+		"""
+		return self._releaseGroupsCount
+
+	def setReleaseGroupsCount(self, value):
+		"""Sets the number of existing release groups.
+
+		@param value: an integer containing the count, or None
+
+		@see: L{getReleaseGroupsCount}, L{setReleaseGroupsOffset}
+		"""
+		self._releaseGroupsCount = value
+
+	releasesCount = property(getReleaseGroupsCount, setReleaseGroupsCount,
+		doc='The total number of release groups')
+
+
+class Rating(object):
+	"""The representation of a MusicBrain rating.
+
+	The rating can have the following values:
+
+	0 = Unrated
+	[1..5] = Rating
+	"""
+	def __init__(self, value=None, count=None):
+		"""Constructor.
+
+		@param value: a string containing the tag's value
+		@param count: the number of users who added this tag
+		"""
+		self._value = value
+		self._count = count
+
+	def getValue(self):
+		"""Returns a string with the tag's value.
+
+		@return: an integer containing the rating's value, or None
+		"""
+		return self._value
+
+	def setValue(self, value):
+		""" Set the value of this rating.
+
+		0 or None = Clear your rating
+		1 - 5 = Rating
+
+		@param value: the rating to apply
+
+		@raise ValueError: if value is not a double or not in the
+		range 0 - 5 or None.
+		"""
+		if value == None:
+		  value = 0
+		try:
+		  value = float(value)
+		except ValueError, e:
+		  raise ValueError("Value for rating needs to be an" \
+		      "float.")
+		if value < 0.0 or value > 5.0:
+		  raise ValueError("Value needs to be in the range [0..5]")
+		self._value = value
+
+	value = property(getValue, setValue, doc='The value of the rating.')
+
+	def getCount(self):
+		"""Returns an integer containing the rating's frequency count.
+
+		@return: an integer containing the rating's frequency count,
+		or None
+		"""
+		return self._count
+	
+	def setCount(self, count):
+		"""Sets the frequency count of this rating.
+		
+		@param count: an integer containing the tag's frequency count
+		"""
+		self._count = count
+		
+	count = property(getCount, setCount, doc="This tag's frequency count.")
+
+	def __str__(self):
+		return str(self._value)
+
+	def __unicode__(self):
+		return unicode(self._value)
+
+
+class Tag(object):
+	"""The representation of a MusicBrainz folksonomy tag.
+
+	The tag's value is the text that's displayed in the tag cloud.
+	The count attribute keeps track of how many users added the tag
+	to its owning entity.
+	"""
+	def __init__(self, value=None, count=None):
+		"""Constructor.
+
+		@param value: a string containing the tag's value
+		@param count: the number of users who added this tag
+		"""
+		self._value = value
+		self._count = count
+
+	def getValue(self):
+		"""Returns a string with the tag's value.
+
+		@return: a string containing the tags's value, or None
+		"""
+		return self._value
+	
+	def setValue(self, value):
+		"""Sets the value of this tag.
+		
+		@param value: A string containing the value of the tag
+		"""
+		self._value = value
+		
+	value = property(getValue, setValue, doc='The value of the text.')
+
+	def getCount(self):
+		"""Returns an integer containing the tag's frequency count.
+
+		@return: an integer containing the tags's frequency count, or None
+		"""
+		return self._count
+	
+	def setCount(self, count):
+		"""Sets the frequency count of this tag.
+		
+		@param count: an integer containing the tag's frequency count
+		"""
+		self._count = count
+		
+	count = property(getCount, setCount, doc="This tag's frequency count.")
+
+	def __str__(self):
+		return str(self._value)
+
+	def __unicode__(self):
+		return unicode(self._value)
+
+
+class Label(Entity):
+	"""Represents a record label.
+	
+	A label within MusicBrainz is an L{Entity}. It contains information
+	about the label like when it was established, its name, label code and
+	other relationships. All release events may be assigned a label.
+	"""
+	TYPE_UNKNOWN = NS_MMD_1 + 'Unknown'
+	
+	TYPE_DISTRIBUTOR = NS_MMD_1 + 'Distributor'
+	TYPE_HOLDING = NS_MMD_1 + 'Holding'
+	TYPE_PRODUCTION = NS_MMD_1 + 'Production'
+	
+	TYPE_ORIGINAL = NS_MMD_1 + 'OriginalProduction'
+	TYPE_BOOTLEG = NS_MMD_1 + 'BootlegProduction'
+	TYPE_REISSUE = NS_MMD_1 + 'ReissueProduction'
+	
+	def __init__(self, id_=None):
+		"""Constructor.
+
+		@param id_: a string containing an absolute URI
+		"""
+		Entity.__init__(self, id_)
+		self._type = None
+		self._name = None
+		self._sortName = None
+		self._disambiguation = None
+		self._countryId = None
+		self._code = None
+		self._beginDate = None
+		self._endDate = None
+		self._aliases = [ ]
+	
+	def getType(self):
+		"""Returns the type of this label.
+
+		@return: a string containing an absolute URI
+		"""
+		return self._type
+	
+	def setType(self, type_):
+		"""Sets the type of this label.
+		
+		@param type_: A string containing the absolute URI of the type of label.
+		"""
+		self._type = type_
+	
+	type = property(getType, setType, doc='The type of label')
+	
+	def getName(self):
+		"""Returns a string with the name of the label.
+
+		@return: a string containing the label's name, or None
+		"""
+		return self._name
+	
+	def setName(self, name):
+		"""Sets the name of this label.
+		
+		@param name: A string containing the name of the label
+		"""
+		self._name = name
+		
+	name = property(getName, setName, doc='The name of the label.')
+	
+	def getSortName(self):
+		"""Returns the label's sort name.
+
+		The sort name is the label's name in a special format which
+		is better suited for lexicographic sorting. The MusicBrainz
+		style guide specifies this format.
+
+		@see: U{The MusicBrainz Style Guidelines
+			}
+		"""
+		return self._sortName
+
+	def setSortName(self, sortName):
+		"""Sets the label's sort name.
+
+		@param sortName: a string containing the label's sort name
+
+		@see: L{getSortName}
+		"""
+		self._sortName = sortName
+
+	sortName = property(getSortName, setSortName,
+		doc="The label's sort name.")
+
+	def getDisambiguation(self):
+		"""Returns the disambiguation attribute.
+
+		This attribute may be used if there is more than one label
+		with the same name. In this case, disambiguation attributes
+		are added to the labels' names to keep them apart.
+
+		@return: a disambiguation string, or None
+
+		@see: L{getUniqueName}
+		"""
+		return self._disambiguation
+
+	def setDisambiguation(self, disambiguation):
+		"""Sets the disambiguation attribute.
+
+		@param disambiguation: a disambiguation string
+
+		@see: L{getDisambiguation}, L{getUniqueName}
+		"""
+		self._disambiguation = disambiguation
+
+	disambiguation = property(getDisambiguation, setDisambiguation,
+		doc="The disambiguation comment.")
+
+	def getUniqueName(self):
+		"""Returns a unique label name (using disambiguation).
+
+		This method returns the label's name together with the
+		disambiguation attribute in parenthesis if it exists.
+
+		@return: a string containing the unique name
+
+		@see: L{getDisambiguation}
+		"""
+		d = self.getDisambiguation() 
+		if d is not None and d.strip() != '':
+			return '%s (%s)' % (self.getName(), d)
+		else: 
+			return self.getName()
+
+	def getBeginDate(self):
+		"""Returns the date this label was established.
+		
+		@return: A string contained the start date, or None
+		"""
+		return self._beginDate
+	
+	def setBeginDate(self, date):
+		"""Set the date this label was established.
+		
+		@param date: A string in the format of YYYY-MM-DD
+		"""
+		self._beginDate = date
+	
+	beginDate = property(getBeginDate, setBeginDate,
+		doc='The date this label was established.')
+
+	def getEndDate(self):
+		"""Returns the date this label closed.
+
+		The returned date has the format 'YYYY', 'YYYY-MM', or 
+		'YYYY-MM-DD', depending on how much detail is known.
+		
+		@return: A string containing the date, or None
+		"""
+		return self._endDate
+	
+	def setEndDate(self, date):
+		"""Set the date this label closed.
+
+		The date may have the format 'YYYY', 'YYYY-MM', or 
+		'YYYY-MM-DD', depending on how much detail is known.
+		
+		@param date: A string containing the date, or None
+		"""
+		self._endDate = date
+	
+	endDate = property(getEndDate, setEndDate,
+		doc='The date this label closed.')
+		
+	def getCountry(self):
+		"""Returns the country the label is located.
+
+		@return: a string containing an ISO-3166 country code, or None
+
+		@see: L{musicbrainz2.utils.getCountryName}
+		"""
+		return self._countryId
+
+	def setCountry(self, country):
+		"""Sets the country the label is located.
+
+		@param country: a string containing an ISO-3166 country code
+		"""
+		self._countryId = country
+
+	country = property(getCountry, setCountry,
+		doc='The country the label is located.')
+
+	def getCode(self):
+		"""Returns the label code.
+
+		Label codes have been introduced by the IFPI (International
+		Federation of Phonogram and Videogram Industries) to uniquely
+		identify record labels. The label code consists of 'LC-' and 4
+		figures (currently being extended to 5 figures).
+
+		@return: a string containing the label code, or None
+		"""
+		return self._code
+
+	def setCode(self, code):
+		"""Sets the label code.
+
+		@param code: a string containing the label code
+		"""
+		self._code = code
+
+	code = property(getCode, setCode,
+		doc='The label code.')
+
+	def getAliases(self):
+		"""Returns the list of aliases for this label.
+
+		@return: a list of L{LabelAlias} objects
+		"""
+		return self._aliases
+
+	aliases = property(getAliases, doc='The list of aliases.')
+
+	def addAlias(self, alias):
+		"""Adds an alias for this label.
+		
+		@param alias: a L{LabelAlias} object
+		"""
+		self._aliases.append(alias)
+
+
+class Release(Entity):
+	"""Represents a Release.
+
+	A release within MusicBrainz is an L{Entity} which contains L{Track}
+	objects.  Releases may be of more than one type: There can be albums,
+	singles, compilations, live recordings, official releases, bootlegs
+	etc.
+
+	@note: The current MusicBrainz server implementation supports only a
+	limited set of types.
+	"""
+	TYPE_NONE = NS_MMD_1 + 'None'
+	TYPE_NON_ALBUM_TRACKS = NS_MMD_1 + "NonAlbum Track"
+
+	TYPE_ALBUM = NS_MMD_1 + 'Album'
+	TYPE_SINGLE = NS_MMD_1 + 'Single'
+	TYPE_EP = NS_MMD_1 + 'EP'
+	TYPE_COMPILATION = NS_MMD_1 + 'Compilation'
+	TYPE_SOUNDTRACK = NS_MMD_1 + 'Soundtrack'
+	TYPE_SPOKENWORD = NS_MMD_1 + 'Spokenword'
+	TYPE_INTERVIEW = NS_MMD_1 + 'Interview'
+	TYPE_AUDIOBOOK = NS_MMD_1 + 'Audiobook'
+	TYPE_LIVE = NS_MMD_1 + 'Live'
+	TYPE_REMIX = NS_MMD_1 + 'Remix'
+	TYPE_OTHER = NS_MMD_1 + 'Other'
+
+	TYPE_OFFICIAL = NS_MMD_1 + 'Official'
+	TYPE_PROMOTION = NS_MMD_1 + 'Promotion'
+	TYPE_BOOTLEG = NS_MMD_1 + 'Bootleg'
+	TYPE_PSEUDO_RELEASE = NS_MMD_1 + 'Pseudo-Release'
+
+	def __init__(self, id_=None, title=None):
+		"""Constructor.
+
+		@param id_: a string containing an absolute URI
+		@param title: a string containing the title
+		"""
+		Entity.__init__(self, id_)
+		self._types = [ ]
+		self._title = title
+		self._textLanguage = None
+		self._textScript = None
+		self._asin = None
+		self._artist = None
+		self._releaseEvents = [ ]
+		#self._releaseEventsCount = None
+		self._releaseGroup = None
+		self._discs = [ ]
+		#self._discIdsCount = None
+		self._tracks = [ ]
+		self._tracksOffset = None
+		self._tracksCount = None
+
+
+	def getTypes(self):
+		"""Returns the types of this release.
+
+		To test for release types, you can use the constants
+		L{TYPE_ALBUM}, L{TYPE_SINGLE}, etc.
+
+		@return: a list of strings containing absolute URIs
+
+		@see: L{musicbrainz2.utils.getReleaseTypeName}
+		"""
+		return self._types
+
+	types = property(getTypes, doc='The list of types for this release.')
+
+	def addType(self, type_):
+		"""Add a type to the list of types.
+
+		@param type_: a string containing absolute URIs
+
+		@see: L{getTypes}
+		"""
+		self._types.append(type_)
+
+	def getTitle(self):
+		"""Returns the release's title.
+
+		@return: a string containing the release's title
+		"""
+		return self._title
+
+	def setTitle(self, title):
+		"""Sets the release's title.
+
+		@param title: a string containing the release's title, or None
+		"""
+		self._title = title
+
+	title = property(getTitle, setTitle, doc='The title of this release.')
+
+	def getTextLanguage(self):
+		"""Returns the language used in release and track titles.
+
+		To represent the language, the ISO-639-2/T standard is used,
+		which provides three-letter terminological language codes like
+		'ENG', 'DEU', 'JPN', 'KOR', 'ZHO' or 'YID'.
+
+		Note that this refers to release and track I{titles}, not
+		lyrics.
+
+		@return: a string containing the language code, or None
+
+		@see: L{musicbrainz2.utils.getLanguageName}
+		"""
+		return self._textLanguage
+
+	def setTextLanguage(self, language):
+		"""Sets the language used in releaes and track titles.
+
+		@param language: a string containing a language code
+
+		@see: L{getTextLanguage}
+		"""
+		self._textLanguage = language
+
+	textLanguage = property(getTextLanguage, setTextLanguage,
+		doc='The language used in release and track titles.')
+
+	def getTextScript(self):
+		"""Returns the script used in release and track titles.
+
+		To represent the script, ISO-15924 script codes are used.
+		Valid codes are, among others: 'Latn', 'Cyrl', 'Hans', 'Hebr'
+
+		Note that this refers to release and track I{titles}, not
+		lyrics.
+
+		@return: a string containing the script code, or None
+
+		@see: L{musicbrainz2.utils.getScriptName}
+		"""
+		return self._textScript
+
+	def setTextScript(self, script):
+		"""Sets the script used in releaes and track titles.
+
+		@param script: a string containing a script code
+
+		@see: L{getTextScript}
+		"""
+		self._textScript = script
+
+	textScript = property(getTextScript, setTextScript,
+		doc='The script used in release and track titles.')
+
+	def getAsin(self):
+		"""Returns the amazon shop identifier (ASIN).
+
+		The ASIN is a 10-letter code (except for books) assigned
+		by Amazon, which looks like 'B000002IT2' or 'B00006I4YD'.
+
+		@return: a string containing the ASIN, or None
+		"""
+		return self._asin
+
+	def setAsin(self, asin):
+		"""Sets the amazon shop identifier (ASIN).
+
+		@param asin: a string containing the ASIN
+
+		@see: L{getAsin}
+		"""
+		self._asin = asin
+
+	asin = property(getAsin, setAsin, doc='The amazon shop identifier.')
+
+	def getArtist(self):
+		"""Returns the main artist of this release.
+
+		@return: an L{Artist} object, or None
+		"""
+		return self._artist
+
+	def setArtist(self, artist):
+		"""Sets this release's main artist.
+
+		@param artist: an L{Artist} object
+		"""
+		self._artist = artist
+
+	artist = property(getArtist, setArtist,
+		doc='The main artist of this release.')
+
+	def getReleaseGroup(self):
+		"""Returns the release group to which this release belongs.
+		
+		@return: a L{ReleaseGroup} object, or None.
+		"""
+		return self._releaseGroup
+
+	def setReleaseGroup(self, releaseGroup):
+		"""Sets the release's release group.
+		
+		@param releaseGroup: a L{ReleaseGroup} object, or None.
+		"""
+		self._releaseGroup = releaseGroup
+
+	releaseGroup = property(getReleaseGroup, setReleaseGroup,
+		doc='The release group this release belongs to.')
+
+	def isSingleArtistRelease(self):
+		"""Checks if this is a single artist's release.
+
+		Returns C{True} if the release's main artist (L{getArtist}) is
+		also the main artist for all of the tracks. This is checked by
+		comparing the artist IDs.
+
+		Note that the release's artist has to be set (see L{setArtist})
+		for this. The track artists may be unset.
+
+		@return: True, if this is a single artist's release
+		"""
+		releaseArtist = self.getArtist()
+		assert releaseArtist is not None, 'Release Artist may not be None!'
+		for track in self.getTracks():
+			if track.getArtist() is None:
+				continue
+			if track.getArtist().getId() != releaseArtist.getId():
+				return False
+
+		return True
+
+	def getTracks(self):
+		"""Returns the tracks this release contains.
+
+		@return: a list containing L{Track} objects
+
+		@see: L{getTracksOffset}, L{getTracksCount}
+		"""
+		return self._tracks
+
+	tracks = property(getTracks, doc='The list of tracks.')
+
+	def addTrack(self, track):
+		"""Adds a track to this release.
+
+		This appends a track at the end of this release's track list.
+
+		@param track: a L{Track} object
+		"""
+		self._tracks.append(track)
+
+	def getTracksOffset(self):
+		"""Returns the offset of the track list.
+
+		This is used if the track list is incomplete (ie. the web
+		service only returned part of the tracks on this release).
+		Note that the offset value is zero-based, which means track
+		C{0} is the first track.
+
+		@return: an integer containing the offset, or None
+
+		@see: L{getTracks}, L{getTracksCount}
+		"""
+		return self._tracksOffset
+
+	def setTracksOffset(self, offset):
+		"""Sets the offset of the track list.
+
+		@param offset: an integer containing the offset, or None
+
+		@see: L{getTracksOffset}, L{setTracksCount}
+		"""
+		self._tracksOffset = offset
+
+	tracksOffset = property(getTracksOffset, setTracksOffset,
+		doc='The offset of the track list.')
+
+	def getTracksCount(self):
+		"""Returns the number of tracks on this release.
+	
+		This may or may not match with the number of elements that
+		L{getTracks} returns. If the count is higher than
+		the list, it indicates that the list is incomplete.
+
+		@return: an integer containing the count, or None
+
+		@see: L{setTracksCount}, L{getTracks}, L{getTracksOffset}
+		"""
+		return self._tracksCount
+
+	def setTracksCount(self, value):
+		"""Sets the number of tracks on this release.
+
+		@param value: an integer containing the count, or None
+
+		@see: L{getTracksCount}, L{setTracksOffset}
+		"""
+		self._tracksCount = value
+
+	tracksCount = property(getTracksCount, setTracksCount,
+		doc='The total number of releases')
+
+
+	def getReleaseEvents(self):
+		"""Returns the list of release events.
+
+		A L{Release} may contain a list of so-called release events,
+		each represented using a L{ReleaseEvent} object. Release
+		evens specify where and when this release was, well, released.
+
+		@return: a list of L{ReleaseEvent} objects
+
+		@see: L{getReleaseEventsAsDict}
+		"""
+		return self._releaseEvents
+
+	releaseEvents = property(getReleaseEvents,
+		doc='The list of release events.')
+
+	def addReleaseEvent(self, event):
+		"""Adds a release event to this release.
+
+		@param event: a L{ReleaseEvent} object
+
+		@see: L{getReleaseEvents}
+		"""
+		self._releaseEvents.append(event)
+
+	def getReleaseEventsAsDict(self):
+		"""Returns the release events represented as a dict.
+
+		Keys are ISO-3166 country codes like 'DE', 'UK', 'FR' etc.
+		Values are dates in 'YYYY', 'YYYY-MM' or 'YYYY-MM-DD' format.
+
+		@return: a dict containing (countryCode, date) entries
+
+		@see: L{getReleaseEvents}, L{musicbrainz2.utils.getCountryName}
+		"""
+		d = { }
+		for event in self.getReleaseEvents():
+			d[event.getCountry()] = event.getDate()
+		return d
+
+	def getEarliestReleaseDate(self):
+		"""Returns the earliest release date.
+
+		This favours complete dates. For example, '2006-09' is
+		returned if there is '2000', too. If there is no release
+		event associated with this release, None is returned.
+
+		@return: a string containing the date, or None 
+
+		@see: L{getReleaseEvents}, L{getReleaseEventsAsDict}
+		"""
+		event = self.getEarliestReleaseEvent()
+
+		if event is None:
+			return None
+		else:
+			return event.getDate()
+
+	def getEarliestReleaseEvent(self):
+		"""Returns the earliest release event.
+
+		This works like L{getEarliestReleaseDate}, but instead of
+		just the date, this returns a L{ReleaseEvent} object.
+
+		@return: a L{ReleaseEvent} object, or None 
+
+		@see: L{getReleaseEvents}, L{getEarliestReleaseDate}
+		"""
+		dates = [ ]
+		for event in self.getReleaseEvents():
+			date = event.getDate()
+			if len(date) == 10:    # 'YYYY-MM-DD'
+				dates.append( (date, event) )
+			elif len(date) == 7:   # 'YYYY-MM'
+				dates.append( (date + '-99', event) )
+			else:
+				dates.append( (date + '-99-99', event) )
+
+		dates.sort(lambda x, y: cmp(x[0], y[0]))
+
+		if len(dates) > 0:
+			return dates[0][1]
+		else:
+			return None
+
+
+	#def getReleaseEventsCount(self):
+	#	"""Returns the number of release events.
+	#
+	#	This may or may not match with the number of elements that
+	#	getReleaseEvents() returns. If the count is higher than
+	#	the list, it indicates that the list is incomplete.
+	#	"""
+	#	return self._releaseEventsCount
+
+	#def setReleaseEventsCount(self, value):
+	#	self._releaseEventsCount = value
+
+	def getDiscs(self):
+		"""Returns the discs associated with this release.
+
+		Discs are currently containers for MusicBrainz DiscIDs.
+		Note that under rare circumstances (identical TOCs), a
+		DiscID could be associated with more than one release.
+
+		@return: a list of L{Disc} objects
+		"""
+		return self._discs
+
+	discs = property(getDiscs, doc='The list of associated discs.')
+
+	def addDisc(self, disc):
+		"""Adds a disc to this release.
+
+		@param disc: a L{Disc} object
+		"""
+		self._discs.append(disc)
+
+	#def getDiscIdsCount(self):
+	#	return self._discIdsCount
+
+	#def setDiscIdsCount(self, value):
+	#	self._discIdsCount = value
+
+
+class ReleaseGroup(Entity):
+	"""Represents a ReleaseGroup.
+
+	A ReleaseGroup in MusicBrainz is an L{Entity} which groups several different
+	versions of L{Release} objects (e.g., different editions of the same album).
+
+	@see: L{Release}
+	@see: L{Entity}
+	"""
+
+	def __init__(self, id_=None, title=None):
+		"""Constructor.
+
+		@param id_: a string containing an absolute URI
+		@param title: a string containing the title
+		"""
+		Entity.__init__(self, id_)
+		self._title = title
+		self._id = id_
+		self._type = None
+		self._releases = [ ]
+		self._artist = None
+		self._releasesOffset = 0
+		self._releasesCount = 0
+
+	def getType(self):
+		"""Returns the type of this release group.
+
+		To test for release types, you can use the constants
+		L{Release.TYPE_ALBUM}, L{Release.TYPE_SINGLE}, etc.
+
+		@return: a string containing an absolute URI, or None.
+
+		@see: L{musicbrainz2.utils.getReleaseTypeName}
+		"""
+		return self._type
+
+	def setType(self, type_):
+		"""Sets the type of this release group.
+
+		Use a constant from the L{Release} class, such as
+		L{Release.TYPE_ALBUM} or L{Release.TYPE_SINGLE} to
+		set the value.
+
+		@param type_: a string containing an absolute URI, or None.
+		
+		@see: L{musicbrainz2.utils.getReleaseTypeName}
+		"""
+		self._type = type_
+
+	type = property(getType, setType,
+		doc = 'The type of this release group.')
+
+	def getReleases(self):
+		"""Gets the releases in this release group.
+
+		@return: a list of L{Release} objects
+		@see: L{Release}
+		"""
+		return self._releases
+
+	releases = property(getReleases,
+		doc = 'The list of releases in this release group.')
+
+	def addRelease(self, release):
+		"""Adds a L{Release} to this release group.
+
+		@param release: a L{Release} object
+		"""
+		self._releases.append(release)
+
+	def getReleasesOffset(self):
+		"""Returns the offset of the release list.
+
+		This is used if the release list is incomplete (i.e., the web
+		service only returned a portion of the releases in this release
+		group).
+
+		@return: an integer containing the offset, or None.
+		@see: L{getReleases}, L{getReleasesCount}
+		"""
+		return self._releasesOffset
+
+	def setReleasesOffset(self, offset):
+		"""Sets the offset of the release list.
+
+		@param offset: an integer containing the offset, or None.
+		@see: L{getReleases}, L{getReleasesOffset}
+		"""
+		self._releasesOffset = offset
+
+	releasesOffset = property(getReleasesOffset, setReleasesOffset,
+		doc='The offset of the release list.')
+
+	def getReleasesCount(self):
+		"""Returns the number of releases in this release group.
+
+		This may or may not match the number of elements returned by
+		L{getReleases}.  If the count is higher than the length of that
+		list, then the list is incomplete.
+
+		@return: an integer containing the count, or None
+		@see: L{getReleases}, L{setReleasesCount}, L{getReleasesOffset}
+		"""
+		return self._releasesCount
+
+	def setReleasesCount(self, value):
+		"""Sets the number of releases in this release group.
+
+		@param value: an integer containing the count, or None.
+		@see: L{getReleases}, L{getReleasesCount}, L{getReleasesOffset}
+		"""
+		self._releasesCount = value
+
+	releasesCount = property(getReleasesCount, setReleasesCount,
+		doc = 'The total number of releases')
+
+	def getTitle(self):
+		"""Returns this release group's title.
+
+		@return: a string containing the release group's title
+		"""
+		return self._title
+
+	def setTitle(self, title):
+		"""Sets the release group's title.
+
+		@param title: a string containing the release group's title.
+		"""
+		self._title = title
+
+	title = property(getTitle, setTitle,
+		doc = 'The title of this release group.')
+
+	def getArtist(self):
+		"""Returns the main artist of this release group.
+
+		@return: an L{Artist} object, or None
+		"""
+		return self._artist
+
+	def setArtist(self, artist):
+		"""Sets the release group's main artist.
+
+		@param artist: an L{Artist} object
+		"""
+		self._artist = artist
+
+	artist = property(getArtist, setArtist,
+		doc = 'The main artist of this release group')
+
+
+class Track(Entity):
+	"""Represents a track.
+
+	This class represents a track which may appear on one or more releases.
+	A track may be associated with exactly one artist (the I{main} artist).
+
+	Using L{getReleases}, you can find out on which releases this track
+	appears. To get the track number, too, use the
+	L{Release.getTracksOffset} method.
+
+	@note: Currently, the MusicBrainz server doesn't support tracks to
+	       be on more than one release.
+
+	@see: L{Release}, L{Artist}
+	"""
+	def __init__(self, id_=None, title=None):
+		"""Constructor.
+
+		@param id_: a string containing an absolute URI
+		@param title: a string containing the title
+		"""
+		Entity.__init__(self, id_)
+		self._title = title
+		self._artist = None
+		self._duration = None
+		self._puids = [ ]
+		self._releases = [ ]
+		self._isrcs = [ ]
+
+	def getTitle(self):
+		"""Returns the track's title.
+
+		The style and format of this attribute is specified by the
+		style guide.
+
+		@return: a string containing the title, or None
+
+		@see: U{The MusicBrainz Style Guidelines
+			}
+		"""
+		return self._title
+
+	def setTitle(self, title):
+		"""Sets the track's title.
+
+		@param title: a string containing the title
+
+		@see: L{getTitle}
+		"""
+		self._title = title
+
+	title = property(getTitle, setTitle, doc="The track's title.")
+
+	def getArtist(self):
+		"""Returns the main artist of this track.
+
+		@return: an L{Artist} object, or None
+		"""
+		return self._artist
+
+	def setArtist(self, artist):
+		"""Sets this track's main artist.
+
+		@param artist: an L{Artist} object
+		"""
+		self._artist = artist
+
+	artist = property(getArtist, setArtist, doc="The track's main artist.")
+
+	def getDuration(self):
+		"""Returns the duration of this track in milliseconds.
+
+		@return: an int containing the duration in milliseconds, or None
+		"""
+		return self._duration
+
+	def setDuration(self, duration):
+		"""Sets the duration of this track in milliseconds.
+
+		@param duration: an int containing the duration in milliseconds
+		"""
+		self._duration = duration
+
+	duration = property(getDuration, setDuration,
+		doc='The duration in milliseconds.')
+
+	def getDurationSplit(self):
+		"""Returns the duration as a (minutes, seconds) tuple.
+
+		If no duration is set, (0, 0) is returned. Seconds are
+		rounded towards the ceiling if at least 500 milliseconds
+		are left.
+
+		@return: a (minutes, seconds) tuple, both entries being ints
+		"""
+		duration = self.getDuration()
+		if duration is None:
+			return (0, 0)
+		else:
+			seconds = int( round(duration / 1000.0) )
+			return (seconds / 60, seconds % 60)
+
+	def getPuids(self):
+		"""Returns the PUIDs associated with this track.
+
+		Please note that a PUID may be associated with more than one
+		track.
+
+		@return: a list of strings, each containing one PUID
+		"""
+		return self._puids
+
+	puids = property(getPuids, doc='The list of associated PUIDs.')
+
+	def addPuid(self, puid):
+		"""Add a PUID to this track.
+
+		@param puid: a string containing a PUID
+		"""
+		self._puids.append(puid)
+	
+	def getISRCs(self):
+		"""Returns the ISRCs associated with this track.
+
+		@return: a list of strings, each containing one ISRC
+		"""
+		return self._isrcs
+
+	isrcs = property(getISRCs, doc='The list of associated ISRCs')
+
+	def addISRC(self, isrc):
+		"""Add a ISRC to this track.
+
+		@param isrc: a string containing an ISRC
+		"""
+		self._isrcs.append(isrc)
+
+	def getReleases(self):
+		"""Returns the list of releases this track appears on.
+
+		@return: a list of L{Release} objects
+		"""
+		return self._releases
+
+	releases = property(getReleases,
+		doc='The releases on which this track appears.')
+
+	def addRelease(self, release):
+		"""Add a release on which this track appears.
+
+		@param release: a L{Release} object
+		"""
+		self._releases.append(release)
+
+
+class Relation(object):
+	"""Represents a relation between two Entities.
+
+	There may be an arbitrary number of relations between all first
+	class objects in MusicBrainz. The Relation itself has multiple
+	attributes, which may or may not be used for a given relation
+	type.
+
+	Note that a L{Relation} object only contains the target but not
+	the source end of the relation.
+
+	@todo: Add some examples.
+
+	@cvar TO_ARTIST: Identifies relations linking to an artist.
+	@cvar TO_RELEASE: Identifies relations linking to a release.
+	@cvar TO_TRACK: Identifies relations linking to a track.
+	@cvar TO_URL: Identifies relations linking to an URL.
+
+	@cvar DIR_NONE: Relation reading direction doesn't matter.
+	@cvar DIR_FORWARD: Relation reading direction is from source to target.
+	@cvar DIR_BACKWARD: Relation reading direction is from target to source.
+	@cvar DIR_BOTH: Relation reading direction doesn't matter (no longer used!).
+	"""
+	# Relation target types
+	#
+	TO_ARTIST = NS_REL_1 + 'Artist'
+	TO_RELEASE = NS_REL_1 + 'Release'
+	TO_TRACK = NS_REL_1 + 'Track'
+	TO_URL = NS_REL_1 + 'Url'
+
+	# Relation reading directions
+	#
+	DIR_BOTH = 'both'
+	DIR_FORWARD = 'forward'
+	DIR_BACKWARD = 'backward'
+	DIR_NONE = 'none'
+
+	def __init__(self, relationType=None, targetType=None, targetId=None,
+			direction=DIR_NONE, attributes=None,
+			beginDate=None, endDate=None, target=None):
+		"""Constructor.
+
+		@param relationType: a string containing an absolute URI
+		@param targetType: a string containing an absolute URI
+		@param targetId: a string containing an absolute URI
+		@param direction: one of C{Relation.DIR_FORWARD},
+		C{Relation.DIR_BACKWARD}, or C{Relation.DIR_NONE}
+		@param attributes: a list of strings containing absolute URIs
+		@param beginDate: a string containing a date
+		@param endDate: a string containing a date
+		@param target: an instance of a subclass of L{Entity}
+		"""
+		self._relationType = relationType
+		self._targetType = targetType
+		self._targetId = targetId
+		self._direction = direction
+		self._beginDate = beginDate
+		self._endDate = endDate
+		self._target = target
+		self._attributes = attributes
+		if self._attributes is None:
+			self._attributes = [ ]
+
+	def getType(self):
+		"""Returns this relation's type.
+
+		@return: a string containing an absolute URI, or None 
+		"""
+		return self._relationType
+
+	def setType(self, type_):
+		"""Sets this relation's type.
+
+		@param type_: a string containing an absolute URI
+		"""
+		self._relationType = type_
+
+	type = property(getType, setType, doc="The relation's type.")
+
+	def getTargetId(self):
+		"""Returns the target's ID.
+
+		This is the ID the relation points to. It is an absolute
+		URI, and in case of an URL relation, it is a URL.
+
+		@return: a string containing an absolute URI
+		"""
+		return self._targetId
+
+	def setTargetId(self, targetId):
+		"""Sets the target's ID.
+
+		@param targetId: a string containing an absolute URI
+
+		@see: L{getTargetId}
+		"""
+		self._targetId = targetId
+
+	targetId = property(getTargetId, setTargetId, doc="The target's ID.")
+
+	def getTargetType(self):
+		"""Returns the target's type.
+
+		For MusicBrainz data, the following target types are defined:
+		 - artists: L{Relation.TO_ARTIST}
+		 - releases: L{Relation.TO_RELEASE}
+		 - tracks: L{Relation.TO_TRACK}
+		 - urls: L{Relation.TO_URL}
+
+		@return: a string containing an absolute URI
+		"""
+		return self._targetType
+
+	def setTargetType(self, targetType):
+		"""Sets the target's type.
+
+		@param targetType: a string containing an absolute URI
+
+		@see: L{getTargetType}
+		"""
+		self._targetType = targetType
+
+	targetId = property(getTargetId, setTargetId,
+		doc="The type of target this relation points to.")
+
+	def getAttributes(self):
+		"""Returns a list of attributes describing this relation.
+
+		The attributes permitted depend on the relation type.
+
+		@return: a list of strings containing absolute URIs
+		"""
+		return self._attributes
+
+	attributes = property(getAttributes,
+		doc='The list of attributes describing this relation.')
+
+	def addAttribute(self, attribute):
+		"""Adds an attribute to the list.
+
+		@param attribute: a string containing an absolute URI
+		"""
+		self._attributes.append(attribute)
+
+	def getBeginDate(self):
+		"""Returns the begin date.
+
+		The definition depends on the relation's type. It may for
+		example be the day of a marriage or the year an artist
+		joined a band. For other relation types this may be
+		undefined.
+
+		@return: a string containing a date
+		"""
+		return self._beginDate
+
+	def setBeginDate(self, dateStr):
+		"""Sets the begin date.
+
+		@param dateStr: a string containing a date
+
+		@see: L{getBeginDate}
+		"""
+		self._beginDate = dateStr
+
+	beginDate = property(getBeginDate, setBeginDate, doc="The begin date.")
+
+	def getEndDate(self):
+		"""Returns the end date.
+
+		As with the begin date, the definition depends on the
+		relation's type. Depending on the relation type, this may
+		or may not be defined.
+
+		@return: a string containing a date
+
+		@see: L{getBeginDate}
+		"""
+		return self._endDate
+
+	def setEndDate(self, dateStr):
+		"""Sets the end date.
+
+		@param dateStr: a string containing a date
+
+		@see: L{getBeginDate}
+		"""
+		self._endDate = dateStr
+
+	endDate = property(getEndDate, setEndDate, doc="The end date.")
+
+	def getDirection(self):
+		"""Returns the reading direction.
+
+		The direction may be one of L{Relation.DIR_FORWARD},
+		L{Relation.DIR_BACKWARD}, or L{Relation.DIR_NONE},
+		depending on how the relation should be read. For example,
+		if direction is L{Relation.DIR_FORWARD} for a cover relation,
+		it is read as "X is a cover of Y". For some relations there is
+		no reading direction (like marriages) and the web service doesn't
+		send a direction. In these cases, the direction is set to
+		L{Relation.DIR_NONE}.
+
+		@return: L{Relation.DIR_FORWARD}, L{Relation.DIR_BACKWARD},
+		or L{Relation.DIR_NONE}
+		"""
+		return self._direction
+
+	def setDirection(self, direction):
+		"""Sets the reading direction.
+
+		@param direction: L{Relation.DIR_FORWARD},
+		L{Relation.DIR_BACKWARD}, or L{Relation.DIR_NONE}
+
+		@see: L{getDirection}
+		"""
+		self._direction = direction
+
+	direction = property(getDirection, setDirection,
+		doc="The reading direction.")
+
+	def getTarget(self):
+		"""Returns this relation's target object.
+
+		Note that URL relations never have a target object. Use the
+		L{getTargetId} method to get the URL.
+
+		@return: a subclass of L{Entity}, or None
+		"""
+		return self._target
+
+	def setTarget(self, target):
+		"""Sets this relation's target object.
+
+		Note that URL relations never have a target object, they
+		are set using L{setTargetId}.
+
+		@param target: a subclass of L{Entity}
+		"""
+		self._target = target
+
+	target = property(getTarget, setTarget,
+		doc="The relation's target object.")
+
+
+class ReleaseEvent(object):
+	"""A release event, indicating where and when a release took place.
+
+	All country codes used must be valid ISO-3166 country codes (i.e. 'DE',
+	'UK' or 'FR'). The dates are strings and must have the format 'YYYY',
+	'YYYY-MM' or 'YYYY-MM-DD'.
+
+	The format of the release medium is a URI that can be compared to the
+	constants on this class (L{FORMAT_CD}, L{FORMAT_DVD} and others).
+	"""
+	FORMAT_CD = NS_MMD_1 + 'CD'
+	FORMAT_DVD = NS_MMD_1 + 'DVD'
+	FORMAT_SACD = NS_MMD_1 + 'SACD'
+	FORMAT_DUALDISC = NS_MMD_1 + 'DualDisc'
+	FORMAT_LASERDISC = NS_MMD_1 + 'LaserDisc'
+	FORMAT_MINIDISC = NS_MMD_1 + 'MiniDisc'
+	FORMAT_VINYL = NS_MMD_1 + 'Vinyl'
+	FORMAT_CASSETTE = NS_MMD_1 + 'Cassette'
+	FORMAT_CARTRIDGE = NS_MMD_1 + 'Cartridge'
+	FORMAT_REEL_TO_REEL = NS_MMD_1 + 'ReelToReel'
+	FORMAT_DAT = NS_MMD_1 + 'DAT'
+	FORMAT_DIGITAL = NS_MMD_1 + 'Digital'
+	FORMAT_WAX_CYLINDER = NS_MMD_1 + 'WaxCylinder'
+	FORMAT_PIANO_ROLL = NS_MMD_1 + 'PianoRoll'
+	FORMAT_OTHER = NS_MMD_1 + 'Other'
+
+	def __init__(self, country=None, dateStr=None):
+		"""Constructor.
+
+		@param country: a string containing an ISO-3166 country code
+		@param dateStr: a string containing a date string
+		"""
+		self._countryId = country
+		self._dateStr = dateStr
+		self._catalogNumber = None
+		self._barcode = None
+		self._label = None
+		self._format = None
+
+	def getCountry(self):
+		"""Returns the country a release took place.
+
+		@note: Due to a server limitation, the web service does not
+		return country IDs for release collection queries. This only
+		affects the L{musicbrainz2.webservice.Query.getReleases} query.
+
+		@return: a string containing an ISO-3166 country code, or None
+
+		@see: L{musicbrainz2.utils.getCountryName}
+		"""
+		return self._countryId
+
+	def setCountry(self, country):
+		"""Sets the country a release took place.
+
+		@param country: a string containing an ISO-3166 country code
+		"""
+		self._countryId = country
+
+	country = property(getCountry, setCountry,
+		doc='The country a release took place.')
+
+	def getCatalogNumber(self):
+		"""Returns the catalog number of this release event.
+
+		@return: A string containing the catalog number, or None
+		"""
+		return self._catalogNumber
+	
+	def setCatalogNumber(self, catalogNumber):
+		"""Sets the catalog number of this release event.
+		
+		@param catalogNumber: A string containing the catalog number
+		"""
+		self._catalogNumber = catalogNumber
+	
+	catalogNumber = property(getCatalogNumber, setCatalogNumber,
+		doc='The catalog number of the release event')
+		
+	def getBarcode(self):
+		"""Returns the barcode of this release event.
+
+		@return: A string containing the barcode, or None
+		"""
+		return self._barcode
+	
+	def setBarcode(self, barcode):
+		"""Sets the barcode of this release event.
+		
+		@param barcode: A string containing the barcode
+		"""
+		self._barcode = barcode
+	
+	barcode = property(getBarcode, setBarcode,
+		doc='The barcode of the release event')
+		
+	def getLabel(self):
+		"""Returns a L{Label} object for the label associated with this release.
+		
+		@return: a L{Label} object, or None
+		"""
+		return self._label
+
+	def setLabel(self, label):
+		"""Sets the label of this release event.
+		
+		@param label: A L{Label} object
+		"""
+		self._label = label
+
+	label = property(getLabel, setLabel, doc='The label of the release')
+
+	def getDate(self):
+		"""Returns the date a release took place.
+
+		@return: a string containing a date
+		"""
+		return self._dateStr
+
+	def setDate(self, dateStr):
+		"""Sets the date a release took place.
+
+		@param dateStr: a string containing a date
+		"""
+		self._dateStr = dateStr
+
+	date = property(getDate, setDate, doc='The date a release took place.')
+
+	def getFormat(self):
+		"""Returns the format of the release medium.
+
+		@return: a string containing a URI, or None
+		"""
+		return self._format
+
+	def setFormat(self, format):
+		"""Sets the format of the release medium.
+
+		@param format: a string containing a URI
+		"""
+		self._format = format
+
+	format = property(getFormat, setFormat,
+		doc='The format of the release medium.')
+
+
+class CDStub(object):
+	"""Represents a CD Stub"""
+
+	def __init__(self, disc):
+		"""Constructor.
+
+		@param disc: a L{Disc} object to create this CD Stub from
+		"""
+		assert isinstance(disc, Disc), 'musicbrainz2.model.Disc expected'
+		self._disc = disc
+		self._tracks = [ ]
+		self._title = ""
+		self._artist = ""
+		self._barcode = ""
+		self._comment = ""
+
+	def setTitle(self, title):
+		"""Sets the title of this release.
+
+		@param title: a string containing the title
+		"""
+		self._title = title
+
+	def getTitle(self):
+		"""Returns the title of this release.
+
+		@return: a string containing the title
+		"""
+		return self._title
+
+	title = property(getTitle, setTitle,
+	       doc='The title of the release')
+
+	def setArtist(self, artist):
+		"""Sets the artist of this release.
+
+		@param artist: a string containing the artist
+		"""
+		self._artist = artist
+
+	def getArtist(self):
+		"""Returns the artist of this release.
+
+		@return: a string containing the artist
+		"""
+		return self._artist
+
+	artist = property(getArtist, setArtist,
+		doc='The artist of the release')
+
+	def setComment(self, comment):
+		"""Sets the comment for this release.
+
+		@param comment: a string containing the comment
+		"""
+		self._comment = comment
+
+	def getComment(self):
+		"""Returns the comment for this release.
+
+		@return: a string containing the comment
+		"""
+		return self._comment
+
+	comment = property(getComment, setComment,
+		 doc='Comment for the release (optional)')
+
+	def setBarcode(self, barcode):
+		"""Sets the barcode of this release.
+
+		@param barcode: a string containing the barcode
+		"""
+		self._barcode = barcode
+
+	def getBarcode(self):
+		"""Returns the barcode of this release.
+
+		@return: a string containing the barcode
+		"""
+		return self._barcode
+
+	barcode = property(getBarcode, setBarcode,
+		 doc='Barcode for the release (optional)')
+
+	def addTrack(self, title, artist=''):
+		"""Add a track to this release
+
+		@param title: a string containing the title of the track
+		@param artist: a string containing the artist of the track, 
+		               if different to the album artist
+		"""
+		self._tracks.append((title, artist))
+
+	def getTracks(self):
+		"""Return all the tracks on the release.
+
+		@return: a list of tuples containing (title, artist) pairs
+		         for each track
+		"""
+		return self._tracks
+
+	tracks = property(getTracks, doc='The tracks of the release.')
+
+class Disc(object):
+	"""Represents an Audio CD.
+
+	This class represents an Audio CD. A disc can have an ID (the
+	MusicBrainz DiscID), which is calculated from the CD's table of
+	contents (TOC). There may also be data from the TOC like the length
+	of the disc in sectors, as well as position and length of the tracks.
+
+	Note that different TOCs, maybe due to different pressings, lead to
+	different DiscIDs. Conversely, if two different discs have the same
+	TOC, they also have the same DiscID (which is unlikely but not
+	impossible). DiscIDs are always 28 characters long and look like this:
+	C{'J68I_CDcUFdCRCIbHSEbTBCbooA-'}. Sometimes they are also referred
+	to as CDIndex IDs.
+
+	The L{MusicBrainz web service } only returns
+	the DiscID and the number of sectors. The DiscID calculation function 
+	L{musicbrainz2.disc.readDisc}, however, can retrieve the other
+	attributes of L{Disc} from an Audio CD in the disc drive.
+	"""
+	def __init__(self, id_=None):
+		"""Constructor.
+
+		@param id_: a string containing a 28-character DiscID 
+		"""
+		self._id = id_
+		self._sectors = None
+		self._firstTrackNum = None
+		self._lastTrackNum = None
+		self._tracks = [ ]
+
+	def getId(self):
+		"""Returns the MusicBrainz DiscID.
+
+		@return: a string containing a 28-character DiscID 
+		"""
+		return self._id
+
+	def setId(self, id_):
+		"""Sets the MusicBrainz DiscId.
+
+		@param id_: a string containing a 28-character DiscID
+		"""
+		self._id = id_
+
+	id = property(getId, setId, doc="The MusicBrainz DiscID.")
+
+	def getSectors(self):
+		"""Returns the length of the disc in sectors.
+
+		@return: the length in sectors as an integer, or None
+		"""
+		return self._sectors
+
+	def setSectors(self, sectors):
+		"""Sets the length of the disc in sectors.
+
+		@param sectors: the length in sectors as an integer
+		"""
+		self._sectors = sectors
+
+	sectors = property(getSectors, setSectors,
+		doc="The length of the disc in sectors.")
+
+	def getFirstTrackNum(self):
+		"""Returns the number of the first track on this disc.
+
+		@return: an int containing the track number, or None
+		"""
+		return self._firstTrackNum
+
+	def setFirstTrackNum(self, trackNum):
+		"""Sets the number of the first track on this disc.
+
+		@param trackNum: an int containing the track number, or None
+		"""
+		self._firstTrackNum = trackNum
+
+	firstTrackNum = property(getFirstTrackNum, setFirstTrackNum,
+		doc="The number of the first track on this disc.")
+
+	def getLastTrackNum(self):
+		"""Returns the number of the last track on this disc.
+
+		@return: an int containing the track number, or None
+		"""
+		return self._lastTrackNum
+
+	def setLastTrackNum(self, trackNum):
+		"""Sets the number of the last track on this disc.
+
+		@param trackNum: an int containing the track number, or None
+		"""
+		self._lastTrackNum = trackNum
+
+	lastTrackNum = property(getLastTrackNum, setLastTrackNum,
+		doc="The number of the last track on this disc.")
+
+	def getTracks(self):
+		"""Returns the sector offset and length of this disc.
+
+		This method returns a list of tuples containing the track
+		offset and length in sectors for all tracks on this disc.
+		The track offset is measured from the beginning of the disc,
+		the length is relative to the track's offset. Note that the
+		leadout track is I{not} included.
+
+		@return: a list of (offset, length) tuples (values are ints)
+		"""
+		return self._tracks
+
+	tracks = property(getTracks,
+		doc='Sector offset and length of all tracks.')
+
+	def addTrack(self, track):
+		"""Adds a track to the list.
+		
+		This method adds an (offset, length) tuple to the list of
+		tracks. The leadout track must I{not} be added. The total
+		length of the disc can be set using L{setSectors}.
+
+		@param track: an (offset, length) tuple (values are ints)
+
+		@see: L{getTracks}
+		"""
+		self._tracks.append(track)
+
+
+class AbstractAlias(object):
+	"""An abstract super class for all alias classes."""
+	def __init__(self, value=None, type_=None, script=None):
+		"""Constructor.
+
+		@param value: a string containing the alias
+		@param type_: a string containing an absolute URI
+		@param script: a string containing an ISO-15924 script code
+		"""
+		self._value = value
+		self._type = type_
+		self._script = script
+
+	def getValue(self):
+		"""Returns the alias.
+
+		@return: a string containing the alias
+		"""
+		return self._value
+
+	def setValue(self, value):
+		"""Sets the alias.
+
+		@param value: a string containing the alias
+		"""
+		self._value = value
+
+	value = property(getValue, setValue, doc='The alias value.')
+
+	def getType(self):
+		"""Returns the alias type.
+
+		@return: a string containing an absolute URI, or None 
+		"""
+		return self._type
+
+	def setType(self, type_):
+		"""Sets the alias type.
+
+		@param type_: a string containing an absolute URI, or None
+		"""
+		self._type = type_
+
+	type = property(getType, setType, doc='The alias type.')
+
+	def getScript(self):
+		"""Returns the alias script.
+
+		@return: a string containing an ISO-15924 script code
+		"""
+		return self._script
+
+	def setScript(self, script):
+		"""Sets the alias script.
+
+		@param script: a string containing an ISO-15924 script code
+		"""
+		self._script = script
+
+	script = property(getScript, setScript, doc='The alias script.')
+
+
+class ArtistAlias(AbstractAlias):
+	"""Represents an artist alias.
+
+	An alias (the I{alias value}) is a different representation of an
+	artist's name. This may be a common misspelling or a transliteration
+	(the I{alias type}).
+
+	The I{alias script} is interesting mostly for transliterations and
+	indicates which script is used for the alias value. To represent the
+	script, ISO-15924 script codes like 'Latn', 'Cyrl', or 'Hebr' are used.
+	"""
+	pass
+
+
+class LabelAlias(AbstractAlias):
+	"""Represents a label alias.
+
+	An alias (the I{alias value}) is a different representation of a
+	label's name. This may be a common misspelling or a transliteration
+	(the I{alias type}).
+
+	The I{alias script} is interesting mostly for transliterations and
+	indicates which script is used for the alias value. To represent the
+	script, ISO-15924 script codes like 'Latn', 'Cyrl', or 'Hebr' are used.
+	"""
+	pass
+
+
+class User(object):
+	"""Represents a MusicBrainz user."""
+
+	def __init__(self):
+		"""Constructor."""
+		self._name = None
+		self._types = [ ]
+		self._showNag = None
+
+	def getName(self):
+		"""Returns the user name.
+
+		@return: a string containing the user name
+		"""
+		return self._name
+
+	def setName(self, name):
+		"""Sets the user name.
+
+		@param name: a string containing the user name
+		"""
+		self._name = name
+
+	name = property(getName, setName, doc='The MusicBrainz user name.')
+
+	def getTypes(self):
+		"""Returns the types of this user.
+
+		Most users' type list is empty. Currently, the following types
+		are defined:
+
+		 - 'http://musicbrainz.org/ns/ext-1.0#AutoEditor'
+		 - 'http://musicbrainz.org/ns/ext-1.0#RelationshipEditor'
+		 - 'http://musicbrainz.org/ns/ext-1.0#Bot'
+		 - 'http://musicbrainz.org/ns/ext-1.0#NotNaggable'
+
+		@return: a list of strings containing absolute URIs
+		"""
+		return self._types
+
+	types = property(getTypes, doc="The user's types.")
+
+	def addType(self, type_):
+		"""Add a type to the list of types.
+
+		@param type_: a string containing absolute URIs
+
+		@see: L{getTypes}
+		"""
+		self._types.append(type_)
+
+	def getShowNag(self):
+		"""Returns true if a nag screen should be displayed to the user.
+
+		@return: C{True}, C{False}, or None
+		"""
+		return self._showNag
+
+	def setShowNag(self, value):
+		"""Sets the value of the nag screen flag.
+
+		If set to C{True}, 
+
+		@param value: C{True} or C{False}
+
+		@see: L{getShowNag}
+		"""
+		self._showNag = value
+
+	showNag = property(getShowNag, setShowNag,
+		doc='The value of the nag screen flag.')
+
+# EOF
diff --git a/musicbrainz2/utils.py b/musicbrainz2/utils.py
new file mode 100644
index 00000000..0eff7be8
--- /dev/null
+++ b/musicbrainz2/utils.py
@@ -0,0 +1,204 @@
+"""Various utilities to simplify common tasks.
+
+This module contains helper functions to make common tasks easier.
+
+@author: Matthias Friedrich 
+"""
+__revision__ = '$Id: utils.py 11853 2009-07-21 09:26:50Z luks $'
+
+import re
+import urlparse
+import os.path
+
+__all__ = [
+	'extractUuid', 'extractFragment', 'extractEntityType',
+	'getReleaseTypeName', 'getCountryName', 'getLanguageName',
+	'getScriptName',
+]
+
+
+# A pattern to split the path part of an absolute MB URI.
+PATH_PATTERN = '^/(artist|release|track|label|release-group)/([^/]*)$'
+
+
+def extractUuid(uriStr, resType=None):
+	"""Extract the UUID part from a MusicBrainz identifier.
+
+	This function takes a MusicBrainz ID (an absolute URI) as the input
+	and returns the UUID part of the URI, thus turning it into a relative
+	URI. If C{uriStr} is None or a relative URI, then it is returned
+	unchanged.
+
+	The C{resType} parameter can be used for error checking. Set it to
+	'artist', 'release', or 'track' to make sure C{uriStr} is a
+	syntactically valid MusicBrainz identifier of the given resource
+	type. If it isn't, a C{ValueError} exception is raised.
+	This error checking only works if C{uriStr} is an absolute URI, of
+	course.
+
+	Example:
+
+	>>> from musicbrainz2.utils import extractUuid
+	>>>  extractUuid('http://musicbrainz.org/artist/c0b2500e-0cef-4130-869d-732b23ed9df5', 'artist')
+	'c0b2500e-0cef-4130-869d-732b23ed9df5'
+	>>>
+
+	@param uriStr: a string containing a MusicBrainz ID (an URI), or None
+	@param resType: a string containing a resource type
+
+	@return: a string containing a relative URI, or None
+
+	@raise ValueError: the given URI is no valid MusicBrainz ID
+	"""
+	if uriStr is None:
+		return None
+
+	(scheme, netloc, path) = urlparse.urlparse(uriStr)[:3]
+
+	if scheme == '':
+		return uriStr	# no URI, probably already the UUID
+
+	if scheme != 'http' or netloc != 'musicbrainz.org':
+		raise ValueError('%s is no MB ID.' % uriStr)
+
+	m = re.match(PATH_PATTERN, path)
+
+	if m:
+		if resType is None:
+			return m.group(2)
+		else:
+			if m.group(1) == resType:
+				return m.group(2)
+			else:
+				raise ValueError('expected "%s" Id' % resType)
+	else:
+		raise ValueError('%s is no valid MB ID.' % uriStr)
+
+
+def extractFragment(uriStr, uriPrefix=None):
+	"""Extract the fragment part from a URI.
+
+	If C{uriStr} is None or no absolute URI, then it is returned unchanged.
+
+	The C{uriPrefix} parameter can be used for error checking. If C{uriStr}
+	is an absolute URI, then the function checks if it starts with
+	C{uriPrefix}. If it doesn't, a C{ValueError} exception is raised.
+
+	@param uriStr: a string containing an absolute URI
+	@param uriPrefix: a string containing an URI prefix
+
+	@return: a string containing the fragment, or None
+
+	@raise ValueError: the given URI doesn't start with C{uriPrefix}
+	"""
+	if uriStr is None:
+		return None
+
+	(scheme, netloc, path, params, query, frag) = urlparse.urlparse(uriStr)
+	if scheme == '':
+		return uriStr # this is no URI
+
+	if uriPrefix is None or uriStr.startswith(uriPrefix):
+		return frag
+	else:
+		raise ValueError("prefix doesn't match URI %s" % uriStr)
+
+
+def extractEntityType(uriStr):
+	"""Returns the entity type an entity URI is referring to.
+
+	@param uriStr: a string containing an absolute entity URI
+
+	@return: a string containing 'artist', 'release', 'track', or 'label'
+
+	@raise ValueError: if the given URI is no valid MusicBrainz ID
+	"""
+	if uriStr is None:
+		raise ValueError('None is no valid entity URI')
+
+	(scheme, netloc, path) = urlparse.urlparse(uriStr)[:3]
+
+	if scheme == '':
+		raise ValueError('%s is no absolute MB ID.' % uriStr)
+
+	if scheme != 'http' or netloc != 'musicbrainz.org':
+		raise ValueError('%s is no MB ID.' % uriStr)
+
+	m = re.match(PATH_PATTERN, path)
+
+	if m:
+		return m.group(1)
+	else:
+		raise ValueError('%s is no valid MB ID.' % uriStr)
+
+
+def getReleaseTypeName(releaseType):
+	"""Returns the name of a release type URI.
+
+	@param releaseType: a string containing a release type URI
+
+	@return: a string containing a printable name for the release type
+
+	@see: L{musicbrainz2.model.Release}
+	"""
+	from musicbrainz2.data.releasetypenames import releaseTypeNames
+	return releaseTypeNames.get(releaseType)
+
+
+def getCountryName(id_):
+	"""Returns a country's name based on an ISO-3166 country code.
+
+	The country table this function is based on has been modified for
+	MusicBrainz purposes by using the extension mechanism defined in
+	ISO-3166. All IDs are still valid ISO-3166 country codes, but some
+	IDs have been added to include historic countries and some of the
+	country names have been modified to make them better suited for
+	display purposes.
+
+	If the country ID is not found, None is returned. This may happen
+	for example, when new countries are added to the MusicBrainz web
+	service which aren't known to this library yet.
+
+	@param id_: a two-letter upper case string containing an ISO-3166 code
+
+	@return: a string containing the country's name, or None
+
+	@see: L{musicbrainz2.model}
+	"""
+	from musicbrainz2.data.countrynames import countryNames
+	return countryNames.get(id_)
+
+
+def getLanguageName(id_):
+	"""Returns a language name based on an ISO-639-2/T code.
+
+	This function uses a subset of the ISO-639-2/T code table to map
+	language IDs (terminologic, not bibliographic ones!) to names.
+
+	@param id_: a three-letter upper case string containing an ISO-639-2/T code
+
+	@return: a string containing the language's name, or None
+
+	@see: L{musicbrainz2.model}
+	"""
+	from musicbrainz2.data.languagenames import languageNames
+	return languageNames.get(id_)
+
+
+def getScriptName(id_):
+	"""Returns a script name based on an ISO-15924 code.
+
+	This function uses a subset of the ISO-15924 code table to map
+	script IDs to names.
+
+	@param id_: a four-letter string containing an ISO-15924 script code
+
+	@return: a string containing the script's name, or None
+
+	@see: L{musicbrainz2.model}
+	"""
+	from musicbrainz2.data.scriptnames import scriptNames
+	return scriptNames.get(id_)
+
+
+# EOF
diff --git a/musicbrainz2/webservice.py b/musicbrainz2/webservice.py
new file mode 100644
index 00000000..a869530d
--- /dev/null
+++ b/musicbrainz2/webservice.py
@@ -0,0 +1,1519 @@
+"""Classes for interacting with the MusicBrainz XML web service.
+
+The L{WebService} class talks to a server implementing the MusicBrainz XML
+web service. It mainly handles URL generation and network I/O. Use this
+if maximum control is needed.
+
+The L{Query} class provides a convenient interface to the most commonly
+used features of the web service. By default it uses L{WebService} to
+retrieve data and the L{XML parser } to parse the
+responses. The results are object trees using the L{MusicBrainz domain
+model }.
+
+@author: Matthias Friedrich 
+"""
+__revision__ = '$Id: webservice.py 12973 2011-04-29 11:49:31Z luks $'
+
+import re
+import urllib
+import urllib2
+import urlparse
+import logging
+import os.path
+from StringIO import StringIO
+import musicbrainz2
+from musicbrainz2.model import Artist, Release, Track
+from musicbrainz2.wsxml import MbXmlParser, ParseError
+import musicbrainz2.utils as mbutils
+
+__all__ = [
+	'WebServiceError', 'AuthenticationError', 'ConnectionError',
+	'RequestError', 'ResourceNotFoundError', 'ResponseError', 
+	'IIncludes', 'ArtistIncludes', 'ReleaseIncludes', 'TrackIncludes',
+	'LabelIncludes', 'ReleaseGroupIncludes',
+	'IFilter', 'ArtistFilter', 'ReleaseFilter', 'TrackFilter',
+	'UserFilter', 'LabelFilter', 'ReleaseGroupFilter',
+	'IWebService', 'WebService', 'Query',
+]
+
+
+class IWebService(object):
+	"""An interface all concrete web service classes have to implement.
+
+	All web service classes have to implement this and follow the
+	method specifications.
+	"""
+
+	def get(self, entity, id_, include, filter, version):
+		"""Query the web service.
+
+		Using this method, you can either get a resource by id (using
+		the C{id_} parameter, or perform a query on all resources of
+		a type.
+
+		The C{filter} and the C{id_} parameter exclude each other. If
+		you are using a filter, you may not set C{id_} and vice versa.
+
+		Returns a file-like object containing the result or raises a
+		L{WebServiceError} or one of its subclasses in case of an
+		error. Which one is used depends on the implementing class.
+
+		@param entity: a string containing the entity's name
+		@param id_: a string containing a UUID, or the empty string
+		@param include: a tuple containing values for the 'inc' parameter
+		@param filter: parameters, depending on the entity
+		@param version: a string containing the web service version to use
+
+		@return: a file-like object
+
+		@raise WebServiceError: in case of errors
+		"""
+		raise NotImplementedError()
+
+
+	def post(self, entity, id_, data, version):
+		"""Submit data to the web service.
+
+		@param entity: a string containing the entity's name
+		@param id_: a string containing a UUID, or the empty string
+		@param data: A string containing the data to post
+		@param version: a string containing the web service version to use
+
+		@return: a file-like object
+
+		@raise WebServiceError: in case of errors
+		"""
+		raise NotImplementedError()
+
+
+class WebServiceError(Exception):
+	"""A web service error has occurred.
+
+	This is the base class for several other web service related
+	exceptions.
+	"""
+
+	def __init__(self, msg='Webservice Error', reason=None):
+		"""Constructor.
+
+		Set C{msg} to an error message which explains why this
+		exception was raised. The C{reason} parameter should be the
+		original exception which caused this L{WebService} exception
+		to be raised. If given, it has to be an instance of
+		C{Exception} or one of its child classes.
+
+		@param msg: a string containing an error message
+		@param reason: another exception instance, or None
+		"""
+		Exception.__init__(self)
+		self.msg = msg
+		self.reason = reason
+
+	def __str__(self):
+		"""Makes this class printable.
+
+		@return: a string containing an error message
+		"""
+		return self.msg
+
+
+class ConnectionError(WebServiceError):
+	"""Getting a server connection failed.
+
+	This exception is mostly used if the client couldn't connect to
+	the server because of an invalid host name or port. It doesn't
+	make sense if the web service in question doesn't use the network.
+	"""
+	pass
+
+
+class RequestError(WebServiceError):
+	"""An invalid request was made.
+
+	This exception is raised if the client made an invalid request.
+	That could be syntactically invalid identifiers or unknown or
+	invalid parameter values.
+	"""
+	pass
+
+
+class ResourceNotFoundError(WebServiceError):
+	"""No resource with the given ID exists.
+
+	This is usually a wrapper around IOError (which is superclass of
+	HTTPError).
+	"""
+	pass
+
+
+class AuthenticationError(WebServiceError):
+	"""Authentication failed.
+
+	This is thrown if user name, password or realm were invalid while
+	trying to access a protected resource.
+	"""
+	pass
+
+
+class ResponseError(WebServiceError):
+	"""The returned resource was invalid.
+
+	This may be due to a malformed XML document or if the requested
+	data wasn't part of the response. It can only occur in case of
+	bugs in the web service itself.
+	"""
+	pass
+
+class DigestAuthHandler(urllib2.HTTPDigestAuthHandler):
+	"""Patched DigestAuthHandler to correctly handle Digest Auth according to RFC 2617.
+	
+	This will allow multiple qop values in the WWW-Authenticate header (e.g. "auth,auth-int").
+	The only supported qop value is still auth, though.
+	See http://bugs.python.org/issue9714
+	
+	@author Kuno Woudt
+	"""
+	def get_authorization(self, req, chal):
+		qop = chal.get('qop')
+		if qop and ',' in qop and 'auth' in qop.split(','):
+			chal['qop'] = 'auth'
+		
+		return urllib2.HTTPDigestAuthHandler.get_authorization(self, req, chal)
+
+class WebService(IWebService):
+	"""An interface to the MusicBrainz XML web service via HTTP.
+
+	By default, this class uses the MusicBrainz server but may be
+	configured for accessing other servers as well using the
+	L{constructor <__init__>}. This implements L{IWebService}, so
+	additional documentation on method parameters can be found there.
+	"""
+
+	def __init__(self, host='musicbrainz.org', port=80, pathPrefix='/ws',
+			username=None, password=None, realm='musicbrainz.org',
+			opener=None):
+		"""Constructor.
+
+		This can be used without parameters. In this case, the
+		MusicBrainz server will be used.
+
+		@param host: a string containing a host name
+		@param port: an integer containing a port number
+		@param pathPrefix: a string prepended to all URLs
+		@param username: a string containing a MusicBrainz user name
+		@param password: a string containing the user's password
+		@param realm: a string containing the realm used for authentication
+		@param opener: an C{urllib2.OpenerDirector} object used for queries
+		"""
+		self._host = host
+		self._port = port
+		self._username = username
+		self._password = password
+		self._realm = realm
+		self._pathPrefix = pathPrefix
+		self._log = logging.getLogger(str(self.__class__))
+
+		if opener is None:
+			self._opener = urllib2.build_opener()
+		else:
+			self._opener = opener
+
+		passwordMgr = self._RedirectPasswordMgr()
+		authHandler = DigestAuthHandler(passwordMgr)
+		authHandler.add_password(self._realm, (), # no host set
+			self._username, self._password)
+		self._opener.add_handler(authHandler)
+
+
+	def _makeUrl(self, entity, id_, include=( ), filter={ },
+			version='1', type_='xml'):
+		params = dict(filter)
+		if type_ is not None:
+			params['type'] = type_
+		if len(include) > 0:
+			params['inc'] = ' '.join(include)
+
+		netloc = self._host
+		if self._port != 80:
+			netloc += ':' + str(self._port)
+		path = '/'.join((self._pathPrefix, version, entity, id_))
+
+		query = urllib.urlencode(params)
+
+		url = urlparse.urlunparse(('http', netloc, path, '', query,''))
+
+		return url
+
+
+	def _openUrl(self, url, data=None):
+		userAgent = 'python-musicbrainz/' + musicbrainz2.__version__
+		req = urllib2.Request(url)
+		req.add_header('User-Agent', userAgent)
+		return self._opener.open(req, data)
+
+
+	def get(self, entity, id_, include=( ), filter={ }, version='1'):
+		"""Query the web service via HTTP-GET.
+
+		Returns a file-like object containing the result or raises a
+		L{WebServiceError}. Conditions leading to errors may be
+		invalid entities, IDs, C{include} or C{filter} parameters
+		and unsupported version numbers.
+
+		@raise ConnectionError: couldn't connect to server
+		@raise RequestError: invalid IDs or parameters
+		@raise AuthenticationError: invalid user name and/or password
+		@raise ResourceNotFoundError: resource doesn't exist
+
+		@see: L{IWebService.get}
+		"""
+		url = self._makeUrl(entity, id_, include, filter, version)
+
+		self._log.debug('GET ' + url)
+
+		try:
+			return self._openUrl(url)
+		except urllib2.HTTPError, e:
+			self._log.debug("GET failed: " + str(e))
+			if e.code == 400:   # in python 2.4: httplib.BAD_REQUEST
+				raise RequestError(str(e), e)
+			elif e.code == 401: # httplib.UNAUTHORIZED
+				raise AuthenticationError(str(e), e)
+			elif e.code == 404: # httplib.NOT_FOUND
+				raise ResourceNotFoundError(str(e), e)
+			else:
+				raise WebServiceError(str(e), e)
+		except urllib2.URLError, e:
+			self._log.debug("GET failed: " + str(e))
+			raise ConnectionError(str(e), e)
+
+
+	def post(self, entity, id_, data, version='1'):
+		"""Send data to the web service via HTTP-POST.
+
+		Note that this may require authentication. You can set
+		user name, password and realm in the L{constructor <__init__>}.
+
+		@raise ConnectionError: couldn't connect to server
+		@raise RequestError: invalid IDs or parameters
+		@raise AuthenticationError: invalid user name and/or password
+		@raise ResourceNotFoundError: resource doesn't exist
+
+		@see: L{IWebService.post}
+		"""
+		url = self._makeUrl(entity, id_, version=version, type_=None)
+
+		self._log.debug('POST ' + url)
+		self._log.debug('POST-BODY: ' + data)
+
+		try:
+			return self._openUrl(url, data)
+		except urllib2.HTTPError, e:
+			self._log.debug("POST failed: " + str(e))
+			if e.code == 400:   # in python 2.4: httplib.BAD_REQUEST
+				raise RequestError(str(e), e)
+			elif e.code == 401: # httplib.UNAUTHORIZED
+				raise AuthenticationError(str(e), e)
+			elif e.code == 404: # httplib.NOT_FOUND
+				raise ResourceNotFoundError(str(e), e)
+			else:
+				raise WebServiceError(str(e), e)
+		except urllib2.URLError, e:
+			self._log.debug("POST failed: " + str(e))
+			raise ConnectionError(str(e), e)
+
+
+	# Special password manager which also works with redirects by simply
+	# ignoring the URI. As a consequence, only *ONE* (username, password)
+	# tuple per realm can be used for all URIs.
+	#
+	class _RedirectPasswordMgr(urllib2.HTTPPasswordMgr):
+		def __init__(self):
+			self._realms = { }
+
+		def find_user_password(self, realm, uri):
+			# ignoring the uri parameter intentionally
+			try:
+				return self._realms[realm]
+			except KeyError:
+				return (None, None)
+
+		def add_password(self, realm, uri, username, password):
+			# ignoring the uri parameter intentionally
+			self._realms[realm] = (username, password)
+
+
+class IFilter(object):
+	"""A filter for collections.
+
+	This is the interface all filters have to implement. Filter classes
+	are initialized with a set of criteria and are then applied to
+	collections of items. The criteria are usually strings or integer
+	values, depending on the filter.
+
+	Note that all strings passed to filters should be unicode strings
+	(python type C{unicode}). Standard strings are converted to unicode
+	internally, but have a limitation: Only 7 Bit pure ASCII characters
+	may be used, otherwise a C{UnicodeDecodeError} is raised.
+	"""
+	def createParameters(self):
+		"""Create a list of query parameters.
+
+		This method creates a list of (C{parameter}, C{value}) tuples,
+		based on the contents of the implementing subclass.
+		C{parameter} is a string containing a parameter name
+		and C{value} an arbitrary string. No escaping of those strings
+		is required. 
+
+		@return: a sequence of (key, value) pairs
+		"""
+		raise NotImplementedError()
+
+
+class ArtistFilter(IFilter):
+	"""A filter for the artist collection."""
+
+	def __init__(self, name=None, limit=None, offset=None, query=None):
+		"""Constructor.
+
+		The C{query} parameter may contain a query in U{Lucene syntax
+		}.
+		Note that the C{name} and C{query} may not be used together.
+
+		@param name: a unicode string containing the artist's name
+		@param limit: the maximum number of artists to return
+		@param offset: start results at this zero-based offset
+		@param query: a string containing a query in Lucene syntax
+		"""
+		self._params = [
+			('name', name),
+			('limit', limit),
+			('offset', offset),
+			('query', query),
+		]
+
+		if not _paramsValid(self._params):
+			raise ValueError('invalid combination of parameters')
+
+	def createParameters(self):
+		return _createParameters(self._params)
+
+
+class LabelFilter(IFilter):
+	"""A filter for the label collection."""
+
+	def __init__(self, name=None, limit=None, offset=None, query=None):
+		"""Constructor.
+
+		The C{query} parameter may contain a query in U{Lucene syntax
+		}.
+		Note that the C{name} and C{query} may not be used together.
+
+		@param name: a unicode string containing the label's name
+		@param limit: the maximum number of labels to return
+		@param offset: start results at this zero-based offset
+		@param query: a string containing a query in Lucene syntax
+		"""
+		self._params = [
+			('name', name),
+			('limit', limit),
+			('offset', offset),
+			('query', query),
+		]
+
+		if not _paramsValid(self._params):
+			raise ValueError('invalid combination of parameters')
+
+	def createParameters(self):
+		return _createParameters(self._params)
+
+class ReleaseGroupFilter(IFilter):
+	"""A filter for the release group collection."""
+
+	def __init__(self, title=None, releaseTypes=None, artistName=None,
+			artistId=None, limit=None, offset=None, query=None):
+		"""Constructor.
+
+		If C{artistId} is set, only releases matching those IDs are
+		returned.  The C{releaseTypes} parameter allows you to limit
+		the types of the release groups returned. You can set it to
+		C{(Release.TYPE_ALBUM, Release.TYPE_OFFICIAL)}, for example,
+		to only get officially released albums. Note that those values
+		are connected using the I{AND} operator. MusicBrainz' support
+		is currently very limited, so C{Release.TYPE_LIVE} and
+		C{Release.TYPE_COMPILATION} exclude each other (see U{the
+		documentation on release attributes
+		} for more
+		information and all valid values).
+
+		If both the C{artistName} and the C{artistId} parameter are
+		given, the server will ignore C{artistName}.
+
+		The C{query} parameter may contain a query in U{Lucene syntax
+		}.
+		Note that C{query} may not be used together with the other
+		parameters except for C{limit} and C{offset}.
+
+		@param title: a unicode string containing the release group's title
+		@param releaseTypes: a sequence of release type URIs
+		@param artistName: a unicode string containing the artist's name
+		@param artistId: a unicode string containing the artist's ID
+		@param limit: the maximum number of release groups to return
+		@param offset: start results at this zero-based offset
+		@param query: a string containing a query in Lucene syntax
+
+		@see: the constants in L{musicbrainz2.model.Release}
+		"""
+		if releaseTypes is None or len(releaseTypes) == 0:
+			releaseTypesStr = None
+		else:
+			releaseTypesStr = ' '.join(map(mbutils.extractFragment, releaseTypes))
+
+		self._params = [
+			('title', title),
+			('releasetypes', releaseTypesStr),
+			('artist', artistName),
+			('artistid', mbutils.extractUuid(artistId)),
+			('limit', limit),
+			('offset', offset),
+			('query', query),
+		]
+
+		if not _paramsValid(self._params):
+			raise ValueError('invalid combination of parameters')
+
+	def createParameters(self):
+		return _createParameters(self._params)
+
+
+class ReleaseFilter(IFilter):
+	"""A filter for the release collection."""
+
+	def __init__(self, title=None, discId=None, releaseTypes=None,
+			artistName=None, artistId=None, limit=None,
+			offset=None, query=None, trackCount=None):
+		"""Constructor.
+
+		If C{discId} or C{artistId} are set, only releases matching
+		those IDs are returned. The C{releaseTypes} parameter allows
+		to limit the types of the releases returned. You can set it to
+		C{(Release.TYPE_ALBUM, Release.TYPE_OFFICIAL)}, for example,
+		to only get officially released albums. Note that those values
+		are connected using the I{AND} operator. MusicBrainz' support
+		is currently very limited, so C{Release.TYPE_LIVE} and
+		C{Release.TYPE_COMPILATION} exclude each other (see U{the
+		documentation on release attributes
+		} for more
+		information and all valid values).
+
+		If both the C{artistName} and the C{artistId} parameter are
+		given, the server will ignore C{artistName}.
+
+		The C{query} parameter may contain a query in U{Lucene syntax
+		}.
+		Note that C{query} may not be used together with the other
+		parameters except for C{limit} and C{offset}.
+
+		@param title: a unicode string containing the release's title
+		@param discId: a unicode string containing the DiscID
+		@param releaseTypes: a sequence of release type URIs
+		@param artistName: a unicode string containing the artist's name
+		@param artistId: a unicode string containing the artist's ID
+		@param limit: the maximum number of releases to return
+		@param offset: start results at this zero-based offset
+		@param query: a string containing a query in Lucene syntax
+		@param trackCount: the number of tracks in the release
+
+		@see: the constants in L{musicbrainz2.model.Release}
+		"""
+		if releaseTypes is None or len(releaseTypes) == 0:
+			releaseTypesStr = None
+		else:
+			tmp = [ mbutils.extractFragment(x) for x in releaseTypes ]
+			releaseTypesStr = ' '.join(tmp)
+
+		self._params = [
+			('title', title),
+			('discid', discId),
+			('releasetypes', releaseTypesStr),
+			('artist', artistName),
+			('artistid', mbutils.extractUuid(artistId)),
+			('limit', limit),
+			('offset', offset),
+			('query', query),
+			('count', trackCount),
+		]
+
+		if not _paramsValid(self._params):
+			raise ValueError('invalid combination of parameters')
+
+	def createParameters(self):
+		return _createParameters(self._params)
+
+
+class TrackFilter(IFilter):
+	"""A filter for the track collection."""
+
+	def __init__(self, title=None, artistName=None, artistId=None,
+			releaseTitle=None, releaseId=None,
+			duration=None, puid=None, limit=None, offset=None,
+			query=None):
+		"""Constructor.
+
+		If C{artistId}, C{releaseId} or C{puid} are set, only tracks
+		matching those IDs are returned.
+
+		The server will ignore C{artistName} and C{releaseTitle} if
+		C{artistId} or ${releaseId} are set respectively.
+
+		The C{query} parameter may contain a query in U{Lucene syntax
+		}.
+		Note that C{query} may not be used together with the other
+		parameters except for C{limit} and C{offset}.
+
+		@param title: a unicode string containing the track's title
+		@param artistName: a unicode string containing the artist's name
+		@param artistId: a string containing the artist's ID
+		@param releaseTitle: a unicode string containing the release's title
+		@param releaseId: a string containing the release's title
+		@param duration: the track's length in milliseconds
+		@param puid: a string containing a PUID
+		@param limit: the maximum number of releases to return
+		@param offset: start results at this zero-based offset
+		@param query: a string containing a query in Lucene syntax
+		"""
+		self._params = [
+			('title', title),
+			('artist', artistName),
+			('artistid', mbutils.extractUuid(artistId)),
+			('release', releaseTitle),
+			('releaseid', mbutils.extractUuid(releaseId)),
+			('duration', duration),
+			('puid', puid),
+			('limit', limit),
+			('offset', offset),
+			('query', query),
+		]
+
+		if not _paramsValid(self._params):
+			raise ValueError('invalid combination of parameters')
+
+	def createParameters(self):
+		return _createParameters(self._params)
+
+
+class UserFilter(IFilter):
+	"""A filter for the user collection."""
+
+	def __init__(self, name=None):
+		"""Constructor.
+
+		@param name: a unicode string containing a MusicBrainz user name
+		"""
+		self._name = name
+
+	def createParameters(self):
+		if self._name is not None:
+			return [ ('name', self._name.encode('utf-8')) ]
+		else:
+			return [ ]
+
+
+class IIncludes(object):
+	"""An interface implemented by include tag generators."""
+	def createIncludeTags(self):
+		raise NotImplementedError()
+
+
+class ArtistIncludes(IIncludes):
+	"""A specification on how much data to return with an artist.
+
+	Example:
+
+	>>> from musicbrainz2.model import Release
+	>>> from musicbrainz2.webservice import ArtistIncludes
+	>>> inc = ArtistIncludes(artistRelations=True, releaseRelations=True,
+	... 		releases=(Release.TYPE_ALBUM, Release.TYPE_OFFICIAL))
+	>>>
+
+	The MusicBrainz server only supports some combinations of release
+	types for the C{releases} and C{vaReleases} include tags. At the
+	moment, not more than two release types should be selected, while
+	one of them has to be C{Release.TYPE_OFFICIAL},
+	C{Release.TYPE_PROMOTION} or C{Release.TYPE_BOOTLEG}.
+
+	@note: Only one of C{releases} and C{vaReleases} may be given.
+	"""
+	def __init__(self, aliases=False, releases=(), vaReleases=(),
+			artistRelations=False, releaseRelations=False,
+			trackRelations=False, urlRelations=False, tags=False,
+			ratings=False, releaseGroups=False):
+
+		assert not isinstance(releases, basestring)
+		assert not isinstance(vaReleases, basestring)
+		assert len(releases) == 0 or len(vaReleases) == 0
+
+		self._includes = {
+			'aliases':		aliases,
+			'artist-rels':		artistRelations,
+			'release-groups':	releaseGroups,
+			'release-rels':		releaseRelations,
+			'track-rels':		trackRelations,
+			'url-rels':		urlRelations,
+			'tags':			tags,
+			'ratings':		ratings,
+		}
+
+		for elem in releases:
+			self._includes['sa-' + mbutils.extractFragment(elem)] = True
+
+		for elem in vaReleases:
+			self._includes['va-' + mbutils.extractFragment(elem)] = True
+
+	def createIncludeTags(self):
+		return _createIncludes(self._includes)
+
+
+class ReleaseIncludes(IIncludes):
+	"""A specification on how much data to return with a release."""
+	def __init__(self, artist=False, counts=False, releaseEvents=False,
+			discs=False, tracks=False,
+			artistRelations=False, releaseRelations=False,
+			trackRelations=False, urlRelations=False,
+			labels=False, tags=False, ratings=False, isrcs=False,
+			releaseGroup=False):
+		self._includes = {
+			'artist':		artist,
+			'counts':		counts,
+			'labels':		labels,
+			'release-groups':	releaseGroup,
+			'release-events':	releaseEvents,
+			'discs':		discs,
+			'tracks':		tracks,
+			'artist-rels':		artistRelations,
+			'release-rels':		releaseRelations,
+			'track-rels':		trackRelations,
+			'url-rels':		urlRelations,
+			'tags':			tags,
+			'ratings':		ratings,
+			'isrcs':		isrcs,
+		}
+
+		# Requesting labels without releaseEvents makes no sense,
+		# so we pull in releaseEvents, if necessary.
+		if labels and not releaseEvents:
+			self._includes['release-events'] = True
+		# Ditto for isrcs with no tracks
+		if isrcs and not tracks:
+			self._includes['tracks'] = True
+
+	def createIncludeTags(self):
+		return _createIncludes(self._includes)
+
+
+class ReleaseGroupIncludes(IIncludes):
+	"""A specification on how much data to return with a release group."""
+
+	def __init__(self, artist=False, releases=False, tags=False):
+		"""Constructor.
+
+		@param artist: Whether to include the release group's main artist info.
+		@param releases: Whether to include the release group's releases.
+		"""
+		self._includes = {
+			'artist':		artist,
+			'releases':		releases,
+		}
+
+	def createIncludeTags(self):
+		return _createIncludes(self._includes)
+
+
+class TrackIncludes(IIncludes):
+	"""A specification on how much data to return with a track."""
+	def __init__(self, artist=False, releases=False, puids=False,
+			artistRelations=False, releaseRelations=False,
+			trackRelations=False, urlRelations=False, tags=False,
+			ratings=False, isrcs=False):
+		self._includes = {
+			'artist':		artist,
+			'releases':		releases,
+			'puids':		puids,
+			'artist-rels':		artistRelations,
+			'release-rels':		releaseRelations,
+			'track-rels':		trackRelations,
+			'url-rels':		urlRelations,
+			'tags':			tags,
+			'ratings':		ratings,
+			'isrcs':		isrcs,
+		}
+
+	def createIncludeTags(self):
+		return _createIncludes(self._includes)
+
+
+class LabelIncludes(IIncludes):
+	"""A specification on how much data to return with a label."""
+	def __init__(self, aliases=False, tags=False, ratings=False):
+		self._includes = {
+			'aliases':		aliases,
+			'tags':			tags,
+			'ratings':		ratings,
+		}
+
+	def createIncludeTags(self):
+		return _createIncludes(self._includes)
+
+
+class Query(object):
+	"""A simple interface to the MusicBrainz web service.
+
+	This is a facade which provides a simple interface to the MusicBrainz
+	web service. It hides all the details like fetching data from a server,
+	parsing the XML and creating an object tree. Using this class, you can
+	request data by ID or search the I{collection} of all resources
+	(artists, releases, or tracks) to retrieve those matching given
+	criteria. This document contains examples to get you started.
+
+
+	Working with Identifiers
+	========================
+
+	MusicBrainz uses absolute URIs as identifiers. For example, the artist
+	'Tori Amos' is identified using the following URI::
+		http://musicbrainz.org/artist/c0b2500e-0cef-4130-869d-732b23ed9df5
+
+	In some situations it is obvious from the context what type of 
+	resource an ID refers to. In these cases, abbreviated identifiers may
+	be used, which are just the I{UUID} part of the URI. Thus the ID above
+	may also be written like this::
+		c0b2500e-0cef-4130-869d-732b23ed9df5
+
+	All methods in this class which require IDs accept both the absolute
+	URI and the abbreviated form (aka the relative URI).
+
+
+	Creating a Query Object
+	=======================
+
+	In most cases, creating a L{Query} object is as simple as this:
+
+	>>> import musicbrainz2.webservice as ws
+	>>> q = ws.Query()
+	>>>
+
+	The instantiated object uses the standard L{WebService} class to
+	access the MusicBrainz web service. If you want to use a different 
+	server or you have to pass user name and password because one of
+	your queries requires authentication, you have to create the
+	L{WebService} object yourself and configure it appropriately.
+	This example uses the MusicBrainz test server and also sets
+	authentication data:
+
+	>>> import musicbrainz2.webservice as ws
+	>>> service = ws.WebService(host='test.musicbrainz.org',
+	...				username='whatever', password='secret')
+	>>> q = ws.Query(service)
+	>>>
+
+
+	Querying for Individual Resources
+	=================================
+
+	If the MusicBrainz ID of a resource is known, then the L{getArtistById},
+	L{getReleaseById}, or L{getTrackById} method can be used to retrieve
+	it. Example:
+
+	>>> import musicbrainz2.webservice as ws
+	>>> q = ws.Query()
+	>>> artist = q.getArtistById('c0b2500e-0cef-4130-869d-732b23ed9df5')
+	>>> artist.name
+	u'Tori Amos'
+	>>> artist.sortName
+	u'Amos, Tori'
+	>>> print artist.type
+	http://musicbrainz.org/ns/mmd-1.0#Person
+	>>>
+
+	This returned just the basic artist data, however. To get more detail
+	about a resource, the C{include} parameters may be used which expect
+	an L{ArtistIncludes}, L{ReleaseIncludes}, or L{TrackIncludes} object,
+	depending on the resource type.
+
+	To get data about a release which also includes the main artist
+	and all tracks, for example, the following query can be used:
+
+	>>> import musicbrainz2.webservice as ws
+	>>> q = ws.Query()
+	>>> releaseId = '33dbcf02-25b9-4a35-bdb7-729455f33ad7'
+	>>> include = ws.ReleaseIncludes(artist=True, tracks=True)
+	>>> release = q.getReleaseById(releaseId, include)
+	>>> release.title
+	u'Tales of a Librarian'
+	>>> release.artist.name
+	u'Tori Amos'
+	>>> release.tracks[0].title
+	u'Precious Things'
+	>>>
+
+	Note that the query gets more expensive for the server the more
+	data you request, so please be nice.
+
+
+	Searching in Collections
+	========================
+
+	For each resource type (artist, release, and track), there is one
+	collection which contains all resources of a type. You can search
+	these collections using the L{getArtists}, L{getReleases}, and
+	L{getTracks} methods. The collections are huge, so you have to
+	use filters (L{ArtistFilter}, L{ReleaseFilter}, or L{TrackFilter})
+	to retrieve only resources matching given criteria.
+
+	For example, If you want to search the release collection for
+	releases with a specified DiscID, you would use L{getReleases}
+	and a L{ReleaseFilter} object:
+
+	>>> import musicbrainz2.webservice as ws
+	>>> q = ws.Query()
+	>>> filter = ws.ReleaseFilter(discId='8jJklE258v6GofIqDIrE.c5ejBE-')
+	>>> results = q.getReleases(filter=filter)
+	>>> results[0].score
+	100
+	>>> results[0].release.title
+	u'Under the Pink'
+	>>>
+
+	The query returns a list of results (L{wsxml.ReleaseResult} objects
+	in this case), which are ordered by score, with a higher score
+	indicating a better match. Note that those results don't contain
+	all the data about a resource. If you need more detail, you can then
+	use the L{getArtistById}, L{getReleaseById}, or L{getTrackById}
+	methods to request the resource.
+
+	All filters support the C{limit} argument to limit the number of
+	results returned. This defaults to 25, but the server won't send
+	more than 100 results to save bandwidth and processing power. Using
+	C{limit} and the C{offset} parameter, you can page through the
+	results.
+
+
+	Error Handling
+	==============
+
+	All methods in this class raise a L{WebServiceError} exception in case
+	of errors. Depending on the method, a subclass of L{WebServiceError} may
+	be raised which allows an application to handle errors more precisely.
+	The following example handles connection errors (invalid host name
+	etc.) separately and all other web service errors in a combined
+	catch clause:
+
+	>>> try:
+	...     artist = q.getArtistById('c0b2500e-0cef-4130-869d-732b23ed9df5')
+	... except ws.ConnectionError, e:
+	...     pass # implement your error handling here
+	... except ws.WebServiceError, e:
+	...     pass # catches all other web service errors
+	... 
+	>>>
+	"""
+
+	def __init__(self, ws=None, wsFactory=WebService, clientId=None):
+		"""Constructor.
+
+		The C{ws} parameter has to be a subclass of L{IWebService}.
+		If it isn't given, the C{wsFactory} parameter is used to
+		create an L{IWebService} subclass.
+
+		If the constructor is called without arguments, an instance
+		of L{WebService} is used, preconfigured to use the MusicBrainz
+		server. This should be enough for most users.
+
+		If you want to use queries which require authentication you
+		have to pass a L{WebService} instance where user name and
+		password have been set.
+
+		The C{clientId} parameter is required for data submission.
+		The format is C{'application-version'}, where C{application}
+		is your application's name and C{version} is a version
+		number which may not include a '-' character.
+
+		@param ws: a subclass instance of L{IWebService}, or None
+		@param wsFactory: a callable object which creates an object
+		@param clientId: a unicode string containing the application's ID
+		"""
+		if ws is None:
+			self._ws = wsFactory()
+		else:
+			self._ws = ws
+
+		self._clientId = clientId
+		self._log = logging.getLogger(str(self.__class__))
+
+
+	def getArtistById(self, id_, include=None):
+		"""Returns an artist.
+
+		If no artist with that ID can be found, C{include} contains
+		invalid tags or there's a server problem, an exception is
+		raised.
+
+		@param id_: a string containing the artist's ID
+		@param include: an L{ArtistIncludes} object, or None
+
+		@return: an L{Artist } object, or None
+
+		@raise ConnectionError: couldn't connect to server
+		@raise RequestError: invalid ID or include tags
+		@raise ResourceNotFoundError: artist doesn't exist
+		@raise ResponseError: server returned invalid data
+		"""
+		uuid = mbutils.extractUuid(id_, 'artist')
+		result = self._getFromWebService('artist', uuid, include)
+		artist = result.getArtist()
+		if artist is not None:
+			return artist
+		else:
+			raise ResponseError("server didn't return artist")
+
+
+	def getArtists(self, filter):
+		"""Returns artists matching given criteria.
+
+		@param filter: an L{ArtistFilter} object
+
+		@return: a list of L{musicbrainz2.wsxml.ArtistResult} objects
+
+		@raise ConnectionError: couldn't connect to server
+		@raise RequestError: invalid ID or include tags
+		@raise ResponseError: server returned invalid data
+		"""
+		result = self._getFromWebService('artist', '', filter=filter)
+		return result.getArtistResults()
+
+	def getLabelById(self, id_, include=None):
+		"""Returns a L{model.Label}
+		
+		If no label with that ID can be found, or there is a server problem,
+		an exception is raised.
+		
+		@param id_: a string containing the label's ID.
+
+		@raise ConnectionError: couldn't connect to server
+		@raise RequestError: invalid ID or include tags
+		@raise ResourceNotFoundError: release doesn't exist
+		@raise ResponseError: server returned invalid data
+		"""
+		uuid = mbutils.extractUuid(id_, 'label')
+		result = self._getFromWebService('label', uuid, include)
+		label = result.getLabel()
+		if label is not None:
+			return label
+		else:
+			raise ResponseError("server didn't return a label")
+	
+	def getLabels(self, filter):
+		result = self._getFromWebService('label', '', filter=filter)
+		return result.getLabelResults()
+
+	def getReleaseById(self, id_, include=None):
+		"""Returns a release.
+
+		If no release with that ID can be found, C{include} contains
+		invalid tags or there's a server problem, and exception is
+		raised.
+
+		@param id_: a string containing the release's ID
+		@param include: a L{ReleaseIncludes} object, or None
+
+		@return: a L{Release } object, or None
+
+		@raise ConnectionError: couldn't connect to server
+		@raise RequestError: invalid ID or include tags
+		@raise ResourceNotFoundError: release doesn't exist
+		@raise ResponseError: server returned invalid data
+		"""
+		uuid = mbutils.extractUuid(id_, 'release')
+		result = self._getFromWebService('release', uuid, include)
+		release = result.getRelease()
+		if release is not None:
+			return release
+		else:
+			raise ResponseError("server didn't return release")
+
+
+	def getReleases(self, filter):
+		"""Returns releases matching given criteria.
+
+		@param filter: a L{ReleaseFilter} object
+
+		@return: a list of L{musicbrainz2.wsxml.ReleaseResult} objects
+
+		@raise ConnectionError: couldn't connect to server
+		@raise RequestError: invalid ID or include tags
+		@raise ResponseError: server returned invalid data
+		"""
+		result = self._getFromWebService('release', '', filter=filter)
+		return result.getReleaseResults()
+	
+	def getReleaseGroupById(self, id_, include=None):
+		"""Returns a release group.
+
+		If no release group with that ID can be found, C{include}
+		contains invalid tags, or there's a server problem, an
+		exception is raised.
+
+		@param id_: a string containing the release group's ID
+		@param include: a L{ReleaseGroupIncludes} object, or None
+
+		@return: a L{ReleaseGroup } object, or None
+
+		@raise ConnectionError: couldn't connect to server
+		@raise RequestError: invalid ID or include tags
+		@raise ResourceNotFoundError: release doesn't exist
+		@raise ResponseError: server returned invalid data
+		"""
+		uuid = mbutils.extractUuid(id_, 'release-group')
+		result = self._getFromWebService('release-group', uuid, include)
+		releaseGroup = result.getReleaseGroup()
+		if releaseGroup is not None:
+			return releaseGroup
+		else:
+			raise ResponseError("server didn't return releaseGroup")
+
+	def getReleaseGroups(self, filter):
+		"""Returns release groups matching the given criteria.
+		
+		@param filter: a L{ReleaseGroupFilter} object
+		
+		@return: a list of L{musicbrainz2.wsxml.ReleaseGroupResult} objects
+		
+		@raise ConnectionError: couldn't connect to server
+		@raise RequestError: invalid ID or include tags
+		@raise ResponseError: server returned invalid data
+		"""
+		result = self._getFromWebService('release-group', '', filter=filter)
+		return result.getReleaseGroupResults()
+
+	def getTrackById(self, id_, include=None):
+		"""Returns a track.
+
+		If no track with that ID can be found, C{include} contains
+		invalid tags or there's a server problem, an exception is
+		raised.
+
+		@param id_: a string containing the track's ID
+		@param include: a L{TrackIncludes} object, or None
+
+		@return: a L{Track } object, or None
+
+		@raise ConnectionError: couldn't connect to server
+		@raise RequestError: invalid ID or include tags
+		@raise ResourceNotFoundError: track doesn't exist
+		@raise ResponseError: server returned invalid data
+		"""
+		uuid = mbutils.extractUuid(id_, 'track')
+		result = self._getFromWebService('track', uuid, include)
+		track = result.getTrack()
+		if track is not None:
+			return track
+		else:
+			raise ResponseError("server didn't return track")
+
+
+	def getTracks(self, filter):
+		"""Returns tracks matching given criteria.
+
+		@param filter: a L{TrackFilter} object
+
+		@return: a list of L{musicbrainz2.wsxml.TrackResult} objects
+
+		@raise ConnectionError: couldn't connect to server
+		@raise RequestError: invalid ID or include tags
+		@raise ResponseError: server returned invalid data
+		"""
+		result = self._getFromWebService('track', '', filter=filter)
+		return result.getTrackResults()
+
+
+	def getUserByName(self, name):
+		"""Returns information about a MusicBrainz user.
+
+		You can only request user data if you know the user name and
+		password for that account. If username and/or password are
+		incorrect, an L{AuthenticationError} is raised.
+
+		See the example in L{Query} on how to supply user name and
+		password.
+
+		@param name: a unicode string containing the user's name
+
+		@return: a L{User } object
+
+		@raise ConnectionError: couldn't connect to server
+		@raise RequestError: invalid ID or include tags
+		@raise AuthenticationError: invalid user name and/or password
+		@raise ResourceNotFoundError: track doesn't exist
+		@raise ResponseError: server returned invalid data
+		"""
+		filter = UserFilter(name=name)
+		result = self._getFromWebService('user', '', None, filter)
+
+		if len(result.getUserList()) > 0:
+			return result.getUserList()[0]
+		else:
+			raise ResponseError("response didn't contain user data")
+
+
+	def _getFromWebService(self, entity, id_, include=None, filter=None):
+		if filter is None:
+			filterParams = [ ]
+		else:
+			filterParams = filter.createParameters()
+
+		if include is None:
+			includeParams = [ ]
+		else:
+			includeParams = include.createIncludeTags()
+
+		stream = self._ws.get(entity, id_, includeParams, filterParams)
+		try:
+			parser = MbXmlParser()
+			return parser.parse(stream)
+		except ParseError, e:
+			raise ResponseError(str(e), e)
+
+
+	def submitPuids(self, tracks2puids):
+		"""Submit track to PUID mappings.
+
+		The C{tracks2puids} parameter has to be a dictionary, with the
+		keys being MusicBrainz track IDs (either as absolute URIs or
+		in their 36 character ASCII representation) and the values
+		being PUIDs (ASCII, 36 characters).
+
+		Note that this method only works if a valid user name and
+		password have been set. See the example in L{Query} on how
+		to supply authentication data.
+
+		@param tracks2puids: a dictionary mapping track IDs to PUIDs
+
+		@raise ConnectionError: couldn't connect to server
+		@raise RequestError: invalid track or PUIDs
+		@raise AuthenticationError: invalid user name and/or password
+		"""
+		assert self._clientId is not None, 'Please supply a client ID'
+		params = [ ]
+		params.append( ('client', self._clientId.encode('utf-8')) )
+
+		for (trackId, puid) in tracks2puids.iteritems():
+			trackId = mbutils.extractUuid(trackId, 'track')
+			params.append( ('puid', trackId + ' ' + puid) )
+
+		encodedStr = urllib.urlencode(params, True)
+
+		self._ws.post('track', '', encodedStr)
+	
+	def submitISRCs(self, tracks2isrcs):
+		"""Submit track to ISRC mappings.
+
+		The C{tracks2isrcs} parameter has to be a dictionary, with the
+		keys being MusicBrainz track IDs (either as absolute URIs or
+		in their 36 character ASCII representation) and the values
+		being ISRCs (ASCII, 12 characters).
+
+		Note that this method only works if a valid user name and
+		password have been set. See the example in L{Query} on how
+		to supply authentication data.
+
+		@param tracks2isrcs: a dictionary mapping track IDs to ISRCs
+
+		@raise ConnectionError: couldn't connect to server
+		@raise RequestError: invalid track or ISRCs
+		@raise AuthenticationError: invalid user name and/or password
+		"""
+		params = [ ]
+
+		for (trackId, isrc) in tracks2isrcs.iteritems():
+			trackId = mbutils.extractUuid(trackId, 'track')
+			params.append( ('isrc', trackId + ' ' + isrc) )
+
+		encodedStr = urllib.urlencode(params, True)
+
+		self._ws.post('track', '', encodedStr)
+
+	def addToUserCollection(self, releases):
+		"""Add releases to a user's collection.
+
+		The releases parameter must be a list. It can contain either L{Release}
+		objects or a string representing a MusicBrainz release ID (either as
+		absolute URIs or in their 36 character ASCII representation).
+
+		Adding a release that is already in the collection has no effect.
+
+		@param releases: a list of releases to add to the user collection
+
+		@raise ConnectionError: couldn't connect to server
+		@raise AuthenticationError: invalid user name and/or password
+		"""
+		rels = []
+		for release in releases:
+			if isinstance(release, Release):
+				rels.append(mbutils.extractUuid(release.id))
+			else:
+				rels.append(mbutils.extractUuid(release))
+		encodedStr = urllib.urlencode({'add': ",".join(rels)}, True)
+		self._ws.post('collection', '', encodedStr)
+
+	def removeFromUserCollection(self, releases):
+		"""Remove releases from a user's collection.
+
+		The releases parameter must be a list. It can contain either L{Release}
+		objects or a string representing a MusicBrainz release ID (either as
+		absolute URIs or in their 36 character ASCII representation).
+
+		Removing a release that is not in the collection has no effect.
+
+		@param releases: a list of releases to remove from the user collection
+
+		@raise ConnectionError: couldn't connect to server
+		@raise AuthenticationError: invalid user name and/or password
+		"""
+		rels = []
+		for release in releases:
+			if isinstance(release, Release):
+				rels.append(mbutils.extractUuid(release.id))
+			else:
+				rels.append(mbutils.extractUuid(release))
+		encodedStr = urllib.urlencode({'remove': ",".join(rels)}, True)
+		self._ws.post('collection', '', encodedStr)
+
+	def getUserCollection(self, offset=0, maxitems=100):
+		"""Get the releases that are in a user's collection
+		
+		A maximum of 100 items will be returned for any one call
+		to this method. To fetch more than 100 items, use the offset
+		parameter.
+
+		@param offset: the offset to start fetching results from
+		@param maxitems: the upper limit on items to return
+
+		@return: a list of L{musicbrainz2.wsxml.ReleaseResult} objects
+
+		@raise ConnectionError: couldn't connect to server
+		@raise AuthenticationError: invalid user name and/or password
+		"""
+		params = { 'offset': offset, 'maxitems': maxitems }
+		
+		stream = self._ws.get('collection', '', filter=params)
+		print stream
+		try:
+			parser = MbXmlParser()
+			result = parser.parse(stream)
+		except ParseError, e:
+			raise ResponseError(str(e), e)
+		
+		return result.getReleaseResults()
+
+	def submitUserTags(self, entityUri, tags):
+		"""Submit folksonomy tags for an entity.
+
+		Note that all previously existing tags from the authenticated
+		user are replaced with the ones given to this method. Other
+		users' tags are not affected.
+		
+		@param entityUri: a string containing an absolute MB ID
+		@param tags: A list of either L{Tag } objects
+		             or strings
+
+		@raise ValueError: invalid entityUri
+		@raise ConnectionError: couldn't connect to server
+		@raise RequestError: invalid ID, entity or tags
+		@raise AuthenticationError: invalid user name and/or password
+		"""
+		entity = mbutils.extractEntityType(entityUri)
+		uuid = mbutils.extractUuid(entityUri, entity)
+		params = (
+			('type', 'xml'),
+			('entity', entity),
+			('id', uuid),
+			('tags', ','.join([unicode(tag).encode('utf-8') for tag in tags]))
+		)
+
+		encodedStr = urllib.urlencode(params)
+
+		self._ws.post('tag', '', encodedStr)
+
+
+	def getUserTags(self, entityUri):
+		"""Returns a list of folksonomy tags a user has applied to an entity.
+
+		The given parameter has to be a fully qualified MusicBrainz ID, as
+		returned by other library functions.
+		
+		Note that this method only works if a valid user name and
+		password have been set. Only the tags the authenticated user
+		applied to the entity will be returned. If username and/or
+		password are incorrect, an AuthenticationError is raised.
+		
+		This method will return a list of L{Tag }
+		objects.
+		
+		@param entityUri: a string containing an absolute MB ID
+		
+		@raise ValueError: invalid entityUri
+  		@raise ConnectionError: couldn't connect to server
+		@raise RequestError: invalid ID or entity
+		@raise AuthenticationError: invalid user name and/or password
+		"""
+		entity = mbutils.extractEntityType(entityUri)
+		uuid = mbutils.extractUuid(entityUri, entity)
+		params = { 'entity': entity, 'id': uuid }
+		
+		stream = self._ws.get('tag', '', filter=params)
+		try:
+			parser = MbXmlParser()
+			result = parser.parse(stream)
+		except ParseError, e:
+			raise ResponseError(str(e), e)
+		
+		return result.getTagList()
+
+	def submitUserRating(self, entityUri, rating):
+		"""Submit rating for an entity.
+
+		Note that all previously existing rating from the authenticated
+		user are replaced with the one given to this method. Other
+		users' ratings are not affected.
+		
+		@param entityUri: a string containing an absolute MB ID
+		@param rating: A L{Rating } object
+		             or integer
+
+		@raise ValueError: invalid entityUri
+		@raise ConnectionError: couldn't connect to server
+		@raise RequestError: invalid ID, entity or tags
+		@raise AuthenticationError: invalid user name and/or password
+		"""
+		entity = mbutils.extractEntityType(entityUri)
+		uuid = mbutils.extractUuid(entityUri, entity)
+		params = (
+			('type', 'xml'),
+			('entity', entity),
+			('id', uuid),
+			('rating', unicode(rating).encode('utf-8'))
+		)
+
+		encodedStr = urllib.urlencode(params)
+
+		self._ws.post('rating', '', encodedStr)
+
+
+	def getUserRating(self, entityUri):
+		"""Return the rating a user has applied to an entity.
+
+		The given parameter has to be a fully qualified MusicBrainz
+		ID, as returned by other library functions.
+		
+		Note that this method only works if a valid user name and
+		password have been set. Only the rating the authenticated user
+		applied to the entity will be returned. If username and/or
+		password are incorrect, an AuthenticationError is raised.
+		
+		This method will return a L{Rating }
+		object.
+		
+		@param entityUri: a string containing an absolute MB ID
+		
+		@raise ValueError: invalid entityUri
+  		@raise ConnectionError: couldn't connect to server
+		@raise RequestError: invalid ID or entity
+		@raise AuthenticationError: invalid user name and/or password
+		"""
+		entity = mbutils.extractEntityType(entityUri)
+		uuid = mbutils.extractUuid(entityUri, entity)
+		params = { 'entity': entity, 'id': uuid }
+		
+		stream = self._ws.get('rating', '', filter=params)
+		try:
+			parser = MbXmlParser()
+			result = parser.parse(stream)
+		except ParseError, e:
+			raise ResponseError(str(e), e)
+		
+		return result.getRating()
+
+	def submitCDStub(self, cdstub):
+		"""Submit a CD Stub to the database.
+
+		The number of tracks added to the CD Stub must match the TOC and DiscID
+		otherwise the submission wil fail. The submission will also fail if 
+		the Disc ID is already in the MusicBrainz database.
+
+		This method will only work if no user name and password are set.
+
+		@param cdstub: a L{CDStub} object to submit
+		
+		@raise RequestError: Missmatching TOC/Track information or the
+		       the CD Stub already exists or the Disc ID already exists
+		"""
+		assert self._clientId is not None, 'Please supply a client ID'
+		disc = cdstub._disc
+		params = [ ]
+		params.append( ('client', self._clientId.encode('utf-8')) )
+		params.append( ('discid', disc.id) )
+		params.append( ('title', cdstub.title) )
+		params.append( ('artist', cdstub.artist) )
+		if cdstub.barcode != "":
+			params.append( ('barcode', cdstub.barcode) )
+		if cdstub.comment != "":
+			params.append( ('comment', cdstub.comment) )
+
+		trackind = 0
+		for track,artist in cdstub.tracks:
+			params.append( ('track%d' % trackind, track) )
+			if artist != "":
+				params.append( ('artist%d' % trackind, artist) )
+
+			trackind += 1
+
+		toc = "%d %d %d " % (disc.firstTrackNum, disc.lastTrackNum, disc.sectors)
+	        toc = toc + ' '.join( map(lambda x: str(x[0]), disc.getTracks()) )
+
+		params.append( ('toc', toc) )
+
+		encodedStr = urllib.urlencode(params)
+		self._ws.post('release', '', encodedStr)
+
+def _createIncludes(tagMap):
+	selected = filter(lambda x: x[1] == True, tagMap.items())
+	return map(lambda x: x[0], selected)
+
+def _createParameters(params):
+	"""Remove (x, None) tuples and encode (x, str/unicode) to utf-8."""
+	ret = [ ]
+	for p in params:
+		if isinstance(p[1], (str, unicode)):
+			ret.append( (p[0], p[1].encode('utf-8')) )
+		elif p[1] is not None:
+			ret.append(p)
+
+	return ret
+
+def _paramsValid(params):
+	"""Check if the query parameter collides with other parameters."""
+	tmp = [ ]
+	for name, value in params:
+		if value is not None and name not in ('offset', 'limit'):
+			tmp.append(name)
+
+	if 'query' in tmp and len(tmp) > 1:
+		return False
+	else:
+		return True
+
+if __name__ == '__main__':
+	import doctest
+	doctest.testmod()
+
+# EOF
diff --git a/musicbrainz2/wsxml.py b/musicbrainz2/wsxml.py
new file mode 100644
index 00000000..7fd2a166
--- /dev/null
+++ b/musicbrainz2/wsxml.py
@@ -0,0 +1,1675 @@
+"""A parser for the Music Metadata XML Format (MMD).
+
+This module contains L{MbXmlParser}, which parses the U{Music Metadata XML
+Format (MMD) } returned by the
+MusicBrainz webservice. 
+
+There are also DOM helper functions in this module used by the parser which
+probably aren't useful to users.
+"""
+__revision__ = '$Id: wsxml.py 12028 2009-09-01 13:15:50Z matt $'
+
+import re
+import logging
+import urlparse
+import xml.dom.minidom
+import xml.sax.saxutils as saxutils 
+from xml.parsers.expat import ExpatError
+from xml.dom import DOMException
+
+import musicbrainz2.utils as mbutils
+import musicbrainz2.model as model
+from musicbrainz2.model import NS_MMD_1, NS_REL_1, NS_EXT_1
+
+__all__ = [
+	'DefaultFactory', 'Metadata', 'ParseError',
+	'MbXmlParser', 'MbXmlWriter',
+	'AbstractResult',
+	'ArtistResult', 'ReleaseResult', 'TrackResult', 'LabelResult',
+	'ReleaseGroupResult'
+]
+
+
+class DefaultFactory(object):
+	"""A factory to instantiate classes from the domain model. 
+
+	This factory may be used to create objects from L{musicbrainz2.model}.
+	"""
+	def newArtist(self): return model.Artist()
+	def newRelease(self): return model.Release()
+	def newReleaseGroup(self): return model.ReleaseGroup()
+	def newTrack(self): return model.Track()
+	def newRelation(self): return model.Relation()
+	def newReleaseEvent(self): return model.ReleaseEvent()
+	def newDisc(self): return model.Disc()
+	def newArtistAlias(self): return model.ArtistAlias()
+	def newUser(self): return model.User()
+	def newLabel(self): return model.Label()
+	def newLabelAlias(self): return model.LabelAlias()
+	def newTag(self): return model.Tag()
+	def newRating(self): return model.Rating()
+
+
+class ParseError(Exception):
+	"""Exception to be thrown if a parse error occurs.
+
+	The C{'msg'} attribute contains a printable error message, C{'reason'}
+	is the lower level exception that was raised.
+	"""
+
+	def __init__(self, msg='Parse Error', reason=None):
+		Exception.__init__(self)
+		self.msg = msg
+		self.reason = reason
+
+	def __str__(self):
+		return self.msg
+
+
+class Metadata(object):
+	"""Represents a parsed Music Metadata XML document.
+
+	The Music Metadata XML format is very flexible and may contain a
+	diverse set of data (e.g. an artist, a release and a list of tracks),
+	but usually only a small subset is used (either an artist, a release
+	or a track, or a lists of objects from one class).
+
+	@see: L{MbXmlParser} for reading, and L{MbXmlWriter} for writing
+		Metadata objects
+	"""
+	def __init__(self):
+		self._artist = None
+		self._release = None
+		self._track = None
+		self._label = None
+		self._releaseGroup = None
+		self._artistResults = [ ]
+		self._artistResultsOffset = None
+		self._artistResultsCount = None
+		self._releaseResults = [ ]
+		self._releaseResultsOffset = None
+		self._releaseResultsCount = None
+		self._releaseGroupResults = [ ]
+		self._releaseGroupResultsOffset = None
+		self._releaseGroupResultsCount = None
+		self._trackResults = [ ]
+		self._trackResultsOffset = None
+		self._trackResultsCount = None
+		self._labelResults = [ ]
+		self._labelResultsOffset = None
+		self._labelResultsCount = None
+		self._tagList = [ ]
+		self._rating = None
+		self._userList = [ ]
+
+	def getArtist(self):
+		return self._artist
+
+	def setArtist(self, artist):
+		self._artist = artist
+
+	artist = property(getArtist, setArtist, doc='An Artist object.')
+	
+	def getLabel(self):
+		return self._label
+	
+	def setLabel(self, label):
+		self._label = label
+	
+	label = property(getLabel, setLabel, doc='A Label object.')
+
+	def getRelease(self):
+		return self._release
+
+	def setRelease(self, release):
+		self._release = release
+
+	release = property(getRelease, setRelease, doc='A Release object.')
+
+	def getReleaseGroup(self):
+		return self._releaseGroup
+
+	def setReleaseGroup(self, releaseGroup):
+		self._releaseGroup = releaseGroup
+
+	releaseGroup = property(getReleaseGroup, setReleaseGroup)
+
+	def getTrack(self):
+		return self._track
+
+	def setTrack(self, track):
+		self._track = track
+
+	track = property(getTrack, setTrack, doc='A Track object.')
+
+	def getArtistResults(self):
+		"""Returns an artist result list. 
+
+		@return: a list of L{ArtistResult} objects.
+		"""
+		return self._artistResults
+
+	artistResults = property(getArtistResults,
+		doc='A list of ArtistResult objects.')
+
+	def getArtistResultsOffset(self):
+		"""Returns the offset of the artist result list.
+
+		The offset is used for paging through the result list. It
+		is zero-based.
+
+		@return: an integer containing the offset, or None
+
+		@see: L{getArtistResults}, L{getArtistResultsCount}
+		"""
+		return self._artistResultsOffset
+
+	def setArtistResultsOffset(self, value):
+		"""Sets the offset of the artist result list.
+
+		@param value: an integer containing the offset, or None
+
+		@see: L{getArtistResultsOffset}
+		"""
+		self._artistResultsOffset = value
+
+	artistResultsOffset = property(
+		getArtistResultsOffset, setArtistResultsOffset,
+		doc='The offset of the artist results.')
+
+	def getArtistResultsCount(self):
+		"""Returns the total number of results available.
+	
+		This may or may not match with the number of elements that
+		L{getArtistResults} returns. If the count is higher than
+		the list, it indicates that the list is incomplete.
+
+		@return: an integer containing the count, or None
+
+		@see: L{setArtistResultsCount}, L{getArtistResultsOffset}
+		"""
+		return self._artistResultsCount
+
+	def setArtistResultsCount(self, value):
+		"""Sets the total number of available results.
+
+		@param value: an integer containing the count, or None
+
+		@see: L{getArtistResults}, L{setArtistResultsOffset}
+		"""
+		self._artistResultsCount = value
+
+	artistResultsCount = property(
+		getArtistResultsCount, setArtistResultsCount,
+		doc='The total number of artists results.')
+
+	def getLabelResults(self):
+		"""Returns a label result list.
+		
+		@return: a list of L{LabelResult} objects.
+		"""
+		return self._labelResults
+	
+	labelResults = property(getLabelResults,
+		doc='A list of LabelResult objects')
+
+	def getLabelResultsOffset(self):
+		"""Returns the offset of the label result list.
+
+		The offset is used for paging through the result list. It
+		is zero-based.
+
+		@return: an integer containing the offset, or None
+
+		@see: L{getLabelResults}, L{getLabelResultsCount}
+		"""
+		return self._labelResultsOffset
+
+	def setLabelResultsOffset(self, value):
+		"""Sets the offset of the label result list.
+
+		@param value: an integer containing the offset, or None
+
+		@see: L{getLabelResultsOffset}
+		"""
+		self._labelResultsOffset = value
+
+	labelResultsOffset = property(
+		getLabelResultsOffset, setLabelResultsOffset,
+		doc='The offset of the label results.')
+
+	def getLabelResultsCount(self):
+		"""Returns the total number of results available.
+	
+		This may or may not match with the number of elements that
+		L{getLabelResults} returns. If the count is higher than
+		the list, it indicates that the list is incomplete.
+
+		@return: an integer containing the count, or None
+
+		@see: L{setLabelResultsCount}, L{getLabelResultsOffset}
+		"""
+		return self._labelResultsCount
+
+	def setLabelResultsCount(self, value):
+		"""Sets the total number of available results.
+
+		@param value: an integer containing the count, or None
+
+		@see: L{getLabelResults}, L{setLabelResultsOffset}
+		"""
+		self._labelResultsCount = value
+
+	labelResultsCount = property(
+		getLabelResultsCount, setLabelResultsCount,
+		doc='The total number of label results.')
+
+	def getReleaseResults(self):
+		"""Returns a release result list. 
+
+		@return: a list of L{ReleaseResult} objects.
+		"""
+		return self._releaseResults
+
+	releaseResults = property(getReleaseResults,
+		doc='A list of ReleaseResult objects.')
+
+	def getReleaseResultsOffset(self):
+		"""Returns the offset of the release result list.
+
+		The offset is used for paging through the result list. It
+		is zero-based.
+
+		@return: an integer containing the offset, or None
+
+		@see: L{getReleaseResults}, L{getReleaseResultsCount}
+		"""
+		return self._releaseResultsOffset
+
+	def setReleaseResultsOffset(self, value):
+		"""Sets the offset of the release result list.
+
+		@param value: an integer containing the offset, or None
+
+		@see: L{getReleaseResultsOffset}
+		"""
+		self._releaseResultsOffset = value
+
+	releaseResultsOffset = property(
+		getReleaseResultsOffset, setReleaseResultsOffset,
+		doc='The offset of the release results.')
+
+	def getReleaseResultsCount(self):
+		"""Returns the total number of results available.
+	
+		This may or may not match with the number of elements that
+		L{getReleaseResults} returns. If the count is higher than
+		the list, it indicates that the list is incomplete.
+
+		@return: an integer containing the count, or None
+
+		@see: L{setReleaseResultsCount}, L{getReleaseResultsOffset}
+		"""
+		return self._releaseResultsCount
+
+	def setReleaseResultsCount(self, value):
+		"""Sets the total number of available results.
+
+		@param value: an integer containing the count, or None
+
+		@see: L{getReleaseResults}, L{setReleaseResultsOffset}
+		"""
+		self._releaseResultsCount = value
+
+	releaseResultsCount = property(
+		getReleaseResultsCount, setReleaseResultsCount,
+		doc='The total number of release results.')
+
+	def getReleaseGroupResults(self):
+		"""Returns a release group result list.
+
+		@return: a list of L{ReleaseGroupResult} objects.
+		"""
+		return self._releaseGroupResults
+
+	releaseGroupResults = property(getReleaseGroupResults,
+		doc = 'A list of ReleaseGroupResult objects.')
+
+	def getReleaseGroupResultsOffset(self):
+		"""Returns the offset of the release group result list.
+
+		The offset is used for paging through the result list.  It
+		is zero-based.
+
+		@return: an integer containing the offset, or None.
+
+		@see: L{getReleaseGroupResults}, L{getReleaseGroupResultsCount}
+		"""
+		return self._releaseGroupResultsOffset
+
+	def setReleaseGroupResultsOffset(self, value):
+		"""Sets the offset of the release group result list.
+
+		@param value: an integer containing the offset, or None
+
+		@see: L{getReleaseGroupResultsOffset}
+		"""
+		self._releaseGroupResultsOffset = value
+
+	releaseGroupResultsOffset = property(
+		getReleaseGroupResultsOffset, setReleaseGroupResultsOffset,
+		doc='The offset of the release group results.')
+
+	def getReleaseGroupResultsCount(self):
+		"""Returns the total number of results available.
+
+		This may or may not match with the number of elements that
+		L{getReleaseGroupResults} returns. If the count is higher than
+		the list, it indicates that the list is incomplete.
+
+		@return: an integer containing the count, or None
+
+		@see: L{setReleaseGroupResultsCount}, L{getReleaseGroupResultsOffset}
+		"""
+		return self._releaseGroupResultsCount
+
+	def setReleaseGroupResultsCount(self, value):
+		"""Sets the total number of available results.
+
+		@param value: an integer containing the count, or None
+
+		@see: L{getReleaseGroupResults}, L{setReleaseGroupResultsOffset}
+		"""
+		self._releaseGroupResultsCount = value
+
+	releaseGroupResultsCount = property(
+		getReleaseGroupResultsCount, setReleaseGroupResultsCount,
+		doc='The total number of release group results.')
+
+	def getTrackResults(self):
+		"""Returns a track result list. 
+
+		@return: a list of L{TrackResult} objects.
+		"""
+		return self._trackResults
+
+	trackResults = property(getTrackResults,
+		doc='A list of TrackResult objects.')
+
+	def getTrackResultsOffset(self):
+		"""Returns the offset of the track result list.
+
+		The offset is used for paging through the result list. It
+		is zero-based.
+
+		@return: an integer containing the offset, or None
+
+		@see: L{getTrackResults}, L{getTrackResultsCount}
+		"""
+		return self._trackResultsOffset
+
+	def setTrackResultsOffset(self, value):
+		"""Sets the offset of the track result list.
+
+		@param value: an integer containing the offset, or None
+
+		@see: L{getTrackResultsOffset}
+		"""
+		self._trackResultsOffset = value
+
+	trackResultsOffset = property(
+		getTrackResultsOffset, setTrackResultsOffset,
+		doc='The offset of the track results.')
+
+	def getTrackResultsCount(self):
+		"""Returns the total number of results available.
+	
+		This may or may not match with the number of elements that
+		L{getTrackResults} returns. If the count is higher than
+		the list, it indicates that the list is incomplete.
+
+		@return: an integer containing the count, or None
+
+		@see: L{setTrackResultsCount}, L{getTrackResultsOffset}
+		"""
+		return self._trackResultsCount
+
+	def setTrackResultsCount(self, value):
+		"""Sets the total number of available results.
+
+		@param value: an integer containing the count, or None
+
+		@see: L{getTrackResults}, L{setTrackResultsOffset}
+		"""
+		self._trackResultsCount = value
+
+	trackResultsCount = property(
+		getTrackResultsCount, setTrackResultsCount,
+		doc='The total number of track results.')
+
+
+	def getTagList(self):
+		"""Returns a list of tags.
+
+		@return: a list of L{model.Tag} objects
+		"""
+		return self._tagList
+
+	tagResults = property(getTagList,
+		doc='A list of Tag objects.')
+
+	def getRating(self):
+		"""Returns the rating.
+
+		@return: rating object
+		"""
+		return self._rating
+
+	def setRating(self, value):
+		"""Sets the rating.
+
+		@param value: a L{model.Rating} object
+		"""
+		self._rating = value
+
+	rating = property(getRating, setRating, doc='A Rating object.')
+
+
+	# MusicBrainz extension to the schema
+	def getUserList(self):
+		"""Returns a list of users.
+
+		@return: a list of L{model.User} objects
+
+		@note: This is a MusicBrainz extension.
+		"""
+		return self._userList
+
+	userResults = property(getUserList,
+		doc='A list of User objects.')
+
+
+class AbstractResult(object):
+	"""The abstract representation of a result.
+
+	A result is an instance of some kind (Artist, Release, ...)
+	associated with a score.
+	"""
+
+	def __init__(self, score):
+		self._score = score
+
+	def getScore(self):
+		"""Returns the result score.
+
+		The score indicates how good this result matches the search
+		parameters. The higher the value, the better the match.
+
+		@return: an int between 0 and 100 (both inclusive), or None
+		"""
+		return self._score
+
+	def setScore(self, score):
+		self._score = score
+
+	score = property(getScore, setScore, doc='The relevance score.')
+
+
+class ArtistResult(AbstractResult):
+	"""Represents an artist result.
+
+	An ArtistResult consists of a I{score} and an artist. The score is a
+	number between 0 and 100, where a higher number indicates a better
+	match.
+	"""
+	def __init__(self, artist, score):
+		super(ArtistResult, self).__init__(score)
+		self._artist = artist
+
+	def getArtist(self):
+		"""Returns an Artist object.
+
+		@return: a L{musicbrainz2.model.Artist} object
+		"""
+		return self._artist
+
+	def setArtist(self, artist):
+		self._artist = artist
+
+	artist = property(getArtist, setArtist, doc='An Artist object.')
+
+
+class ReleaseResult(AbstractResult):
+	"""Represents a release result.
+
+	A ReleaseResult consists of a I{score} and a release. The score is a
+	number between 0 and 100, where a higher number indicates a better
+	match.
+	"""
+	def __init__(self, release, score):
+		super(ReleaseResult, self).__init__(score)
+		self._release = release
+
+	def getRelease(self):
+		"""Returns a Release object.
+
+		@return: a L{musicbrainz2.model.Release} object
+		"""
+		return self._release
+
+	def setRelease(self, release):
+		self._release = release
+
+	release = property(getRelease, setRelease, doc='A Release object.')
+
+class ReleaseGroupResult(AbstractResult):
+	"""Represents a release group result.
+
+	A ReleaseGroupResult consists of a I{score} and a release group.  The
+	score is a number between 0 and 100, where a higher number indicates
+	a better match.
+	"""
+	def __init__(self, releaseGroup, score):
+		super(ReleaseGroupResult, self).__init__(score)
+		self._releaseGroup = releaseGroup
+
+	def getReleaseGroup(self):
+		"""Returns a ReleaseGroup object.
+
+		@return: a L{musicbrainz2.model.ReleaseGroup} object
+		"""
+		return self._releaseGroup
+
+	def setReleaseGroup(self, value):
+		self._releaseGroup = value
+
+	releaseGroup = property(getReleaseGroup, setReleaseGroup, doc='A ReleaseGroup object.')
+
+class TrackResult(AbstractResult):
+	"""Represents a track result.
+
+	A TrackResult consists of a I{score} and a track. The score is a
+	number between 0 and 100, where a higher number indicates a better
+	match.
+	"""
+	def __init__(self, track, score):
+		super(TrackResult, self).__init__(score)
+		self._track = track
+
+	def getTrack(self):
+		"""Returns a Track object.
+
+		@return: a L{musicbrainz2.model.Track} object
+		"""
+		return self._track
+
+	def setTrack(self, track):
+		self._track = track
+
+	track = property(getTrack, setTrack, doc='A Track object.')
+
+
+class LabelResult(AbstractResult):
+	"""Represents a label result.
+
+	An LabelResult consists of a I{score} and a label. The score is a
+	number between 0 and 100, where a higher number indicates a better
+	match.
+	"""
+	def __init__(self, label, score):
+		super(LabelResult, self).__init__(score)
+		self._label = label
+
+	def getLabel(self):
+		"""Returns a Label object.
+
+		@return: a L{musicbrainz2.model.Label} object
+		"""
+		return self._label
+
+	def setLabel(self, label):
+		self._label = label
+
+	label = property(getLabel, setLabel, doc='A Label object.')
+
+
+class MbXmlParser(object):
+	"""A parser for the Music Metadata XML format.
+
+	This parser supports all basic features and extensions defined by
+	MusicBrainz, including unlimited document nesting. By default it
+	reads an XML document from a file-like object (stream) and returns
+	an object tree representing the document using classes from
+	L{musicbrainz2.model}.
+
+	The implementation tries to be as permissive as possible. Invalid
+	contents are skipped, but documents have to be well-formed and using
+	the correct namespace. In case of unrecoverable errors, a L{ParseError}
+	exception is raised.
+
+	@see: U{The Music Metadata XML Format
+		}
+	"""
+
+	def __init__(self, factory=DefaultFactory()):
+		"""Constructor.
+
+		The C{factory} parameter has be an instance of L{DefaultFactory}
+		or a subclass of it. It is used by L{parse} to obtain objects
+		from L{musicbrainz2.model} to build resulting object tree.
+		If you supply your own factory, you have to make sure all
+		returned objects have the same interface as their counterparts
+		from L{musicbrainz2.model}.
+
+		@param factory: an object factory 
+		"""
+		self._log = logging.getLogger(str(self.__class__))
+		self._factory = factory
+
+	def parse(self, inStream):
+		"""Parses the MusicBrainz web service XML.
+
+		Returns a L{Metadata} object representing the parsed XML or
+		raises a L{ParseError} exception if the data was malformed.
+		The parser tries to be liberal and skips invalid content if
+		possible.
+
+		Note that an L{IOError} may be raised if there is a problem
+		reading C{inStream}.
+
+		@param inStream: a file-like object
+		@return: a L{Metadata} object (never None)
+		@raise ParseError: if the document is not valid
+		@raise IOError: if reading from the stream failed
+		"""
+
+		try:
+			doc = xml.dom.minidom.parse(inStream)
+
+			# Try to find the root element. If this isn't an mmd
+			# XML file or the namespace is wrong, this will fail.
+			elems = doc.getElementsByTagNameNS(NS_MMD_1, 'metadata')
+
+			if len(elems) != 0:
+				md = self._createMetadata(elems[0])
+			else:
+				msg = 'cannot find root element mmd:metadata'
+				self._log.debug('ParseError: ' + msg)
+				raise ParseError(msg)
+
+			doc.unlink()
+
+			return md
+		except ExpatError, e:
+			self._log.debug('ExpatError: ' + str(e))
+			raise ParseError(msg=str(e), reason=e)
+		except DOMException, e:
+			self._log.debug('DOMException: ' + str(e))
+			raise ParseError(msg=str(e), reason=e)
+			
+
+	def _createMetadata(self, metadata):
+		md = Metadata()
+
+		for node in _getChildElements(metadata):
+			if _matches(node, 'artist'):
+				md.artist = self._createArtist(node)
+			elif _matches(node, 'release'):
+				md.release = self._createRelease(node)
+			elif _matches(node, 'release-group'):
+				md.releaseGroup = self._createReleaseGroup(node)
+			elif _matches(node, 'track'):
+				md.track = self._createTrack(node)
+			elif _matches(node, 'label'):
+				md.label = self._createLabel(node)
+			elif _matches(node, 'artist-list'):
+				(offset, count) = self._getListAttrs(node)
+				md.artistResultsOffset = offset
+				md.artistResultsCount = count
+				self._addArtistResults(node, md.getArtistResults())
+			elif _matches(node, 'release-list'):
+				(offset, count) = self._getListAttrs(node)
+				md.releaseResultsOffset = offset
+				md.releaseResultsCount = count
+				self._addReleaseResults(node, md.getReleaseResults())
+			elif _matches(node, 'release-group-list'):
+				(offset, count) = self._getListAttrs(node)
+				md.releaseGroupResultsOffset = offset
+				md.releaseGroupResultsCount = count
+				self._addReleaseGroupResults(node, md.getReleaseGroupResults())
+			elif _matches(node, 'track-list'):
+				(offset, count) = self._getListAttrs(node)
+				md.trackResultsOffset = offset
+				md.trackResultsCount = count
+				self._addTrackResults(node, md.getTrackResults())
+			elif _matches(node, 'label-list'):
+				(offset, count) = self._getListAttrs(node)
+				md.labelResultsOffset = offset
+				md.labelResultsCount = count
+				self._addLabelResults(node, md.getLabelResults())
+			elif _matches(node, 'tag-list'):
+				self._addTagsToList(node, md.getTagList())
+			elif _matches(node, 'user-list', NS_EXT_1):
+				self._addUsersToList(node, md.getUserList())
+
+		return md
+
+
+	def _addArtistResults(self, listNode, resultList):
+		for c in _getChildElements(listNode):
+			artist = self._createArtist(c)
+			score = _getIntAttr(c, 'score', 0, 100, ns=NS_EXT_1)
+			if artist is not None:
+				resultList.append(ArtistResult(artist, score))
+
+	def _addReleaseResults(self, listNode, resultList):
+		for c in _getChildElements(listNode):
+			release = self._createRelease(c)
+			score = _getIntAttr(c, 'score', 0, 100, ns=NS_EXT_1)
+			if release is not None:
+				resultList.append(ReleaseResult(release, score))
+
+	def _addReleaseGroupResults(self, listNode, resultList):
+		for c in _getChildElements(listNode):
+			releaseGroup = self._createReleaseGroup(c)
+			score = _getIntAttr(c, 'score', 0, 100, ns=NS_EXT_1)
+			if releaseGroup is not None:
+				resultList.append(ReleaseGroupResult(releaseGroup, score))
+
+	def _addTrackResults(self, listNode, resultList):
+		for c in _getChildElements(listNode):
+			track = self._createTrack(c)
+			score = _getIntAttr(c, 'score', 0, 100, ns=NS_EXT_1)
+			if track is not None:
+				resultList.append(TrackResult(track, score))
+
+	def _addLabelResults(self, listNode, resultList):
+		for c in _getChildElements(listNode):
+			label = self._createLabel(c)
+			score = _getIntAttr(c, 'score', 0, 100, ns=NS_EXT_1)
+			if label is not None:
+				resultList.append(LabelResult(label, score))
+
+	def _addReleasesToList(self, listNode, resultList):
+		self._addToList(listNode, resultList, self._createRelease)
+
+	def _addReleaseGroupsToList(self, listNode, resultList):
+		self._addToList(listNode, resultList, self._createReleaseGroup)
+
+	def _addTracksToList(self, listNode, resultList):
+		self._addToList(listNode, resultList, self._createTrack)
+
+	def _addUsersToList(self, listNode, resultList):
+		self._addToList(listNode, resultList, self._createUser)
+
+	def _addTagsToList(self, listNode, resultList):
+		self._addToList(listNode, resultList, self._createTag)
+
+	def _addTagsToEntity(self, listNode, entity):
+		for node in _getChildElements(listNode):
+			tag = self._createTag(node)
+			entity.addTag(tag)
+
+	def _addRatingToEntity(self, attrNode, entity):
+		rating = self._createRating(attrNode)
+		entity.setRating(rating)
+
+	def _addToList(self, listNode, resultList, creator):
+		for c in _getChildElements(listNode):
+			resultList.append(creator(c))
+
+	def _getListAttrs(self, listNode):
+		offset = _getIntAttr(listNode, 'offset')
+		count = _getIntAttr(listNode, 'count')
+		return (offset, count)
+
+
+	def _createArtist(self, artistNode):
+		artist = self._factory.newArtist()
+		artist.setId(_getIdAttr(artistNode, 'id', 'artist'))
+		artist.setType(_getUriAttr(artistNode, 'type'))
+		
+		for node in _getChildElements(artistNode):
+			if _matches(node, 'name'):
+				artist.setName(_getText(node))
+			elif _matches(node, 'sort-name'):
+				artist.setSortName(_getText(node))
+			elif _matches(node, 'disambiguation'):
+				artist.setDisambiguation(_getText(node))
+			elif _matches(node, 'life-span'):
+				artist.setBeginDate(_getDateAttr(node, 'begin'))
+				artist.setEndDate(_getDateAttr(node, 'end'))
+			elif _matches(node, 'alias-list'):
+				self._addArtistAliases(node, artist)
+			elif _matches(node, 'release-list'):
+				(offset, count) = self._getListAttrs(node)
+				artist.setReleasesOffset(offset)
+				artist.setReleasesCount(count)
+				self._addReleasesToList(node, artist.getReleases())
+			elif _matches(node, 'release-group-list'):
+				(offset, count) = self._getListAttrs(node)
+				artist.setReleaseGroupsOffset(offset)
+				artist.setReleaseGroupsCount(count)
+				self._addReleaseGroupsToList(node, artist.getReleaseGroups())
+			elif _matches(node, 'relation-list'):
+				self._addRelationsToEntity(node, artist)
+			elif _matches(node, 'tag-list'):
+				self._addTagsToEntity(node, artist)
+			elif _matches(node, 'rating'):
+				self._addRatingToEntity(node, artist)
+
+		return artist
+
+	def _createLabel(self, labelNode):
+		label = self._factory.newLabel()
+		label.setId(_getIdAttr(labelNode, 'id', 'label'))
+		label.setType(_getUriAttr(labelNode, 'type'))
+		
+		for node in _getChildElements(labelNode):
+			if _matches(node, 'name'):
+				label.setName(_getText(node))
+			if _matches(node, 'sort-name'):
+				label.setSortName(_getText(node))
+			elif _matches(node, 'disambiguation'):
+				label.setDisambiguation(_getText(node))
+			elif _matches(node, 'label-code'):
+				label.setCode(_getText(node))
+			elif _matches(node, 'country'):
+				country = _getText(node, '^[A-Z]{2}$')
+				label.setCountry(country)
+			elif _matches(node, 'life-span'):
+				label.setBeginDate(_getDateAttr(node, 'begin'))
+				label.setEndDate(_getDateAttr(node, 'end'))
+			elif _matches(node, 'alias-list'):
+				self._addLabelAliases(node, label)
+			elif _matches(node, 'tag-list'):
+				self._addTagsToEntity(node, label)
+			elif _matches(node, 'rating'):
+				self._addRatingToEntity(node, label)
+
+		return label
+
+	def _createRelease(self, releaseNode):
+		release = self._factory.newRelease()
+		release.setId(_getIdAttr(releaseNode, 'id', 'release'))
+		for t in _getUriListAttr(releaseNode, 'type'):
+			release.addType(t)
+
+		for node in _getChildElements(releaseNode):
+			if _matches(node, 'title'):
+				release.setTitle(_getText(node))
+			elif _matches(node, 'text-representation'):
+				lang = _getAttr(node, 'language', '^[A-Z]{3}$')
+				release.setTextLanguage(lang)
+				script = _getAttr(node, 'script', '^[A-Z][a-z]{3}$')
+				release.setTextScript(script)
+			elif _matches(node, 'asin'):
+				release.setAsin(_getText(node))
+			elif _matches(node, 'artist'):
+				release.setArtist(self._createArtist(node))
+			elif _matches(node, 'release-event-list'):
+				self._addReleaseEvents(node, release)
+			elif _matches(node, 'release-group'):
+				release.setReleaseGroup(self._createReleaseGroup(node))
+			elif _matches(node, 'disc-list'):
+				self._addDiscs(node, release)
+			elif _matches(node, 'track-list'):
+				(offset, count) = self._getListAttrs(node)
+				release.setTracksOffset(offset)
+				release.setTracksCount(count)
+				self._addTracksToList(node, release.getTracks())
+			elif _matches(node, 'relation-list'):
+				self._addRelationsToEntity(node, release)
+			elif _matches(node, 'tag-list'):
+				self._addTagsToEntity(node, release)
+			elif _matches(node, 'rating'):
+				self._addRatingToEntity(node, release)
+
+		return release
+
+	def _createReleaseGroup(self, node):
+		rg = self._factory.newReleaseGroup()
+		rg.setId(_getIdAttr(node, 'id', 'release-group'))
+		rg.setType(_getUriAttr(node, 'type'))
+
+		for child in _getChildElements(node):
+			if _matches(child, 'title'):
+				rg.setTitle(_getText(child))
+			elif _matches(child, 'artist'):
+				rg.setArtist(self._createArtist(child))
+			elif _matches(child, 'release-list'):
+				(offset, count) = self._getListAttrs(child)
+				rg.setReleasesOffset(offset)
+				rg.setReleasesCount(count)
+				self._addReleasesToList(child, rg.getReleases())
+
+		return rg
+
+	def _addReleaseEvents(self, releaseListNode, release):
+		for node in _getChildElements(releaseListNode):
+			if _matches(node, 'event'):
+				country = _getAttr(node, 'country', '^[A-Z]{2}$')
+				date = _getDateAttr(node, 'date')
+				catalogNumber = _getAttr(node, 'catalog-number')
+				barcode = _getAttr(node, 'barcode')
+				format = _getUriAttr(node, 'format')
+
+				# The date attribute is mandatory. If it isn't present,
+				# we don't add anything from this release event.
+				if date is not None:
+					event = self._factory.newReleaseEvent()
+					event.setCountry(country)
+					event.setDate(date)
+					event.setCatalogNumber(catalogNumber)
+					event.setBarcode(barcode)
+					event.setFormat(format)
+					
+					for subNode in _getChildElements(node):
+						if _matches(subNode, 'label'):
+							event.setLabel(self._createLabel(subNode))
+					
+					release.addReleaseEvent(event)
+
+
+	def _addDiscs(self, discIdListNode, release):
+		for node in _getChildElements(discIdListNode):
+			if _matches(node, 'disc') and node.hasAttribute('id'):
+				d = self._factory.newDisc()
+				d.setId(node.getAttribute('id'))
+				d.setSectors(_getIntAttr(node, 'sectors', 0))
+				release.addDisc(d)
+
+
+	def _addArtistAliases(self, aliasListNode, artist):
+		for node in _getChildElements(aliasListNode):
+			if _matches(node, 'alias'):
+				alias = self._factory.newArtistAlias()
+				self._initializeAlias(alias, node)
+				artist.addAlias(alias)
+
+
+	def _addLabelAliases(self, aliasListNode, label):
+		for node in _getChildElements(aliasListNode):
+			if _matches(node, 'alias'):
+				alias = self._factory.newLabelAlias()
+				self._initializeAlias(alias, node)
+				label.addAlias(alias)
+
+
+	def _initializeAlias(self, alias, node):
+		alias.setValue(_getText(node))
+		alias.setType(_getUriAttr(node, 'type'))
+		alias.setScript(_getAttr(node, 'script',
+			'^[A-Z][a-z]{3}$'))
+
+
+	def _createTrack(self, trackNode):
+		track = self._factory.newTrack()
+		track.setId(_getIdAttr(trackNode, 'id', 'track'))
+
+		for node in _getChildElements(trackNode):
+			if _matches(node, 'title'):
+				track.setTitle(_getText(node))
+			elif _matches(node, 'artist'):
+				track.setArtist(self._createArtist(node))
+			elif _matches(node, 'duration'):
+				track.setDuration(_getPositiveIntText(node))
+			elif _matches(node, 'release-list'):
+				self._addReleasesToList(node, track.getReleases())
+			elif _matches(node, 'puid-list'):
+				self._addPuids(node, track)
+			elif _matches(node, 'isrc-list'):
+				self._addISRCs(node, track)
+			elif _matches(node, 'relation-list'):
+				self._addRelationsToEntity(node, track)
+			elif _matches(node, 'tag-list'):
+				self._addTagsToEntity(node, track)
+			elif _matches(node, 'rating'):
+				self._addRatingToEntity(node, track)
+
+		return track
+
+	# MusicBrainz extension
+	def _createUser(self, userNode):
+		user = self._factory.newUser()
+		for t in _getUriListAttr(userNode, 'type', NS_EXT_1):
+			user.addType(t)
+
+		for node in _getChildElements(userNode):
+			if _matches(node, 'name'):
+				user.setName(_getText(node))
+			elif _matches(node, 'nag', NS_EXT_1):
+				user.setShowNag(_getBooleanAttr(node, 'show'))
+
+		return user
+
+	def _createRating(self, ratingNode):
+		rating = self._factory.newRating()
+		rating.value = _getText(ratingNode)
+		rating.count = _getIntAttr(ratingNode, 'votes-count')
+		return rating
+
+	def _createTag(self, tagNode):
+		tag = self._factory.newTag()
+		tag.value = _getText(tagNode)
+		tag.count = _getIntAttr(tagNode, 'count')
+		return tag
+
+	
+	def _addPuids(self, puidListNode, track):
+		for node in _getChildElements(puidListNode):
+			if _matches(node, 'puid') and node.hasAttribute('id'):
+				track.addPuid(node.getAttribute('id'))
+
+	def _addISRCs(self, isrcListNode, track):
+		for node in _getChildElements(isrcListNode):
+			if _matches(node, 'isrc') and node.hasAttribute('id'):
+				track.addISRC(node.getAttribute('id'))
+
+	def _addRelationsToEntity(self, relationListNode, entity):
+		targetType = _getUriAttr(relationListNode, 'target-type', NS_REL_1)
+
+		if targetType is None:
+			return
+
+		for node in _getChildElements(relationListNode):
+			if _matches(node, 'relation'):
+				rel = self._createRelation(node, targetType)
+				if rel is not None:
+					entity.addRelation(rel)
+
+
+	def _createRelation(self, relationNode, targetType):
+		relation = self._factory.newRelation()
+
+		relation.setType(_getUriAttr(relationNode, 'type', NS_REL_1))
+		relation.setTargetType(targetType)
+		resType = _getResourceType(targetType)
+		relation.setTargetId(_getIdAttr(relationNode, 'target', resType))
+
+		if relation.getType() is None \
+				or relation.getTargetType() is None \
+				or relation.getTargetId() is None:
+			return None
+
+		relation.setDirection(_getDirectionAttr(relationNode, 'direction'))
+		relation.setBeginDate(_getDateAttr(relationNode, 'begin'))
+		relation.setEndDate(_getDateAttr(relationNode, 'end'))
+
+		for a in _getUriListAttr(relationNode, 'attributes', NS_REL_1):
+			relation.addAttribute(a)
+
+		target = None
+		children = _getChildElements(relationNode)
+		if len(children) > 0:
+			node = children[0]
+			if _matches(node, 'artist'):
+				target = self._createArtist(node)	
+			elif _matches(node, 'release'):
+				target = self._createRelease(node)	
+			elif _matches(node, 'track'):
+				target = self._createTrack(node)	
+
+		relation.setTarget(target)
+
+		return relation
+
+
+#
+# XML output
+#
+
+class _XmlWriter(object):
+	def __init__(self, outStream, indentAmount='  ', newline="\n"):
+		self._out = outStream
+		self._indentAmount = indentAmount
+		self._stack = [ ]
+		self._newline = newline
+
+	def prolog(self, encoding='UTF-8', version='1.0'):
+		pi = '' % (version, encoding)
+		self._out.write(pi + self._newline)
+
+	def start(self, name, attrs={ }):
+		indent = self._getIndention()
+		self._stack.append(name)
+		self._out.write(indent + self._makeTag(name, attrs) + self._newline)
+
+	def end(self):
+		name = self._stack.pop()
+		indent = self._getIndention()
+		self._out.write('%s\n' % (indent, name))
+
+	def elem(self, name, value, attrs={ }):
+		# delete attributes with an unset value
+		for (k, v) in attrs.items():
+			if v is None or v == '':
+				del attrs[k]
+
+		if value is None or value == '':
+			if len(attrs) == 0:
+				return
+			self._out.write(self._getIndention())
+			self._out.write(self._makeTag(name, attrs, True) + '\n')
+		else:
+			escValue = saxutils.escape(value or '')
+			self._out.write(self._getIndention())
+			self._out.write(self._makeTag(name, attrs))
+			self._out.write(escValue)
+			self._out.write('\n' % name)
+
+	def _getIndention(self):
+		return self._indentAmount * len(self._stack)
+
+	def _makeTag(self, name, attrs={ }, close=False):
+		ret = '<' + name
+
+		for (k, v) in attrs.iteritems():
+			if v is not None:
+				v = saxutils.quoteattr(str(v))
+				ret += ' %s=%s' % (k, v)
+
+		if close:
+			return ret + '/>'
+		else:
+			return ret + '>'
+
+
+
+class MbXmlWriter(object):
+	"""Write XML in the Music Metadata XML format."""
+
+	def __init__(self, indentAmount='  ', newline="\n"):
+		"""Constructor.
+
+		@param indentAmount: the amount of whitespace to use per level
+		"""
+		self._indentAmount = indentAmount
+		self._newline = newline
+
+
+	def write(self, outStream, metadata):
+		"""Writes the XML representation of a Metadata object to a file.
+
+		@param outStream: an open file-like object
+		@param metadata: a L{Metadata} object
+		"""
+		xml = _XmlWriter(outStream, self._indentAmount, self._newline)
+
+		xml.prolog()
+		xml.start('metadata', {
+			'xmlns': NS_MMD_1,
+			'xmlns:ext': NS_EXT_1,
+		})
+
+		self._writeArtist(xml, metadata.getArtist())
+		self._writeRelease(xml, metadata.getRelease())
+		self._writeReleaseGroup(xml, metadata.getReleaseGroup())
+		self._writeTrack(xml, metadata.getTrack())
+		self._writeLabel(xml, metadata.getLabel())
+
+		if len(metadata.getArtistResults()) > 0:
+			xml.start('artist-list', {
+				'offset': metadata.artistResultsOffset,
+				'count': metadata.artistResultsCount,
+			})
+			for result in metadata.getArtistResults():
+				self._writeArtist(xml, result.getArtist(),
+					result.getScore())
+			xml.end()
+
+		if len(metadata.getReleaseResults()) > 0:
+			xml.start('release-list', {
+				'offset': metadata.releaseResultsOffset,
+				'count': metadata.releaseResultsCount,
+			})
+			for result in metadata.getReleaseResults():
+				self._writeRelease(xml, result.getRelease(),
+					result.getScore())
+			xml.end()
+
+		if len(metadata.getReleaseGroupResults()) > 0:
+			xml.start('release-group-list', {
+				'offset': metadata.releaseGroupResultsOffset,
+				'count': metadata.releaseGroupResultsCount
+			})
+			for result in metadata.getReleaseGroupResults():
+				self._writeReleaseGroup(xml, result.getReleaseGroup(),
+					result.getScore())
+			xml.end()
+
+		if len(metadata.getTrackResults()) > 0:
+			xml.start('track-list', {
+				'offset': metadata.trackResultsOffset,
+				'count': metadata.trackResultsCount,
+			})
+			for result in metadata.getTrackResults():
+				self._writeTrack(xml, result.getTrack(),
+					result.getScore())
+			xml.end()
+
+		if len(metadata.getLabelResults()) > 0:
+			xml.start('label-list', {
+				'offset': metadata.labelResultsOffset,
+				'count': metadata.labelResultsCount,
+			})
+			for result in metadata.getLabelResults():
+				self._writeLabel(xml, result.getLabel(),
+					result.getScore())
+			xml.end()
+
+		xml.end()
+
+
+	def _writeArtist(self, xml, artist, score=None):
+		if artist is None:
+			return
+
+		xml.start('artist', {
+			'id': mbutils.extractUuid(artist.getId()),
+			'type': mbutils.extractFragment(artist.getType()),
+			'ext:score': score,
+		})
+
+		xml.elem('name', artist.getName())
+		xml.elem('sort-name', artist.getSortName())
+		xml.elem('disambiguation', artist.getDisambiguation())
+		xml.elem('life-span', None, {
+			'begin': artist.getBeginDate(),
+			'end': artist.getEndDate(),
+		})
+
+		if len(artist.getAliases()) > 0:
+			xml.start('alias-list')
+			for alias in artist.getAliases():
+				xml.elem('alias', alias.getValue(), {
+					'type': alias.getType(),
+					'script': alias.getScript(),
+				})
+			xml.end()
+
+		if len(artist.getReleases()) > 0:
+			xml.start('release-list')
+			for release in artist.getReleases():
+				self._writeRelease(xml, release)
+			xml.end()
+
+		if len(artist.getReleaseGroups()) > 0:
+			xml.start('release-group-list')
+			for releaseGroup in artist.getReleaseGroups():
+				self._writeReleaseGroup(xml, releaseGroup)
+			xml.end()
+
+		self._writeRelationList(xml, artist)
+		# TODO: extensions
+
+		xml.end()
+
+
+	def _writeRelease(self, xml, release, score=None):
+		if release is None:
+			return
+
+		types = [mbutils.extractFragment(t) for t in release.getTypes()]
+		typesStr = None
+		if len(types) > 0:
+			typesStr = ' '.join(types)
+
+		xml.start('release', {
+			'id': mbutils.extractUuid(release.getId()),
+			'type': typesStr,
+			'ext:score': score,
+		})
+
+		xml.elem('title', release.getTitle())
+		xml.elem('text-representation', None, {
+			'language': release.getTextLanguage(),
+			'script': release.getTextScript()
+		})
+		xml.elem('asin', release.getAsin())
+
+		self._writeArtist(xml, release.getArtist())
+		self._writeReleaseGroup(xml, release.getReleaseGroup())
+
+		if len(release.getReleaseEvents()) > 0:
+			xml.start('release-event-list')
+			for event in release.getReleaseEvents():
+				self._writeReleaseEvent(xml, event)
+			xml.end()
+
+		if len(release.getDiscs()) > 0:
+			xml.start('disc-list')
+			for disc in release.getDiscs():
+				xml.elem('disc', None, { 'id': disc.getId() })
+			xml.end()
+
+		if len(release.getTracks()) > 0:
+			# TODO: count attribute
+			xml.start('track-list', {
+				'offset': release.getTracksOffset()
+			})
+			for track in release.getTracks():
+				self._writeTrack(xml, track)
+			xml.end()
+		
+		self._writeRelationList(xml, release)
+		# TODO: extensions
+
+		xml.end()
+
+	def _writeReleaseGroup(self, xml, rg, score = None):
+		if rg is None:
+			return
+
+		xml.start('release-group', {
+			'id': mbutils.extractUuid(rg.getId()),
+			'type': mbutils.extractFragment(rg.getType()),
+			'ext:score': score,
+		})
+
+		xml.elem('title', rg.getTitle())
+		self._writeArtist(xml, rg.getArtist())
+
+		if len(rg.getReleases()) > 0:
+			xml.start('release-list')
+			for rel in rg.getReleases():
+				self._writeRelease(xml, rel)
+			xml.end()
+
+		xml.end()
+
+	def _writeReleaseEvent(self, xml, event):
+		xml.start('event', {
+			'country': event.getCountry(),
+			'date': event.getDate(),
+			'catalog-number': event.getCatalogNumber(),
+			'barcode': event.getBarcode(),
+			'format': event.getFormat()
+		})
+
+		self._writeLabel(xml, event.getLabel())
+
+		xml.end()
+
+
+	def _writeTrack(self, xml, track, score=None):
+		if track is None:
+			return
+
+		xml.start('track', {
+			'id': mbutils.extractUuid(track.getId()),
+			'ext:score': score,
+		})
+		
+		xml.elem('title', track.getTitle())
+		xml.elem('duration', str(track.getDuration()))
+		self._writeArtist(xml, track.getArtist())
+
+		if len(track.getReleases()) > 0:
+			# TODO: offset + count
+			xml.start('release-list')
+			for release in track.getReleases():
+				self._writeRelease(xml, release)
+			xml.end()
+
+		if len(track.getPuids()) > 0:
+			xml.start('puid-list')
+			for puid in track.getPuids():
+				xml.elem('puid', None, { 'id': puid })
+			xml.end()
+
+		self._writeRelationList(xml, track)
+		# TODO: extensions
+
+		xml.end()
+
+
+	def _writeLabel(self, xml, label, score=None):
+		if label is None:
+			return
+
+		xml.start('label', {
+			'id': mbutils.extractUuid(label.getId()),
+			'type': mbutils.extractFragment(label.getType()),
+			'ext:score': score,
+		})
+
+		xml.elem('name', label.getName())
+		xml.elem('sort-name', label.getSortName())
+		xml.elem('disambiguation', label.getDisambiguation())
+		xml.elem('life-span', None, {
+			'begin': label.getBeginDate(),
+			'end': label.getEndDate(),
+		})
+
+		if len(label.getAliases()) > 0:
+			xml.start('alias-list')
+			for alias in label.getAliases():
+				xml.elem('alias', alias.getValue(), {
+					'type': alias.getType(),
+					'script': alias.getScript(),
+				})
+			xml.end()
+
+		# TODO: releases, artists
+
+		self._writeRelationList(xml, label)
+		# TODO: extensions
+
+		xml.end()
+
+
+	def _writeRelationList(self, xml, entity):
+		for tt in entity.getRelationTargetTypes():
+			xml.start('relation-list', {
+				'target-type': mbutils.extractFragment(tt),
+			})
+			for rel in entity.getRelations(targetType=tt):
+				self._writeRelation(xml, rel, tt)
+			xml.end()
+
+
+	def _writeRelation(self, xml, rel, targetType):
+		relAttrs = ' '.join([mbutils.extractFragment(a) 
+				for a in rel.getAttributes()])
+
+		if relAttrs == '':
+			relAttrs = None
+
+		attrs = {
+			'type': mbutils.extractFragment(rel.getType()),
+			'target': rel.getTargetId(),
+			'direction': rel.getDirection(),
+			'begin': rel.getBeginDate(),
+			'end': rel.getBeginDate(),
+			'attributes': relAttrs,
+		}
+
+		if rel.getTarget() is None:
+			xml.elem('relation', None, attrs)
+		else:
+			xml.start('relation', attrs)
+			if targetType == NS_REL_1 + 'Artist':
+				self._writeArtist(xml, rel.getTarget())
+			elif targetType == NS_REL_1 + 'Release':
+				self._writeRelease(xml, rel.getTarget())
+			elif targetType == NS_REL_1 + 'Track':
+				self._writeTrack(xml, rel.getTarget())
+			xml.end()
+			
+
+#
+# DOM Utilities
+#
+
+def _matches(node, name, namespace=NS_MMD_1):
+	"""Checks if an xml.dom.Node and a given name and namespace match."""
+
+	if node.localName == name and node.namespaceURI == namespace:
+		return True
+	else:
+		return False
+
+
+def _getChildElements(parentNode):
+	"""Returns all direct child elements of the given xml.dom.Node."""
+
+	children = [ ]
+	for node in parentNode.childNodes:
+		if node.nodeType == node.ELEMENT_NODE:
+			children.append(node)
+
+	return children
+
+
+def _getText(element, regex=None, default=None):
+	"""Returns the text content of the given xml.dom.Element.
+
+	This function simply fetches all contained text nodes, so the element
+	should not contain child elements.
+	"""
+	res = ''
+	for node in element.childNodes:
+		if node.nodeType == node.TEXT_NODE:
+			res += node.data
+
+	if regex is None or re.match(regex, res):
+		return res
+	else:
+		return default
+
+
+def _getPositiveIntText(element):
+	"""Returns the text content of the given xml.dom.Element as an int."""
+
+	res = _getText(element)
+
+	if res is None:
+		return None
+
+	try:
+		return int(res)
+	except ValueError:
+		return None
+
+
+def _getAttr(element, attrName, regex=None, default=None, ns=None):
+	"""Returns an attribute of the given element.
+
+	If there is no attribute with that name or the attribute doesn't
+	match the regular expression, default is returned.
+	"""
+	if element.hasAttributeNS(ns, attrName):
+		content = element.getAttributeNS(ns, attrName)
+
+		if regex is None or re.match(regex, content):
+			return content
+		else:
+			return default
+	else:
+		return default
+
+
+def _getDateAttr(element, attrName):
+	"""Gets an incomplete date from an attribute."""
+	return _getAttr(element, attrName, '^\d+(-\d\d)?(-\d\d)?$')
+
+
+def _getIdAttr(element, attrName, typeName):
+	"""Gets an ID from an attribute and turns it into an absolute URI."""
+	value = _getAttr(element, attrName)
+
+	return _makeAbsoluteUri('http://musicbrainz.org/' + typeName + '/', value)
+
+	
+
+def _getIntAttr(element, attrName, min=0, max=None, ns=None):
+	"""Gets an int from an attribute, or None."""
+	try:
+		val = int(_getAttr(element, attrName, ns=ns))
+
+		if max is None:
+			max = val
+
+		if min <= val <= max:
+			return val
+		else:
+			return None
+	except ValueError:
+		return None # raised if conversion to int fails
+	except TypeError:
+		return None # raised if no such attribute exists
+
+
+def _getUriListAttr(element, attrName, prefix=NS_MMD_1):
+	"""Gets a list of URIs from an attribute."""
+	if not element.hasAttribute(attrName):
+		return [ ]
+
+	f = lambda x: x != ''
+	uris = filter(f, re.split('\s+', element.getAttribute(attrName)))
+
+	m = lambda x: _makeAbsoluteUri(prefix, x)
+	uris = map(m, uris)
+
+	return uris
+
+
+def _getUriAttr(element, attrName, prefix=NS_MMD_1):
+	"""Gets a URI from an attribute.
+
+	This also works for space-separated URI lists. In this case, the
+	first URI is returned.
+	"""
+	uris = _getUriListAttr(element, attrName, prefix)
+	if len(uris) > 0:
+		return uris[0]
+	else:
+		return None
+
+
+def _getBooleanAttr(element, attrName):
+	"""Gets a boolean value from an attribute."""
+	value = _getAttr(element, attrName)
+	if value == 'true':
+		return True
+	elif value == 'false':	
+		return False
+	else:
+		return None
+
+
+def _getDirectionAttr(element, attrName):
+	"""Gets the Relation reading direction from an attribute."""
+	regex = '^\s*(' + '|'.join((
+				model.Relation.DIR_FORWARD,
+				model.Relation.DIR_BACKWARD)) + ')\s*$'
+	return _getAttr(element, 'direction', regex, model.Relation.DIR_NONE)
+
+
+def _makeAbsoluteUri(prefix, uriStr):
+	"""Creates an absolute URI adding prefix, if necessary."""
+	if uriStr is None:
+		return None
+
+	(scheme, netloc, path, params, query, frag) = urlparse.urlparse(uriStr)
+
+	if scheme == '' and netloc == '':
+		return prefix + uriStr
+	else:
+		return uriStr
+ 
+ 
+def _getResourceType(uri):
+	"""Gets the resource type from a URI.
+
+	The resource type is the basename of the URI's path.
+	"""
+	m = re.match('^' + NS_REL_1 + '(.*)$', uri)
+	
+	if m:
+		return m.group(1).lower()
+	else:
+		return None
+
+# EOF
diff --git a/search.py b/search.py
new file mode 100644
index 00000000..5adea6d0
--- /dev/null
+++ b/search.py
@@ -0,0 +1,29 @@
+import sys
+import musicbrainz2.webservice as ws
+import musicbrainz2.model as m
+
+def findArtist(name):
+
+	if len(name) == 0 or name == 'Add an artist':
+		return '''
Please enter an artist
'''
+		
+	q = ws.Query()
+
+	f = ws.ArtistFilter(name, limit=5)
+	artistResults = ws.Query().getArtists(ws.ArtistFilter(name, limit=5))
+		
+	if len(artistResults) > 1:
+	
+		return '''We found a few different artists. Which one did you want?

'''
+
+		for result in artistResults:
+			artist = result.artist
+			return ''' %s 
''' % (artist.id, artist.name)
+			
+	elif len(artistRestuls) == 1:
+		
+		return '''Ok, we're going to add %s''' % artist.name
+		
+	else:
+
+		return '''We couldn't find any artists!'''
\ No newline at end of file
diff --git a/server.conf b/server.conf
new file mode 100644
index 00000000..74a48353
--- /dev/null
+++ b/server.conf
@@ -0,0 +1,19 @@
+[global]
+server.socket_host = "0.0.0.0"
+server.socket_port = 8181
+server.thread_pool = 10
+
+[/]
+tools.staticdir.root = os.getcwd()
+
+[/data/images]
+tools.staticdir.on = True
+tools.staticdir.dir = "data/images"
+
+[/data/css]
+tools.staticdir.on = True
+tools.staticdir.dir = "data/css"
+
+[/data/js]
+tools.staticdir.on = True
+tools.staticdir.dir = "data/js"
\ No newline at end of file
diff --git a/templates.py b/templates.py
new file mode 100644
index 00000000..11218fe1
--- /dev/null
+++ b/templates.py
@@ -0,0 +1,30 @@
+_header = '''
+	
+	
+		headphones
+		
+	
+	
+	
'''
+			
+_logobar = '''
+		
+			

+			
+			


+	'''
+
+_nav = '''

+					HOME
+					UPCOMING
+					MANAGE    
+					HISTORY
+					SETTINGS
+					SHUTDOWN
+			
'''
+	
+_footer = '''
+	

+	
+	'''
\ No newline at end of file
diff --git a/webServer.py b/webServer.py
new file mode 100644
index 00000000..f6eddc17
--- /dev/null
+++ b/webServer.py
@@ -0,0 +1,350 @@
+import templates
+import config
+import cherrypy
+import search
+import musicbrainz2.webservice as ws
+import musicbrainz2.model as m
+import musicbrainz2.utils as u
+import os
+import string
+import time
+import sqlite3
+import sys
+import configobj
+
+
+
+database = os.path.join(os.path.dirname(__file__), 'headphones.db')
+
+class Headphones:
+
+	def index(self):
+		page = [templates._header]
+		page.append(templates._logobar)
+		page.append(templates._nav)
+		#Display Database if it exists:
+		if os.path.exists(database):
+			conn=sqlite3.connect(database)
+			c=conn.cursor()
+			c.execute('SELECT ArtistName, ArtistID, Status from artists order by ArtistSortName')
+			results = c.fetchall()
+			c.close()
+			i = 0
+			page.append('''

+						
+						
+						
+						
+						
+						''')
+			while i < len(results):
+				c.execute('''SELECT AlbumTitle, ReleaseDate, DateAdded, AlbumID from albums WHERE ArtistName="%s" order by ReleaseDate DESC''' % results[i][0])
+				latestalbum = c.fetchall()
+				if latestalbum[0][1] > latestalbum[0][2]:
+					newalbumName = '%s' % (latestalbum[0][3], latestalbum[0][0])
+					releaseDate = '(%s)' % latestalbum[0][1]
+				else:
+					newalbumName = 'None'
+					releaseDate = ""
+				if results[i][2] == 'Paused':
+					newStatus = '''%s(resume)''' % (results[i][2], results[i][1])
+				else:
+					newStatus = '''%s(pause)''' % (results[i][2], results[i][1])
+				page.append('''
+								
+								''' % (results[i][1], results[i][0], results[i][1], results[i][1], newStatus, newalbumName, releaseDate))	
+				i = i+1
+			page.append('''
Artist NameStatusUpcoming Albums      
%s 
+								(link) [delete]%s%s %s 
''')
+		else:
+			page.append("""
Add some artists to the database!
""")
+		page.append(templates._footer)
+		return page
+	index.exposed = True
+	
+
+	def artistPage(self, ArtistID):
+		page = [templates._header]
+		page.append(templates._logobar)
+		page.append(templates._nav)
+		conn=sqlite3.connect(database)
+		c=conn.cursor()
+		c.execute('''SELECT AlbumTitle, ReleaseDate, AlbumID, Status, ArtistName, AlbumASIN from albums WHERE ArtistID="%s" order by ReleaseDate DESC''' % ArtistID)
+		results = c.fetchall()
+		c.close()
+		i = 0
+		page.append('''

+						
%s 

+						
+						
+						
+						
+						
+						
+						''' % (results[0][4]))
+		while i < len(results):
+			if results[i][3] == 'Skipped':
+				newStatus = '''%s [want]''' % (results[i][3], results[i][2], ArtistID)
+			elif results[i][3] == 'Wanted':
+				newStatus = '''%s[skip]''' % (results[i][3], results[i][2], ArtistID)				
+			elif results[i][3] == 'Downloaded':
+				newStatus = '''%s[retry]''' % (results[i][3], results[i][2], ArtistID)
+			else:
+				newStatus = '%s' % (results[i][3])
+			page.append('''
+							
+							
+							''' % (results[i][5], results[i][2], results[i][0], results[i][2], results[i][1], newStatus))	
+			i = i+1
+		page.append('''
Album NameRelease DateStatus      
%s 
+							(link)%s%s
''')
+		page.append(templates._footer)
+		return page
+	artistPage.exposed = True
+	
+	
+	def albumPage(self, AlbumID):
+		page = [templates._header]
+		page.append(templates._logobar)
+		page.append(templates._nav)
+		
+		conn=sqlite3.connect(database)
+		c=conn.cursor()
+		c.execute('''SELECT ArtistID, ArtistName, AlbumTitle, TrackTitle, TrackDuration, TrackID, AlbumASIN from tracks WHERE AlbumID="%s"''' % AlbumID)
+		results = c.fetchall()
+		if results[0][6]:
+			albumart = '''


''' % results[0][6]
+		else:
+			albumart = ''
+		c.close()
+		i = 0
+		page.append('''

+					%s - %s
%s
+					

+					
+					
+					
+					
+					''' % (results[0][0], results[0][1], results[0][2], albumart))
+		while i < len(results):
+			page.append('''
+							
+							''' % (i+1, results[i][3], results[i][5], results[i][4]))	
+			i = i+1
+		page.append('''
Track #Track TitleDuration      
%s%s (link)%s
''')
+
+		
+		page.append(templates._footer)
+		return page
+	
+	albumPage.exposed = True
+	
+	
+	def findArtist(self, name):
+	
+		page = [templates._header]
+		if len(name) == 0 or name == 'Add an artist':
+			raise cherrypy.HTTPRedirect("/")
+		else:
+			artistResults = ws.Query().getArtists(ws.ArtistFilter(string.replace(name, '&', '%38'), limit=8))
+			if len(artistResults) == 0:
+				page.append('''No results!Go back''')
+				
+			elif len(artistResults) > 1:
+				page.append('''Search returned multiple artists. Click the artist you want to add:

''')
+				for result in artistResults:
+					artist = result.artist
+					page.append('''%s (more info)
''' % (u.extractUuid(artist.id), artist.name, u.extractUuid(artist.id)))
+				return page
+			else:
+				for result in artistResults:
+					artist = result.artist
+					raise cherrypy.HTTPRedirect("/addArtist?artistid=%s" % u.extractUuid(artist.id))
+		
+	findArtist.exposed = True
+
+	def artistInfo(self, artistid):
+		page = [templates._header]
+		inc = ws.ArtistIncludes(releases=(m.Release.TYPE_OFFICIAL, m.Release.TYPE_ALBUM), releaseGroups=True)
+		artist = ws.Query().getArtistById(artistid, inc)
+		page.append('''Artist Name: %s 
 ''' % artist.name)
+		page.append('''Unique ID: %s 

Albums:
''' % u.extractUuid(artist.id))
+		for rg in artist.getReleaseGroups():
+			page.append('''%s 
''' % rg.title)
+		return page
+		
+	artistInfo.exposed = True
+
+	def addArtist(self, artistid):
+		inc = ws.ArtistIncludes(releases=(m.Release.TYPE_OFFICIAL, m.Release.TYPE_ALBUM), ratings=False, releaseGroups=False)
+		artist = ws.Query().getArtistById(artistid, inc)
+		conn=sqlite3.connect(database)
+		c=conn.cursor()
+		c.execute('CREATE TABLE IF NOT EXISTS artists (ArtistID TEXT UNIQUE, ArtistName TEXT, ArtistSortName TEXT, DateAdded TEXT, Status TEXT)')
+		c.execute('CREATE TABLE IF NOT EXISTS albums (ArtistID TEXT, ArtistName TEXT, AlbumTitle TEXT, AlbumASIN TEXT, ReleaseDate TEXT, DateAdded TEXT, AlbumID TEXT UNIQUE, Status TEXT)')
+		c.execute('CREATE TABLE IF NOT EXISTS tracks (ArtistID TEXT, ArtistName TEXT, AlbumTitle TEXT, AlbumASIN TEXT, AlbumID TEXT, TrackTitle TEXT, TrackDuration TEXT, TrackID TEXT)')
+		c.execute('SELECT ArtistID from artists')
+		artistlist = c.fetchall()
+		if any(artistid in x for x in artistlist):
+			page = [templates._header]
+			page.append('''%s has already been added. Go back.''' % artist.name)
+			return page
+		else:
+			c.execute('INSERT INTO artists VALUES( ?, ?, ?, CURRENT_DATE, ?)', (artistid, artist.name, artist.sortName, 'Active'))
+			for release in artist.getReleases():
+				releaseid = u.extractUuid(release.id)
+				inc = ws.ReleaseIncludes(artist=True, releaseEvents= True, tracks= True, releaseGroup=True)
+				results = ws.Query().getReleaseById(releaseid, inc)
+				time.sleep(0.6)
+				for event in results.releaseEvents:
+					if event.country == 'US':
+						c.execute('INSERT INTO albums VALUES( ?, ?, ?, ?, ?, CURRENT_DATE, ?, ?)', (artistid, results.artist.name, results.title, results.asin, results.getEarliestReleaseDate(), u.extractUuid(results.id), 'Skipped'))
+						conn.commit()
+						c.execute('SELECT ReleaseDate, DateAdded from albums WHERE AlbumID="%s"' % u.extractUuid(results.id))
+						latestrelease = c.fetchall()
+						if latestrelease[0][0] > latestrelease[0][1]:
+							c.execute('UPDATE albums SET Status = "Wanted" WHERE AlbumID="%s"' % u.extractUuid(results.id))
+						else:
+							pass
+						for track in results.tracks:
+							c.execute('INSERT INTO tracks VALUES( ?, ?, ?, ?, ?, ?, ?, ?)', (artistid, results.artist.name, results.title, results.asin, u.extractUuid(results.id), track.title, track.duration, u.extractUuid(track.id)))
+							conn.commit()
+							c.close()
+					else:
+						pass
+			raise cherrypy.HTTPRedirect("/")
+		
+		
+	addArtist.exposed = True
+	
+		#page for pausing an artist
+	def pauseArtist(self, ArtistID):
+		conn=sqlite3.connect(database)
+		c=conn.cursor()
+		c.execute('UPDATE artists SET status = "Paused" WHERE ArtistId="%s"' % ArtistID)
+		conn.commit()
+		c.close()
+		raise cherrypy.HTTPRedirect("/")
+		
+	pauseArtist.exposed = True
+	
+	def resumeArtist(self, ArtistID):
+		conn=sqlite3.connect(database)
+		c=conn.cursor()
+		c.execute('UPDATE artists SET status = "Active" WHERE ArtistId="%s"' % ArtistID)
+		conn.commit()
+		c.close()
+		raise cherrypy.HTTPRedirect("/")
+		
+	resumeArtist.exposed = True
+	
+	def deleteArtist(self, ArtistID):
+		conn=sqlite3.connect(database)
+		c=conn.cursor()
+		c.execute('''DELETE from artists WHERE ArtistID="%s"''' % ArtistID)
+		c.execute('''DELETE from albums WHERE ArtistID="%s"''' % ArtistID)
+		c.execute('''DELETE from tracks WHERE ArtistID="%s"''' % ArtistID)
+		conn.commit()
+		c.close()
+		raise cherrypy.HTTPRedirect("/")
+		
+	deleteArtist.exposed = True
+	
+	
+	def queueAlbum(self, AlbumID, ArtistID):
+		conn=sqlite3.connect(database)
+		c=conn.cursor()
+		c.execute('UPDATE albums SET status = "Wanted" WHERE AlbumID="%s"' % AlbumID)
+		conn.commit()
+		c.close()
+		raise cherrypy.HTTPRedirect("/artistPage?ArtistID=%s" % ArtistID)
+		
+	queueAlbum.exposed = True
+
+	def unqueueAlbum(self, AlbumID, ArtistID):
+		conn=sqlite3.connect(database)
+		c=conn.cursor()
+		c.execute('UPDATE albums SET status = "Skipped" WHERE AlbumID="%s"' % AlbumID)
+		conn.commit()
+		c.close()
+		raise cherrypy.HTTPRedirect("/artistPage?ArtistID=%s" % ArtistID)
+		
+	unqueueAlbum.exposed = True
+	
+	
+	
+	
+	def upcoming(self):
+		page = [templates._header]
+		page.append(templates._logobar)
+		page.append(templates._nav)
+		page.append(templates._footer)
+		return page
+	upcoming.exposed = True
+	
+	def manage(self):
+		page = [templates._header]
+		page.append(templates._logobar)
+		page.append(templates._nav)
+		page.append(templates._footer)
+		return page
+	manage.exposed = True
+	
+	def history(self):
+		page = [templates._header]
+		page.append(templates._logobar)
+		page.append(templates._nav)
+		page.append(templates._footer)
+		return page
+	history.exposed = True
+	
+	def config(self):
+		page = [templates._header]
+		page.append(templates._logobar)
+		page.append(templates._nav)
+		page.append(config.form)
+		page.append(templates._footer)
+		return page
+					
+	config.exposed = True
+	
+	def configUpdate(self, http_host='localhost', http_username=None, http_port=8181, http_password=None, launch_browser=0,
+		sab_host=None, sab_username=None, sab_apikey=None, sab_password=None, sab_category=None, music_download_dir=None,
+		usenet_retention=None, nzbmatrix=0, nzbmatrix_username=None, nzbmatrix_apikey=None, include_lossless=0, 
+		move_to_itunes=0, path_to_itunes=None, rename_mp3s=0, add_album_art=0):
+		
+		configs = configobj.ConfigObj(os.path.join(os.path.dirname(__file__), 'config.ini'))
+		SABnzbd = configs['SABnzbd']
+		General = configs['General']
+		NZBMatrix = configs['NZBMatrix']
+		General['http_host'] = http_host
+		General['http_port'] = http_port
+		General['http_username'] = http_username
+		General['http_password'] = http_password
+		General['launch_browser'] = launch_browser
+		SABnzbd['sab_host'] = sab_host
+		SABnzbd['sab_username'] = sab_username
+		SABnzbd['sab_password'] = sab_password		
+		SABnzbd['sab_apikey'] = sab_apikey
+		SABnzbd['sab_category'] = sab_category
+		General['music_download_dir'] = music_download_dir
+		General['usenet_retention'] = usenet_retention
+		NZBMatrix['nzbmatrix'] = nzbmatrix
+		NZBMatrix['nzbmatrix_username'] = nzbmatrix_username
+		NZBMatrix['nzbmatrix_apikey'] = nzbmatrix_apikey
+		General['include_lossless'] = include_lossless
+		General['move_to_itunes'] = move_to_itunes
+		General['path_to_itunes'] = path_to_itunes
+		General['rename_mp3s'] = rename_mp3s
+		General['add_album_art'] = add_album_art
+		
+		configs.write()
+		reload(config)
+		raise cherrypy.HTTPRedirect("/config")
+		
+		
+	configUpdate.exposed = True
+
+	def shutdown(self):
+		sys.exit('Headphones is shutting down')
+	shutdown.exposed = True
\ No newline at end of file