Make gettext Unicode interface consistent and clean up the docs.

1 files changed, 79 insertions, 92 deletions

diff --git a/Doc/library/gettext.rst b/Doc/library/gettext.rst
index 2b344e0..458eec0 100644
--- a/Doc/library/gettext.rst
+++ b/Doc/library/gettext.rst
@@ -66,8 +66,8 @@ class-based API instead.
 
 .. function:: lgettext(message)
 
-   Equivalent to :func:`gettext`, but the translation is returned in the preferred
-   system encoding, if no other encoding was explicitly set with
+   Equivalent to :func:`gettext`, but the translation is returned in the
+   preferred system encoding, if no other encoding was explicitly set with
    :func:`bind_textdomain_codeset`.
 
 
@@ -78,8 +78,8 @@ class-based API instead.
 
 .. function:: ldgettext(domain, message)
 
-   Equivalent to :func:`dgettext`, but the translation is returned in the preferred
-   system encoding, if no other encoding was explicitly set with
+   Equivalent to :func:`dgettext`, but the translation is returned in the
+   preferred system encoding, if no other encoding was explicitly set with
    :func:`bind_textdomain_codeset`.
 
 
@@ -99,8 +99,8 @@ class-based API instead.
 
 .. function:: lngettext(singular, plural, n)
 
-   Equivalent to :func:`ngettext`, but the translation is returned in the preferred
-   system encoding, if no other encoding was explicitly set with
+   Equivalent to :func:`ngettext`, but the translation is returned in the
+   preferred system encoding, if no other encoding was explicitly set with
    :func:`bind_textdomain_codeset`.
 
 
@@ -169,13 +169,14 @@ class can also install themselves in the built-in namespace as the function
 
 .. function:: translation(domain[, localedir[, languages[, class_[, fallback[, codeset]]]]])
 
-   Return a :class:`Translations` instance based on the *domain*, *localedir*, and
-   *languages*, which are first passed to :func:`find` to get a list of the
+   Return a :class:`Translations` instance based on the *domain*, *localedir*,
+   and *languages*, which are first passed to :func:`find` to get a list of the
    associated :file:`.mo` file paths.  Instances with identical :file:`.mo` file
-   names are cached.  The actual class instantiated is either *class_* if provided,
-   otherwise :class:`GNUTranslations`.  The class's constructor must take a single
-   file object argument. If provided, *codeset* will change the charset used to
-   encode translated strings.
+   names are cached.  The actual class instantiated is either *class_* if
+   provided, otherwise :class:`GNUTranslations`.  The class's constructor must
+   take a single file object argument.  If provided, *codeset* will change the
+   charset used to encode translated strings in the :meth:`lgettext` and
+   :meth:`lngettext` methods.
 
    If multiple files are found, later files are used as fallbacks for earlier ones.
    To allow setting the fallback, :func:`copy.copy` is used to clone each
@@ -187,7 +188,7 @@ class can also install themselves in the built-in namespace as the function
    :class:`NullTranslations` instance if *fallback* is true.
 
 
-.. function:: install(domain[, localedir [, codeset[, names]]]])
+.. function:: install(domain[, localedir[, codeset[, names]]]])
 
    This installs the function :func:`_` in Python's builtin namespace, based on
    *domain*, *localedir*, and *codeset* which are passed to the function
@@ -225,92 +226,92 @@ are the methods of :class:`NullTranslations`:
    :meth:`add_fallback`.  It then calls ``self._parse(fp)`` if *fp* is not
    ``None``.
 
+   .. method:: _parse(fp)
 
-        .. method:: NullTranslations._parse(fp)
-
-           No-op'd in the base class, this method takes file object *fp*, and reads the
-           data from the file, initializing its message catalog.  If you have an
-           unsupported message catalog file format, you should override this method to
-           parse your format.
+      No-op'd in the base class, this method takes file object *fp*, and reads
+      the data from the file, initializing its message catalog.  If you have an
+      unsupported message catalog file format, you should override this method
+      to parse your format.
 
 
-        .. method:: NullTranslations.add_fallback(fallback)
+   .. method:: add_fallback(fallback)
 
-           Add *fallback* as the fallback object for the current translation object. A
-           translation object should consult the fallback if it cannot provide a
-           translation for a given message.
+      Add *fallback* as the fallback object for the current translation object.
+      A translation object should consult the fallback if it cannot provide a
+      translation for a given message.
 
 
-        .. method:: NullTranslations.gettext(message)
+   .. method:: gettext(message)
 
