Package CyberRail :: Package common :: Module httpclient :: Class Request
[hide private]
[frames] | no frames]

Class Request

source code


A request is all the data needed by an HTTP transaction to complete.

In order to complete an HTTP transaction, you have to build a Request, configure it with yours needs, send it, eventually feed it with a body if it is needed, and read the response (if any).

A request contains headers. You can set whatever headers you want, but be aware that HTTP only contains a delimited set of headers. In doubt, do not set anything. Requests without user-set-headers should be valid.

A request can contain a body if you need it. While preparing the request, you can :

See setBody() for more details.

Once your request is ready, call send(). You will receive the answer via a callback.


Note: A request will pass through these differents steps. Each transition can lead to the error state.

Instance Methods [hide private]
 
__init__(self, url=None, method='GET', headers=None, credentials=None, body=None)
Create a request
source code
 
setUrl(self, url)
Set various elements of the request given the value of the URL:
source code
 
setMethod(self, method)
Set the HTTP method, like "GET", "POST", "HEAD", etc.
source code
 
setHint(self, key, value)
Set some optionnal features of the request:
source code
 
setBody(self, data)
There is 4 ways to set the body.
source code
 
setResponseBodyMethod(self, method)
There is 4 ways to set the method the body will be retreived.
source code
 
setHeader(self, key, value) source code
 
getHeaders(self) source code
 
send(self, callback, connectionsPool=None)
Send the request.
source code
 
_pollFinished(self, response) source code
 
_shouldWeWaitForPreresponse(self) source code
 
_onEvent(self, event)
Event from the communication manager.
source code
 
_prepareBody(self)
Fix Content-length, transfert encoding, and so on given various parameters in the requests
source code
 
_buffersBody(self, event=None)
We have to buffer the entire body in order to fix the Content-Length header.
source code
 
_onBufferRequestBodyDataRead(self, event)
Read events when buffering the body request.
source code
 
_beginConnection(self)
Ask a connection
source code
 
_cancelRequest(self, reason)
In case of IO errors.
source code
 
_preparePreamble(self)
Construct the HTTP Request based on the informations we have
source code
 
_onConnectionReady(self, con)
The connection is now ready, we can send something on it.
source code
 
_sendBody(self)
Send the body...
source code
 
_onLiveBodyDataRead(self, event)
Data read from the stream for the request body, then sent.
source code
 
addBodyData(self, data, endingHeaders=None)
Send part of the request body.
source code
 
_sendBodyChunk(self, data)
Send a chunk of the request body.
source code
 
_onData(self, data)
Some data is arriving on our socket...
source code
 
_stopSendingBody(self)
In case of emergency...
source code
 
_onConnectionClosed(self)
Server has close the connection while we used it.
source code
 
_onPreResponseHeaders(self, data)
Response is coming.
source code
 
_getRemoteVersion(self) source code
 
_onResponseHeaders(self, data)
Response is coming.
source code
 
_onResponseBody(self, data=None)
Manage data that should be the body of the response...
source code
 
_onIOError(self, error, data=None)
Called when an IO error occusrs.
source code
 
_cleanup(self)
The HTTP transaction is now completed, but the TCP connection is still alive.
source code
 
_closeResponseBody(self)
Call the callback when the response is finished.
source code

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __repr__, __setattr__, __sizeof__, __str__, __subclasshook__

