Make public the base loader classes

The loaders are a companion part to the authentication plugins that
assist in loading a specific plugin from options supplied via a config
file, command line arguments or other mechanisms.

The Base loaders handle the options that are common to a specific
identity authentication mechanism. They were added to the private
directory in the move from keystoneclient as they are only used by the
loaders defined in that directory and it gave us time to settle the
interfaces.

They are not expected to be private forever as they are expected to be
reused by anyone that is developing identity plugins outside of the
keystoneauth repository.

Closes-Bug: #1507423
Change-Id: I4b2fc321ae75e92509aacb15ac21e96880f2b20e

keystoneauth1/loading/__init__.py

@@ -13,6 +13,7 @@
 from keystoneauth1.loading.base import *  # noqa
 from keystoneauth1.loading import cli
 from keystoneauth1.loading import conf
+from keystoneauth1.loading.identity import *  # noqa
 from keystoneauth1.loading.opts import *  # noqa
 from keystoneauth1.loading import session
 
@@ -40,6 +41,13 @@ __all__ = (
     'get_plugin_loader',
     'PLUGIN_NAMESPACE',
 
+    # loading.identity
+    'BaseIdentityLoader',
+    'BaseV2Loader',
+    'BaseV3Loader',
+    'BaseFederationLoader',
+    'BaseGenericLoader',
+
     # auth cli
     'register_auth_argparse_arguments',
     'load_auth_from_argparse_arguments',

keystoneauth1/loading/_plugins/identity/base.py

@@ -1,27 +0,0 @@
-# Licensed under the Apache License, Version 2.0 (the "License"); you may
-# not use this file except in compliance with the License. You may obtain
-# a copy of the License at
-#
-#      http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-# License for the specific language governing permissions and limitations
-# under the License.
-
-from keystoneauth1 import loading
-
-
-class BaseIdentityLoader(loading.BaseLoader):
-
-    def get_options(self):
-        options = super(BaseIdentityLoader, self).get_options()
-
-        options.extend([
-            loading.Opt('auth-url',
-                        required=True,
-                        help='Authentication URL'),
-        ])
-
-        return options

keystoneauth1/loading/_plugins/identity/generic.py

@@ -12,32 +12,9 @@
 
 from keystoneauth1 import identity
 from keystoneauth1 import loading
-from keystoneauth1.loading._plugins.identity import base
 
 
-class GenericBaseLoader(base.BaseIdentityLoader):
+class Token(loading.BaseGenericLoader):
-
-    def get_options(self):
-        options = super(GenericBaseLoader, self).get_options()
-
-        options.extend([
-            loading.Opt('domain-id', help='Domain ID to scope to'),
-            loading.Opt('domain-name', help='Domain name to scope to'),
-            loading.Opt('project-id', help='Project ID to scope to',
-                        deprecated=[loading.Opt('tenant-id')]),
-            loading.Opt('project-name', help='Project name to scope to',
-                        deprecated=[loading.Opt('tenant-name')]),
-            loading.Opt('project-domain-id',
-                        help='Domain ID containing project'),
-            loading.Opt('project-domain-name',
-                        help='Domain name containing project'),
-            loading.Opt('trust-id', help='Trust ID'),
-        ])
-
-        return options
-
-
-class Token(GenericBaseLoader):
 
     @property
     def plugin_class(self):
@@ -53,7 +30,7 @@ class Token(GenericBaseLoader):
         return options
 
 
-class Password(GenericBaseLoader):
+class Password(loading.BaseGenericLoader):
 
     @property
     def plugin_class(self):

keystoneauth1/loading/_plugins/identity/v2.py

@@ -12,24 +12,9 @@
 
 from keystoneauth1 import identity
 from keystoneauth1 import loading
-from keystoneauth1.loading._plugins.identity import base
 
 
-class BaseV2Loader(base.BaseIdentityLoader):
+class Token(loading.BaseV2Loader):
-
-    def get_options(self):
-        options = super(BaseV2Loader, self).get_options()
-
-        options.extend([
-            loading.Opt('tenant-id', help='Tenant ID'),
-            loading.Opt('tenant-name', help='Tenant Name'),
-            loading.Opt('trust-id', help='Trust ID'),
-        ])
-
-        return options
-
-
-class Token(BaseV2Loader):
 
     @property
     def plugin_class(self):
@@ -45,7 +30,7 @@ class Token(BaseV2Loader):
         return options
 
 
-class Password(BaseV2Loader):
+class Password(loading.BaseV2Loader):
 
     @property
     def plugin_class(self):

keystoneauth1/loading/_plugins/identity/v3.py

@@ -13,42 +13,9 @@
 from keystoneauth1 import exceptions
 from keystoneauth1 import identity
 from keystoneauth1 import loading
-from keystoneauth1.loading._plugins.identity import base
 
 
-class BaseV3Loader(base.BaseIdentityLoader):
+class Password(loading.BaseV3Loader):
-
-    def get_options(self):
-        options = super(BaseV3Loader, self).get_options()
-
-        options.extend([
-            loading.Opt('domain-id', help='Domain ID to scope to'),
-            loading.Opt('domain-name', help='Domain name to scope to'),
-            loading.Opt('project-id', help='Project ID to scope to'),
-            loading.Opt('project-name', help='Project name to scope to'),
-            loading.Opt('project-domain-id',
-                        help='Domain ID containing project'),
-            loading.Opt('project-domain-name',
-                        help='Domain name containing project'),
-            loading.Opt('trust-id', help='Trust ID'),
-        ])
-
-        return options
-
-    def load_from_options(self, **kwargs):
-        if (kwargs.get('project_name') and
-                not (kwargs.get('project_domain_name') or
-                     kwargs.get('project_domain_id'))):
-            m = "You have provided a project_name. In the V3 identity API a " \
-                "project_name is only unique within a domain so you must " \
-                "also provide either a project_domain_id or " \
-                "project_domain_name."
-            raise exceptions.OptionError(m)
-
-        return super(BaseV3Loader, self).load_from_options(**kwargs)
-
-
-class Password(BaseV3Loader):
 
     @property
     def plugin_class(self):
@@ -82,7 +49,7 @@ class Password(BaseV3Loader):
         return super(Password, self).load_from_options(**kwargs)
 
 
-class Token(BaseV3Loader):
+class Token(loading.BaseV3Loader):
 
     @property
     def plugin_class(self):
@@ -100,22 +67,7 @@ class Token(BaseV3Loader):
         return options
 
 
-class FederatedBase(BaseV3Loader):
+class _OpenIDConnectBase(loading.BaseFederationLoader):
-
-    def get_options(self):
-        options = super(FederatedBase, self).get_options()
-
-        options.extend([
-            loading.Opt('identity-provider',
-                        help="Identity Provider's name"),
-            loading.Opt('protocol',
-                        help='Protocol for federated plugin'),
-        ])
-
-        return options
-
-
-class _OpenIDConnectBase(FederatedBase):
 
     def get_options(self):
         options = super(_OpenIDConnectBase, self).get_options()

keystoneauth1/loading/identity.py

@@ -0,0 +1,152 @@
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+from keystoneauth1 import exceptions
+from keystoneauth1.loading import base
+from keystoneauth1.loading import opts
+
+__all__ = ['BaseIdentityLoader',
+           'BaseV2Loader',
+           'BaseV3Loader',
+           'BaseFederationLoader',
+           'BaseGenericLoader']
+
+
+class BaseIdentityLoader(base.BaseLoader):
+    """Base Option handling for identity plugins.
+
+    This class defines options and handling that should be common across all
+    plugins that are developed against the OpenStack identity service. It
+    provides the options expected by the
+    :py:class:`keystoneauth1.identity.BaseIdentityPlugin` class.
+    """
+
+    def get_options(self):
+        options = super(BaseIdentityLoader, self).get_options()
+
+        options.extend([
+            opts.Opt('auth-url',
+                     required=True,
+                     help='Authentication URL'),
+        ])
+
+        return options
+
+
+class BaseV2Loader(BaseIdentityLoader):
+    """Base Option handling for identity plugins.
+
+    This class defines options and handling that should be common to the V2
+    identity API. It provides the options expected by the
+    :py:class:`keystoneauth1.identity.v2.Auth` class.
+    """
+
+    def get_options(self):
+        options = super(BaseV2Loader, self).get_options()
+
+        options.extend([
+            opts.Opt('tenant-id', help='Tenant ID'),
+            opts.Opt('tenant-name', help='Tenant Name'),
+            opts.Opt('trust-id', help='Trust ID'),
+        ])
+
+        return options
+
+
+class BaseV3Loader(BaseIdentityLoader):
+    """Base Option handling for identity plugins.
+
+    This class defines options and handling that should be common to the V3
+    identity API. It provides the options expected by the
+    :py:class:`keystoneauth1.identity.v3.Auth` class.
+    """
+
+    def get_options(self):
+        options = super(BaseV3Loader, self).get_options()
+
+        options.extend([
+            opts.Opt('domain-id', help='Domain ID to scope to'),
+            opts.Opt('domain-name', help='Domain name to scope to'),
+            opts.Opt('project-id', help='Project ID to scope to'),
+            opts.Opt('project-name', help='Project name to scope to'),
+            opts.Opt('project-domain-id',
+                     help='Domain ID containing project'),
+            opts.Opt('project-domain-name',
+                     help='Domain name containing project'),
+            opts.Opt('trust-id', help='Trust ID'),
+        ])
+
+        return options
+
+    def load_from_options(self, **kwargs):
+        if (kwargs.get('project_name') and
+                not (kwargs.get('project_domain_name') or
+                     kwargs.get('project_domain_id'))):
+            m = "You have provided a project_name. In the V3 identity API a " \
+                "project_name is only unique within a domain so you must " \
+                "also provide either a project_domain_id or " \
+                "project_domain_name."
+            raise exceptions.OptionError(m)
+
+        return super(BaseV3Loader, self).load_from_options(**kwargs)
+
+
+class BaseFederationLoader(BaseV3Loader):
+    """Base Option handling for federation plugins.
+
+    This class defines options and handling that should be common to the V3
+    identity federation API. It provides the options expected by the
+    :py:class:`keystoneauth1.identity.v3.FederationBaseAuth` class.
+    """
+
+    def get_options(self):
+        options = super(BaseFederationLoader, self).get_options()
+
+        options.extend([
+            opts.Opt('identity-provider',
+                     help="Identity Provider's name",
+                     required=True),
+            opts.Opt('protocol',
+                     help='Protocol for federated plugin',
+                     required=True),
+        ])
+
+        return options
+
+
+class BaseGenericLoader(BaseIdentityLoader):
+    """Base Option handling for generic plugins.
+
+    This class defines options and handling that should be common to generic
+    plugins. These plugins target the OpenStack identity service however are
+    designed to be independent of API version. It provides the options expected
+    by the :py:class:`keystoneauth1.identity.v3.BaseGenericPlugin` class.
+    """
+
+    def get_options(self):
+        options = super(BaseGenericLoader, self).get_options()
+
+        options.extend([
+            opts.Opt('domain-id', help='Domain ID to scope to'),
+            opts.Opt('domain-name', help='Domain name to scope to'),
+            opts.Opt('project-id', help='Project ID to scope to',
+                     deprecated=[opts.Opt('tenant-id')]),
+            opts.Opt('project-name', help='Project name to scope to',
+                     deprecated=[opts.Opt('tenant-name')]),
+            opts.Opt('project-domain-id',
+                     help='Domain ID containing project'),
+            opts.Opt('project-domain-name',
+                     help='Domain name containing project'),
+            opts.Opt('trust-id', help='Trust ID'),
+        ])
+
+        return options