Resource, Request, and Response
===============================
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 :apidoc:`twisted.web2.iweb.IResource`

A resource (:apidoc:`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 (:apidoc:`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:

1) Response code. This should be one of the standard HTTP response codes, either as defined in the :apidoc:`twisted.web2.responsecode` module, or, equivilently, just an integer. If left unspecified, the default is responsecode.OK, or 200. 

2) Headers. The headers, as stored in the response object are an instance of :apidoc:`twisted.web2.http_headers.Headers`. For convenience, you may also simply pass a dictionary of name to value which will automatiaclly be turned into the ``Headers`` 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.

3) 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 :apidoc:`twisted.web2.stream.IByteStream`. For more detail on streams, see the :apidoc:`twisted.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 :apidoc:`twisted.web2.http.Request`, and the application server subclass of that in :apidoc:`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 :apidoc:`twisted.web2`.

Here are the attributes on the incoming Request object likely to be of interest:

1) ``.method`` - Request method. This is the HTTP method, e.g. "GET" or "HEAD" or "POST".
2) ``.headers`` - A :apidoc:`twisted.web2.http_headers.Headers`` instance.
3) ``.stream`` - The incoming data stream, an implementor of :apidoc:`twisted.web2.stream.IByteStream`.
4) ``.remoteAddr`` - The address of the remote host, a :apidoc:`twisted.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:

4) ``.scheme`` - the request scheme the user used, e.g. "http" or "https".
5) ``.host`` - the hostname the client sent the request to, e.g. "localhost"
6) ``.port`` - the port the client sent the request to, e.g. "80"
7) ``.path`` - the complete path, as a string
8) ``.params`` - The url "parameters". This is an obscure part of the url spec that you're unlikely to ever have a use for.
9) ``.querystring`` - The query objarguments as a string.
10) ``.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:

11) ``.prepath`` - A list of url segments that have already been processed by a locateChild method.
12) ``.postpath`` - A list of url segments yet to be processed.


.. _Headers: headers.html
.. _object traversal: object-traversal.html
