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

Changeset 373

Show
Ignore:
Timestamp:
06/23/05 21:14:22
Author:
peterhunt
Message:

spellchecking/grammatical stuff, and some pretty comprehensive docs on cpg.request and cpg.response.

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

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

    r325 r373  
    1010  <section id="cpgrequest"> 
    1111    <title>cpg.request</title> 
     12    <section> 
     13      <title>cpg.request.remoteAddr</title> 
     14      <para>This attribute is a string containing the IP address of the client.</para> 
     15    </section> 
     16    <section> 
     17      <title>cpg.request.remoteHost</title> 
     18      <para>This attribute is a string containing the remote hostname of the client.</para> 
     19    </section> 
     20    <section> 
     21      <title>cpg.request.headerMap</title> 
     22      <para>This attribute is dictionary containing the received HTTP headers.</para> 
     23    </section> 
     24    <section> 
     25      <title>cpg.request.requestLine</title> 
     26      <para>This attribute is a string containing the first line of the raw HTTP request.</para> 
     27    </section> 
     28    <section> 
     29      <title>cpg.request.simpleCookie</title> 
     30      <para>This attribute is a SimpleCookie instance from the standard library's Cookie module 
     31      which contains the incoming cookie values from the client.</para> 
     32    </section> 
     33    <section> 
     34      <title>cpg.request.remoteAddr</title> 
     35      <para>This attribute is a string containing the IP address of the client.</para> 
     36    </section> 
     37    <section> 
     38      <title>cpg.request.rfile</title> 
     39      <para>This attribute is the input stream to the client. See cpg.request.processRequestBody 
     40      for more information.</para> 
     41    </section> 
     42    <section> 
     43      <title>cpg.request.processRequestBody</title> 
     44      <para>This attribute should be accessed during the beforeRequestBody stage of the request 
     45      (if you don't know what this means, read the section on filters). This specifies whether 
     46      or not the request's POST data will be parsed into the cpg.request.paramMap. 
     47      It defaults to true for POST requests, but when false, cpg.request.rfile will be readable by 
     48      the exposed method. Otherwise, rfile is completely read before control is handled to the 
     49      exposed method.</para> 
     50    </section> 
     51    <section> 
     52      <title>cpg.request.method</title> 
     53      <para>This attribute is a string containing the HTTP request method, such as GET or POST.</para> 
     54    </section> 
     55    <section> 
     56      <title>cpg.request.protocol</title> 
     57      <para>This attribute is a string containing the HTTP protocol of the request in the form of 
     58      HTTP/x.x</para> 
     59    </section> 
     60    <section> 
     61      <title>cpg.request.queryString</title> 
     62      <para>This attribute is a string containing the query string of the request (the part 
     63      of the URL following '?').</para> 
     64    </section> 
     65    <section> 
     66      <title>cpg.request.path</title> 
     67      <para>This attribute is a string containing the path of the resource the client requested.</para> 
     68    </section> 
     69    <section> 
     70      <title>cpg.request.paramMap</title> 
     71      <para>This attribute is a dictionary containing the query string and POST arguments 
     72      of this request.</para> 
     73    </section> 
     74    <section> 
     75      <title>cpg.request.base</title> 
     76      <para>This attribute is a string containing the root URL of the server.</para> 
     77    </section> 
     78    <section> 
     79      <title>cpg.request.browserUrl</title> 
     80      <para>This attribute is a string containing the URL the client requested.</para> 
     81    </section> 
     82    <section> 
     83      <title>cpg.request.objectPath</title> 
     84      <para>This attribute is a string containing the path of the exposed method that will 
     85      be called to handle this request. This is usually the same as cpg.request.path, but 
     86      can be changed in a filter to change which method is actually called.</para> 
     87    </section> 
     88    <section> 
     89      <title>cpg.request.originalPath</title> 
     90      <para>This attribute is a string containing the original value of cpg.request.path, 
     91      in case it is modified by a filter during the request.</para> 
     92    </section> 
     93    <section> 
     94      <title>cpg.request.originalParamMap</title> 
     95      <para>This attribute is a string containing the original value of cpg.request.paramMap, 
     96      in case it is modified by a filter during the request.</para> 
     97    </section> 
    1298  </section> 
    1399  <section id="cpgresponse"> 
    14100    <title>cpg.response</title> 
     101    <section> 
     102      <title>cpg.response.headerMap</title> 
     103      <para>This attribute is a dictionary with automatically titled keys. It holds all outgoing 
     104      HTTP headers to the client.</para> 
     105    </section> 
     106    <section> 
     107      <title>cpg.response.simpleCookie</title> 
     108      <para>This attribute is a SimpleCookie instance from the standard library's Cookie module. It 
     109      contains the outgoing cookie values.</para> 
     110    </section> 
     111    <section> 
     112      <title>cpg.response.body</title> 
     113      <para>This attribute is originally just the return value of the exposed method, but by the end of the 
     114      request it must be an iterable (usually a list or generator of strings) which will be the 
     115      content of the HTTP response.</para> 
     116    </section> 
     117    <section> 
     118      <title>cpg.response.status</title> 
     119      <para>This attribute is a string containing the HTTP response code in the form "### Reason Phrase", 
     120      i.e. "200 OK"</para> 
     121    </section> 
     122  </section> 
     123  <section id="cpgserver"> 
     124    <title>cpg.server</title> 
     125    <section> 
     126      <title>cpg.server.start()</title> 
     127    </section> 
     128    <section> 
     129      <title>cpg.server.stop()</title> 
     130    </section> 
     131    <section> 
     132      <title>cpg.server.onStartServerList</title> 
     133    </section> 
     134    <section> 
     135      <title>cpg.server.onStopServerList</title> 
     136    </section> 
     137    <section> 
     138      <title>cpg.server.onStartThreadList</title> 
     139    </section> 
     140    <section> 
     141      <title>cpg.server.onStopThreadList</title> 
     142    </section> 
     143  </section> 
     144  <section id="cpgconfig"> 
     145    <title>cpg.config</title> 
     146  </section> 
     147  <section id="cperror"> 
     148    <title>cherrypy.cperror</title> 
     149  </section> 
     150  <section id="lib"> 
     151    <title>CherryPy included library functions</title> 
     152    <section> 
     153      <title>cherrypy.lib.cptools</title> 
     154      <section> 
     155        <title>ExposeItems</title> 
     156      </section> 
     157      <section> 
     158        <title>PositionalParametersAware</title> 
     159      </section> 
     160    </section> 
    15161  </section> 
    16162  <section id="specialfunctions"> 
    17     <title>Special functions</title> 
     163    <title>Special functions and attributes</title> 
     164    <section> 
     165      <title>_cpOnError</title> 
     166    </section> 
     167    <section> 
     168      <title>_cpFilterList</title> 
     169    </section> 
     170  </section> 
     171  <section id="filters"> 
     172    <title>Filter API</title> 
     173    <section> 
     174      <title>onStartResource</title> 
     175    </section> 
     176    <section> 
     177      <title>beforeRequestBody</title> 
     178    </section> 
     179    <section> 
     180      <title>beforeMain</title> 
     181    </section> 
     182    <section> 
     183      <title>beforeFinalize</title> 
     184    </section> 
     185    <section> 
     186      <title>onEndResource</title> 
     187    </section> 
     188    <section> 
     189      <title>beforeErrorResponse</title> 
     190    </section> 
     191    <section> 
     192      <title>afterErrorResponse</title> 
     193    </section> 
    18194  </section> 
    19195</section> 

  • trunk/docs/book/xml/byexample.xml

    r370 r373  
    3030  <section> 
    3131    <title>Exposed Methods</title> 
     32    <para> 
     33    For security reasons, CherryPy requires developers to explicitly specify which methods may 
     34    be accessed via the web. The 'exposed' attribute, when set totrue, indicates that a given 
     35    method is published to the web. 
     36    </para> 
    3237    <example> 
    3338      <title>Exposed Methods</title> 
    …… 
    4247  <section> 
    4348    <title>Get and Post</title> 
     49    <para> 
     50    The majority of web applications need to deal with HTML forms and consequently HTTP GET and POST. 
     51    GET and POST variables are automatically decoded and passed to exposed methods as named arguments. 
     52    </para> 
    4453    <example> 
    4554      <title>Get and Post</title> 

  • trunk/docs/book/xml/sessions.xml

    r368 r373  
    77  <abstract> 
    88    <para> 
    9       CherryPY2.1 Includes a powerfull new sessionFilter. 
    10       The old session system was difficult to extend and was not thread safe.   
    11       The new system adresses these issues and includes several powerfull new features. 
     9      CherryPy 2.1 includes a powerful sessions system provided via a new "sessionFilter". 
     10      The old sessions system was difficult to extend and was not thread safe, while the 
     11      new system addresses these issues and includes several powerful new features. 
    1212    </para> 
    1313  </abstract> 
    …… 
    4444          <listitem>get(key, default)      </listitem> 
    4545        </itemizedlist> 
    46         SessionDicts also contain the following attributes: 
     46        SessionDicts also provide the following attributes: 
    4747        <itemizedlist> 
    4848          <listitem>sessionKey (read only)</listitem> 
    …… 
    5858      <para> 
    5959        cpg.sessions is the single point of access for all session data. 
    60         When each request is proccessed the sessionFilter looks for any sessions defined  
    61         for requested portion of the site.  For each named session, a SessionDict is created and  
    62         attached to cpg.sessions, as an attribute bearing the session name. 
    63       </para> 
    64        
    65       <para> 
    66       Given a session named "checkoutSession", all session data will be accessed through: 
    67       <blockqoute>cpg.sessions.checkoutSession</blockqoute> 
     60        At the beginning of each request, the sessionFilter checks for any sessions that may 
     61        have been defined for the requested portion of the site. 
     62        For each defined session, a SessionDict is created and is added as an attribute of 
     63        cpg.sessions. 
     64      </para> 
     65       
     66      <para> 
     67      For example, given a session named "checkoutSession", all data for this session will 
     68      be accessible through: <blockqoute>cpg.sessions.checkoutSession</blockqoute> 
    6869      </para> 
    6970 
    …… 
    8586        <title>The default session</title> 
    8687        <para> 
    87           By defualt the session filter provide a session named "default",  
     88          By default, the sessionFilter provides a session named "default",  
    8889          which is accessed through "cpg.sessions.default". 
    8990        </para> 
    9091 
    9192        <para> 
    92           Unless there is a clear advantage to having more that one named sessions,  
     93          Unless there is a clear advantage to having more that one named session,  
    9394          the default session should be used to store all session data. 
    94           The default session may (in the future) be optomized to provide better performance 
    95           than can be achived with named sessions. 
     95          The default session may (in the future) be optimized to provide superior 
     96          performance than that of custom named sessions. 
    9697        </para> 
    9798      </section> <!-- end default session section --> 
    …… 
    101102      <title>_cpSessionsList</title> 
    102103      <para> 
    103         Named sessions are created by placing an entry into the _cpSessionsList. 
    104         _cpSessionsList is a class attribute containing a list sessions defined for that class. 
     104        Named sessions are created by placing an entry into _cpSessionsList. 
     105        _cpSessionsList is a special class attribute containing a list of 
     106        sessions defined for that particular class. 
    105107      </para> 
    106108      <example> 
    …… 
    109111        </para> 
    110112        <programlisting> 
    111           class myBBS: 
     113          class MyBBS: 
    112114              # create a session named 'admin' using the SessionStorageClass 
    113115              _cpSessionList = [SessionStorageClass(sessionName = 'admin')] 
    114116 
    115117              def admin(self): 
    116                   if cpg.session.admin['user'] != root: 
     118                  if cpg.session.admin['user'] != "root": 
    117119                      return "you are not root" 
    118120        </programlisting> 
    …… 
    124126  <section id="sessionstoragetypes"> 
    125127    <title>Session Storage Types</title> 
    126     <para>The following storage drivers are built in: ram, file, ayndb, sqlobject</para> 
     128    <para>CherryPy includes several session storage backends: ram, file, anydb, sqlobject</para> 
    127129    <section> 
    128130      <title>ram storage</title> 
    129131      <para> 
    130           The ram driver stores all sessiondata in memory. 
    131           It is the only storage driver capable of holding any python object. 
    132           All session data is lost when the server shuts down (included autoreloads.) 
     132          The ram driver stores all session data in memory. 
     133          It is the only storage driver capable of holding any Python object, including those 
     134          that are not-picklable, such as file handles, sockets, and running generators. 
     135          When using ream sessions, keep in mind that all session data is lost when the server 
     136          shuts down, even during auto-reloads. 
    133137      </para> 
    134138    </section> <!-- end ram storage section --> 
    …… 
    137141      <title>file storage</title> 
    138142      <para> 
    139         The file storage driver pickles the data for each session and stores it in a seperate file.   
     143        The file storage driver pickles the data for each session and stores it in separate files.   
    140144        Cleaning up expired sessions is a slow operation (this should change soon.) 
    141145      </para> 
    …… 
    145149      <title>anydb storage</title> 
    146150      <para> 
    147           The anydb storage driver stores session data with the shelve module, which in turn 
     151          The anydb storage driver stores session data using the shelve module, which in turn 
    148152          uses the anydb module.  The andyb driver can only be used to store picklable objects. 
    149153      </para> 
    …… 
    153157      <title>Relational Storage</title> 
    154158      <para> 
    155         With relation database drivers, all data is stored in a relational database table.  Due to the nature of 
     159        With relational database drivers, all data is stored in a relational database table.  Due to the nature of 
    156160        relational databases, there are several restrictions on how data can be stored.  Each session 
    157161        is stored as a single row in the session table.  The session table must be created with a column 
    158162        for each variable needed by the application.  This makes it impossible to store arbitrary key/value pairs,  
    159         as can be done using several of the other storage drivers.  Relational database also place 
     163        as can be done using several of the other storage drivers.  In addition, relational databases also place 
    160164        restrictions on the type of data that can be stored in each column.  Attempting to store the wrong 
    161         type of data in a table will result in an error. 
    162       </para> 
    163        
    164       <para> 
    165         Despite this restrictions, storing session data in relational database has many advantages. 
    166         Many web applications already use of relational databases, this approach allows session data 
    167         to be integrated into a prexisting database.  This approach allows a level of scalability not possible 
    168         with other storage drivers.  With a network database, session data can be easily shared between a cluster  
    169         of web servers. 
     165        type of data in a session variable will result in an error. 
     166      </para> 
     167       
     168      <para> 
     169        Despite these restrictions, storing session data in relational database has many advantages. 
     170        This approach allows session data to be integrated into an existing relational database, which 
     171        dynamic web applications often use anyway.  This approach allows for a level of scalability not possible 
     172        with other storage drivers.  In addition, by using a networked database server, session data can be easily 
     173        shared between a cluster of web servers. 
    170174      </para> 
    171175 
    …… 
    194198      <title>BaseSessionDict</title> 
    195199      <para> 
    196         BaseSessionDict is the base class for the dictionary like class used to access session data. 
    197         SessionDicts impliment the most frequently used features of python dictionaries. 
    198         It is important not to add new features to a custom SessionDict class, because it could break 
     200        BaseSessionDict is the base class for the dictionary-like class used to access session data. 
     201        SessionDicts implement the most frequently used features of Python dictionaries. 
     202        DO NOT add new features to a custom SessionDict class, as it could break 
    199203        compatibility with other storage drivers. 
    200204 
    201         It may not be necessary to write a custom SessionDict class.  The sessoinFilter includes a  
     205        Sometimes it is not necessary to write a custom SessionDict class because the sessionFilter includes a  
    202206        SimpleSessionDict.  The SimpleSessionDict is used by several storage drivers and may be  
    203207        adequate for a custom storage driver. 
    …… 
    208212      <title>BaseSession</title> 
    209213      <para> 
    210         BaseSession os the base class for all session storage drivers.  There are a number of methods that must be 
    211         implimented by every storage driver. 
     214        BaseSession is the base class for all session storage drivers.  There are a number of methods that must be 
     215        implemented by every storage driver. 
    212216      </para> 
    213217    </section> 

Hosted by WebFaction

Log in as guest/cpguest to create tickets