twisted.web.iweb.IAgent(Interface) interface documentationtwisted.web.iweb
(View In Hierarchy)
Known implementations: twisted.web.client.Agent, twisted.web.client.ContentDecoderAgent, twisted.web.client.CookieAgent, twisted.web.client.ProxyAgent, twisted.web.client.RedirectAgent
An agent makes HTTP requests.
The way in which requests are issued is left up to each implementation. Some may issue them directly to the server indicated by the net location portion of the request URL. Others may use a proxy specified by system configuration.
Processing of responses is also left very widely specified. An implementation may perform no special handling of responses, or it may implement redirect following or content negotiation, it may implement a cookie store or automatically respond to authentication challenges. It may implement many other unforeseen behaviors as well.
It is also intended that IAgent implementations
be composable. An implementation which provides cookie handling features
should re-use an implementation that provides connection pooling and this
combination could be used by an implementation which adds content
negotiation functionality. Some implementations will be completely
self-contained, such as those which actually perform the network operations
to send and receive requests, but most or all other implementations should
implement a small number of new features (perhaps one new feature) and
delegate the rest of the request/response machinery to another
implementation.
This allows for great flexibility in the behavior an IAgent will provide.
For example, an IAgent with web
browser-like behavior could be obtained by combining a number of
(hypothetical) implementations:
baseAgent = Agent(reactor)
redirect = BrowserLikeRedirectAgent(baseAgent, limit=10)
authenticate = AuthenticateAgent(
redirect, [diskStore.credentials, GtkAuthInterface()])
cookie = CookieAgent(authenticate, diskStore.cookie)
decode = ContentDecoderAgent(cookie, [(b"gzip", GzipDecoder())])
cache = CacheAgent(decode, diskStore.cache)
doSomeRequests(cache)
| Method | request | Request the resource at the given location. |
Request the resource at the given location.
| Parameters | method | The request method to use, such as "GET",
"HEAD", "PUT",
"POST", etc. (type: bytes) |
| uri | The location of the resource to request. This should be an absolute URI
but some implementations may support relative URIs (with absolute or
relative paths). HTTP and HTTPS are the schemes most likely
to be supported but others may be as well. (type: bytes) | |
| headers | The headers to send with the request (or None
to send no extra headers). An implementation may add its own headers to
this (for example for client identification or content negotiation). (type: Headers or
None) | |
| bodyProducer | An object which can generate bytes to make up the body of this request (for
example, the properly encoded contents of a file for a file upload). Or,
None
if the request is to have no body. (type: IBodyProducer
provider) | |
| Returns | A Deferred
that fires with an IResponse provider
when the header of the response has been received (regardless of the
response status code) or with a Failure if
there is any problem which prevents that response from being received
(including problems that prevent the request from being sent). (type: Deferred) | |