rvbd.common.connection
This module contains the Connection class, which is the underlying object for communicating with a device via REST.
Connection
class rvbd.common.connection.Connection
This class handles all HTTP/HTTPS communication with a device,
including connection management, connection pooling, XML and JSON
requests and responses. This class is normally instantiated
by a Service
object, but may be used separately as needed.
Authentication is not handled directly by this class. The caller
must set the appropriate headers for authentication either
using the extra_headers
parameter or by calling the add_headers
method. The latter will affect all subsequent requests.
Connection(hostname, port=None, force_ssl=True, pool_size=1, reauthenticate_handler=None, test_resource=None)
hostname
is the name or IP address of the device to connect to
port
is the TCP port to use for the connection. This may be either
a single port or a list of ports to try. By default, ports
443 and 80 will be tried.
force_ssl
when set to True will only allow SSL based connections.
If False, only allow non-SSL connections. If set to None
(the default) try SSL first, then try non-SSL.
pool_size
is the number of simultaneous connections to establish as
part of a connection pool. Default is 1.
reauthenticate_handler
, if set, should contain callable that is
invoked if a request returns a session expiration error.
If the call succeeds, then the request is retried once.
request(urlpath, method="GET", body="", params=None, extra_headers=None)
Send a generic HTTP request to the host.
On success, the httplib response object is returned. Any pending data must be read by the caller.
On failure, an exception is raised. Any data on the response object is drained before failing.
urlpath
is the full path of the resource from the initial slash.
For example "/api/common/1.0/ping"
method
is the HTTP method to use. Default is GET.
body
is the full text to send as the body of the message as is.
params
is a dictionary of URL parameters to attach to the request.
The keys and values will be urlencoded.
extra_headers
is a dictionary of additional HTTP headers to send
with the request.
xml_request(urlpath, method="GET", body="", params=None, extra_headers=None)
Send an XML request to the host.
This is similar to request
except the Content-Type and Accept headres
are set to text/xml. In addition, any response will be XML-decoded as
an xml.etree.ElementTree. The body is assumed to be an XML encoded
text string and is inserted into the HTTP payload as-is.
json_request(urlpath, method="GET", data=None, params=None, extra_headers=None)
Send a JSON request to the host.
For POST/PUT requests, the data
parameter will be JSON-encoded before
transmission. For all requests, the response is JSON-decoded using the
DictObject class before returning.
post_raw(urlpath, data, params=None, extra_headers=None)
Upload raw data to the given URL path with the given content type.
data
may be either a string or a python file object.
extra_headers
is a dictionary of additional HTTP headers to send
with the request (e.g. Content-Type, Content-Disposition)
params
is a dictionary of URL parameters to attach to the request.
The keys and values will be urlencoded.
Returns location information if resource has been created, otherwise the response body (if any).
type object 'Connection' has no attribute 'get_raw' add_headers(headers)
Add the dictionary HEADERS to the list of customer headers for all requests
Drop any custom headers in the list of header names in HEADERS