The three main APIs you will have to be concerned about, as a normal user of the framework are the Resource, Request, and Response objects.
Resources
The core resource API is described
by twisted.web2.iweb.IResource
A resource
(twisted.web2.resource.Resource
)
will generally be the superclass of the classes you define. As
you saw in the intro document, it supports two operations:
rendering and locating a child resource. This is described in
more detail in object
traversal
Response
The response object
(twisted.web2.http.Response
)
contains the state which will be sent back to the client. You
construct
one as follows:
Response(code=None, headers=None, stream=None)
The arguments, in detail are:
- Response code. This should be one of the standard HTTP
response codes, either as defined in the
twisted.web2.responsecode
module, or, equivilently, just an integer. If left unspecified, the default is responsecode.OK, or 200. - Headers. The headers, as stored in the response object are
an instance of
twisted.web2.http_headers.Headers
. For convenience, you may also simply pass a dictionary of name to value which will automatiaclly be turned into theHeaders
instance for you. Please note that the values used here are not the direct string representations that will be sent to the client, but rather, an already-parsed representation. This is to centralize the tricky business of parsing HTTP headers correctly, and to ensure that issues like quoting are taken care of automatically. See Headers for details about the parsed representation for each header. If left unspecified, only the default headers added by the core are output. - The output stream. At the simplest level, you can simply
pass a string for this argument, and the string will be
output. However, underlying this is a much more powerful
system which allows for the efficient streaming output of
arbitrarily large data from a file or other sources, such as a
CGI process or an outgoing HTTP request to another
server. This is accomplished by providing an implementor of
twisted.web2.stream.IByteStream
. For more detail on streams, see thetwisted.web2.stream
module.
Request
The request object holds all the data regarding this particular
incoming connection from the client. There are two requst
objects in web2: the core http request
in twisted.web2.http.Request
, and the
application server subclass of that
in twisted.web2.server.Request
. The
second is the one you will be using, and that is described
here. The first is a subset thereof that is only interesting to
someone wanting to replace the application server portion of
twisted.web2
.
method
- Request method. This is the HTTP method, e.g. "GET" or "HEAD" or "POST".headers
- Atwisted.web2.http_headers.Headers
instance.stream
- The incoming data stream, an implementor oftwisted.web2.stream.IByteStream
remoteAddr
- The address of the remote host, atwisted.internet.interfaces.IAddress
.
Then there's the attributes that make up a url. Note that all of these, including scheme, host, and port, may be specified by the client:
scheme
- the request scheme the user used, e.g. "http" or "https".host
- the hostname the client sent the request to, e.g. "localhost"port
- the port the client sent the request to, e.g. "80"path
- the complete path, as a stringparams
- The url "parameters". This is an obscure part of the url spec that you're unlikely to ever have a use for.querystring
- The query objarguments as a string.args
- The parsed form arguments, as a dictionary, including POST arguments if applicable. This is in the form of a dictionary of lists. The string "?a=1&c=1&c=2" will get turned into {'a':['1'], 'c':['1', '2']}.
Then, the pieces of the parsed url as its being traversed:
prepath
- A list of url segments that have already been processed by a locateChild method.postpath
- A list of url segments yet to be processed.