class twisted.web.iweb.IAgent(Interface): (source)
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) | |