-           If a fallback has been set, forward :meth:`gettext` to the fallback. Otherwise,
-           return the translated message.  Overridden in derived classes.
+      If a fallback has been set, forward :meth:`gettext` to the fallback.
+      Otherwise, return the translated message.  Overridden in derived classes.
 
 
-        .. method:: NullTranslations.lgettext(message)
+   .. method:: lgettext(message)
 
-           If a fallback has been set, forward :meth:`lgettext` to the fallback. Otherwise,
-           return the translated message.  Overridden in derived classes.
+      If a fallback has been set, forward :meth:`lgettext` to the fallback.
+      Otherwise, return the translated message.  Overridden in derived classes.
 
 
-        .. method:: NullTranslations.ngettext(singular, plural, n)
+   .. method:: ngettext(singular, plural, n)
 
-           If a fallback has been set, forward :meth:`ngettext` to the fallback. Otherwise,
-           return the translated message.  Overridden in derived classes.
+      If a fallback has been set, forward :meth:`ngettext` to the fallback.
+      Otherwise, return the translated message.  Overridden in derived classes.
 
 
-        .. method:: NullTranslations.lngettext(singular, plural, n)
+   .. method:: lngettext(singular, plural, n)
 
-           If a fallback has been set, forward :meth:`ngettext` to the fallback. Otherwise,
-           return the translated message.  Overridden in derived classes.
+      If a fallback has been set, forward :meth:`ngettext` to the fallback.
+      Otherwise, return the translated message.  Overridden in derived classes.
 
 
-        .. method:: NullTranslations.info()
+   .. method:: info()
 
-           Return the "protected" :attr:`_info` variable.
+      Return the "protected" :attr:`_info` variable.
 
 
-        .. method:: NullTranslations.charset()
+   .. method:: charset()
 
-           Return the "protected" :attr:`_charset` variable.
+      Return the "protected" :attr:`_charset` variable, which is the encoding of
+      the message catalog file.
 
 
-        .. method:: NullTranslations.output_charset()
+   .. method:: output_charset()
 
-           Return the "protected" :attr:`_output_charset` variable, which defines the
-           encoding used to return translated messages.
+      Return the "protected" :attr:`_output_charset` variable, which defines the
+      encoding used to return translated messages in :meth:`lgettext` and
+      :meth:`lngettext`.
 
 
-        .. method:: NullTranslations.set_output_charset(charset)
+   .. method:: set_output_charset(charset)
 
-           Change the "protected" :attr:`_output_charset` variable, which defines the
-           encoding used to return translated messages.
+      Change the "protected" :attr:`_output_charset` variable, which defines the
+      encoding used to return translated messages.
 
 
-        .. method:: NullTranslations.install([names])
+   .. method:: install([names])
 
-           this method installs :meth:`self.gettext` into the built-in namespace, 
-           binding it to ``_``.
+      This method installs :meth:`self.gettext` into the built-in namespace,
+      binding it to ``_``.
 
-           If the *names* parameter is given, it must be a sequence containing
-           the names of functions you want to install in the builtin namespace
-           in addition to :func:`_`.  Supported names are ``'gettext'`` (bound
-           to :meth:`self.gettext`), ``'ngettext'`` (bound to
-           :meth:`self.ngettext`), ``'lgettext'`` and ``'lngettext'``.
+      If the *names* parameter is given, it must be a sequence containing the
+      names of functions you want to install in the builtin namespace in
+      addition to :func:`_`.  Supported names are ``'gettext'`` (bound to
+      :meth:`self.gettext`), ``'ngettext'`` (bound to :meth:`self.ngettext`),
+      ``'lgettext'`` and ``'lngettext'``.
 
-           Note that this is only one way, albeit the most convenient way, to
-           make the :func:`_` function available to your application.  Because
-           it affects the entire application globally, and specifically the
-           built-in namespace, localized modules should never install
-           :func:`_`. Instead, they should use this code to make :func:`_`
-           available to their module::
+      Note that this is only one way, albeit the most convenient way, to make
+      the :func:`_` function available to your application.  Because it affects
+      the entire application globally, and specifically the built-in namespace,
+      localized modules should never install :func:`_`. Instead, they should use
+      this code to make :func:`_` available to their module::
 
