From 490466b2a211db21b97cc9fced38ee19f9e7056e Mon Sep 17 00:00:00 2001 From: Doug Hellmann Date: Fri, 27 Jun 2014 12:26:57 -0700 Subject: [PATCH] Shift public API to top level package Rather than forcing everyone to say "from oslo.i18n import gettextutils" allow "from oslo import i18n". Change-Id: If87182beb8c7fa6a12f7a1524fdda4910b4e19d5 --- doc/source/api.rst | 14 +++--- doc/source/guidelines.rst | 2 +- doc/source/usage.rst | 22 +++++----- oslo/i18n/__init__.py | 16 +++++++ oslo/i18n/_factory.py | 5 +++ .../{gettextutils.py => _gettextutils.py} | 12 ++--- oslo/i18n/_lazy.py | 4 ++ oslo/i18n/_translate.py | 4 ++ tests/test_factory.py | 28 ++++++------ tests/test_gettextutils.py | 32 +++++++------- tests/test_lazy.py | 5 +-- tests/test_logging.py | 6 +-- tests/test_public_api.py | 44 +++++++++++++++++++ tox.ini | 2 +- 14 files changed, 136 insertions(+), 60 deletions(-) rename oslo/i18n/{gettextutils.py => _gettextutils.py} (92%) create mode 100644 tests/test_public_api.py diff --git a/doc/source/api.rst b/doc/source/api.rst index 480a772..441cde4 100644 --- a/doc/source/api.rst +++ b/doc/source/api.rst @@ -2,12 +2,12 @@ API ===== -oslo.i18n.gettextutils -====================== +oslo.i18n +========= -.. automodule:: oslo.i18n.gettextutils +.. automodule:: oslo.i18n -.. autoclass:: oslo.i18n.gettextutils.TranslatorFactory +.. autoclass:: oslo.i18n.TranslatorFactory :members: .. seealso:: @@ -15,15 +15,15 @@ oslo.i18n.gettextutils An example of using a :class:`TranslatorFactory` is provided in :ref:`integration-module`. -.. autofunction:: oslo.i18n.gettextutils.enable_lazy +.. autofunction:: oslo.i18n.enable_lazy .. seealso:: :ref:`lazy-translation` -.. autofunction:: oslo.i18n.gettextutils.translate +.. autofunction:: oslo.i18n.translate -.. autofunction:: oslo.i18n.gettextutils.get_available_languages +.. autofunction:: oslo.i18n.get_available_languages oslo.i18n.log ============= diff --git a/doc/source/guidelines.rst b/doc/source/guidelines.rst index 18dbe3c..36627d3 100644 --- a/doc/source/guidelines.rst +++ b/doc/source/guidelines.rst @@ -4,7 +4,7 @@ Text messages the user sees via exceptions or API calls should be translated using -:py:attr:`TranslatorFactory.primary `, which should +:py:attr:`TranslatorFactory.primary `, which should be installed as ``_()`` in the integration module. .. seealso:: diff --git a/doc/source/usage.rst b/doc/source/usage.rst index 89f054f..4d7964c 100644 --- a/doc/source/usage.rst +++ b/doc/source/usage.rst @@ -16,14 +16,14 @@ Creating an Integration Module To use oslo.i18n in a project, you will need to create a small integration module to hold an instance of -:class:`~oslo.i18n.gettextutils.TranslatorFactory` and references to +:class:`~oslo.i18n.TranslatorFactory` and references to the marker functions the factory creates. :: - from oslo.i18n import gettextutils + from oslo import i18n - _translators = gettextutils.TranslatorFactory(domain='myapp') + _translators = i18n.TranslatorFactory(domain='myapp') # The primary translation function using the well-known name "_" _ = _translators.primary @@ -85,14 +85,14 @@ To enable lazy translation, call :func:`enable_lazy`. :: - from oslo.i18n import gettextutils + from oslo import i18n - gettextutils.enable_lazy() + i18n.enable_lazy() Translating Messages ==================== -Use :func:`~oslo.i18n.gettextutils.translate` to translate strings to +Use :func:`~oslo.i18n.translate` to translate strings to a specific locale. :func:`translate` handles delayed translation and strings that have already been translated immediately. It should be used at the point where the locale to be used is known, which is often @@ -101,9 +101,9 @@ emitted. :: - from oslo.i18n import gettextutils + from oslo import i18n - trans_msg = gettextutils.translate(msg, desired_locale=my_locale) + trans_msg = i18n.translate(msg, desired_locale=my_locale) if desired_locale is not specified then the default locale is used. @@ -112,14 +112,14 @@ Available Languages Only the languages that have translations provided are available for translation. To determine which languages are available the -:func:`~oslo.i18n.gettextutils.get_available_languages` is provided. Since different languages +:func:`~oslo.i18n.get_available_languages` is provided. Since different languages can be installed for each domain, the domain must be specified. :: - from oslo.i18n import gettextutils + from oslo import i18n - avail_lang = gettextutils.get_available_languages('myapp') + avail_lang = i18n.get_available_languages('myapp') .. seealso:: diff --git a/oslo/i18n/__init__.py b/oslo/i18n/__init__.py index e69de29..4602749 100644 --- a/oslo/i18n/__init__.py +++ b/oslo/i18n/__init__.py @@ -0,0 +1,16 @@ +# 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 ._factory import * +from ._gettextutils import * +from ._lazy import * +from ._translate import * diff --git a/oslo/i18n/_factory.py b/oslo/i18n/_factory.py index 9390098..c7a7217 100644 --- a/oslo/i18n/_factory.py +++ b/oslo/i18n/_factory.py @@ -26,6 +26,11 @@ from oslo.i18n import _locale from oslo.i18n import _message +__all__ = [ + 'TranslatorFactory', +] + + class TranslatorFactory(object): "Create translator functions" diff --git a/oslo/i18n/gettextutils.py b/oslo/i18n/_gettextutils.py similarity index 92% rename from oslo/i18n/gettextutils.py rename to oslo/i18n/_gettextutils.py index 97900a6..d7ddeb5 100644 --- a/oslo/i18n/gettextutils.py +++ b/oslo/i18n/_gettextutils.py @@ -24,11 +24,13 @@ import os from babel import localedata import six -# Expose a few internal pieces as part of our public API. -from oslo.i18n._factory import TranslatorFactory # noqa -from oslo.i18n._lazy import enable_lazy # noqa +from oslo.i18n import _factory from oslo.i18n import _locale -from oslo.i18n._translate import translate # noqa + +__all__ = [ + 'install', + 'get_available_languages', +] def install(domain): @@ -50,7 +52,7 @@ def install(domain): any available locale. """ from six import moves - tf = TranslatorFactory(domain) + tf = _factory.TranslatorFactory(domain) moves.builtins.__dict__['_'] = tf.primary diff --git a/oslo/i18n/_lazy.py b/oslo/i18n/_lazy.py index f7e0398..82de17d 100644 --- a/oslo/i18n/_lazy.py +++ b/oslo/i18n/_lazy.py @@ -14,6 +14,10 @@ # License for the specific language governing permissions and limitations # under the License. +__all__ = [ + 'enable_lazy', +] + USE_LAZY = False diff --git a/oslo/i18n/_translate.py b/oslo/i18n/_translate.py index 037651a..4b25b71 100644 --- a/oslo/i18n/_translate.py +++ b/oslo/i18n/_translate.py @@ -16,6 +16,10 @@ import six +__all__ = [ + 'translate', +] + def translate(obj, desired_locale=None): """Gets the translated unicode representation of the given object. diff --git a/tests/test_factory.py b/tests/test_factory.py index 4bdef17..762f1a3 100644 --- a/tests/test_factory.py +++ b/tests/test_factory.py @@ -18,9 +18,9 @@ import mock from oslotest import base as test_base import six +from oslo.i18n import _factory from oslo.i18n import _lazy from oslo.i18n import _message -from oslo.i18n import gettextutils class TranslatorFactoryTest(test_base.BaseTestCase): @@ -36,56 +36,56 @@ class TranslatorFactoryTest(test_base.BaseTestCase): super(TranslatorFactoryTest, self).tearDown() def test_lazy(self): - gettextutils.enable_lazy(True) + _lazy.enable_lazy(True) with mock.patch.object(_message, 'Message') as msg: - tf = gettextutils.TranslatorFactory('domain') + tf = _factory.TranslatorFactory('domain') tf.primary('some text') msg.assert_called_with('some text', domain='domain') def test_not_lazy(self): - gettextutils.enable_lazy(False) + _lazy.enable_lazy(False) with mock.patch.object(_message, 'Message') as msg: msg.side_effect = AssertionError('should not use Message') - tf = gettextutils.TranslatorFactory('domain') + tf = _factory.TranslatorFactory('domain') tf.primary('some text') def test_change_lazy(self): - gettextutils.enable_lazy(True) - tf = gettextutils.TranslatorFactory('domain') + _lazy.enable_lazy(True) + tf = _factory.TranslatorFactory('domain') r = tf.primary('some text') self.assertIsInstance(r, _message.Message) - gettextutils.enable_lazy(False) + _lazy.enable_lazy(False) r = tf.primary('some text') # Python 2.6 doesn't have assertNotIsInstance(). self.assertFalse(isinstance(r, _message.Message)) def test_py2(self): - gettextutils.enable_lazy(False) + _lazy.enable_lazy(False) with mock.patch.object(six, 'PY3', False): with mock.patch('gettext.translation') as translation: trans = mock.Mock() translation.return_value = trans trans.gettext.side_effect = AssertionError( 'should have called ugettext') - tf = gettextutils.TranslatorFactory('domain') + tf = _factory.TranslatorFactory('domain') tf.primary('some text') trans.ugettext.assert_called_with('some text') def test_py3(self): - gettextutils.enable_lazy(False) + _lazy.enable_lazy(False) with mock.patch.object(six, 'PY3', True): with mock.patch('gettext.translation') as translation: trans = mock.Mock() translation.return_value = trans trans.ugettext.side_effect = AssertionError( 'should have called gettext') - tf = gettextutils.TranslatorFactory('domain') + tf = _factory.TranslatorFactory('domain') tf.primary('some text') trans.gettext.assert_called_with('some text') def test_log_level_domain_name(self): - with mock.patch.object(gettextutils.TranslatorFactory, + with mock.patch.object(_factory.TranslatorFactory, '_make_translation_func') as mtf: - tf = gettextutils.TranslatorFactory('domain') + tf = _factory.TranslatorFactory('domain') tf._make_log_translation_func('mylevel') mtf.assert_called_with('domain-log-mylevel') diff --git a/tests/test_gettextutils.py b/tests/test_gettextutils.py index 49996ed..11759a2 100644 --- a/tests/test_gettextutils.py +++ b/tests/test_gettextutils.py @@ -23,9 +23,10 @@ from oslotest import base as test_base from oslotest import moxstubout import six +from oslo.i18n import _factory +from oslo.i18n import _gettextutils from oslo.i18n import _lazy from oslo.i18n import _message -from oslo.i18n import gettextutils LOG = logging.getLogger(__name__) @@ -40,7 +41,7 @@ class GettextTest(test_base.BaseTestCase): self.mox = moxfixture.mox # remember so we can reset to it later in case it changes self._USE_LAZY = _lazy.USE_LAZY - self.t = gettextutils.TranslatorFactory('oslo.i18n.test') + self.t = _factory.TranslatorFactory('oslo.i18n.test') def tearDown(self): # reset to value before test @@ -50,14 +51,14 @@ class GettextTest(test_base.BaseTestCase): def test_gettext_does_not_blow_up(self): LOG.info(self.t.primary('test')) - def test_gettextutils_install(self): - gettextutils.install('blaa') - gettextutils.enable_lazy(False) + def test__gettextutils_install(self): + _gettextutils.install('blaa') + _lazy.enable_lazy(False) self.assertTrue(isinstance(self.t.primary('A String'), six.text_type)) - gettextutils.install('blaa') - gettextutils.enable_lazy(True) + _gettextutils.install('blaa') + _lazy.enable_lazy(True) self.assertTrue(isinstance(self.t.primary('A Message'), _message.Message)) @@ -65,7 +66,7 @@ class GettextTest(test_base.BaseTestCase): with mock.patch('os.environ.get') as environ_get: with mock.patch('gettext.install'): environ_get.return_value = '/foo/bar' - gettextutils.install('blaa') + _gettextutils.install('blaa') environ_get.assert_calls([mock.call('BLAA_LOCALEDIR')]) def test_gettext_install_updates_builtins(self): @@ -74,14 +75,15 @@ class GettextTest(test_base.BaseTestCase): environ_get.return_value = '/foo/bar' if '_' in six.moves.builtins.__dict__: del six.moves.builtins.__dict__['_'] - gettextutils.install('blaa') + _gettextutils.install('blaa') self.assertIn('_', six.moves.builtins.__dict__) def test_get_available_languages(self): # All the available languages for which locale data is available def _mock_locale_identifiers(): - # 'zh', 'zh_Hant'. 'zh_Hant_HK', 'fil' all have aliases missing - # from babel but we add them in gettextutils, we test that here too + # 'zh', 'zh_Hant'. 'zh_Hant_HK', 'fil' all have aliases + # missing from babel but we add them in _gettextutils, we + # test that here too return ['zh', 'es', 'nl', 'fr', 'zh_Hant', 'zh_Hant_HK', 'fil'] self.stubs.Set(localedata, @@ -102,8 +104,8 @@ class GettextTest(test_base.BaseTestCase): # en_US should always be available no matter the domain # and it should also always be the first element since order matters - domain_1_languages = gettextutils.get_available_languages('domain_1') - domain_2_languages = gettextutils.get_available_languages('domain_2') + domain_1_languages = _gettextutils.get_available_languages('domain_1') + domain_2_languages = _gettextutils.get_available_languages('domain_2') self.assertEqual('en_US', domain_1_languages[0]) self.assertEqual('en_US', domain_2_languages[0]) # The domain languages should be included after en_US with @@ -118,8 +120,8 @@ class GettextTest(test_base.BaseTestCase): self.assertIn('fr', domain_2_languages) self.assertIn('zh_Hant', domain_2_languages) self.assertIn('zh_TW', domain_2_languages) - self.assertEqual(2, len(gettextutils._AVAILABLE_LANGUAGES)) + self.assertEqual(2, len(_gettextutils._AVAILABLE_LANGUAGES)) # Now test an unknown domain, only en_US should be included - unknown_domain_languages = gettextutils.get_available_languages('huh') + unknown_domain_languages = _gettextutils.get_available_languages('huh') self.assertEqual(1, len(unknown_domain_languages)) self.assertIn('en_US', unknown_domain_languages) diff --git a/tests/test_lazy.py b/tests/test_lazy.py index 1183b8f..9e79bc4 100644 --- a/tests/test_lazy.py +++ b/tests/test_lazy.py @@ -17,7 +17,6 @@ from oslotest import base as test_base from oslo.i18n import _lazy -from oslo.i18n import gettextutils class LazyTest(test_base.BaseTestCase): @@ -32,10 +31,10 @@ class LazyTest(test_base.BaseTestCase): def test_enable_lazy(self): _lazy.USE_LAZY = False - gettextutils.enable_lazy() + _lazy.enable_lazy() self.assertTrue(_lazy.USE_LAZY) def test_disable_lazy(self): _lazy.USE_LAZY = True - gettextutils.enable_lazy(False) + _lazy.enable_lazy(False) self.assertFalse(_lazy.USE_LAZY) diff --git a/tests/test_logging.py b/tests/test_logging.py index f750488..a146709 100644 --- a/tests/test_logging.py +++ b/tests/test_logging.py @@ -17,7 +17,7 @@ import mock from oslotest import base as test_base -from oslo.i18n import gettextutils +from oslo.i18n import _factory class LogLevelTranslationsTest(test_base.BaseTestCase): @@ -35,8 +35,8 @@ class LogLevelTranslationsTest(test_base.BaseTestCase): self._test('critical') def _test(self, level): - with mock.patch.object(gettextutils.TranslatorFactory, + with mock.patch.object(_factory.TranslatorFactory, '_make_translation_func') as mtf: - tf = gettextutils.TranslatorFactory('domain') + tf = _factory.TranslatorFactory('domain') getattr(tf, 'log_%s' % level) mtf.assert_called_with('domain-log-%s' % level) diff --git a/tests/test_public_api.py b/tests/test_public_api.py new file mode 100644 index 0000000..b14c218 --- /dev/null +++ b/tests/test_public_api.py @@ -0,0 +1,44 @@ +# 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. +"""A few tests that use the public API to ensure the imports work. +""" + +import unittest + +import mock + +from oslo import i18n +from oslo.i18n import _lazy + + +class PublicAPITest(unittest.TestCase): + + def test_create_factory(self): + i18n.TranslatorFactory('domain') + + def test_install(self): + with mock.patch('six.moves.builtins'): + i18n.install('domain') + + def test_get_available_languages(self): + i18n.get_available_languages('domains') + + def test_toggle_lazy(self): + original = _lazy.USE_LAZY + try: + i18n.enable_lazy(True) + i18n.enable_lazy(False) + finally: + i18n.enable_lazy(original) + + def test_translate(self): + i18n.translate(u'string') diff --git a/tox.ini b/tox.ini index c969b2c..52ba80a 100644 --- a/tox.ini +++ b/tox.ini @@ -35,7 +35,7 @@ commands = python setup.py testr --coverage --testr-args='{posargs}' show-source = True ignore = E123,E125,H803 builtins = _ -exclude=.venv,.git,.tox,dist,doc,*openstack/common*,*lib/python*,*egg,build, +exclude=.venv,.git,.tox,dist,doc,*openstack/common*,*lib/python*,*egg,build,__init__.py [hacking] import_exceptions =