diff --git a/openstack-common.conf b/openstack-common.conf index b6e6298..95f8e0a 100644 --- a/openstack-common.conf +++ b/openstack-common.conf @@ -1,6 +1,7 @@ [DEFAULT] # The list of modules to copy from oslo-incubator.git +module=gettextutils # The base module to hold the copy of openstack.common -base=os_cloud_config \ No newline at end of file +base=os_cloud_config diff --git a/os_cloud_config/exception.py b/os_cloud_config/exception.py new file mode 100644 index 0000000..36a0e08 --- /dev/null +++ b/os_cloud_config/exception.py @@ -0,0 +1,50 @@ +# -*- coding: utf-8 -*- + +# 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. + +import logging + +from os_cloud_config.openstack.common.gettextutils import _ + + +LOG = logging.getLogger(__name__) + + +class CloudConfigException(Exception): + """Base os-cloud-config exception + + To correctly use this class, inherit from it and define + a 'message' property. That message will get printf'd + with the keyword arguments provided to the constructor. + + """ + msg_fmt = _("An unknown exception occurred.") + + def __init__(self, message=None, **kwargs): + self.kwargs = kwargs + + if not message: + try: + message = self.msg_fmt % kwargs + + except Exception: + # kwargs doesn't match a variable in the message + # log the issue and the kwargs + LOG.exception('Exception in string format operation') + for name, value in kwargs.iteritems(): + LOG.error("%s: %s" % (name, value)) + + # at least get the core message out if something happened + message = self.msg_fmt + + super(CloudConfigException, self).__init__(message) diff --git a/os_cloud_config/keystone.py b/os_cloud_config/keystone.py new file mode 100644 index 0000000..ce84095 --- /dev/null +++ b/os_cloud_config/keystone.py @@ -0,0 +1,130 @@ +# -*- coding: utf-8 -*- + +# 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. + +import logging + +import keystoneclient.v3.client as ksclient + +LOG = logging.getLogger(__name__) + + +def initialize(host, admin_token, admin_email, admin_password): + """Perform post-heat initialization of Keystone. + + :param host: ip/hostname of node where Keystone is running + :param admin_token: admin token to use with Keystone's admin endpoint + :param admin_email: admin user's e-mail address to be set + :param admin_password: admin user's password to be set + """ + + keystone = _create_admin_client(host, admin_token) + + _create_roles(keystone) + _create_projects(keystone) + _create_admin_user(keystone, admin_email, admin_password) + + +def initialize_for_swift(host, admin_token): + """Create roles in Keystone for use with Swift. + + :param host: ip/hostname of node where Keystone is running + :param admin_token: admin token to use with Keystone's admin endpoint + """ + keystone = _create_admin_client(host, admin_token) + + LOG.debug('Creating swiftoperator role.') + keystone.roles.create('swiftoperator') + LOG.debug('Creating ResellerAdmin role.') + keystone.roles.create('ResellerAdmin') + + +def initialize_for_heat(host, admin_token, domain_admin_password): + """Create Heat domain and an admin user for it. + + :param host: ip/hostname of node where Keystone is running + :param admin_token: admin token to use with Keystone's admin endpoint + :param domain_admin_password: heat domain admin's password to be set + """ + keystone = _create_admin_client(host, admin_token) + admin_role = keystone.roles.find(name='admin') + + LOG.debug('Creating heat domain.') + heat_domain = keystone.domains.create( + 'heat', + description='Owns users and projects created by heat' + ) + LOG.debug('Creating heat_domain_admin user.') + heat_admin = keystone.users.create( + 'heat_domain_admin', + description='Manages users and projects created by heat', + domain=heat_domain, + password=domain_admin_password, + ) + LOG.debug('Granting admin role to heat_domain_admin user on heat domain.') + keystone.roles.grant(admin_role, + user=heat_admin, + domain=heat_domain) + + +def _create_admin_client(host, admin_token): + """Create Keystone v3 client for admin endpoint. + + :param host: ip/hostname of node where Keystone is running + :param admin_token: admin token to use with Keystone's admin endpoint + """ + admin_url = "http://%s:35357/v3" % host + return ksclient.Client(endpoint=admin_url, token=admin_token) + + +def _create_roles(keystone): + """Create initial roles in Keystone. + + :param keystone: keystone v3 client + """ + LOG.debug('Creating admin role.') + keystone.roles.create('admin') + LOG.debug('Creating Member role.') + keystone.roles.create('Member') + + +def _create_projects(keystone): + """Create initial projects in Keystone. + + :param keystone: keystone v3 client + """ + LOG.debug('Creating admin project.') + keystone.projects.create('admin', None) + LOG.debug('Creating service project.') + keystone.projects.create('service', None) + + +def _create_admin_user(keystone, admin_email, admin_password): + """Create admin user in Keystone. + + :param keystone: keystone v3 client + :param admin_email: admin user's e-mail address to be set + :param admin_password: admin user's password to be set + """ + admin_project = keystone.projects.find(name='admin') + admin_role = keystone.roles.find(name='admin') + + LOG.debug('Creating admin user.') + admin_user = keystone.users.create('admin', + email=admin_email, + password=admin_password, + project=admin_project) + LOG.debug('Granting admin role to admin user on admin project.') + keystone.roles.grant(admin_role, + user=admin_user, + project=admin_project) diff --git a/os_cloud_config/openstack/__init__.py b/os_cloud_config/openstack/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/os_cloud_config/openstack/common/__init__.py b/os_cloud_config/openstack/common/__init__.py new file mode 100644 index 0000000..2a00f3b --- /dev/null +++ b/os_cloud_config/openstack/common/__init__.py @@ -0,0 +1,2 @@ +import six +six.add_move(six.MovedModule('mox', 'mox', 'mox3.mox')) diff --git a/os_cloud_config/openstack/common/gettextutils.py b/os_cloud_config/openstack/common/gettextutils.py new file mode 100644 index 0000000..af9dea3 --- /dev/null +++ b/os_cloud_config/openstack/common/gettextutils.py @@ -0,0 +1,474 @@ +# Copyright 2012 Red Hat, Inc. +# Copyright 2013 IBM Corp. +# All Rights Reserved. +# +# 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. + +""" +gettext for openstack-common modules. + +Usual usage in an openstack.common module: + + from os_cloud_config.openstack.common.gettextutils import _ +""" + +import copy +import functools +import gettext +import locale +from logging import handlers +import os +import re + +from babel import localedata +import six + +_localedir = os.environ.get('os_cloud_config'.upper() + '_LOCALEDIR') +_t = gettext.translation('os_cloud_config', localedir=_localedir, fallback=True) + +# We use separate translation catalogs for each log level, so set up a +# mapping between the log level name and the translator. The domain +# for the log level is project_name + "-log-" + log_level so messages +# for each level end up in their own catalog. +_t_log_levels = dict( + (level, gettext.translation('os_cloud_config' + '-log-' + level, + localedir=_localedir, + fallback=True)) + for level in ['info', 'warning', 'error', 'critical'] +) + +_AVAILABLE_LANGUAGES = {} +USE_LAZY = False + + +def enable_lazy(): + """Convenience function for configuring _() to use lazy gettext + + Call this at the start of execution to enable the gettextutils._ + function to use lazy gettext functionality. This is useful if + your project is importing _ directly instead of using the + gettextutils.install() way of importing the _ function. + """ + global USE_LAZY + USE_LAZY = True + + +def _(msg): + if USE_LAZY: + return Message(msg, domain='os_cloud_config') + else: + if six.PY3: + return _t.gettext(msg) + return _t.ugettext(msg) + + +def _log_translation(msg, level): + """Build a single translation of a log message + """ + if USE_LAZY: + return Message(msg, domain='os_cloud_config' + '-log-' + level) + else: + translator = _t_log_levels[level] + if six.PY3: + return translator.gettext(msg) + return translator.ugettext(msg) + +# Translators for log levels. +# +# The abbreviated names are meant to reflect the usual use of a short +# name like '_'. The "L" is for "log" and the other letter comes from +# the level. +_LI = functools.partial(_log_translation, level='info') +_LW = functools.partial(_log_translation, level='warning') +_LE = functools.partial(_log_translation, level='error') +_LC = functools.partial(_log_translation, level='critical') + + +def install(domain, lazy=False): + """Install a _() function using the given translation domain. + + Given a translation domain, install a _() function using gettext's + install() function. + + The main difference from gettext.install() is that we allow + overriding the default localedir (e.g. /usr/share/locale) using + a translation-domain-specific environment variable (e.g. + NOVA_LOCALEDIR). + + :param domain: the translation domain + :param lazy: indicates whether or not to install the lazy _() function. + The lazy _() introduces a way to do deferred translation + of messages by installing a _ that builds Message objects, + instead of strings, which can then be lazily translated into + any available locale. + """ + if lazy: + # NOTE(mrodden): Lazy gettext functionality. + # + # The following introduces a deferred way to do translations on + # messages in OpenStack. We override the standard _() function + # and % (format string) operation to build Message objects that can + # later be translated when we have more information. + def _lazy_gettext(msg): + """Create and return a Message object. + + Lazy gettext function for a given domain, it is a factory method + for a project/module to get a lazy gettext function for its own + translation domain (i.e. nova, glance, cinder, etc.) + + Message encapsulates a string so that we can translate + it later when needed. + """ + return Message(msg, domain=domain) + + from six import moves + moves.builtins.__dict__['_'] = _lazy_gettext + else: + localedir = '%s_LOCALEDIR' % domain.upper() + if six.PY3: + gettext.install(domain, + localedir=os.environ.get(localedir)) + else: + gettext.install(domain, + localedir=os.environ.get(localedir), + unicode=True) + + +class Message(six.text_type): + """A Message object is a unicode object that can be translated. + + Translation of Message is done explicitly using the translate() method. + For all non-translation intents and purposes, a Message is simply unicode, + and can be treated as such. + """ + + def __new__(cls, msgid, msgtext=None, params=None, + domain='os_cloud_config', *args): + """Create a new Message object. + + In order for translation to work gettext requires a message ID, this + msgid will be used as the base unicode text. It is also possible + for the msgid and the base unicode text to be different by passing + the msgtext parameter. + """ + # If the base msgtext is not given, we use the default translation + # of the msgid (which is in English) just in case the system locale is + # not English, so that the base text will be in that locale by default. + if not msgtext: + msgtext = Message._translate_msgid(msgid, domain) + # We want to initialize the parent unicode with the actual object that + # would have been plain unicode if 'Message' was not enabled. + msg = super(Message, cls).__new__(cls, msgtext) + msg.msgid = msgid + msg.domain = domain + msg.params = params + return msg + + def translate(self, desired_locale=None): + """Translate this message to the desired locale. + + :param desired_locale: The desired locale to translate the message to, + if no locale is provided the message will be + translated to the system's default locale. + + :returns: the translated message in unicode + """ + + translated_message = Message._translate_msgid(self.msgid, + self.domain, + desired_locale) + if self.params is None: + # No need for more translation + return translated_message + + # This Message object may have been formatted with one or more + # Message objects as substitution arguments, given either as a single + # argument, part of a tuple, or as one or more values in a dictionary. + # When translating this Message we need to translate those Messages too + translated_params = _translate_args(self.params, desired_locale) + + translated_message = translated_message % translated_params + + return translated_message + + @staticmethod + def _translate_msgid(msgid, domain, desired_locale=None): + if not desired_locale: + system_locale = locale.getdefaultlocale() + # If the system locale is not available to the runtime use English + if not system_locale[0]: + desired_locale = 'en_US' + else: + desired_locale = system_locale[0] + + locale_dir = os.environ.get(domain.upper() + '_LOCALEDIR') + lang = gettext.translation(domain, + localedir=locale_dir, + languages=[desired_locale], + fallback=True) + if six.PY3: + translator = lang.gettext + else: + translator = lang.ugettext + + translated_message = translator(msgid) + return translated_message + + def __mod__(self, other): + # When we mod a Message we want the actual operation to be performed + # by the parent class (i.e. unicode()), the only thing we do here is + # save the original msgid and the parameters in case of a translation + params = self._sanitize_mod_params(other) + unicode_mod = super(Message, self).__mod__(params) + modded = Message(self.msgid, + msgtext=unicode_mod, + params=params, + domain=self.domain) + return modded + + def _sanitize_mod_params(self, other): + """Sanitize the object being modded with this Message. + + - Add support for modding 'None' so translation supports it + - Trim the modded object, which can be a large dictionary, to only + those keys that would actually be used in a translation + - Snapshot the object being modded, in case the message is + translated, it will be used as it was when the Message was created + """ + if other is None: + params = (other,) + elif isinstance(other, dict): + params = self._trim_dictionary_parameters(other) + else: + params = self._copy_param(other) + return params + + def _trim_dictionary_parameters(self, dict_param): + """Return a dict that only has matching entries in the msgid.""" + # NOTE(luisg): Here we trim down the dictionary passed as parameters + # to avoid carrying a lot of unnecessary weight around in the message + # object, for example if someone passes in Message() % locals() but + # only some params are used, and additionally we prevent errors for + # non-deepcopyable objects by unicoding() them. + + # Look for %(param) keys in msgid; + # Skip %% and deal with the case where % is first character on the line + keys = re.findall('(?:[^%]|^)?%\((\w*)\)[a-z]', self.msgid) + + # If we don't find any %(param) keys but have a %s + if not keys and re.findall('(?:[^%]|^)%[a-z]', self.msgid): + # Apparently the full dictionary is the parameter + params = self._copy_param(dict_param) + else: + params = {} + # Save our existing parameters as defaults to protect + # ourselves from losing values if we are called through an + # (erroneous) chain that builds a valid Message with + # arguments, and then does something like "msg % kwds" + # where kwds is an empty dictionary. + src = {} + if isinstance(self.params, dict): + src.update(self.params) + src.update(dict_param) + for key in keys: + params[key] = self._copy_param(src[key]) + + return params + + def _copy_param(self, param): + try: + return copy.deepcopy(param) + except TypeError: + # Fallback to casting to unicode this will handle the + # python code-like objects that can't be deep-copied + return six.text_type(param) + + def __add__(self, other): + msg = _('Message objects do not support addition.') + raise TypeError(msg) + + def __radd__(self, other): + return self.__add__(other) + + def __str__(self): + # NOTE(luisg): Logging in python 2.6 tries to str() log records, + # and it expects specifically a UnicodeError in order to proceed. + msg = _('Message objects do not support str() because they may ' + 'contain non-ascii characters. ' + 'Please use unicode() or translate() instead.') + raise UnicodeError(msg) + + +def get_available_languages(domain): + """Lists the available languages for the given translation domain. + + :param domain: the domain to get languages for + """ + if domain in _AVAILABLE_LANGUAGES: + return copy.copy(_AVAILABLE_LANGUAGES[domain]) + + localedir = '%s_LOCALEDIR' % domain.upper() + find = lambda x: gettext.find(domain, + localedir=os.environ.get(localedir), + languages=[x]) + + # NOTE(mrodden): en_US should always be available (and first in case + # order matters) since our in-line message strings are en_US + language_list = ['en_US'] + # NOTE(luisg): Babel <1.0 used a function called list(), which was + # renamed to locale_identifiers() in >=1.0, the requirements master list + # requires >=0.9.6, uncapped, so defensively work with both. We can remove + # this check when the master list updates to >=1.0, and update all projects + list_identifiers = (getattr(localedata, 'list', None) or + getattr(localedata, 'locale_identifiers')) + locale_identifiers = list_identifiers() + + for i in locale_identifiers: + if find(i) is not None: + language_list.append(i) + + # NOTE(luisg): Babel>=1.0,<1.3 has a bug where some OpenStack supported + # locales (e.g. 'zh_CN', and 'zh_TW') aren't supported even though they + # are perfectly legitimate locales: + # https://github.com/mitsuhiko/babel/issues/37 + # In Babel 1.3 they fixed the bug and they support these locales, but + # they are still not explicitly "listed" by locale_identifiers(). + # That is why we add the locales here explicitly if necessary so that + # they are listed as supported. + aliases = {'zh': 'zh_CN', + 'zh_Hant_HK': 'zh_HK', + 'zh_Hant': 'zh_TW', + 'fil': 'tl_PH'} + for (locale, alias) in six.iteritems(aliases): + if locale in language_list and alias not in language_list: + language_list.append(alias) + + _AVAILABLE_LANGUAGES[domain] = language_list + return copy.copy(language_list) + + +def translate(obj, desired_locale=None): + """Gets the translated unicode representation of the given object. + + If the object is not translatable it is returned as-is. + If the locale is None the object is translated to the system locale. + + :param obj: the object to translate + :param desired_locale: the locale to translate the message to, if None the + default system locale will be used + :returns: the translated object in unicode, or the original object if + it could not be translated + """ + message = obj + if not isinstance(message, Message): + # If the object to translate is not already translatable, + # let's first get its unicode representation + message = six.text_type(obj) + if isinstance(message, Message): + # Even after unicoding() we still need to check if we are + # running with translatable unicode before translating + return message.translate(desired_locale) + return obj + + +def _translate_args(args, desired_locale=None): + """Translates all the translatable elements of the given arguments object. + + This method is used for translating the translatable values in method + arguments which include values of tuples or dictionaries. + If the object is not a tuple or a dictionary the object itself is + translated if it is translatable. + + If the locale is None the object is translated to the system locale. + + :param args: the args to translate + :param desired_locale: the locale to translate the args to, if None the + default system locale will be used + :returns: a new args object with the translated contents of the original + """ + if isinstance(args, tuple): + return tuple(translate(v, desired_locale) for v in args) + if isinstance(args, dict): + translated_dict = {} + for (k, v) in six.iteritems(args): + translated_v = translate(v, desired_locale) + translated_dict[k] = translated_v + return translated_dict + return translate(args, desired_locale) + + +class TranslationHandler(handlers.MemoryHandler): + """Handler that translates records before logging them. + + The TranslationHandler takes a locale and a target logging.Handler object + to forward LogRecord objects to after translating them. This handler + depends on Message objects being logged, instead of regular strings. + + The handler can be configured declaratively in the logging.conf as follows: + + [handlers] + keys = translatedlog, translator + + [handler_translatedlog] + class = handlers.WatchedFileHandler + args = ('/var/log/api-localized.log',) + formatter = context + + [handler_translator] + class = openstack.common.log.TranslationHandler + target = translatedlog + args = ('zh_CN',) + + If the specified locale is not available in the system, the handler will + log in the default locale. + """ + + def __init__(self, locale=None, target=None): + """Initialize a TranslationHandler + + :param locale: locale to use for translating messages + :param target: logging.Handler object to forward + LogRecord objects to after translation + """ + # NOTE(luisg): In order to allow this handler to be a wrapper for + # other handlers, such as a FileHandler, and still be able to + # configure it using logging.conf, this handler has to extend + # MemoryHandler because only the MemoryHandlers' logging.conf + # parsing is implemented such that it accepts a target handler. + handlers.MemoryHandler.__init__(self, capacity=0, target=target) + self.locale = locale + + def setFormatter(self, fmt): + self.target.setFormatter(fmt) + + def emit(self, record): + # We save the message from the original record to restore it + # after translation, so other handlers are not affected by this + original_msg = record.msg + original_args = record.args + + try: + self._translate_and_log_record(record) + finally: + record.msg = original_msg + record.args = original_args + + def _translate_and_log_record(self, record): + record.msg = translate(record.msg, self.locale) + + # In addition to translating the message, we also need to translate + # arguments that were passed to the log method that were not part + # of the main message e.g., log.info(_('Some message %s'), this_one)) + record.args = _translate_args(record.args, self.locale) + + self.target.emit(record) diff --git a/os_cloud_config/tests/test_keystone.py b/os_cloud_config/tests/test_keystone.py new file mode 100644 index 0000000..2ccd33d --- /dev/null +++ b/os_cloud_config/tests/test_keystone.py @@ -0,0 +1,90 @@ +# -*- coding: utf-8 -*- + +# 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. + +import mock + +from os_cloud_config import keystone +from os_cloud_config.tests import base + + +class KeystoneTest(base.TestCase): + + def test_initialize(self): + self._patch_client() + + keystone.initialize( + '192.0.0.3', 'mytoken', 'admin@example.org', 'adminpasswd') + + self.client.roles.create.assert_has_calls( + [mock.call('admin'), mock.call('Member')]) + + self.client.projects.create.assert_has_calls( + [mock.call('admin', None), mock.call('service', None)]) + + self.client.projects.find.assert_called_once_with(name='admin') + self.client.users.create.assert_called_once_with( + 'admin', email='admin@example.org', password='adminpasswd', + project=self.client.projects.find.return_value) + + self.client.roles.find.assert_called_once_with(name='admin') + self.client.roles.grant.assert_called_once_with( + self.client.roles.find.return_value, + user=self.client.users.create.return_value, + project=self.client.projects.find.return_value) + + def test_initialize_for_swift(self): + self._patch_client() + + keystone.initialize_for_swift('192.0.0.3', 'mytoken') + + self.client.roles.create.assert_has_calls( + [mock.call('swiftoperator'), mock.call('ResellerAdmin')]) + + def test_initialize_for_heat(self): + self._patch_client() + + keystone.initialize_for_heat('192.0.0.3', 'mytoken', 'heatadminpasswd') + + self.client.domains.create.assert_called_once_with( + 'heat', description='Owns users and projects created by heat') + self.client.users.create.assert_called_once_with( + 'heat_domain_admin', + description='Manages users and projects created by heat', + domain=self.client.domains.create.return_value, + password='heatadminpasswd') + self.client.roles.find.assert_called_once_with(name='admin') + self.client.roles.grant.assert_called_once_with( + self.client.roles.find.return_value, + user=self.client.users.create.return_value, + domain=self.client.domains.create.return_value) + + @mock.patch('os_cloud_config.keystone.ksclient.Client') + def test_create_admin_client(self, client): + self.assertEqual( + client.return_value, + keystone._create_admin_client('192.0.0.3', 'mytoken')) + client.assert_called_once_with(endpoint='http://192.0.0.3:35357/v3', + token='mytoken') + + def _patch_client(self): + self.client = mock.MagicMock() + self.create_admin_client_patcher = mock.patch( + 'os_cloud_config.keystone._create_admin_client') + create_admin_client = self.create_admin_client_patcher.start() + self.addCleanup(self._patch_client_cleanup) + create_admin_client.return_value = self.client + + def _patch_client_cleanup(self): + self.create_admin_client_patcher.stop() + self.client = None diff --git a/requirements.txt b/requirements.txt index aedc312..feb6427 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,2 +1,5 @@ pbr>=0.6,<1.0 + Babel>=1.3 +python-keystoneclient>=0.6.0 +oslo.config>=1.2.0 diff --git a/test-requirements.txt b/test-requirements.txt index ee8be1c..d544bb7 100644 --- a/test-requirements.txt +++ b/test-requirements.txt @@ -3,6 +3,7 @@ hacking>=0.8.0,<0.9 coverage>=3.6 discover fixtures>=0.3.14 +mock>=1.0 python-subunit>=0.0.18 sphinx>=1.1.2,<1.2 oslo.sphinx