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

Changeset 705

Show
Ignore:
Timestamp:
10/03/05 01:05:52
Author:
fumanchu
Message:

Lots of updates to apireference.xml.

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • trunk/docs/book/xml/apireference.xml

    r701 r705  
    44    <title>API reference</title> 
    55    <section id="cherrypy"> 
    6         <title>cherrypy</title> 
    7         <itemizedlist> 
    8             <listitem> 
    9                 <title>cherrypy.threadData</title> 
    10                 <para>This attribute holds attributes that map to this thread only.</para> 
    11             </listitem> 
    12         </itemizedlist> 
     6        <title>cherrypy.threadData</title> 
     7        <para>This attribute holds attributes that map to this thread only.</para> 
    138    </section> 
    149    <section id="cherrypyrequest"> 
    …… 
    1611        <section> 
    1712            <title>cherrypy.request.remoteAddr</title> 
    18             <para>This attribute is a string containing the IP address of the client. It will 
    19             be an empty string if it is not available.</para> 
     13            <para>This attribute is a string containing the IP address of the client. It will be an 
     14            empty string if it is not available.</para> 
    2015        </section> 
    2116        <section> 
    2217            <title>cherrypy.request.remotePort</title> 
    23             <para>This attribute is an int containing the TCP port number of the client. It 
    24             will be -1 if it is not available.</para> 
     18            <para>This attribute is an int containing the TCP port number of the client. It will be 
     19            -1 if it is not available.</para> 
    2520        </section> 
    2621        <section> 
    2722            <title>cherrypy.request.remoteHost</title> 
    28             <para>This attribute is a string containing the remote hostname of the 
    29             client.</para> 
     23            <para>This attribute is a string containing the remote hostname of the client.</para> 
    3024        </section> 
    3125        <section> 
    3226            <title>cherrypy.request.headerMap</title> 
    33             <para>This attribute is dictionary containing the received HTTP headers.</para> 
     27            <para>This attribute is a dictionary containing the received HTTP headers, with 
     28            automatically titled keys (e.g., "Content-Type"). As it's a dictionary, no duplicates are 
     29            allowed.</para> 
     30        </section> 
     31        <section> 
     32            <title>cherrypy.request.headers</title> 
     33            <para>This attribute is a list of (header, value) tuples containing the received HTTP 
     34            headers. In general, you probably want to use headerMap instead; this is only here in 
     35            case you need to inspect duplicates in the request headers.</para> 
    3436        </section> 
    3537        <section> 
    3638            <title>cherrypy.request.requestLine</title> 
    37             <para>This attribute is a string containing the first line of the raw HTTP 
    38             request.</para> 
     39            <para>This attribute is a string containing the first line of the raw HTTP request; for 
     40            example, "GET /path/page HTTP/1.1".</para> 
    3941        </section> 
    4042        <section> 
    4143            <title>cherrypy.request.simpleCookie</title> 
    42             <para>This attribute is a SimpleCookie instance from the standard library's 
    43             Cookie module which contains the incoming cookie values from the client.</para> 
     44            <para>This attribute is a SimpleCookie instance from the standard library's Cookie module 
     45            which contains the incoming cookie values from the client.</para> 
    4446        </section> 
    4547        <section> 
    4648            <title>cherrypy.request.rfile</title> 
    47             <para>This attribute is the input stream to the client. See 
     49            <para>This attribute is the input stream to the client, if applicable. See 
    4850            cherrypy.request.processRequestBody for more information.</para> 
    4951        </section> 
    5052        <section> 
     53            <title>cherrypy.request.body</title> 
     54            <para>This attribute is the request entity body, if applicable. See 
     55            cherrypy.request.processRequestBody for more information.</para> 
     56        </section> 
     57        <section> 
    5158            <title>cherrypy.request.processRequestBody</title> 
    52             <para>This attribute should be accessed during the beforeRequestBody stage of the 
    53             request (if you don't know what this means, read the section on filters). This 
    54             specifies whether or not the request's POST data will be parsed into the 
    55             cherrypy.request.paramMap. It defaults to true for POST requests, but when false, 
    56             cherrypy.request.rfile will be readable by the exposed method. Otherwise, rfile 
    57             is completely read before control is handled to the exposed method.</para> 
     59            <para>This attribute specifies whether or not the request's body (request.rfile, which is 
     60            POST or PUT data) will be handled by CherryPy. If True (the default for POST and PUT 
     61            requests), then request.rfile will be consumed by CherryPy (and unreadable after that). 
     62            If the request Content-Type is "application/x-www-form-urlencoded", then the rfile will 
     63            be parsed and placed into request.paramMap; otherwise, it will be available in 
     64            request.body. If cherrypy.request.processRequestBody is False, then the rfile is not 
     65            consumed, but will be readable by the exposed method.</para> 
    5866        </section> 
    5967        <section> 
    6068            <title>cherrypy.request.method</title> 
    61             <para>This attribute is a string containing the HTTP request method, such as GET 
    62             or POST.</para> 
     69            <para>This attribute is a string containing the HTTP request method, such as GET or 
     70            POST.</para> 
    6371        </section> 
    6472        <section> 
    6573            <title>cherrypy.request.protocol</title> 
    66             <para>This attribute is a string containing the HTTP protocol of the request in 
    67             the form of HTTP/x.x</para> 
     74            <para>This attribute is a string containing the HTTP protocol of the request in the form 
     75            of HTTP/x.x</para> 
     76        </section> 
     77        <section> 
     78            <title>cherrypy.request.version</title> 
     79            <para>This attribute is a Version object which represents the HTTP protocol. It's the 
     80            same os request.protocol, but allows easy comparisons like <code>if 
     81            cherrypy.request.version &gt;= "1.1": do_http_1_1_thing</code>.</para> 
    6882        </section> 
    6983        <section> 
    7084            <title>cherrypy.request.queryString</title> 
    71             <para>This attribute is a string containing the query string of the request (the 
    72             part of the URL following '?').</para> 
     85            <para>This attribute is a string containing the query string of the request (the part of 
     86            the URL following '?').</para> 
    7387        </section> 
    7488        <section> 
    …… 
    7993        <section> 
    8094            <title>cherrypy.request.paramMap</title> 
    81             <para>This attribute is a dictionary containing the query string and POST 
    82             arguments of this request.</para> 
     95            <para>This attribute is a dictionary containing the query string and POST arguments of 
     96            this request.</para> 
    8397        </section> 
    8498        <section> 
    8599            <title>cherrypy.request.base</title> 
    86             <para>This attribute is a string containing the root URL of the server.</para> 
     100            <para>This attribute is a string containing the root URL of the server. By default, it is 
     101            equal to request.scheme://request.headerMap['Host'].</para> 
    87102        </section> 
    88103        <section> 
    89104            <title>cherrypy.request.browserUrl</title> 
    90             <para>This attribute is a string containing the URL the client requested.</para> 
     105            <para>This attribute is a string containing the URL the client requested. By default, it 
     106            is equal to <code>request.base + request.path</code>.</para> 
    91107        </section> 
    92108        <section> 
    93109            <title>cherrypy.request.objectPath</title> 
    94             <para>This attribute is a string containing the path of the exposed method that 
    95             will be called to handle this request. This is usually the same as 
    96             cherrypy.request.path, but can be changed in a filter to change which method is 
    97             actually called.</para> 
     110            <para>This attribute is a string containing the path of the exposed method that will be 
     111            called to handle this request. This is usually the same as cherrypy.request.path, but can 
     112            be changed in a filter to change which method is actually called.</para> 
    98113        </section> 
    99114        <section> 
    100115            <title>cherrypy.request.originalPath</title> 
    101             <para>This attribute is a string containing the original value of 
    102             cherrypy.request.path, in case it is modified by a filter during the 
    103             request.</para> 
     116            <para>This attribute is a string containing the original value of cherrypy.request.path, 
     117            in case it is modified by a filter during the request.</para> 
    104118        </section> 
    105119        <section> 
    106120            <title>cherrypy.request.originalParamMap</title> 
    107121            <para>This attribute is a string containing the original value of 
    108             cherrypy.request.paramMap, in case it is modified by a filter during the 
    109             request.</para> 
     122            cherrypy.request.paramMap, in case it is modified by a filter during the request.</para> 
    110123        </section> 
    111124        <section> 
    112125            <title>cherrypy.request.scheme</title> 
    113             <para>This attribute is a string containing the URL scheme used in this request. 
    114             It is either "http" or "https".</para> 
     126            <para>This attribute is a string containing the URL scheme used in this request. It is 
     127            either "http" or "https".</para> 
    115128        </section> 
    116129    </section> 
    …… 
    120133        <section> 
    121134            <title>cherrypy.response.headerMap</title> 
    122             <para>This attribute is a dictionary with automatically titled keys. It holds all 
    123             outgoing HTTP headers to the client.</para> 
     135            <para>This attribute is a dictionary with automatically titled keys (e.g., 
     136            "Content-Length"). It holds all outgoing HTTP headers to the client.</para> 
     137        </section> 
     138        <section> 
     139            <title>cherrypy.response.headers</title> 
     140            <para>This attribute is a list of (header, value) tuples. It's not available until the 
     141            response has been finalized; it's really only there in the extremely rare cases when you 
     142            need duplicate response headers. In general, you should use request.headerMap 
     143            instead.</para> 
    124144        </section> 
    125145        <section> 
    126146            <title>cherrypy.response.simpleCookie</title> 
    127             <para>This attribute is a SimpleCookie instance from the standard library's 
    128             Cookie module. It contains the outgoing cookie values.</para> 
     147            <para>This attribute is a SimpleCookie instance from the standard library's Cookie 
     148            module. It contains the outgoing cookie values.</para> 
    129149        </section> 
    130150        <section> 
    131151            <title>cherrypy.response.body</title> 
    132             <para>This attribute is originally just the return value of the exposed method, 
    133             but by the end of the request it must be an iterable (usually a list or generator 
    134             of strings) which will be the content of the HTTP response.</para> 
     152            <para>This attribute is originally just the return value of the exposed method, but by 
     153            the end of the request it must be an iterable (usually a list or generator of strings) 
     154            which will be the content of the HTTP response.</para> 
    135155        </section> 
    136156        <section> 
    137157            <title>cherrypy.response.status</title> 
    138             <para>This attribute is a string containing the HTTP response code in the form 
    139             "### Reason Phrase", i.e. "200 OK"</para> 
     158            <para>This attribute is a string containing the HTTP response code in the form "### 
     159            Reason-Phrase", i.e. "200 OK". You may also set it to an int, in which case the response 
     160            finalization process will supply a Reason-Phrase for you.</para> 
     161        </section> 
     162        <section> 
     163            <title>cherrypy.response.version</title> 
     164            <para>This attribute is a Version object, representing the HTTP protocol version of the 
     165            response. This is not necessarily the value that will be written in the response! 
     166            Instead, it should be used to determine which features are <emphasis>available</emphasis> 
     167            for the response. For example, an HTTP server may send an HTTP/1.1 response even though 
     168            the client is known to only understand HTTP/1.0—the response.version will be set to 
     169            Version("1.0") to inform you of this, so that you (and CherryPy) can restrict the 
     170            response to HTTP/1.0 features only.</para> 
    140171        </section> 
    141172    </section> 
    …… 
    143174        <title>cherrypy.server</title> 
    144175        <section> 
    145             <title>cherrypy.server.start()</title> 
    146             <para>Start the CherryPy Server.</para> 
     176            <title>cherrypy.server.start(initOnly=False, serverClass=_missing)</title> 
     177            <para>Start the CherryPy Server. Simple websites may call this without any arguments, to 
     178            run the default server. If initOnly is False (the default), this function will block 
     179            until KeyboardInterrupt or SystemExit is raised, so that the process will persist. When 
     180            using one of the built-in HTTP servers, you should leave this set to False. You should 
     181            only set it to True if you're running CherryPy as an extension to another HTTP server 
     182            (for example, when using Apache and mod_python with CherryPy), in which case the foreign 
     183            HTTP server should do its own process-management.</para> 
     184            <para>Use the serverClass argument to specify that you wish to use an HTTP server other 
     185            than the default, built-in WSGIServer. If missing, config.get("server.class") will be 
     186            checked for an alternate value; otherwise, the default is used. Possible alternate values 
     187            (you may pass the class names as a string if you wish):</para> 
     188            <itemizedlist> 
     189                <listitem> 
     190                    <para><code>cherrypy._cphttpserver.CherryHTTPServer</code>: this will load the 
     191                    old, single-threaded built-in HTTP server. This server is deprecated and will 
     192                    probably be removed in CherryPy 2.2.</para> 
     193                </listitem> 
     194                <listitem> 
     195                    <para><code>cherrypy._cphttpserver.PooledThreadServer</code>: this will load the 
     196                    old, multi-threaded built-in HTTP server. This server is deprecated and will 
     197                    probably be removed in CherryPy 2.2.</para> 
     198                </listitem> 
     199                <listitem> 
     200                    <para><code>cherrypy._cphttpserver.embedded_server</code>: use this to 
     201                    automatically select between the CherryHTTPServer and the PooledThreadServer 
     202                    based on the value of config.get("server.threadPool") and 
     203                    config.get("server.socketFile").</para> 
     204                </listitem> 
     205                <listitem> 
     206                    <para><code>None</code>: this will not load any HTTP server. Note that this is 
     207                    not the default; the default (if serverClass is not given) is to load the 
     208                    WSGIServer.</para> 
     209                </listitem> 
     210                <listitem> 
     211                    <para>Any other class (or dotted-name string): load a custom HTTP server.</para> 
     212                </listitem> 
     213            </itemizedlist> 
     214            <para>You <emphasis>must</emphasis> call this function from Python's main thread, and set 
     215            initOnly to False, if you want CherryPy to shut down when KeyboardInterrupt or SystemExit 
     216            are raised (including Ctrl-C). The only time you might want to do otherwise is if you run 
     217            CherryPy as a Windows service, or as an extension to, say, mod_python, and even then, you 
     218            might want to anyway.</para> 
     219        </section> 
     220        <section> 
     221            <title>cherrypy.server.blocking</title> 
     222            <para>If the "initOnly" argument to server.start is True, this will be False, and 
     223            vice-versa.</para> 
     224        </section> 
     225        <section> 
     226            <title>cherrypy.server.httpserverclass</title> 
     227            <para>Whatever HTTP server class is set in server.start will be stuck in here.</para> 
     228        </section> 
     229        <section> 
     230            <title>cherrypy.server.httpserver</title> 
     231            <para>Whatever HTTP server class is set in server.start will be instantiated and stuck in 
     232            here.</para> 
     233        </section> 
     234        <section> 
     235            <title>cherrypy.server.state</title> 
     236            <para>One of three values, indicating the state of the server:<itemizedlist> 
     237                    <listitem> 
     238                        <para>STOPPED = 0: The server hasn't been started, and will not accept 
     239                        requests.</para> 
     240                    </listitem> 
     241                    <listitem> 
     242                        <para>STARTING = None: The server is in the process of starting, or an error 
     243                        occured while trying to start the server.</para> 
     244                    </listitem> 
     245                    <listitem> 
     246                        <para>STARTED = 1: The server has started (including an HTTP server if 
     247                        requested), and is ready to receive requests.</para> 
     248                    </listitem> 
     249                </itemizedlist></para> 
     250        </section> 
     251        <section> 
     252            <title>cherrypy.server.ready</title> 
     253            <para>True if the server is ready to receive requests, false otherwise. Read-only.</para> 
     254        </section> 
     255        <section> 
     256            <title>cherrypy.server.wait()</title> 
     257            <para>Since server.start usually blocks, other threads need to be started before calling 
     258            server.start; however, they often must wait for server.start to complete it's setup of 
     259            the HTTP server. Use this function from other threads to make them wait for the HTTP 
     260            server to be ready to receive requests.</para> 
     261        </section> 
     262        <section> 
     263            <title>cherrypy.server.start_with_callback(func, args=(), kwargs={}, 
     264            serverClass=_missing)</title> 
     265            <para>Since server.start usually blocks, use this to easily run another function in a new 
     266            thread. It starts the new thread and then runs server.start. The new thread automatically 
     267            waits for the server to finish its startup procedure.</para> 
    147268        </section> 
    148269        <section> 
    149270            <title>cherrypy.server.stop()</title> 
    150             <para>Stop the CherryPy Server.</para> 
     271            <para>Stop the CherryPy Server. Well, "suspend" might be a better term—this doesn't 
     272            terminate the process.</para> 
     273        </section> 
     274        <section> 
     275            <title>cherrypy.server.interrupt</title> 
     276            <para>Usually None, set this to KeyboardInterrupt() or SystemExit() to shut down the 
     277            entire process. That is, the new exception will be raised in the main thread.</para> 
    151278        </section> 
    152279        <section> 
    …… 
    164291        <section> 
    165292            <title>cherrypy.server.onStartThreadList</title> 
    166             <para>A list of functions that will be called when each thread is started.</para> 
     293            <para>A list of functions that will be called when each request thread is started. Note 
     294            that such threads do not need to be started or controlled by CherryPy; for example, when 
     295            using CherryPy with mod_python, Apache will start and stop the request threads. 
     296            Nevertheless, CherryPy will run the onStartThreadList functions upon the first request 
     297            using each distinct thread.</para> 
    167298        </section> 
    168299        <section> 
    169300            <title>cherrypy.server.onStopThreadList</title> 
    170             <para>A list of functions that will be called when each thread is stopped.</para> 
     301            <para>A list of functions that will be called when each request thread is stopped.</para> 
     302        </section> 
     303        <section> 
     304            <title>cherrypy.server.request()</title> 
     305            <para>HTTP servers should call this function to hand off the HTTP request to the CherryPy 
     306            core. There is no return value; instead, the core sets response content in the 
     307            cherrypy.response object.</para> 
    171308        </section> 
    172309    </section> 
    …… 
    175312        <title>cherrypy.config</title> 
    176313        <section> 
    177             <title>cherrypy.config.get(key, defaultValue = None, returnSection = 
    178             False)</title> 
    179             <para>This function returns the configuration value for the given key. The 
    180             function checks if the setting is defined for the current request path, it walks 
    181             up the request path until the key is found, or it returns the default value. If 
    182             returnSection is True, the function returns the configuration path where the key 
    183             is defined.</para> 
     314            <title>cherrypy.config.get(key, defaultValue = None, returnSection = False)</title> 
     315            <para>This function returns the configuration value for the given key. The function 
     316            checks if the setting is defined for the current request path; it walks up the request 
     317            path until the key is found, or it returns the default value. If returnSection is True, 
     318            the function returns the configuration path where the key is defined instead.</para> 
    184319        </section> 
    185320        <section> 
    186321            <title>cherrypy.config.getAll(key)</title> 
    187322            <para>The getAll function returns a list containing a (path, value) tuple for all 
    188             occurences of the key within the request path. This function allows applications 
    189             to inherit configuration data defined for parent paths.</para> 
     323            occurences of the key within the request path. This function allows applications to 
     324            inherit configuration data defined for parent paths.</para> 
    190325        </section> 
    191326        <section> 
    192327            <title>cherrypy.config.update(updateMap=None, file=None)</title> 
    193             <para>Function to update the configuration map. upDateMap is a dictionary of the 
    194             form {'sectionPath' : { } }, file is the path to the configuration file.</para> 
     328            <para>Function to update the configuration map. The "updateMap" argument is a dictionary 
     329            of the form {'sectionPath' : { } }. The "file" argument is the path to the configuration 
     330            file.</para> 
    195331        </section> 
    196332    </section> 
    …… 
    199335        <section> 
    200336            <title>cherrypy.HTTPError</title> 
    201             <para>This exception can be used to automatically send a response using a http 
    202             status code, with an appropriate error page.</para> 
     337            <para>This exception can be used to automatically send a response using a http status 
     338            code, with an appropriate error page.</para> 
     339            <section> 
     340                <title>cherrypy.NotFound</title> 
     341                <para>This exception is raised when CherryPy is unable to map a requested path to an 
     342                internal method. It's a subclass of HTTPError.</para> 
     343            </section> 
    203344        </section> 
    204345        <section> 
    …… 
    207348        </section> 
    208349        <section> 
    209             <title>cherrypy.NotFound</title> 
    210             <para>This exception is raised when CherryPy is unable to map a requested path to 
    211             an internal method.</para> 
    212         </section> 
    213         <section> 
    214350            <title>cherrypy.InternalRedirect</title> 
    215             <para>This exception will redirect processing to another path within the site 
    216             (without informing the client).</para> 
     351            <para>This exception will redirect processing to another path within the site (without 
     352            informing the client).</para> 
    217353        </section> 
    218354    </section> 
    …… 
    235371        <section> 
    236372            <title>_cpOnError</title> 
    237             <para>_cpOnError is a function for handling unanticipated exceptions, whether 
    238             raised by CherryPy itself, or in user applications. The default simply raises 
     373            <para>_cpOnError is a function for handling unanticipated exceptions, whether raised by 
     374            CherryPy itself, or in user applications. The default simply raises 
    239375            HTTPError(500).</para> 
    240376        </section> 
    241377        <section> 
    242378            <title>_cpFilterList</title> 
    243             <para>User defined filters are enabled using the class attribute _cpFilterList. 
    244             Any filter instances placed in _cpFilterList will be applied to all methods of 
    245             the class.</para> 
     379            <para>User defined filters are enabled using the class attribute _cpFilterList. Any 
     380            filter instances placed in _cpFilterList will be applied to all methods of the 
     381            class.</para> 
    246382        </section> 
    247383    </section> 

Hosted by WebFaction

Log in as guest/cpguest to create tickets