t.w.h.Request : class documentation

Part of twisted.web.http View Source View In Hierarchy

Known subclasses: twisted.web.proxy.ProxyRequest, twisted.web.proxy.ReverseProxyRequest, twisted.web.server.Request

A HTTP request.

Subclasses should override the process() method to determine how the request will be processed.

Instance Variable method The HTTP method that was used.
Instance Variable uri The full URI that was requested (includes arguments).
Instance Variable path The path only (arguments not included).
Instance Variable args All of the arguments, including URL and POST arguments. (type: A mapping of strings (the argument names) to lists of values. i.e., ?foo=bar&foo=baz&quux=spam results in {'foo': ['bar', 'baz'], 'quux': ['spam']}.)
Instance Variable requestHeaders All received HTTP request headers. (type: http_headers.Headers)
Instance Variable received_headers 0 Backwards-compatibility access to requestHeaders. Use requestHeaders instead. received_headers behaves mostly like a dict and does not provide access to all header values.
Instance Variable responseHeaders All HTTP response headers to be sent. (type: http_headers.Headers)
Instance Variable headers 0 Backwards-compatibility access to responseHeaders. Use responseHeaders instead. headers behaves mostly like a dict and does not provide access to all header values nor does it allow multiple values for one header to be set.
Instance Variable notifications A list of Deferreds which are waiting for notification that the response to this request has been finished (successfully or with an error). Don't use this attribute directly, instead use the Request.notifyFinish method.
Method __init__
Method headers Transform the Headers-style responseHeaders attribute into a deprecated dict-style headers attribute.
Method received_headers Transform the Headers-style requestHeaders attribute into a deprecated dict-style received_headers attribute.
Method __setattr__ Support assignment of dict instances to received_headers for backwards-compatibility.
Method noLongerQueued Notify the object that it is no longer queued.
Method gotLength Called when HTTP channel got length of content in this request.
Method parseCookies Parse cookie headers.
Method handleContentChunk Write a chunk of data.
Method requestReceived Called by channel when all data has been received.
Method __repr__ Return a string description of the request including such information as the request method and request URI.
Method process Override in subclasses.
Method registerProducer Register a producer.
Method unregisterProducer Unregister the producer.
Method getHeader Get an HTTP request header.
Method getCookie Get a cookie that was sent from the network.
Method notifyFinish Notify when the response to this request has finished.
Method finish Indicate that all response data has been written to this Request.
Method write Write some data as a result of an HTTP request. The first time this is called, it writes out response data.
Method addCookie Set an outgoing HTTP cookie.
Method setResponseCode Set the HTTP response code.
Method setHeader Set an HTTP response header. Overrides any previously set values for this header.
Method redirect Utility function that does a redirect.
Method setLastModified Set the Last-Modified time for the response to this request.
Method setETag Set an entity tag for the outgoing response.
Method getAllHeaders Return dictionary mapping the names of all received headers to the last value received for each.
Method getRequestHostname Get the hostname that the user passed in to the request.
Method getHost Get my originally requesting transport's host.
Method setHost Change the host and port the request thinks it's using.
Method getClientIP Return the IP address of the client who submitted this request.
Method isSecure Return True if this request is using a secure transport.
Method getUser Return the HTTP user sent with this request, if any.
Method getPassword Return the HTTP password sent with this request, if any.
Method getClient Undocumented
Method connectionLost There is no longer a connection for this request to respond over. Clean up anything which can't be useful anymore.
Instance Variable _disconnected A flag which is False until the connection over which this request was received is closed and which is True after that. (type: bool)
Method _warnHeaders Emit a warning related to use of one of the deprecated headers or received_headers attributes.
Method _cleanup Called when have finished responding and are no longer queued.
Method _authorize Undocumented
method =
The HTTP method that was used.
uri =
The full URI that was requested (includes arguments).
path =
The path only (arguments not included).
args =
All of the arguments, including URL and POST arguments. (type: A mapping of strings (the argument names) to lists of values. i.e., ?foo=bar&foo=baz&quux=spam results in {'foo': ['bar', 'baz'], 'quux': ['spam']}.)
requestHeaders =
All received HTTP request headers. (type: http_headers.Headers)
received_headers 0 =
Backwards-compatibility access to requestHeaders. Use requestHeaders instead. received_headers behaves mostly like a dict and does not provide access to all header values.
responseHeaders =
All HTTP response headers to be sent. (type: http_headers.Headers)
headers 0 =
Backwards-compatibility access to responseHeaders. Use responseHeaders instead. headers behaves mostly like a dict and does not provide access to all header values nor does it allow multiple values for one header to be set.
notifications =
A list of Deferreds which are waiting for notification that the response to this request has been finished (successfully or with an error). Don't use this attribute directly, instead use the Request.notifyFinish method.
_disconnected =
A flag which is False until the connection over which this request was received is closed and which is True after that. (type: bool)
def __init__(self, channel, queued): (source)
overridden in twisted.web.proxy.ProxyRequest, twisted.web.proxy.ReverseProxyRequest, twisted.web.server.Request
Parameterschannelthe channel we're connected to.
queuedare we in the request queue, or can we start writing to the transport?
def _warnHeaders(self, old, new): (source)
Emit a warning related to use of one of the deprecated headers or received_headers attributes.
ParametersoldThe name of the deprecated attribute to which the warning pertains.
newThe name of the preferred attribute which replaces the old attribute.
@property
def headers(self): (source)
Transform the Headers-style responseHeaders attribute into a deprecated dict-style headers attribute.
@property
def received_headers(self): (source)
Transform the Headers-style requestHeaders attribute into a deprecated dict-style received_headers attribute.
def __setattr__(self, name, value): (source)
Support assignment of dict instances to received_headers for backwards-compatibility.
def _cleanup(self): (source)
Called when have finished responding and are no longer queued.
def noLongerQueued(self): (source)
Notify the object that it is no longer queued.