-              import gettext
-              t = gettext.translation('mymodule', ...)
-              _ = t.gettext
+         import gettext
+         t = gettext.translation('mymodule', ...)
+         _ = t.gettext
 
-           This puts :func:`_` only in the module's global namespace and so only
-           affects calls within this module.
+      This puts :func:`_` only in the module's global namespace and so only
+      affects calls within this module.
 
 
 The :class:`GNUTranslations` class
@@ -329,7 +330,10 @@ key ``Content-Type`` is found, then the ``charset`` property is used to
 initialize the "protected" :attr:`_charset` instance variable, defaulting to
 ``None`` if not found.  If the charset encoding is specified, then all message
 ids and message strings read from the catalog are converted to Unicode using
-this encoding.
+this encoding, else ASCII encoding is assumed.
+
+Since message ids are read as Unicode strings too, all :meth:`*gettext` methods
+will assume message ids as Unicode strings, not byte strings.
 
 The entire set of key/value pairs are placed into a dictionary and set as the
 "protected" :attr:`_info` instance variable.
@@ -344,25 +348,23 @@ The following methods are overridden from the base class implementation:
 .. method:: GNUTranslations.gettext(message)
 
    Look up the *message* id in the catalog and return the corresponding message
-   string, as a bytestring encoded with the catalog's charset encoding, if
-   known.  If there is no entry in the catalog for the *message* id, and a fallback
-   has been set, the look up is forwarded to the fallback's :meth:`gettext` method.
-   Otherwise, the *message* id is returned.
+   string, as a Unicode string.  If there is no entry in the catalog for the
+   *message* id, and a fallback has been set, the look up is forwarded to the
+   fallback's :meth:`gettext` method.  Otherwise, the *message* id is returned.
 
 
 .. method:: GNUTranslations.lgettext(message)
 
-   Equivalent to :meth:`gettext`, but the translation is returned in the preferred
-   system encoding, if no other encoding was explicitly set with
-   :meth:`set_output_charset`.
+   Equivalent to :meth:`gettext`, but the translation is returned as a
+   bytestring encoded in the selected output charset, or in the preferred system
+   encoding if no encoding was explicitly set with :meth:`set_output_charset`.
 
 
 .. method:: GNUTranslations.ngettext(singular, plural, n)
 
    Do a plural-forms lookup of a message id.  *singular* is used as the message id
    for purposes of lookup in the catalog, while *n* is used to determine which
-   plural form to use.  The returned message string is a bytestring encoded with
-   the catalog's charset encoding, if known.
+   plural form to use.  The returned message string is a Unicode string.
 
    If the message id is not found in the catalog, and a fallback is specified, the
    request is forwarded to the fallback's :meth:`ngettext` method.  Otherwise, when
@@ -380,9 +382,9 @@ The following methods are overridden from the base class implementation:
 
 .. method:: GNUTranslations.lngettext(singular, plural, n)
 
-   Equivalent to :meth:`gettext`, but the translation is returned in the preferred
-   system encoding, if no other encoding was explicitly set with
-   :meth:`set_output_charset`.
+   Equivalent to :meth:`gettext`, but the translation is returned as a
+   bytestring encoded in the selected output charset, or in the preferred system
+   encoding if no encoding was explicitly set with :meth:`set_output_charset`.
 
 
 Solaris message catalog support
@@ -609,21 +611,6 @@ marked with :func:`N_`. :program:`pygettext` and :program:`xpot` both support
 this through the use of command line switches.
 
 
-:func:`gettext` vs. :func:`lgettext`
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-In Python 2.4 the :func:`lgettext` family of functions were introduced. The
-intention of these functions is to provide an alternative which is more
-compliant with the current implementation of GNU gettext. Unlike
-:func:`gettext`, which returns strings encoded with the same codeset used in the
-translation file, :func:`lgettext` will return strings encoded with the
-preferred system encoding, as returned by :func:`locale.getpreferredencoding`.
-Also notice that Python 2.4 introduces new functions to explicitly choose the
-codeset used in translated strings. If a codeset is explicitly set, even
-:func:`lgettext` will return translated strings in the requested codeset, as
-would be expected in the GNU gettext implementation.
-
-
 Acknowledgements
 ----------------