Add Transport doc

Basic overview of the Transport class with some sample code.

Change-Id: I214f494da1f2674041ef0dd753cae4f3706966d9

README.rst

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

doc/source/index.rst

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

doc/source/transport.rst

@@ -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``