The gruvi.http module implements a HTTP client and server.
The client and server are relatively complete implementations of the HTTP protocol. Some of the supported features are: keepalive, pipelining, chunked transfers and trailers.
Some general notes about the implementation:
Some important points about the use of binary versus unicode types in the API:
Exception that is raised in case of HTTP protocol errors.
A HTTP request.
Instances of this class are returned by HttpProtocol.request(). This class allows you to write the request body yourself using the write() and end_request() methods. This can be useful if you need to send a large input that cannot be easily presented as as a file-like object or a generator, or if you want to use “chunked” encoding trailers.
Start a new HTTP request.
This method is called by HttpProtocol.request(). It creates a new HTTP request header and sends it to the transport.
The body parameter is a hint that specifies the body that will be sent in the future, but it will not actually send it. This method tries to deduce the Content-Length of the body that follows from it.
Write buf to the request body.
End the request body.
The optional trailers argument can be used to add trailers. This requires “chunked” encoding.
A HTTP response.
Instances of this class are returned by HttpProtocol.getresponse(). This class allows you to get access to all information related to a HTTP response, including the HTTP headers and body.
The HTTP version as a (major, minor) tuple.
The HTTP status code, as an integer.
The response headers, as a list of (name, value) pairs.
The response trailers, as a list of (name, value) pairs.
The trailers will only be available after the entire response has been read. Most servers do not generate trailers.
Return the value of HTTP header name.
If the header does not exist, return default.
Return a the value of a HTTP trailer name.
If the trailer does not exist, return default.
A gruvi.StreamReader instance for reading the response body.
A alias for self.body.read().
A alias for self.body.read1().
A alias for self.body.readline().
A alias for self.body.readlines().
Bases: gruvi.MessageProtocol
HTTP protocol implementation.
The server_side argument specifies whether this is a client or server side protocol.
If this is a server side protocol, the wsgi_application argument is mandatory and it must be a WSGI application callable.
The server_name argument can be used to override the server name for server side protocols. If not provided, then the socket name of the listening socket will be used.
Return whether the protocol is server-side.
Return the server name.
Make a new HTTP request.
The method argument is the HTTP method to be used. It must be specified as a string, for example 'GET' or 'POST'. The url argument specifies the URL and must be a string as well.
The optional headers argument specifies extra HTTP headers to use in the request. It must be a list of (name, value) tuples, with name and value a string.
The optional body argument may be used to specify a body to include in the request. It must be a bytes or str instance, a file-like object, or an iterable producing bytes or str instances. The default value for the body is the empty string b'' which sends an empty body. To send potentially very large bodies, use the file or iterator interface. Using these interfaces will send the body under the “chunked” transfer encoding. This has the added advantage that the body size does not need to be known up front.
The body may also be the None, which means that you need to send the request body yourself. This is explained below.
This method sends the request header, and if a body was specified, the request body as well. It then returns a HttpRequest instance.
If however you passsed a body of None then you must use the HttpRequest.write() and HttpRequest.end_request() methods if the HttpRequest instance to send the request body yourself. This functionality is only useful if you want to sent trailers with the HTTP “chunked” encoding. Trailers are not normally used.
The response to the request can be obtained by calling the getresponse() method.
You may make multiple requests before reading a response. This is called pipelining, and can improve per request latency greatly. For every request that you make, you must call getresponse() exactly once. The remote HTTP implementation will send by the responses in the same order as the requests.
This method is a switchpoint.
Wait for and return a HTTP response.
The return value is a HttpResponse instance. When this method returns, only the response header has been read. The response body can be read using the HttpResponse.read() and similar methods.
Note that it is required that you read the entire body of each response if you use HTTP pipelining. Specifically, it is an error to call getresponse() when the body of the response returned by a previous invocation has not yet been fully read.
This method is a switchpoint.
Bases: gruvi.Client
A HTTP client.
The optional timeout argument can be used to specify a timeout for the various network operations used within the client.
An alias for self.protocol.getresponse().
An alias for self.protocol.request().
Bases: gruvi.Server
A HTTP server.
The constructor takes the following arguments. The wsgi_handler argument must be a WSGI callable. See PEP 333.
The optional server_name argument can be used to specify a server name. This might be needed by the WSGI application to construct absolute URLs. If not provided, then the host portion of the address passed to listen() will be used.
The optional timeout argument can be used to specify a timeout for the various network operations used within the server.