Clean up LanguageImporter. Update documentation.

* Fix caching.
* Report missing/incomplete modules and
  language-variant substitutions (info).
* Move documentation from instance to class definition.

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk@8467 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

4 files changed, 39 insertions, 49 deletions

diff --git a/docutils/HISTORY.txt b/docutils/HISTORY.txt
index beebb6426..5a7669fc3 100644
--- a/docutils/HISTORY.txt
+++ b/docutils/HISTORY.txt
@@ -22,6 +22,7 @@ Changes Since 0.16
 
   - Explicit include test subdirectory contents in MANIFEST.in to avoid
     inclusion of test outputs.
+  - Fix [ 385 ]: Import of language modules.
 
 Release 0.16
 ============
diff --git a/docutils/docs/howto/i18n.txt b/docutils/docs/howto/i18n.txt
index 69bf19fda..b1bf56801 100644
--- a/docutils/docs/howto/i18n.txt
+++ b/docutils/docs/howto/i18n.txt
@@ -29,7 +29,8 @@ Docutils is designed to work flexibly with text in multiple languages
 be [#]_) fully parameterized.  To enable a new language, two modules
 have to be added to the project: one for Docutils itself (the
 `Docutils Language Module`_) and one for the reStructuredText parser
-(the `reStructuredText Language Module`_).
+(the `reStructuredText Language Module`_). Users may add local language
+support via a module in the PYTHONPATH root (e.g. the working directory).
 
 .. [#] If anything in Docutils is insufficiently parameterized, it
    should be considered a bug.  Please report bugs to the Docutils
@@ -71,25 +72,6 @@ is "en" for English.  Examples of module names include ``en.py``,
    02iso-3166-code-lists/index.html
 
 
-Python Code
-===========
-
-Generally Python code in Docutils is ASCII-only.  In language modules,
-Unicode-escapes can be used for non-ASCII characters.
-
-`PEP 263`_ introduces source code encodings to Python modules,
-implemented beginning in Python 2.3.  Especially for languages with
-non-Latin scripts, using UTF-8 encoded literal Unicode strings increases the
-readability. Start the source code file with the magic comment::
-
-  # -*- coding: utf-8 -*-
-
-As mentioned in the note above, developers are invited to explore
-"gettext" and other i18n technologies.
-
-.. _PEP 263: http://www.python.org/peps/pep-0263.html
-
-
 Docutils Language Module
 ========================
 
diff --git a/docutils/docutils/languages/__init__.py b/docutils/docutils/languages/__init__.py
index d4448167a..7730c320f 100644
--- a/docutils/docutils/languages/__init__.py
+++ b/docutils/docutils/languages/__init__.py
@@ -16,8 +16,16 @@ from importlib import import_module
 
 from docutils.utils import normalize_language_tag
 
+
 class LanguageImporter(object):
+    """Import language modules.
+
+    When called with a BCP 47 language tag, instances return a module
+    with localisations from `docutils.languages` or the PYTHONPATH.
 
+    If there is no matching module, warn (if a `reporter` is passed)
+    and fall back to English.
+    """
     packages = ('docutils.languages.', '')
     warn_msg = ('Language "%s" not supported: '
                 'Docutils-generated text will be in English.')
@@ -27,21 +35,22 @@ class LanguageImporter(object):
     def __init__(self):
         self.cache = {}
 
-    def import_from_packages(self, name):
+    def import_from_packages(self, name, reporter=None):
         """Try loading module `name` from `self.packages`."""
-        try:
-            return self.cache[name]
-        except KeyError:
-            pass
+        module = None
         for package in self.packages:
             try:
                 module = import_module(package+name)
                 self.check_content(module)
             except (ImportError, AttributeError):
+                if reporter and module:
+                    reporter.info('%s is no complete Docutils language module.'
+                                  %module)
+                elif reporter:
+                    reporter.info('Module "%s" not found.'%(package+name))
                 continue
-            self.cache[name] = module
-            return module
-        return None
+            break
+        return module
 
     def check_content(self, module):
         """Check if we got a Docutils language module."""
@@ -57,21 +66,18 @@ class LanguageImporter(object):
             pass
         for tag in normalize_language_tag(language_code):
             tag = tag.replace('-', '_') # '-' not valid in module names
-            module = self.import_from_packages(tag)
+            module = self.import_from_packages(tag, reporter)
             if module is not None:
-                return module
-        if reporter is not None:
-            reporter.warning(self.warn_msg % language_code)
-        module = self.import_from_packages('en')
-        self.cache[tag] = module # warn only one time!
+                break
+        else:
+            if reporter:
+                reporter.warning(self.warn_msg % language_code)
+            if self.fallback:
+                module = self.import_from_packages(self.fallback)
+        if reporter and (language_code != 'en'):
+            reporter.info('Using %s for language "%s".'%(module, language_code))
+        self.cache[language_code] = module
         return module
 
 
 get_language = LanguageImporter()
-"""Return module with language localizations
-
-from `docutils.languages` or the PYTHONPATH.
-
-The argument `language_code` is a "BCP 47" language tag.
-If there is no matching module, warn and fall back to English.
-"""
diff --git a/docutils/docutils/parsers/rst/languages/__init__.py b/docutils/docutils/parsers/rst/languages/__init__.py
index e4cf69993..f99901243 100644
--- a/docutils/docutils/parsers/rst/languages/__init__.py
+++ b/docutils/docutils/parsers/rst/languages/__init__.py
@@ -17,6 +17,15 @@ import sys
 from docutils.languages import LanguageImporter
 
 class RstLanguageImporter(LanguageImporter):
+    """Import language modules.
+
+    When called with a BCP 47 language tag, instances return a module
+    with localisations for "directive" and "role" names for  from
+    `docutils.parsers.rst.languages` or the PYTHONPATH.
+
+    If there is no matching module, warn (if a `reporter` is passed)
+    and return None.
+    """
     packages = ('docutils.parsers.rst.languages.', '')
     warn_msg = 'rST localisation for language "%s" not found.'
     fallback = None
@@ -28,11 +37,3 @@ class RstLanguageImporter(LanguageImporter):
             raise ImportError
 
 get_language = RstLanguageImporter()
-"""Return module with language localizations for reStructuredText.
-
-Get translated directive and rolenames from `docutils.parsers.rst.languages`
-or the PYTHONPATH.
-
-The argument `language_code` is a "BCP 47" language tag.
-If there is no matching module, warn and return None.
-"""