twisted.web.iweb.IAgent : API documentation

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)

def request(method, uri, headers=None, bodyProducer=None): (source)

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 `NoneType`)
	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`)

t.w.i.IAgent(Interface) : interface documentation