Transport

The 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.

The common OpenStack functionality added include:

  • Log all requests and responses at debug level.
  • Support json encoding in the request() method.
  • Set the default user_agent at Transport creation. If it is set to None to skip the header.
  • Set the default verify at Transport creation.

Examples

Basic HTTP GET

Making a basic HTTP GET call is very simple:

from openstack import transport
trans = transport.Transport()
versions = trans.get('http://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('http://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('https://cloud.example.com:5000', verify=True)

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

versions = trans.get('https://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

User-Agent handling as constructed by this class follows RFC 7231 Section 5.5.3. A well-formed user-agent is constructed on name/version product identifiers, such that MyProgram/1.0 is a proper user-agent.

  • The default USER_AGENT contains the SDK version as well as RFC-compliant values from requests.utils.default_user_agent, including versions of requests, Python, and the operating system.
  • Any user_agent argument passed when creating a Transport is prepended to the default.
  • Any user_agent passed in a request() call is prepended to one used for that Transport instance.
  • Any string passed as the User-Agent in a dictionary of headers to request() will be used directly. If at the same time a user_agent argument has been passed to request(), it will be used and follows the rules above.
openstack.transport.USER_AGENT = 'python-openstacksdk/0.3.2 python-requests/2.4.3 CPython/2.7.8 Linux/3.16.0-4-amd64'

Default value for the HTTP User-Agent header. The default includes the version information of the SDK as well as requests, Python, and the operating system.

Transport Object

class openstack.transport.Transport(user_agent=None, verify=True, redirect=30, accept='application/json')

Create a new Transport object.

In addition to those listed below, all arguments available to requests.Session are available here:

Parameters:
  • user_agent (string) – Set the User-Agent header. When no value is provided, the default of USER_AGENT will be used. When a value is provided, it will be prepended to USER_AGENT.
  • verify (boolean/string) – If True, the SSL cert will be verified. A CA_BUNDLE path can also be provided.
  • redirect (boolean/integer) – (integer) The maximum number of redirections followed in a request. (boolean) No redirections if False, requests.Session handles redirection if True. (optional)
  • accept (string) – Type of output to accept
request(method, url, redirect=None, **kwargs)

Send a request

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

Parameters:
  • method (string) – Request HTTP method
  • url (string) – Request URL
  • redirect (boolean/integer) – (integer) The maximum number of redirections followed in a request. (boolean) No redirections if False, requests.Session handles redirection if True. (optional)

The following additional kw args are supported:

Parameters:
  • json (object) – Request body to be encoded as JSON Overwrites data argument if present
  • accept (string) – Set the Accept header; overwrites any value that may be in the headers dict. Header is omitted if None.
  • user_agent (string) – Prepend an additional value to the existing User-Agent header.

Remaining kw args from requests.Session.request() supported

Table Of Contents

Previous topic

Session

Next topic

BaseAuthPlugin

This Page