Class Variables [hide private]
  URI = re.compile(r'^(([^:/\?#]+):)?(//([^/\?#]*))?([^\?#]*)(\?...
Properties [hide private]

Inherited from object: __class__

Method Details [hide private]

__init__(self, url=None, method='GET', headers=None, credentials=None, body=None)
(Constructor)

source code 

Create a request

Parameters:
  • url - The url to call (the same as setUrl)
  • method - HTTP method to use (the same as setMethod)
  • headers - A dict containing specific headers (like setHeaders)
  • credentials - credentials that could be used for this request (not used)
  • body - body that should be used dor this request (the same as setBody)
Overrides: object.__init__

setUrl(self, url)

source code 

Set various elements of the request given the value of the URL:

  • host
  • port
  • path
  • credentials

setMethod(self, method)

source code 

Set the HTTP method, like "GET", "POST", "HEAD", etc.

You could put any method you want, but you should know that HTTP only know a small predefined set of methods.

setHint(self, key, value)

source code 

Set some optionnal features of the request:

  • connection:
    • "open": the connection will stay open after the request, if possible
    • "close": the connection will get closed after the request
  • preresponse:
    • True: the 100-continue mechanism will be used if possible
  • version:
    • "poll": the server will get polled for its version before the request

setBody(self, data)

source code 

There is 4 ways to set the body.

  • data is None (default) No body will be sent.
  • data is a string or bytes. There is no restriction for this. Will be sent without interaction with the caller.
  • data is a stream (actually a tuple with a communication manager and a cid)

    In this case, all the data in the in-buffer will be sent until eof, or if a Content-length header has been sent, until n bytes have been read.

    Depending the version of HTTP, requirements will not be the same :

    If HTTP version is 1.0 and no Content-length is set, the stream will be entirely buffered to know the size of the body.

    If HTTP version is 1.1 and no Content-length is set, the stream will be read until EOF, then the body will finish.

    If Content-length is set, the stream will be read until the body size is reach. If the stream is not large enough, the connection will be aborted, and an exception will rise. You should avoid setting Content-length unless you know what you are doing. If server is know to be HTTP/1.1, the Content-length header will be discarded from the request.

    It is wise to pass the stream in hold state, in order not to fill too much memory.

  • data is DELAYED (a module global variable)

    You will be able to set the data in the "sending" request state.

    You could send as much data as you want with addBodyData(). HTTP server version must be 1.1 in order for this to work finely.

    You can use this with HTTP 1.0, but you must set the Content-length header before calling send(). In this case, finishBodyData() becomes unnecessary and sholdn't be used. The connection will be stalled until you add the right number of bytes.

setResponseBodyMethod(self, method)

source code 

There is 4 ways to set the method the body will be retreived.

- method is None
  Body, if any, is discarded.

- method is STORE (default)
  All body will be read and stored in the Response object. The
  callback of the send method will be called once the body
  is completly retrieved.

- method is CALLBACK
  The callback specified in the send method will be called each
  time a part of the response is received. The response buffer
  will contain only the received part.

- method is a stream (actually a tuple with a communication manager
  and a cid)
  The body response will be written on this stream, then the 
  callback will be called. The Response won't contain any body
  response.

send(self, callback, connectionsPool=None)

source code 

Send the request. If the request body has been set to DELAYED (and server has not refused it), callback will be called when reaching the "sending" state. If the response body has been set to CALLBACK, this callback will be called when reaching "receiving" state. Else, callback will be called at the "finish" state.

It is not wise to change some part of the request after calling this method.

Parameters:
  • callback - a callable that will be called whenever a caller interaction is needed. See setRequestBody() and setResponseBodyMethod for complete protocol with this callback. This one takes a response as first argument.
  • connectionsPool - if None, the global connectionsPool will be used (default case).

_buffersBody(self, event=None)

source code 

We have to buffer the entire body in order to fix the Content-Length header. We are in the HTTP/1.0 protocol, so we can't use chunked encoding.

addBodyData(self, data, endingHeaders=None)

source code 

Send part of the request body. When request body method is DELAYED, the callback is called and you have to furnish some data with this method.

Once all data has been sent, you have to (HTTP/1.1) call this with an empty string, and some final headers (not yet implemented). It is safe to call this method for request body termination with HTTP/1.0

Note: do not call this when not in the "sending" state.

_sendBodyChunk(self, data)

source code 

Send a chunk of the request body. A chunk can just be a part of the stream, or chunked data, as defined in RFC.

_stopSendingBody(self)

source code 

In case of emergency... Something went wrong

_onConnectionClosed(self)

source code 

Server has close the connection while we used it. It is ok in receiving state if the server didn't give us a content length or a chunked encoding. In all other case, either its a bug somewhere, or an IO error occured.

_onPreResponseHeaders(self, data)

source code 

Response is coming. Headers first.

_onResponseHeaders(self, data)

source code 

Response is coming. Headers first.

_cleanup(self)

source code 

The HTTP transaction is now completed, but the TCP connection is still alive. We do some cleanup before returning the one.

_closeResponseBody(self)

source code 

Call the callback when the response is finished. And close its storage if its a stream


Class Variable Details [hide private]

URI

Value:
re.compile(r'^(([^:/\?#]+):)?(//([^/\?#]*))?([^\?#]*)(\?([^#]*))?(#(.*\
))?')