deb-python-openstacksdk/doc/source/transport.rst

Transport

Class openstack.transport.Transport is a subclass of requests.Session that adds some features that are common in OpenStack APIs or can be globally controlled by an application. Its use is incredibly similar to requests.Session such that we only will cover the differences in detail here.

Transport object

Create a new Transport object. In addition to those listed below, all arguments available to requests.Session are available here:

• user_agent - Set the default User-Agent header (default: None)
• verify - If True, the SSL cert will be verified. It can also be set to a CA_BUNDLE path. (default: True)
• redirect - Disallow redirects if False, or allow requests.Session to handle redirects if True. An integer can instead be passed to specify the maximum number of redirections followed.

Method Transport.request(method, url, redirect=None, **kwargs)

Perform an HTTP request. The following arguments differ from requests.Session:

• redirect - (integer) The maximum number of redirections followed in a request. (boolean) No redirections if False, requests.Session handles redirection if True. (default: openstack.transport.DEFAULT_REDIRECT_LIMIT)
• json - Request body to be encoded as JSON. Overwrites data argument if present. (default: None)
• user_agent - Set the default User-Agent header (default: None)

Examples

Basic HTTP GET

Making a basic HTTP GET call is very simple:

from openstack import transport
trans = transport.Transport()
versions = trans.get('cloud.example.com:5000').json()

will retrieve the version data served by the Identity API into a Python dict.

HTTP POST

Creating a new object in an OpenStack service is similarly simple:

from openstack import transport
trans = transport.Transport()
new_record = {'name': 'The White Albumn', 'artist': 'The Beatles'}
resp = trans.post('cloud.example.com:4999/record', json=new_record)

Passing in the new_record dict with the json keyword argument performs the json.dumps() prior to the request being sent. This is an addition to the capabilities of requests.Session.

Additional HTTP Methods

Just as in requests.Session, all of the HTTP verbs have corresponding methods in the Transport object.

SSL/TLS and Certificates

The verify argument to Transport.request() can now be set when the Transport object is created. It can still be overwritten during any individual call to request() or the HTTP verb methods.

To set the default hostname verification for the Transport to use a custom CA certificate file:

from openstack import transport
trans = transport.Transport(verify='/etc/tls/local-ca-certs.crt')

The same usage from requests is still available. To use the default CA certificate file for a single request:

versions = trans.get('cloud.example.com:5000', verify=True)

Or hit on a host with a self-signed certificate:

versions = trans.get('cloud.example.com:5000', verify=None)

Redirection

Redirection handling differs from requests by default as this module is expected to be primarily used for querying REST API servers. The redirection model differs in that requests follows some browser patterns where it will redirect POSTs as GETs for certain statuses which is not want we want for an API.

See: https://en.wikipedia.org/wiki/Post/Redirect/Get

User Agent

The User-Agent header may be set when the Transport object is created in addition to the existing per-request mode. The determination of how to set the User-Agent header is as follows:

• If the user_agent argument is included in the request() call use it
• Else if User-Agent is set in the headers dict use it
• Else if user_agent argument is included in the Transport construction use it
• Else use transport.DEFAULT_USER_AGENT