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
Jamie Lennox 2015-11-03 11:49:52 +11:00
parent 72f225eaf4
commit bb98d0182d
3 changed files with 47 additions and 0 deletions

doc/source/extras.rst Normal file
View File

@ -0,0 +1,24 @@
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.

View File

@ -13,6 +13,9 @@ Contents:
Release Notes

View File

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