diff options
author | Doug Hellmann <doug.hellmann@dreamhost.com> | 2014-06-27 11:43:34 -0700 |
---|---|---|
committer | Doug Hellmann <doug@doughellmann.com> | 2014-08-23 15:03:16 -0400 |
commit | 688076eb6976d508997e10e22337cd4707303066 (patch) | |
tree | a42555041e57033ebfe08a26687737305ff5112f | |
parent | a4fc251e94c94c4a33a218c99271f601dd87b268 (diff) | |
download | oslo-i18n-688076eb6976d508997e10e22337cd4707303066.tar.gz |
Document how to add import exceptions
Add documentation for how to add import exceptions so hacking does not
complain about the way the library is used.
Change-Id: Ic33307215abbc38d3d3d2435588f79dc115510fd
-rw-r--r-- | doc/source/usage.rst | 39 |
1 files changed, 39 insertions, 0 deletions
diff --git a/doc/source/usage.rst b/doc/source/usage.rst index 4d7964c..aa4effe 100644 --- a/doc/source/usage.rst +++ b/doc/source/usage.rst @@ -21,6 +21,8 @@ the marker functions the factory creates. :: + # app/i18n.py + from oslo import i18n _translators = i18n.TranslatorFactory(domain='myapp') @@ -62,6 +64,43 @@ for each message: :func:`gettextutils.install` should be replaced with the application or library integration module described here. +Handling hacking Objections to Imports +====================================== + +The OpenStack style guidelines prefer importing modules and accessing +names from those modules after import, rather than importing the names +directly. For example: + +:: + + # WRONG + from foo import bar + + bar() + + # RIGHT + + import foo + + foo.bar() + +The linting tool hacking_ will typically complain about importing +names from within modules. It is acceptable to bypass this for the +translation marker functions, because they must have specific names +and their use pattern is dictated by the message catalog extraction +tools rather than our style guidelines. To bypass the hacking check +for imports from the integration module, add an import exception to +``tox.ini``. + +For example:: + + # tox.ini + [hacking] + import_exceptions = + app.i18n + +.. _hacking: https://pypi.python.org/pypi/hacking + .. _lazy-translation: Lazy Translation |