/usr/share/doc/python-twisted-web2/howto/resource-apis.html is in python-twisted-web2 8.1.0-3build1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 | <?xml version="1.0"?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml" lang="en"><head><title>Twisted Documentation: Resource, Request, and Response</title><link href="stylesheet.css" type="text/css" rel="stylesheet" /></head><body bgcolor="white"><h1 class="title">Resource, Request, and Response</h1><div class="toc"><ol><li><a href="#auto0">Resources</a></li><li><a href="#auto1">Response</a></li><li><a href="#auto2">Request</a></li></ol></div><div class="content"><span></span><p>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.</p><h2>Resources<a name="auto0"></a></h2><p>The core resource API is described
by <code class="API"><a href="http://twistedmatrix.com/documents/8.1.0/api/twisted.web2.iweb.IResource.html" title="twisted.web2.iweb.IResource">twisted.web2.iweb.IResource</a></code></p><p>A resource
(<code class="API"><a href="http://twistedmatrix.com/documents/8.1.0/api/twisted.web2.resource.Resource.html" title="twisted.web2.resource.Resource">twisted.web2.resource.Resource</a></code>)
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 <a href="object-traversal.html">object
traversal</a></p><h2>Response<a name="auto1"></a></h2><p>The response object
(<code class="API"><a href="http://twistedmatrix.com/documents/8.1.0/api/twisted.web2.http.Response.html" title="twisted.web2.http.Response">twisted.web2.http.Response</a></code>)
contains the state which will be sent back to the client. You
construct
one as follows:</p><pre class="python">
<span class="py-src-variable">Response</span>(<span class="py-src-variable">code</span>=<span class="py-src-variable">None</span>, <span class="py-src-variable">headers</span>=<span class="py-src-variable">None</span>, <span class="py-src-variable">stream</span>=<span class="py-src-variable">None</span>)
</pre><p>The arguments, in detail are:</p><ol><li>Response code. This should be one of the standard HTTP
response codes, either as defined in the <code class="API"><a href="http://twistedmatrix.com/documents/8.1.0/api/
twisted.web2.responsecode.html" title="
twisted.web2.responsecode">
twisted.web2.responsecode</a></code> module, or, equivilently,
just an
integer. If left unspecified, the default is responsecode.OK,
or 200.
</li><li>Headers. The headers, as stored in the response object are
an instance of <code class="API"><a href="http://twistedmatrix.com/documents/8.1.0/api/twisted.web2.http_headers.Headers.html" title="twisted.web2.http_headers.Headers">twisted.web2.http_headers.Headers</a></code>. For
convenience, you may also simply pass a dictionary of name to
value which will automatiaclly be turned into the
<code class="python">Headers</code> 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 <a href="headers.html">Headers</a> for
details about the parsed representation for each header. If
left unspecified, only the default headers added by the core
are output.
</li><li>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
<code class="API"><a href="http://twistedmatrix.com/documents/8.1.0/api/twisted.web2.stream.IByteStream.html" title="twisted.web2.stream.IByteStream">twisted.web2.stream.IByteStream</a></code>. For
more detail on streams, see
the <code class="API"><a href="http://twistedmatrix.com/documents/8.1.0/api/twisted.web2.stream.html" title="twisted.web2.stream">twisted.web2.stream</a></code> module.
</li></ol><h2>Request<a name="auto2"></a></h2><p>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 <code class="API"><a href="http://twistedmatrix.com/documents/8.1.0/api/twisted.web2.http.Request.html" title="twisted.web2.http.Request">twisted.web2.http.Request</a></code>, and the
application server subclass of that
in <code class="API"><a href="http://twistedmatrix.com/documents/8.1.0/api/twisted.web2.server.Request.html" title="twisted.web2.server.Request">twisted.web2.server.Request</a></code>. 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
<code class="API"><a href="http://twistedmatrix.com/documents/8.1.0/api/twisted.web2.html" title="twisted.web2">twisted.web2</a></code>.</p><ol><li><code class="python">method</code> - Request method. This is
the HTTP method, e.g. "GET" or "HEAD" or
"POST".
</li><li><code class="python">headers</code> -
A <code class="API"><a href="http://twistedmatrix.com/documents/8.1.0/api/twisted.web2.http_headers.Headers.html" title="twisted.web2.http_headers.Headers">twisted.web2.http_headers.Headers</a></code>
instance.
</li><li><code class="python">stream</code> - The incoming data
stream, an implementor
of <code class="API"><a href="http://twistedmatrix.com/documents/8.1.0/api/twisted.web2.stream.IByteStream.html" title="twisted.web2.stream.IByteStream">twisted.web2.stream.IByteStream</a></code></li><li><code class="python">remoteAddr</code> - The address of the
remote host,
a <code class="API"><a href="http://twistedmatrix.com/documents/8.1.0/api/twisted.internet.interfaces.IAddress.html" title="twisted.internet.interfaces.IAddress">twisted.internet.interfaces.IAddress</a></code>.
</li></ol><p>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:</p><ol><li><code class="python">scheme</code> - the request scheme the
user used, e.g. "http" or "https".</li><li><code class="python">host</code> - the hostname the client
sent the request to, e.g. "localhost"</li><li><code class="python">port</code> - the port the client sent
the request to, e.g. "80"</li><li><code class="python">path</code> - the complete path, as a
string</li><li><code class="python">params</code> - The url
"parameters". This is an obscure part of the url spec
that you're unlikely to ever have a use for.</li><li><code class="python">querystring</code> - The query
objarguments as a string.</li><li><code class="python">args</code> - 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']}.</li></ol><p>Then, the pieces of the parsed url as its being traversed:</p><ol><li><code class="python">prepath</code> - A list of url segments
that have already been processed by a locateChild method.</li><li><code class="python">postpath</code> - A list of url segments
yet to be processed.</li></ol></div><p><a href="index.html">Index</a></p><span class="version">Version: 8.1.0</span></body></html>
|