From bb98d0182df9a1b6fb22fa96d31972b6222178c2 Mon Sep 17 00:00:00 2001 From: Jamie Lennox Date: Tue, 3 Nov 2015 11:49:52 +1100 Subject: [PATCH] Declare an extras directory for plugins Create an extras directory and add some explanatory documentation for dealing with plugins defined in extras. Change-Id: Ibdd6bc16f38d1b9ca38db775671876458ec60e7a --- doc/source/extras.rst | 24 ++++++++++++++++++++++++ doc/source/index.rst | 3 +++ keystoneauth1/extras/__init__.py | 20 ++++++++++++++++++++ 3 files changed, 47 insertions(+) create mode 100644 doc/source/extras.rst create mode 100644 keystoneauth1/extras/__init__.py diff --git a/doc/source/extras.rst b/doc/source/extras.rst new file mode 100644 index 00000000..0c6ef853 --- /dev/null +++ b/doc/source/extras.rst @@ -0,0 +1,24 @@ +====== +Extras +====== + +The extensibility of keystoneauth plugins is purposefully designed to allow a +range of different authentication mechanisms that don't have to reside in the +upstream packages. There are however a number of plugins that upstream supports +that involve additional dependencies that the keystoneauth package cannot +depend upon directly. + +To get around this we utilize setuptools `extras dependencies `_ for additional +plugins. To use a plugin like the kerberos plugin that has additional +dependencies you must install the additional dependencies like:: + + pip install keystoneauth1[kerberos] + +By convention (not a requirement) extra plugins have a module located in the +keystoneauth1.extras module with the same name as the dependency. eg:: + + $ from keystoneauth1.extras import kerberos + +There is no keystoneauth specific check that the correct dependencies are +installed for accessing a module. You would expect to see standard python +ImportError when the required dependencies are not found. diff --git a/doc/source/index.rst b/doc/source/index.rst index 09d9bbe2..24d9843a 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -13,6 +13,9 @@ Contents: using-sessions authentication-plugins + + extras + api/modules Release Notes diff --git a/keystoneauth1/extras/__init__.py b/keystoneauth1/extras/__init__.py new file mode 100644 index 00000000..fbcb3520 --- /dev/null +++ b/keystoneauth1/extras/__init__.py @@ -0,0 +1,20 @@ +# 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. + +# NOTE(jamielennox): This directory is designed to reflect the dependency +# extras in the setup.cfg file. If you create an additional dependency section +# like 'kerberos' in the setup.cfg it is expected that there be a kerberos +# package here that can be imported. +# +# e.g. from keystoneauth1.extras import kerberos + +pass