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

Changeset 969

Show
Ignore:
Timestamp:
02/16/06 02:35:35
Author:
fumanchu
Message:

Docs: cherrypy.tree

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

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

    r952 r969  
    9090        <section> 
    9191            <title>cherrypy.request.wsgi_environ</title> 
    92             <para>This attribute is a dictionary containing the WSGI environment for the request.  In non-WSGI settings (i.e., running under _cphttpserver), it is an empty dictionary.</para> 
     92            <para>This attribute is a dictionary containing the WSGI environment for the request. In 
     93            non-WSGI settings (i.e., running under _cphttpserver), it is absent.</para> 
    9394        </section> 
    9495        <section> 
    …… 
    229230            </itemizedlist> 
    230231            <para>You <emphasis>must</emphasis> call this function from Python's main thread, and set 
    231             init_only to False, if you want CherryPy to shut down when KeyboardInterrupt or SystemExit 
    232             are raised (including Ctrl-C). The only time you might want to do otherwise is if you run 
    233             CherryPy as a Windows service, or as an extension to, say, mod_python, and even then, you 
    234             might want to anyway.</para> 
     232            init_only to False, if you want CherryPy to shut down when KeyboardInterrupt or 
     233            SystemExit are raised (including Ctrl-C). The only time you might want to do otherwise is 
     234            if you run CherryPy as a Windows service, or as an extension to, say, mod_python, and 
     235            even then, you might want to anyway.</para> 
    235236        </section> 
    236237        <section> 
    …… 
    277278        </section> 
    278279        <section> 
    279             <title>cherrypy.server.start_with_callback(func, args=(), kwargs={}, 
    280             server_class = _missing)</title> 
     280            <title>cherrypy.server.start_with_callback(func, args=(), kwargs={}, server_class = 
     281            _missing)</title> 
    281282            <para>Since server.start usually blocks, use this to easily run another function in a new 
    282283            thread. It starts the new thread and then runs server.start. The new thread automatically 
    …… 
    348349            <title>cherrypy.config.environments</title> 
    349350            <para>Dict containing config defaults for each named server.environment.</para> 
     351        </section> 
     352    </section> 
     353    <section> 
     354        <title>cherrypy.tree</title> 
     355        <para>The Tree class is used to keep track of where applications are mounted. To "mount" an 
     356        application means to have its root respond to a URL other than "/". By using 
     357        <code>cherrypy.tree</code>, you can easily mount applications and remember where you mounted 
     358        them!</para> 
     359        <section> 
     360            <title>cherrypy.tree.mount(app_root, baseurl=None, conf=None)</title> 
     361            <para>Function to mount a tree of objects at the given baseurl, using the given 
     362            configuration dict or filename. If baseurl is None or missing, it is assumed to be "/" 
     363            unless the config specifies <code>[global] mount_point = "/path/to/approot"</code>. If 
     364            conf is not None, then each of its sections (which should be a relative URL, like 
     365            "/skins/deepblue/main") will be prefixed with the baseurl, so that config lookups are 
     366            also "mounted" at the base URL.</para> 
     367            <para>Note that, by using tree.mount, your approot may not be found at cherrypy.root; 
     368            there may be several "dummy" objects placed in-between cherrypy.root and your 
     369            application's root instance.</para> 
     370        </section> 
     371        <section> 
     372            <title>cherrypy.tree.mount_points</title> 
     373            <para>A dict of the form {baseurl: approot-instance}.</para> 
     374        </section> 
     375        <section> 
     376            <title>cherrypy.tree.mount_point(path=None)</title> 
     377            <para>A method which finds the appropriate baseurl for a given path. If path is None or 
     378            missing, cherrypy.request.object_path is used. If multiple applications "contain" the 
     379            given path, the longer baseurl is returned. That is, if App1 is mounted at "/" and App2 
     380            is mounted at "/path/to/app", then 
     381            <code>cherrypy.tree.mount_point("/path/to/app/main")</code> will return 
     382            "/path/to/app".</para> 
     383            <para>Once you have obtained the baseurl using mount_point, you can obtain a reference to 
     384            the application root object by looking up 
     385            <code>cherrypy.tree.mount_points[baseurl]</code>.</para> 
     386        </section> 
     387        <section> 
     388            <title>cherrypy.tree.url(path, mount_point=None)</title> 
     389            <para>Prefixes the given path with the given mount_point, which isn't very exciting 
     390            unless mount_point is None or missing, in which case, cherrypy.request.object_path will 
     391            be used to find the current mount_point and prefix <emphasis>that</emphasis> to the given 
     392            path.</para> 
    350393        </section> 
    351394    </section> 

  • trunk/docs/book/xml/configureapplication.xml

    r325 r969  
    1 <?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="configureapplication"> 
    6   <title>Configure an application</title> 
     1<?xml version="1.0" encoding="UTF-8"?> 
     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="configureapplication"> 
     4    <title>Mounting applications</title> 
     5    <para>So far, we have talked about applications as if they are always "mounted" at root; that is, 
     6    that the URL "/" is the "base URL" for the application. However, this rarely happens in practice. 
     7    Often, you not only have an application mounted at some other base URL, but it must coexist with 
     8    other applications (perhaps in the same process). CherryPy has always allowed applications to be 
     9    deployed simultaneously, but it was often a difficult process, and required a lot of manual 
     10    manipulation of the <code>cherrypy.root</code> tree, and of config file paths.</para> 
     11    <para> Beginning in version 2.2, CherryPy provides a tool to make mounting applications easier: 
     12    <code>cherrypy.tree.mount(app_root, baseurl=None, conf=None)</code>. You pass it a handler tree, 
     13    the base URL for the app, and a config dict or filename, and it does all of the "hard work" for 
     14    you. For example, instead of writing this:</para> 
     15    <example> 
     16        <programlisting>import cherrypy 
     17 
     18class Root: 
     19    def index(self): 
     20        return "Hello world! This is %s" % cherrypy.request.path 
     21    index.exposed = True 
     22 
     23cherrypy.root.path.to.approot = Root() 
     24cherrypy.config.update({'/path/to/approot/':  
     25                           {'server.log_file': '/var/log/myapp.log'} 
     26                       })</programlisting> 
     27    </example> 
     28    <para>...you can now write the last two lines like this:</para> 
     29    <example> 
     30        <programlisting>cherrypy.tree.mount(Root(), "/path/to/approot", 
     31                    {'/': {'server.log_file': '/var/log/myapp.log'}})</programlisting> 
     32    </example> 
     33    <para>The call to mount() will prefix all of the config-section paths with your mount point path. 
     34    If you use a config file instead of a Python dict, it becomes even cleaner.</para> 
     35    <para>You can read more about the <code>cherrypy.tree</code> object in the API Reference later in 
     36    this book.</para> 
    737</section> 

Hosted by WebFaction

Log in as guest/cpguest to create tickets