Merge "Update developer docs for keystoneauth session"

doc/source/using-api-v2.rst

@@ -26,8 +26,8 @@ attribute of the ``Client`` class is a tenant manager::
     >>> keystone.tenants.list() # List tenants
 
 You create a valid ``keystoneclient.v2_0.client.Client`` object by passing
-authentication data to the constructor. Authentication and examples of common
-tasks are provided below.
+a :class:`~keystoneauth1.session.Session` to the constructor. Authentication
+and examples of common tasks are provided below.
 
 You can generally expect that when the client needs to propagate an exception
 it will raise an instance of subclass of
@@ -45,22 +45,30 @@ endpoint and using the admin token (sometimes referred to as the service
 token). The token is specified as the ``admin_token`` configuration option in
 your keystone.conf config file, which is typically in /etc/keystone::
 
+    >>> from keystoneauth1.identity import v2
+    >>> from keystoneauth1 import session
     >>> from keystoneclient.v2_0 import client
     >>> token = '012345SECRET99TOKEN012345'
     >>> endpoint = 'http://192.168.206.130:35357/v2.0'
-    >>> keystone = client.Client(token=token, endpoint=endpoint)
+    >>> auth = v2.Token(auth_url=endpoint, token=token)
+    >>> sess = session.Session(auth=auth)
+    >>> keystone = client.Client(session=sess)
 
 If you have a username and password, authentication is done against the
 public endpoint. You must also specify a tenant that is associated with the
 user::
 
+    >>> from keystoneauth1.identity import v2
+    >>> from keystoneauth1 import session
     >>> from keystoneclient.v2_0 import client
     >>> username='adminUser'
     >>> password='secretword'
     >>> tenant_name='openstackDemo'
     >>> auth_url='http://192.168.206.130:5000/v2.0'
-    >>> keystone = client.Client(username=username, password=password,
+    >>> auth = v2.Password(username=username, password=password,
     ...                    tenant_name=tenant_name, auth_url=auth_url)
+    >>> sess = session.Session(auth=auth)
+    >>> keystone = client.Client(session=sess)
 
 Creating tenants
 ================

doc/source/using-api-v3.rst

@@ -84,11 +84,11 @@ Authenticating Using Sessions
 =============================
 
 Instantiate a :py:class:`keystoneclient.v3.client.Client` using a
-:py:class:`~keystoneclient.session.Session` to provide the authentication
+:py:class:`~keystoneauth1.session.Session` to provide the authentication
 plugin, SSL/TLS certificates, and other data::
 
-    >>> from keystoneclient.auth.identity import v3
-    >>> from keystoneclient import session
+    >>> from keystoneauth1.identity import v3
+    >>> from keystoneauth1 import session
     >>> from keystoneclient.v3 import client
     >>> auth = v3.Password(auth_url='https://my.keystone.com:5000/v3',
     ...                    user_id='myuserid',
@@ -117,7 +117,7 @@ password::
     ...                          username=username, password=password,
     ...                          user_domain_name=user_domain_name)
 
-A :py:class:`~keystoneclient.session.Session` should be passed to the Client
+A :py:class:`~keystoneauth1.session.Session` should be passed to the Client
 instead. Using a Session you're not limited to authentication using a username
 and password but can take advantage of other more secure authentication
 methods.

doc/source/using-sessions.rst

@@ -5,7 +5,7 @@ Using Sessions
 Introduction
 ============
 
-The :py:class:`keystoneclient.session.Session` class was introduced into
+The :py:class:`keystoneauth1.session.Session` class was introduced into
 keystoneclient as an attempt to bring a unified interface to the various
 OpenStack clients that share common authentication and request parameters
 between a variety of services.
@@ -55,8 +55,8 @@ service and fetch a new one.
 
 An example from keystoneclient::
 
-    >>> from keystoneclient.auth.identity import v3
-    >>> from keystoneclient import session
+    >>> from keystoneauth1.identity import v3
+    >>> from keystoneauth1 import session
     >>> from keystoneclient.v3 import client
 
     >>> auth = v3.Password(auth_url='https://my.keystone.com:5000/v3',
@@ -189,11 +189,12 @@ While authentication plugins will endeavour to maintain a consistent set of
 arguments for an ``endpoint_filter`` the concept of an authentication plugin is
 purposefully generic and a specific mechanism may not know how to interpret
 certain arguments and ignore them. For example the
-:py:class:`keystoneclient.auth.token_endpoint.Token` plugin (which is used when
-you want to always use a specific endpoint and token combination) will always
-return the same endpoint regardless of the parameters to ``endpoint_filter`` or
-a custom OpenStack authentication mechanism may not have the concept of
-multiple ``interface`` options and choose to ignore that parameter.
+:py:class:`keystoneauth1.identity.generic.token.Token` plugin (which is used
+when you want to always use a specific endpoint and token combination) will
+always return the same endpoint regardless of the parameters to
+``endpoint_filter`` or a custom OpenStack authentication mechanism may not have
+the concept of multiple ``interface`` options and choose to ignore that
+parameter.
 
 There is some expectation on the user that they understand the limitations of
 the authentication system they are using.