We start writing whatever data we have to the transport, etc.

This method is not intended for users.

def gotLength(self, length): (source)
Called when HTTP channel got length of content in this request.

This method is not intended for users.

ParameterslengthThe length of the request body, as indicated by the request headers. None if the request headers do not indicate a length.
def parseCookies(self): (source)
Parse cookie headers.

This method is not intended for users.

def handleContentChunk(self, data): (source)
Write a chunk of data.

This method is not intended for users.

def requestReceived(self, command, path, version): (source)
Called by channel when all data has been received.

This method is not intended for users.

ParameterscommandThe HTTP verb of this request. This has the case supplied by the client (eg, it maybe "get" rather than "GET"). (type: bytes)
pathThe URI of this request. (type: bytes)
versionThe HTTP version of this request. (type: bytes)
def __repr__(self): (source)
Return a string description of the request including such information as the request method and request URI.
ReturnsA string loosely describing this Request object. (type: str)
def process(self): (source)
overridden in twisted.web.proxy.ProxyRequest, twisted.web.proxy.ReverseProxyRequest, twisted.web.server.Request
Override in subclasses.

This method is not intended for users.

def registerProducer(self, producer, streaming): (source)
overridden in twisted.web.distrib.Request
Register a producer.
def unregisterProducer(self): (source)
overridden in twisted.web.distrib.Request
Unregister the producer.
def getHeader(self, key): (source)
Get an HTTP request header.
ParameterskeyThe name of the header to get the value of. (type: bytes)
ReturnsThe value of the specified header, or None if that header was not present in the request. (type: bytes or NoneType)
def getCookie(self, key): (source)
Get a cookie that was sent from the network.
def notifyFinish(self): (source)
Notify when the response to this request has finished.
ReturnsA Deferred which will be triggered when the request is finished -- with a None value if the request finishes successfully or with an error if the request is interrupted by an error (for example, the client closing the connection prematurely). (type: Deferred)
def finish(self): (source)
overridden in twisted.web.server.Request
Indicate that all response data has been written to this Request.
def write(self, data): (source)
overridden in twisted.web.server.Request
Write some data as a result of an HTTP request. The first time this is called, it writes out response data.
ParametersdataSome bytes to be sent as part of the response body. (type: bytes)
def addCookie(self, k, v, expires=None, domain=None, path=None, max_age=None, comment=None, secure=None): (source)
Set an outgoing HTTP cookie.

