Correct Doc location and update for middleware only

Correct the location of the documents and only publish middleware
documentation.

doc/Makefile

@@ -62,9 +62,9 @@ qthelp:
 	@echo
 	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
 	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
-	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/python-keystoneclient.qhcp"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/keystonemiddleware.qhcp"
 	@echo "To view the help file:"
-	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/python-keystoneclient.qhc"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/keystonemiddleware.qhc"
 
 latex:
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex

doc/ext/apidoc.py

@@ -35,10 +35,10 @@ def run_apidoc(app):
     run_already = True
 
     package_dir = path.abspath(path.join(app.srcdir, '..', '..',
-                                         'keystoneclient'))
+                                         'keystonemiddleware'))
     source_dir = path.join(app.srcdir, 'api')
     apidoc.main(['apidoc', package_dir, '-f',
-                 '-H', 'keystoneclient Modules',
+                 '-H', 'keystonemiddleware Modules',
                  '-o', source_dir])
 
 

doc/source/conf.py

@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 #
-# python-keystoneclient documentation build configuration file, created by
+# keystonemiddleware documentation build configuration file, created by
 # sphinx-quickstart on Sun Dec  6 14:19:25 2009.
 #
 # This file is execfile()d with the current directory set to its containing
@@ -64,13 +64,13 @@ source_suffix = '.rst'
 master_doc = 'index'
 
 # General information about the project.
-project = 'python-keystoneclient'
+project = 'keystonemiddleware'
 copyright = 'OpenStack Contributors'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
-version_info = pbr.version.VersionInfo('python-keystoneclient')
+version_info = pbr.version.VersionInfo('keystonemiddleware')
 # The short X.Y version.
 version = version_info.version_string()
 # The full version, including alpha/beta/rc tags.
@@ -117,10 +117,7 @@ pygments_style = 'sphinx'
 # Grouping the document tree for man pages.
 # List of tuples 'sourcefile', 'target', 'title', 'Authors name', 'manual'
 
-man_pages = [
+man_pages = []
-    ('man/keystone', 'keystone', 'Client for OpenStack Identity API',
-     ['OpenStack Contributors'], 1),
-]
 
 # -- Options for HTML output --------------------------------------------------
 
@@ -195,7 +192,7 @@ html_last_updated_fmt = os.popen(git_cmd).read()
 #html_file_suffix = ''
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'python-keystoneclientdoc'
+htmlhelp_basename = 'keystonemiddlewaredoc'
 
 
 # -- Options for LaTeX output -------------------------------------------------
