Add Transport doc

Basic overview of the Transport class with some sample code.

Change-Id: I214f494da1f2674041ef0dd753cae4f3706966d9
This commit is contained in:
Dean Troyer 2014-04-09 14:55:28 -05:00 committed by Terry Howe
parent f47198fca6
commit fcc7d7e1e6
3 changed files with 120 additions and 1 deletions

View File

@ -1,4 +1,3 @@
====================
OpenStack Python SDK
====================

View File

@ -10,4 +10,12 @@ Contents:
usage
contributing
Classes
=======
.. toctree::
:maxdepth: 1
transport
.. include:: ../../README.rst

112
doc/source/transport.rst Normal file
View File

@ -0,0 +1,112 @@
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
----------------
Class ``openstack.transport.Transport(user_agent=None, verify=True, redirect=DEFAULT_REDIRECT_LIMIT, ...)``
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``