Application API proposal (CP 3+)

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
2 messages Options
Reply | Threaded
Open this post in threaded view
|

Application API proposal (CP 3+)

Robert Brewer

"""CherryPy Application API.


Application objects
-------------------
CherryPy uses an application object to implement a collection of URI's
which maps to a collection of page handlers. The exact implementation
of that mapping is dependent on the dispatcher(s) which the application
employs internally; by default, the external application interface only
exposes a "script name" (root URI) for the entire collection.

An application object MUST contain the following three attributes:

    * script_name: a string, containing the "mount point" for this
object.
        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.
        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 nested dict, containing configuration entries which
apply
        to this application, of the form: {section: {entry name:
value}}.
        The 'section' keys MUST be strings. If they represent URI paths,
        they MUST begin with a slash, and MUST be relative to this
object's
        script_name. If they do not begin with a slash, they SHOULD be
        treated as arbitrary section names, which applications MAY use
as
        they see fit. The 'entry name' keys MUST be strings, and in the
        case of path sections, SHOULD be namespaced. See _cpconfig.
        The values may be arbitrary Python values.
    * namespaces: a dict of namespace names and handlers. See _cpconfig.

Application objects also MUST possess a "merge" method, that takes a
single
"config" argument, which MUST be a dict, nested in the same manner as
the
application object's config. The "merge" method MUST combine the
supplied
config with the application object's existing config dict in such a way
that
the supplied config overrides (overwrites) entries in the existing
config.
The "merge" method MUST NOT remove any values in the existing config
unless
replacing them with a new value, or performing the removal via a
namespace
handler. The "merge" method MUST pass all entries in the supplied config
to
the proper namespace handler (if any). It MUST NOT pass any entries from
the
existing config to namespace handlers, since these entries will have
already
been handled when they were first merged. Callers SHOULD NOT attempt to
add
config entries to the application object via any means other than
passing a
new config dict to the "merge" method.

The specification of application objects excludes calling syntax by
design;
their implementation, however, MAY include additional methods which are
used
to associate them with an HTTP request, and even initiate the handling
of
each request. For example, the reference implementation extends the spec
by adding a __call__ method which acts as a "WSGI application
interface";
WSGI servers and middleware hand off request processing to a CherryPy
application object by calling it.

In addition, application objects MAY possess other attributes and
methods
which consumers can use to differentiate them. For example, a consumer
might wish to use different application objects based on the "Accept"
HTTP
request header, in which case a cooperating creator of application
objects
could give each object an additional "accept" attribute.
"""


Robert Brewer
System Architect
Amor Ministries
[hidden email]

--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups "cherrypy-devel" group.
To post to this group, send email to [hidden email]
To unsubscribe from this group, send email to [hidden email]
For more options, visit this group at http://groups-beta.google.com/group/cherrypy-devel
-~----------~----~----~----~------~----~------~--~---

Reply | Threaded
Open this post in threaded view
|

Re: Application API proposal (CP 3+)

Robert Brewer

Sylvain noted on IRC that having such a large amount of text in the
actual .py files would be a burden on runtime memory. So I'd like to
propose leaving the actual spec out of those and placing it all
together into its own "spec.txt" or something similar, perhaps even in
the 'docs' folder instead of 'cherrypy'.

If we're doing that, then it makes little sense for me to keep posting
snippets (as if they were all going in separate module docstrings). So
I've combined everything I have so far into
http://www.cherrypy.org/wiki/CherryPySpec. Feel very free to edit that
page and just add commentary inline as we go. You can even break it up
by inserting close
}}}

and open brackets

{{{
to make it flow a little better when rendered (try to consolidate your
comments in between sections).


Robert Brewer
System Architect
Amor Ministries
[hidden email]


--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups "cherrypy-devel" group.
To post to this group, send email to [hidden email]
To unsubscribe from this group, send email to [hidden email]
For more options, visit this group at http://groups-beta.google.com/group/cherrypy-devel
-~----------~----~----~----~------~----~------~--~---