Requests¶
This module implements functions to easily handle the intricacies of the HTTP protocol. The name and the API are inspired by the wonderful Python module Requests. To use requests a net driver must have been properly configured and started.
-
get
(url, params=None, headers=None, connection=None, stream_callback=None, stream_chunk=512)¶ Implements the GET method of the HTTP protocol. A tcp connection is made to the host:port given in the url using the default net driver.
If params is given as a dictionary, each pair (key, value) is appended to the requested url, properly encoded and sent.
If headers is given as a dictionary, each pair (key, value) is appropriately sent as a HTTP request header. Mandatory headers are transparently handled: “Host:” is always derived by parsing url; other headers are set to defaults if not given: for example “Connection: close” is sent if no value for “Connection” is specified in headers. To request a permanent connection, headers must contain the pair {“Connection”:”Keep-Alive”}.
If connection is given, the initial connection step is skipped and connection is used for communication. This feature allows the reuse of a connection to a HTTP server opened with a “Keep-Alive” header.
get returns a
Response
instance.Exceptions can be raised:
HTTPConnectionError
when the HTTP server can’t be contacted;IOError
when the source of error lies at the socket level (i.e. closed sockets, invalid sockets, etc..)If the parameter stream_callback is given, the HTTP body data will be retrieved in chunk s of stream_chunk size and passed as arguments to stream_callback one by one. If stream_callback is used, the content of
Response
instance is the last chunk.
-
post
(url, data=None, json=None, headers=None, ctx=None)¶ Implements the POST method of the HTTP protocol. A tcp connection is made to the host:port given in the url using the default net driver.
If headers is given as a dictionary, each pair (key, value) is appropriately sent as a HTTP request header. Mandatory headers are transparently handled: “Host:” is always derived by parsing url; other headers are set to defaults if not given: for example “Connection: close” is sent if no value for “Connection” is specified in headers. To request a permanent connection, headers must contain the pair {“Connection”:”Keep-Alive”}.
If data is provided (always as dictionary), each pair (key, value) will be form-encoded and send in the body of the request with {“content-type”:”application/x-www-form-urlencoded”} appended in the headers. If json is provided (always as dictionary), json data will send in the body of the request with {“content-type”:”application/json”} appended in the headers.
Note
if both (data and json) dict are provided, json data are ignored and post request is performed with urlencoded data.
post returns a
Response
instance.Exceptions can be raised:
HTTPConnectionError
when the HTTP server can’t be contacted;IOError
when the source of error lies at the socket level (i.e. closed sockets, invalid sockets, etc..)
-
put
(url, data=None, json=None, headers=None, ctx=None)¶ Implements the PUT method of the HTTP protocol. A tcp connection is made to the host:port given in the url using the default net driver.
If headers is given as a dictionary, each pair (key, value) is appropriately sent as a HTTP request header. Mandatory headers are transparently handled: “Host:” is always derived by parsing url; other headers are set to defaults if not given: for example “Connection: close” is sent if no value for “Connection” is specified in headers. To request a permanent connection, headers must contain the pair {“Connection”:”Keep-Alive”}.
If data is provided (always as dictionary), each pair (key, value) will be form-encoded and send in the body of the request with {“content-type”:”application/x-www-form-urlencoded”} appended in the headers. If json is provided (always as dictionary), json data will send in the body of the request with {“content-type”:”application/json”} appended in the headers.
Note
if both (data and json) dict are provided, json data are ignored and post request is performed with urlencoded data.
put returns a
Response
instance.Exceptions can be raised:
HTTPConnectionError
when the HTTP server can’t be contacted;IOError
when the source of error lies at the socket level (i.e. closed sockets, invalid sockets, etc..)
-
patch
(url, data=None, headers=None, ctx=None)¶ Implements the PATCH method of the HTTP protocol. A tcp connection is made to the host:port given in the url using the default net driver.
If headers is given as a dictionary, each pair (key, value) is appropriately sent as a HTTP request header. Mandatory headers are transparently handled: “Host:” is always derived by parsing url; other headers are set to defaults if not given: for example “Connection: close” is sent if no value for “Connection” is specified in headers. To request a permanent connection, headers must contain the pair {“Connection”:”Keep-Alive”}.
If data is provided (always as dictionary), each pair (key, value) will be form-encoded and send in the body of the request with {“content-type”:”application/x-www-form-urlencoded”} appended in the headers. If json is provided (always as dictionary), json data will send in the body of the request with {“content-type”:”application/json”} appended in the headers.
Note
if both (data and json) dict are provided, json data are ignored and post request is performed with urlencoded data.
patch returns a
Response
instance.Exceptions can be raised:
HTTPConnectionError
when the HTTP server can’t be contacted;IOError
when the source of error lies at the socket level (i.e. closed sockets, invalid sockets, etc..)
-
delete
(url, headers=None, ctx=None)¶ Implements the DELETE method of the HTTP protocol. A tcp connection is made to the host:port given in the url using the default net driver.
If headers is given as a dictionary, each pair (key, value) is appropriately sent as a HTTP request header. Mandatory headers are transparently handled: “Host:” is always derived by parsing url; other headers are set to defaults if not given: for example “Connection: close” is sent if no value for “Connection” is specified in headers. To request a permanent connection, headers must contain the pair {“Connection”:”Keep-Alive”}.
delete returns a
Response
instance.Exceptions can be raised:
HTTPConnectionError
when the HTTP server can’t be contacted;IOError
when the source of error lies at the socket level (i.e. closed sockets, invalid sockets, etc..)
-
head
(url, headers=None, ctx=None)¶ Implements the HEAD method of the HTTP protocol. A tcp connection is made to the host:port given in the url using the default net driver.
If headers is given as a dictionary, each pair (key, value) is appropriately sent as a HTTP request header. Mandatory headers are transparently handled: “Host:” is always derived by parsing url; other headers are set to defaults if not given: for example “Connection: close” is sent if no value for “Connection” is specified in headers. To request a permanent connection, headers must contain the pair {“Connection”:”Keep-Alive”}.
head returns a
Response
instance.Exceptions can be raised:
HTTPConnectionError
when the HTTP server can’t be contacted;IOError
when the source of error lies at the socket level (i.e. closed sockets, invalid sockets, etc..)
-
options
(url, headers=None, ctx=None)¶ Implements the OPTIONS method of the HTTP protocol. A tcp connection is made to the host:port given in the url using the default net driver.
If headers is given as a dictionary, each pair (key, value) is appropriately sent as a HTTP request header. Mandatory headers are transparently handled: “Host:” is always derived by parsing url; other headers are set to defaults if not given: for example “Connection: close” is sent if no value for “Connection” is specified in headers. To request a permanent connection, headers must contain the pair {“Connection”:”Keep-Alive”}.
options returns a
Response
instance.Exceptions can be raised:
HTTPConnectionError
when the HTTP server can’t be contacted;IOError
when the source of error lies at the socket level (i.e. closed sockets, invalid sockets, etc..)
-
upload
(url, fd, ctx=None, mime_type="application/octet-stream", method="POST")¶ Upload a file identified by fd to url. fd must provide methods read and size.
A tcp connection is made to the host:port given in the url using the default net driver.
The type of the file contents and the HTTP method (POST pr PUT) can be customized.
upload returns a
Response
instance.Exceptions can be raised:
HTTPConnectionError
when the HTTP server can’t be contacted;IOError
when the source of error lies at the socket level (i.e. closed sockets, invalid sockets, file, etc..)
-
class
Response
¶ This class represent the result of a HTTP request.
It contains the following members:
-
status
¶ Contains the HTTP response code
-
content
¶ It is the bytearray containing the byte version of the content section of a HTTP response
-
headers
¶ A dictionary with all the response headers
-
connection
¶ the connection used to communicate with the server, or None if it has been closed.
-
-
text
()¶ Returns a string representing the content section of the HTTP response