Download Install Tutorial Docs FAQ Tools Wiki ∇ License Team IRC Planet Involvement Shop Book

Changeset 780

Show
Ignore:
Timestamp:
11/02/05 18:27:07
Author:
fumanchu
Message:

Docs: new config, error sections for 2.2.

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • trunk/docs/book/xml/configsystemoverview.xml

    r683 r780  
    11<?xml version="1.0" encoding="UTF-8"?> 
    2 <section xmlns:db="http://docbook.org/docbook-ng" 
    3          xmlns:xi="http://www.w3.org/2001/XInclude" 
    4          xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
    5          xml:id="configsystemoverview"> 
    6   <title>Configuration system overview</title> 
    7   <para>The CherryPy configuration system provides fine-grained control over 
    8   how each part of the application should react. You will use it for two 
    9   reasons:</para> 
    10   <itemizedlist> 
    11     <listitem>Web server settings</listitem> 
    12     <listitem>Enabling filters per path</listitem> 
    13   </itemizedlist> 
    14   <para>You will be able to declare the configuration settings either from a 
    15   file or from a Python dictionary.</para> 
    16   <para>First of all, let's see how a typical configuration file is 
    17   defined.</para> 
    18   <example> 
    19     <title>Configuration file</title> 
    20     <programlisting linenumbering="numbered"> 
     2<section xmlns:db="http://docbook.org/docbook-ng" xmlns:xi="http://www.w3.org/2001/XInclude" 
     3         xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xml:id="configsystemoverview"> 
     4    <title>Configuration system</title> 
     5    <para>The CherryPy configuration system provides fine-grained control over how each part of the 
     6    application should react. You will use it for two reasons:</para> 
     7    <itemizedlist> 
     8        <listitem> 
     9            <para>Web server settings</para> 
     10        </listitem> 
     11        <listitem> 
     12            <para>Enabling filters per path</para> 
     13        </listitem> 
     14    </itemizedlist> 
     15    <para>You will be able to declare the configuration settings either from a file or from a Python 
     16    dictionary.</para> 
     17    <para>First of all, let's see how a typical configuration file is defined.</para> 
     18    <example> 
     19        <title>Configuration file</title> 
     20        <programlisting linenumbering="numbered"> 
    2121            # The configuration file called myconfigfile.conf 
    2222            [global] 
    …… 
    4545            cherrypy.config.update(file="myconfigfile.conf")  
    4646        </programlisting> 
    47   </example> 
    48   <para>The settings can also be defined using a python dictionary instead of 
    49   a file as follows:</para> 
    50   <example> 
    51     <title>Configuration dictionary</title> 
    52     <programlisting linenumbering="numbered"> 
     47    </example> 
     48    <para>The settings can also be defined using a python dictionary instead of a file as 
     49  follows:</para> 
     50    <example> 
     51        <title>Configuration dictionary</title> 
     52        <programlisting linenumbering="numbered"> 
    5353      settings = {  
    5454         'global': { 
    …… 
    7777      cherrypy.config.update(settings) 
    7878        </programlisting> 
    79   </example> 
    80   <para>Each section of the configuration refers to a URL path; each path is 
    81   mapped to a published object of the tree handled by CherryPy. Therefore when 
    82   the server receives a request for <code>/css/default.css</code>, the static 
    83   filter will be called and the server will actually return the physical file 
    84   name <filename>data/css/default.css</filename>.</para> 
    85   <para>Since the path <code>/service/xmlrpc</code> has the XML-RPC filter 
    86   enabled, all the exposed methods of the object 
    87   <code>cherrypy.root.service.xmlrpc</code> will be treated as XML-RPC 
    88   methods.</para> 
    89   <para>The root entry, defined as <code>global</code>, is also responsible 
    90   for defining the server settings such as the port, the protocol version to 
    91   use by default, the number of threads to start with the server, etc.</para> 
    92   <para>All values in the configuration file must be valid Python values. 
    93   Strings must be quoted, booleans must be True or False, etc.</para> 
    94   <para>The <code>server.environment</code> entry controls how CherryPy should 
    95   run. Three values are legal:</para> 
    96   <itemizedlist> 
    97     <listitem>development <itemizedlist> 
    98         <listitem>logDebugInfoFilter is enabled by default</listitem> 
    99         <listitem>HTTPErrors (and therefore the default _cpOnError) display 
    100         tracebacks in the browser if errors occur</listitem> 
    101         <listitem>autoreload is enabled by default</listitem> 
    102       </itemizedlist></listitem> 
    103     <listitem>production <itemizedlist> 
    104         <listitem>logDebugInfoFilter is disabled by default</listitem> 
    105         <listitem> 
    106           <para>tracebacks are logged, but are not displayed in the 
    107           browser</para> 
    108         </listitem> 
    109         <listitem>autoreload is disabled by default</listitem> 
    110       </itemizedlist></listitem> 
    111     <listitem>staging (same as production for the moment)</listitem> 
    112   </itemizedlist> 
     79    </example> 
     80    <section> 
     81        <title>Configuration Sections</title> 
     82        <para>Each section of the configuration refers to an object path; the object path is used to 
     83        lookup the correct handler for each Request-URI. Therefore when the server receives a 
     84        Request-URI of <code>/css/default.css</code>, the static filter will handle the request, and 
     85        the server will actually return the physical file at 
     86        <filename>data/css/default.css</filename>. Since the path <code>/service/xmlrpc</code> has 
     87        the XML-RPC filter enabled, all the exposed methods of the object 
     88        <code>cherrypy.root.service.xmlrpc</code> will be treated as XML-RPC methods.</para> 
     89        <para>The <code>global</code> entry represents settings which apply outside the request 
     90        process, including server settings such as the port, the protocol version to use by default, 
     91        the number of threads to start with the server, etc. This is <emphasis>not</emphasis> the 
     92        same as the root entry <code>[/]</code>, which maps to cherrypy.root.</para> 
     93        <para>By default, URI's and object paths are equivalent; however, filters may rewrite the 
     94        objectPath to produce a different mapping between URI's and handlers. This is necessary, for 
     95        example, when mounting applications at virtual roots (e.g. serving the object path 
     96        <code>/welcome</code> at the URI "/users/~rdelon/welcome").</para> 
     97    </section> 
     98    <section> 
     99        <title>Configuration Entries</title> 
     100        <para>All values in the configuration file must be valid Python values. Strings must be 
     101        quoted, booleans must be True or False, etc.</para> 
     102        <section> 
     103            <title>server.environment</title> 
     104            <para>The <code>server.environment</code> entry controls how CherryPy should run. Three 
     105            values are built in:</para> 
     106            <itemizedlist> 
     107                <listitem> 
     108                    <para>development</para> 
     109                    <itemizedlist> 
     110                        <listitem> 
     111                            <para>logDebugInfoFilter is enabled</para> 
     112                        </listitem> 
     113                        <listitem> 
     114                            <para>HTTPErrors (and therefore the default _cpOnError) display 
     115                            tracebacks in the browser if errors occur</para> 
     116                        </listitem> 
     117                        <listitem> 
     118                            <para>autoreload is enabled</para> 
     119                        </listitem> 
     120                        <listitem> 
     121                            <para>NotFound errors (404) are listed in the error.log</para> 
     122                        </listitem> 
     123                    </itemizedlist> 
     124                </listitem> 
     125                <listitem> 
     126                    <para>production</para> 
     127                    <itemizedlist> 
     128                        <listitem> 
     129                            <para>logDebugInfoFilter is disabled</para> 
     130                        </listitem> 
     131                        <listitem> 
     132                            <para>tracebacks are logged, but are not displayed in the browser</para> 
     133                        </listitem> 
     134                        <listitem> 
     135                            <para>autoreload is disabled</para> 
     136                        </listitem> 
     137                        <listitem> 
     138                            <para>NotFound errors (404) aren't listed in the error log</para> 
     139                        </listitem> 
     140                    </itemizedlist> 
     141                </listitem> 
     142                <listitem> 
     143                    <para>staging (same as production for the moment)</para> 
     144                </listitem> 
     145            </itemizedlist> 
     146            <para>Beginning in CherryPy 2.2, the behavior of each environment is defined in 
     147            <code>cherrypy.config.environments</code>, a dict whose keys are "development", 
     148            "production", etc, and whose values are dicts of config keys and values. Application 
     149            developers are free to modify existing environments, or define new environments for use 
     150            by their deployers, by modifying this container. For example, if you develop an 
     151            application which absolutely cannot handle autoreload, your app can set 
     152            <code>cherrypy.config.environments['development']['autoreload.on'] = False</code>. 
     153            Deployers who selected the "development" environment would then be free from the danger 
     154            of autoreload interacting with your application. Another example of using 
     155            config.environments directly might be an application which needs a "development" and 
     156            "production" environment, but also separate "beta", "rc", "live data" and/or "testing" 
     157            environments.</para> 
     158        </section> 
     159    </section> 
    113160</section> 

  • trunk/docs/book/xml/errorhandling.xml

    r683 r780  
    11<?xml version="1.0" encoding="UTF-8"?> 
    2 <section xmlns:db="http://docbook.org/docbook-ng" 
    3          xmlns:xi="http://www.w3.org/2001/XInclude" 
    4          xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
    5          xml:id="globaloverviewcherrypy"> 
     2<section xmlns:db="http://docbook.org/docbook-ng" xmlns:xi="http://www.w3.org/2001/XInclude" 
     3         xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xml:id="globaloverviewcherrypy"> 
    64    <title>Exceptions and Error Handling</title> 
    7     <para> 
    8         Unhandled exceptions raised inside CherryPy applications result in a call 
    9         to the _cpOnError function.  HTTPError and HTTPRedirect exceptions do not 
    10         result in calls to _cpOnError.  HTTPError exceptions force the server to set  
    11         response status and return an error page. 
    12     </para> 
     5    <section> 
     6        <title>Unanticipated exceptions</title> 
     7        <para>When an unhandled exception is raised inside CherryPy, three actions occur (in 
     8        order):</para> 
     9        <itemizedlist> 
     10            <listitem> 
     11                <para><code>beforeErrorResponse</code> filter methods are called</para> 
     12            </listitem> 
     13            <listitem> 
     14                <para>a <code>_cpOnError</code> method is called</para> 
     15            </listitem> 
     16            <listitem> 
     17                <para><code>afterErrorResponse</code> filter methods are called</para> 
     18            </listitem> 
     19        </itemizedlist> 
     20        <para>The error response filter methods are defined by each filter; they cannot prevent the 
     21        call to <code>_cpOnError</code> (unless <code>beforeErrorResponse</code> raises an exception, 
     22        including HTTPRedirect).</para> 
     23        <para>The <code>_cpOnError</code> function is a CherryPy "special attribute"; that is, you 
     24        can define your own <code>_cpOnError</code> method for any branch in your 
     25        <code>cherrypy.root</code> object tree, and it will be invoked for all child handlers. For 
     26        example:</para> 
     27        <example> 
     28            <title>A custom <code>_cpOnError</code> method</title> 
     29            <programlisting>import cherrypy 
     30 
     31class Root: 
     32     
     33    def _cpOnError(self): 
     34        cherrypy.response.body = ("We apologise for the fault in the website. " 
     35                                  "Those responsible have been sacked.") 
     36     
     37    def index(self): 
     38        return "A m" + 00 + "se once bit my sister..." 
     39    index.exposed = True</programlisting> 
     40        </example> 
     41        <para>The default <code>_cpOnError</code> function simply responds as if an HTTPError 500 had 
     42        been raised (see the next section).</para> 
     43        <para>If an HTTPRedirect is raised during the error-handling process, it will be handled 
     44        appropriately. If any other kind of error occurs during the handling of an initial error, 
     45        then CherryPy punts, returning a bare-bones, <code>text/plain</code> error response 
     46        (containing both tracebacks if <code>server.showTracebacks</code> is True).</para> 
     47    </section> 
     48    <section> 
     49        <title>HTTPError</title> 
     50        <para>HTTPError exceptions do not result in calls to <code>_cpOnError</code>. Instead, they 
     51        have their own <code>_cpOnHTTPError</code> function. Like <code>_cpOnError</code>, this is a 
     52        "special attribute" and can be overridden by cherrypy.root objects. The default 
     53        <code>_cpOnHTTPError</code> handler sets the HTTP response to a pretty HTML error 
     54        page.</para> 
     55    </section> 
     56    <section> 
     57        <title>HTTPRedirect</title> 
     58        <para>HTTPRedirect exceptions are not errors; therefore, there is no way to override their 
     59        behavior. They set the response to an appropriate status, header set, and body, according to 
     60        the HTTP spec.</para> 
     61    </section> 
    1362</section> 

Hosted by WebFaction

Log in as guest/cpguest to create tickets