@@ -210,8 +207,8 @@ htmlhelp_basename = 'python-keystoneclientdoc'
 # (source start file, target name, title, author, documentclass [howto/manual])
 # .
 latex_documents = [
-    ('index', 'python-keystoneclient.tex',
+    ('index', 'keystonmiddleware.tex',
-     'python-keystoneclient Documentation',
+     'keystonemiddleware Documentation',
      'Nebula Inc, based on work by Rackspace and Jacob Kaplan-Moss',
      'manual'),
 ]

doc/source/index.rst

@@ -0,0 +1,34 @@
+Python Middleware for OpenStack Identity API (Keystone)
+=======================================================
+
+This is the middleware provided for integrating with the OpenStack 
+Identity API and handling authorization enforcement based upon the
+data within the OpenStack Identity tokens.
+
+Contents:
+
+.. toctree::
+   :maxdepth: 1
+
+   middlewarearchitecture
+
+Contributing
+============
+
+Code is hosted `on GitHub`_. Submit bugs to the Keystone project on
+`Launchpad`_. Submit code to the ``openstack/keystonemiddleware`` project
+using `Gerrit`_.
+
+.. _on GitHub: https://github.com/openstack/keystonemiddleware
+.. _Launchpad: https://launchpad.net/keystonemiddleware
+.. _Gerrit: http://wiki.openstack.org/GerritWorkflow
+
+Run tests with ``python setup.py test``.
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+

doc/source/middlewarearchitecture.rst

@@ -32,7 +32,7 @@ authentication middleware which acts as the internal API mechanism for
 OpenStack projects based on the WSGI standard.
 
 This documentation describes the implementation in
-:class:`keystoneclient.middleware.auth_token`
+:class:`keystonemiddleware.auth_token`
 
 Specification Overview
 ======================
@@ -120,7 +120,7 @@ a WSGI component. Example for the auth_token middleware::
     pipeline = authtoken myService
 
     [filter:authtoken]
-    paste.filter_factory = keystoneclient.middleware.auth_token:filter_factory
+    paste.filter_factory = keystonemiddleware.auth_token:filter_factory
 
     # Prefix to prepend at the beginning of the path (string
     # value)
@@ -246,7 +246,7 @@ config file. For example in Nova, all middleware parameters can be removed
 from api-paste.ini::
 
     [filter:authtoken]
-    paste.filter_factory = keystoneclient.middleware.auth_token:filter_factory
+    paste.filter_factory = keystonemiddleware.auth_token:filter_factory
 
 and set in nova.conf::
 
@@ -414,10 +414,10 @@ unsuccessful.
 Extended the request with additional User Information
 -----------------------------------------------------
 
-:py:class:`keystoneclient.middleware.auth_token.AuthProtocol` extends the
+:py:class:`keystonemiddleware.auth_token.AuthProtocol` extends the
 request with additional information if the user has been authenticated. See the
 "What we add to the request for use by the OpenStack service" section in
-:py:mod:`keystoneclient.middleware.auth_token` for the list of fields set by
+:py:mod:`keystonemiddleware.auth_token` for the list of fields set by
 the auth_token middleware.
 
 

docs/source/index.rst

@@ -1,42 +0,0 @@
-Python bindings to the OpenStack Identity API (Keystone)
-========================================================
-
-This is a client for OpenStack Identity API. There's a Python API for
-:doc:`Identity API v3 <using-api-v3>` and :doc:`v2 <using-api-v2>` (the
-:mod:`keystoneclient` modules), and a command-line script (installed as
-:doc:`keystone <man/keystone>`).
-
-Contents:
-
-.. toctree::
-   :maxdepth: 1
-
-   man/keystone
-   using-sessions
-   using-api-v2
-   using-api-v3
-
-   middlewarearchitecture
-
-   api/modules
-
-Contributing
-============
-
-Code is hosted `on GitHub`_. Submit bugs to the Keystone project on
-`Launchpad`_. Submit code to the ``openstack/python-keystoneclient`` project
-using `Gerrit`_.
-
-.. _on GitHub: https://github.com/openstack/python-keystoneclient
-.. _Launchpad: https://launchpad.net/python-keystoneclient
-.. _Gerrit: http://wiki.openstack.org/GerritWorkflow
-
-Run tests with ``python setup.py test``.
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-

docs/source/man/keystone.rst

@@ -1,150 +0,0 @@
-========================================
-:program:`keystone` command line utility
-========================================
-
-.. program:: keystone
-.. highlight:: bash
-
-SYNOPSIS
-========
-
-:program:`keystone` [options] <command> [command-options]
-
-:program:`keystone help`
-
-:program:`keystone help` <command>
-
-
-DESCRIPTION
-===========
-
-The :program:`keystone` command line utility interacts with services providing
-OpenStack Identity API (e.g. Keystone).
-
-To communicate with the API, you will need to be authenticated - and the
-:program:`keystone` provides multiple options for this.
-
-While bootstrapping keystone the authentication is accomplished with a
-shared secret token and the location of the Identity API endpoint. The
-shared secret token is configured in keystone.conf as "admin_token".
-
-You can specify those values on the command line with :option:`--os-token`
-and :option:`--os-endpoint`, or set them in environment variables:
-
-.. envvar:: OS_SERVICE_TOKEN
-
-    Your keystone administrative token
-
-.. envvar:: OS_SERVICE_ENDPOINT
-
-    Your Identity API endpoint
-
-The command line options will override any environment variables set.
-
-If you already have accounts, you can use your OpenStack username and
-password. You can do this with the :option:`--os-username`,
-:option:`--os-password`.
-
-Keystone allows a user to be associated with one or more projects which are
-historically called tenants.  To specify the project for which you want to
-authorize against, you may optionally specify a :option:`--os-tenant-id` or
-:option:`--os-tenant-name`.
-
-Instead of using options, it is easier to just set them as environment
-variables:
-
-.. envvar:: OS_USERNAME
-
-    Your Keystone username.
-
-.. envvar:: OS_PASSWORD
-
-    Your Keystone password.
-
-.. envvar:: OS_TENANT_NAME
-
-    Name of Keystone project.
-
-.. envvar:: OS_TENANT_ID
-
-    ID of Keystone Tenant.
-
-.. envvar:: OS_AUTH_URL
-
-    The OpenStack API server URL.
-
-.. envvar:: OS_IDENTITY_API_VERSION
-
-    The OpenStack Identity API version.
-
-.. envvar:: OS_CACERT
-
-    The location for the CA truststore (PEM formatted) for this client.
-
-.. envvar:: OS_CERT
-
-    The location for the keystore (PEM formatted) containing the public
-    key of this client.  This keystore can also optionally contain the
-    private key of this client.
-
-.. envvar:: OS_KEY
-
-    The location for the keystore (PEM formatted) containing the private
-    key of this client.  This value can be empty if the private key is
-    included in the OS_CERT file.
-
-For example, in Bash you'd use::
-
-    export OS_USERNAME=yourname
-    export OS_PASSWORD=yadayadayada
-    export OS_TENANT_NAME=myproject
-    export OS_AUTH_URL=http(s)://example.com:5000/v2.0/
-    export OS_IDENTITY_API_VERSION=2.0
-    export OS_CACERT=/etc/keystone/yourca.pem
-    export OS_CERT=/etc/keystone/yourpublickey.pem
-    export OS_KEY=/etc/keystone/yourprivatekey.pem
-
-
-OPTIONS
-=======
-
-To get a list of available commands and options run::
-
-    keystone help
-
-To get usage and options of a command::
-
-    keystone help <command>
-
-
-EXAMPLES
-========
-
-Get information about endpoint-create command::
-
-    keystone help endpoint-create
-
-View endpoints of OpenStack services::
-
-    keystone catalog
-
-Create a 'service' project::
-
-    keystone tenant-create --name=service
-
-Create service user for nova::
-
-    keystone user-create --name=nova \
-                         --tenant_id=<project ID> \
-                         --email=nova@nothing.com
-
-View roles::
-
-    keystone role-list
-
-
-BUGS
-====
-
-Keystone client is hosted in Launchpad so you can view current bugs at
-https://bugs.launchpad.net/python-keystoneclient/.

docs/source/using-api-v2.rst

@@ -1,117 +0,0 @@
-=================
-The Client v2 API
-=================
-
-Introduction
-============
-
-The main concepts in the Identity v2 API are:
-
- * tenants
- * users
- * roles
- * services
- * endpoints
-
-The client v2 API lets you query and make changes through
-managers. For example, to manipulate tenants, you interact with a
-``keystoneclient.v2_0.tenants.TenantManager`` object.
-
-You obtain access to managers through via attributes of the
-``keystoneclient.v2_0.client.Client`` object. For example, the ``tenants``
-attribute of the ``Client`` class is a tenant manager::
-
-    >>> from keystoneclient.v2_0 import client
-    >>> keystone = client.Client(...)
-    >>> 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.
-
-You can generally expect that when the client needs to propagate an exception
-it will raise an instance of subclass of
-``keystoneclient.exceptions.ClientException``
-
-Authenticating
-==============
-
-There are two ways to authenticate against Keystone:
- * against the admin endpoint with the admin token
- * against the public endpoint with a username and password
-
-If you are an administrator, you can authenticate by connecting to the admin
-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 keystoneclient.v2_0 import client
-    >>> token = '012345SECRET99TOKEN012345'
-    >>> endpoint = 'http://192.168.206.130:35357/v2.0'
-    >>> keystone = client.Client(token=token, endpoint=endpoint)
-
-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 keystoneclient.v2_0 import client
-    >>> username='adminUser'
-    >>> password='secreetword'
-    >>> tenant_name='openstackDemo'
-    >>> auth_url='http://192.168.206.130:5000/v2.0'
-    >>> keystone = client.Client(username=username, password=password,
-    ...                          tenant_name=tenant_name, auth_url=auth_url)
-
-Creating tenants
-================
-
-This example will create a tenant named *openStackDemo*::
-
-    >>> from keystoneclient.v2_0 import client
-    >>> keystone = client.Client(...)
-    >>> keystone.tenants.create(tenant_name="openstackDemo",
-    ...                         description="Default Tenant", enabled=True)
-    <Tenant {u'id': u'9b7962da6eb04745b477ae920ad55939', u'enabled': True, u'description': u'Default Tenant', u'name': u'openstackDemo'}>
-
-Creating users
-==============
-
-This example will create a user named *adminUser* with a password *secretword*
-in the opoenstackDemo tenant. We first need to retrieve the tenant::
-
-    >>> from keystoneclient.v2_0 import client
-    >>> keystone = client.Client(...)
-    >>> tenants = keystone.tenants.list()
-    >>> my_tenant = [x for x in tenants if x.name=='openstackDemo'][0]
-    >>> my_user = keystone.users.create(name="adminUser",
-    ...                                 password="secretword",
-    ...                                 tenant_id=my_tenant.id)
-
-Creating roles and adding users
-===============================
-
-This example will create an admin role and add the *my_user* user to that
-role, but only for the *my_tenant* tenant:
-
-    >>> from keystoneclient.v2_0 import client
-    >>> keystone = client.Client(...)
-    >>> role = keystone.roles.create('admin')
-    >>> my_tenant = ...
-    >>> my_user = ...
-    >>> keystone.roles.add_user_role(my_user, role, my_tenant)
-
-Creating services and endpoints
-===============================
-
-This example will create the service and corresponding endpoint for the
-Compute service::
-
-    >>> from keystoneclient.v2_0 import client
-    >>> keystone = client.Client(...)
-    >>> service = keystone.services.create(name="nova", service_type="compute",
-    ...                                    description="Nova Compute Service")
-    >>> keystone.endpoints.create(
-    ...     region="RegionOne", service_id=service.id,
-    ...     publicurl="http://192.168.206.130:8774/v2/%(tenant_id)s",
-    ...     adminurl="http://192.168.206.130:8774/v2/%(tenant_id)s",
-    ...     internalurl="http://192.168.206.130:8774/v2/%(tenant_id)s")

docs/source/using-api-v3.rst

@@ -1,113 +0,0 @@
-=================
-The Client v3 API
-=================
-
-Introduction
-============
-
-The main concepts in the Identity v3 API are:
-
- * credentials
- * domains
- * endpoints
- * groups
- * policies
- * projects
- * role assignments
- * roles
- * services
- * trusts
- * users
-
-The :py:mod:`keystoneclient.v3.client` API lets you query and make changes
-through ``managers``. For example, to manipulate a project (formerly
-called tenant), you interact with a
-:py:class:`keystoneclient.v3.projects.ProjectManager` object.
-
-You obtain access to managers through attributes of a
-:py:class:`keystoneclient.v3.client.Client` object. For example, the
-``projects`` attribute of a ``Client`` object is a projects manager::
-
-    >>> from keystoneclient.v3 import client
-    >>> keystone = client.Client(...)
-    >>> keystone.projects.list() # List projects
-
-While it is possible to instantiate a
-:py:class:`keystoneclient.v3.client.Client` object (as done above for
-clarity), the recommended approach is to use the discovery mechanism
-provided by the :py:class:`keystoneclient.client.Client` class. The
-appropriate class will be instantiated depending on the API versions
-available::
-
-    >>> from keystoneclient import client
-    >>> keystone =
-    ...    client.Client(auth_url='http://localhost:5000', ...)
-    >>> type(keystone)
-    <class 'keystoneclient.v3.client.Client'>
-
-One can force the use of a specific version of the API, either by
-using the ``version`` keyword argument::
-
-    >>> from keystoneclient import client
-    >>> keystone = client.Client(auth_url='http://localhost:5000',
-                                 version=(2,), ...)
-    >>> type(keystone)
-    <class 'keystoneclient.v2_0.client.Client'>
-    >>> keystone = client.Client(auth_url='http://localhost:5000',
-                                 version=(3,), ...)
-    >>> type(keystone)
-    <class 'keystoneclient.v3.client.Client'>
-
-Or by specifying directly the specific API version authentication URL
-as the auth_url keyword argument::
-
-    >>> from keystoneclient import client
-    >>> keystone =
-    ...     client.Client(auth_url='http://localhost:5000/v2.0', ...)
-    >>> type(keystone)
-    <class 'keystoneclient.v2_0.client.Client'>
-    >>> keystone =
-    ...     client.Client(auth_url='http://localhost:5000/v3', ...)
-    >>> type(keystone)
-    <class 'keystoneclient.v3.client.Client'>
-
-Upon successful authentication, a :py:class:`keystoneclient.v3.client.Client`
-object is returned (when using the Identity v3 API). 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
-``keystoneclient.exceptions.ClientException`` (see
-:py:class:`keystoneclient.openstack.common.apiclient.exceptions.ClientException`)
-
-Authenticating
-==============
-
-You can authenticate against Keystone using a username, a user domain
-name (which will default to 'Default' if it is not specified) and a
-password::
-
-    >>> from keystoneclient import client
-    >>> auth_url = 'http://localhost:5000'
-    >>> username = 'adminUser'
-    >>> user_domain_name = 'Default'
-    >>> password = 'secreetword'
-    >>> keystone = client.Client(auth_url=auth_url, version=(3,),
-    ...                          username=username, password=password,
-    ...                          user_domain_name=user_domain_name)
-
-You may optionally specify a domain or project (along with its project
-domain name), to obtain a scoped token::
-
-    >>> from keystoneclient import client
-    >>> auth_url = 'http://localhost:5000'
-    >>> username = 'adminUser'
-    >>> user_domain_name = 'Default'
-    >>> project_name = 'demo'
-    >>> project_domain_name = 'Default'
-    >>> password = 'secreetword'
-    >>> keystone = client.Client(auth_url=auth_url, version=(3,),
-    ...                          username=username, password=password,
-    ...                          user_domain_name=user_domain_name,
-    ...                          project_name=project_name,
-    ...                          project_domain_name=project_domain_name)

docs/source/using-sessions.rst

@@ -1,198 +0,0 @@
-==============
-Using Sessions
-==============
-
-Introduction
-============
-
-The :py:class:`keystoneclient.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.
-
-The model for using a Session and auth plugin as well as the general terms used
-have been heavily inspired by the `requests <http://docs.python-requests.org>`_
-library. However neither the Session class nor any of the authentication
-plugins rely directly on those concepts from the requests library so you should
-not expect a direct translation.
-
-Features
---------
-
-- Common client authentication
-
-  Authentication is handled by one of a variety of authentication plugins and
-  then this authentication information is shared between all the services that
-  use the same Session object.
-
-- Security maintenance
-
-  Security code is maintained in a single place and reused between all
-  clients such that in the event of problems it can be fixed in a single
-  location.
-
-- Standard discovery mechanisms
-
-  Clients are not expected to have any knowledge of an identity token or any
-  other form of identification credential. Service and endpoint discovery are
-  handled by the Session and plugins.
-
-
-Sessions for Users
-==================
-
-The Session object is the contact point to your OpenStack cloud services. It
-stores the authentication credentials and connection information required to
-communicate with OpenStack such that it can be reused to communicate with many
-services.  When creating services this Session object is passed to the client
-so that it may use this information.
-
-A Session will authenticate on demand. When a request that requires
-authentication passes through the Session the authentication plugin will be
-asked for a valid token. If a valid token is available it will be used
-otherwise the authentication plugin may attempt to contact the authentication
-service and fetch a new one.
-
-An example from keystoneclient::
-
-    >>> from keystoneclient.auth.identity import v3
-    >>> from keystoneclient import session
-    >>> from keystoneclient.v3 import client
-
-    >>> auth = v3.Password(auth_url='https://my.keystone.com:5000/v2.0',
-    ...                    username='myuser',
-    ...                    password='mypassword',
-    ...                    project_id='proj')
-    >>> sess = session.Session(auth=auth,
-    ...                        verify='/path/to/ca.cert')
-    >>> ks = client.Client(session=sess)
-    >>> users = ks.users.list()
-
-As clients adopt this means of operating they will be created in a similar
-fashion by passing the Session object to the client's constructor.
-
-
-Migrating keystoneclient to use a Session
------------------------------------------
-
-By using a session with a keystonclient Client we define that you have opted in
-to new behaviour defined by the session. For example authentication is now
-on-demand rather than on creation. To allow this change in behaviour there are
-a number of functions that have changed behaviour or are no longer available.
-
-For example the
-:py:meth:`keystoneclient.httpclient.HTTPClient.authenticate` command used
-to be able to always re-authenticate the current client and fetch a new token.
-As this is now controlled by the Session and not the client this has changed,
-however the function will still exist to provide compatibility with older
-clients.
-
-Likewise certain parameters such as ``user_id`` and ``auth_token`` that used to
-be available on the client object post authentication will remain
-uninitialized.
-
-When converting an application to use a session object with keystoneclient you
-should be aware of the possibility of changes to authentication and
-authentication parameters and make sure to test your code thoroughly. It should
-have no impact on the typical CRUD interaction with the client.
-
-
-Sharing Authentication Plugins
-------------------------------
-
-A session can only contain one authentication plugin however there is nothing
-that specifically binds the authentication plugin to that session, a new
-Session can be created that reuses the existing authentication plugin::
-
-    >>> new_sess = session.Session(auth=sess.auth,
-                                   verify='/path/to/different-cas.cert')
-
-In this case we cannot know which session object will be used when the plugin
-performs the authentication call so the command must be able to succeed with
-either.
-
-Authentication plugins can also be provided on a per-request basis. This will
-be beneficial in a situation where a single session is juggling multiple
-authentication credentials::
-
-    >>> sess.get('https://my.keystone.com:5000/v3',
-                 auth=my_auth_plugin)
-
-If an auth plugin is provided via parameter then it will override any auth
-plugin on the session.
-
-Sessions for Client Developers
-==============================
-
-Sessions are intended to take away much of the hassle of dealing with
-authentication data and token formats. Clients should be able to specify filter
-parameters for selecting the endpoint and have the parsing of the catalog
-managed for them.
-
-Authentication
---------------
-
-When making a request with a session object you can simply pass the keyword
-parameter ``authenticated`` to indicate whether the argument should contain a
-token, by default a token is included if an authentication plugin is available::
-
-    >>> # In keystone this route is unprotected by default
-    >>> resp = sess.get('https://my.keystone.com:5000/v3',
-                        authenticated=False)
-
-
-Service Discovery
------------------
-
-In OpenStack the URLs of available services are distributed to the user as a
-part of the token they receive called the Service Catalog. Clients are expected
-to use the URLs from the Service Catalog rather than have them provided.
-
-In general a client does not need to know the full URL for the server that they
-are communicating with, simply that it should send a request to a path
-belonging to the correct service.
-
-This is controlled by the ``endpoint_filter`` parameter to a request which
-contains all the information an authentication plugin requires to determine the
-correct URL to which to send a request. When using this mode only the path for
-the request needs to be specified::
-
-    >>> resp = session.get('/v3/users',
-                           endpoint_filter={'service_type': 'identity',
-                                            'interface': 'public',
-                                            'region_name': 'myregion'})
-
-``endpoint_filter`` accepts a number of arguments with which it can determine
-an endpoint url:
-
-- ``service_type``: the type of service. For example ``identity``, ``compute``,
-  ``volume`` or many other predefined identifiers.
-
-- ``interface``: the network exposure the interface has. This will be one of:
-
-  - ``public``: An endpoint that is available to the wider internet or network.
-  - ``internal``: An endpoint that is only accessible within the private network.
-  - ``admin``: An endpoint to be used for administrative tasks.
-
-- ``region_name``: the name of the region where the endpoint resides.
-
-The endpoint filter is a simple key-value filter and can be provided with any
-number of arguments. It is then up to the auth plugin to correctly use the
-parameters it understands.
-
-The session object determines the URL matching the filter and append to it the
-provided path and so create a valid request. If multiple URL matches are found
-then any one may be chosen.
-
-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.
-
-There is some expectation on the user that they understand the limitations of
-the authentication system they are using.