In general, you should consider using sessions instead of cookies, see twisted.web.server.Request.getSession and the twisted.web.server.Session class for details.

def setResponseCode(self, code, message=None): (source)
Set the HTTP response code.
def setHeader(self, name, value): (source)
Set an HTTP response header. Overrides any previously set values for this header.
ParametersnameThe name of the header for which to set the value. (type: bytes)
valueThe value to set for the named header. (type: bytes)
def redirect(self, url): (source)
Utility function that does a redirect.

The request should have finish() called after this.

def setLastModified(self, when): (source)
Set the Last-Modified time for the response to this request.

If I am called more than once, I ignore attempts to set Last-Modified earlier, only replacing the Last-Modified time if it is to a later value.

If I am a conditional request, I may modify my response code to NOT_MODIFIED if appropriate for the time given.

ParameterswhenThe last time the resource being returned was modified, in seconds since the epoch. (type: number)
ReturnsIf I am a If-Modified-Since conditional request and the time given is not newer than the condition, I return http.CACHED to indicate that you should write no body. Otherwise, I return a false value.
def setETag(self, etag): (source)
Set an entity tag for the outgoing response.

That's "entity tag" as in the HTTP/1.1 ETag header, "used for comparing two or more entities from the same requested resource."

If I am a conditional request, I may modify my response code to NOT_MODIFIED or PRECONDITION_FAILED, if appropriate for the tag given.

ParametersetagThe entity tag for the resource being returned. (type: string)
ReturnsIf I am a If-None-Match conditional request and the tag matches one in the request, I return http.CACHED to indicate that you should write no body. Otherwise, I return a false value.
def getAllHeaders(self): (source)
Return dictionary mapping the names of all received headers to the last value received for each.

Since this method does not return all header information, self.requestHeaders.getAllRawHeaders() may be preferred.

def getRequestHostname(self): (source)
Get the hostname that the user passed in to the request.

This will either use the Host: header (if it is available) or the host we are listening on if the header is unavailable.

Returnsthe requested hostname (type: bytes)
def getHost(self): (source)
Get my originally requesting transport's host.

Don't rely on the 'transport' attribute, since Request objects may be copied remotely. For information on this method's return value, see twisted.internet.tcp.Port.

def setHost(self, host, port, ssl=0): (source)

Change the host and port the request thinks it's using.

This method is useful for working with reverse HTTP proxies (e.g. both Squid and Apache's mod_proxy can do this), when the address the HTTP client is using is different than the one we're listening on.

For example, Apache may be listening on https://www.example.com/, and then forwarding requests to http://localhost:8080/, but we don't want HTML produced by Twisted to say b'http://localhost:8080/', they should say b'https://www.example.com/', so we do:

  request.setHost(b'www.example.com', 443, ssl=1)
ParametershostThe value to which to change the host header. (type: bytes)
sslA flag which, if True, indicates that the request is considered secure (if True, isSecure will return True). (type: bool)
def getClientIP(self): (source)
Return the IP address of the client who submitted this request.
Returnsthe client IP address (type: str)
def isSecure(self): (source)
Return True if this request is using a secure transport.

Normally this method returns True if this request's HTTPChannel instance is using a transport that implements ISSLTransport.

This will also return True if setHost() has been called with ssl=True.

ReturnsTrue if this request is secure (type: bool)
def _authorize(self): (source)
Undocumented
def getUser(self): (source)
Return the HTTP user sent with this request, if any.

If no user was supplied, return the empty string.

Returnsthe HTTP user, if any (type: bytes)
def getPassword(self): (source)
Return the HTTP password sent with this request, if any.

If no password was supplied, return the empty string.

Returnsthe HTTP password, if any (type: bytes)
def getClient(self): (source)
Undocumented
def connectionLost(self, reason): (source)
There is no longer a connection for this request to respond over. Clean up anything which can't be useful anymore.
API Documentation for Twisted, generated by pydoctor at 2014-05-12 18:27:00.