#2512 implement the 3.0 gettext API

All the u* gettext variants were renamed to their
none u* variants, since there's no point in translating
to byte strings. I also killed off the unicode parameters
for install

1 files changed, 66 insertions, 116 deletions

diff --git a/Doc/library/gettext.rst b/Doc/library/gettext.rst
index fa1271a..2b344e0 100644
--- a/Doc/library/gettext.rst
+++ b/Doc/library/gettext.rst
@@ -187,12 +187,11 @@ class can also install themselves in the built-in namespace as the function
    :class:`NullTranslations` instance if *fallback* is true.
 
 
-.. function:: install(domain[, localedir[, unicode [, 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
-   :func:`translation`.  The *unicode* flag is passed to the resulting translation
-   object's :meth:`install` method.
+   :func:`translation`.
 
    For the *names* parameter, please see the description of the translation
    object's :meth:`install` method.
@@ -227,107 +226,91 @@ are the methods of :class:`NullTranslations`:
    ``None``.
 
 
-   .. method:: _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.
-
+        .. method:: NullTranslations._parse(fp)
 
-   .. method:: add_fallback(fallback)
+           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.
 
-      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.add_fallback(fallback)
 
-   .. method:: gettext(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.
 
-      If a fallback has been set, forward :meth:`gettext` to the
-      fallback. Otherwise, return the translated message.  Overridden in derived
-      classes.
 
+        .. method:: NullTranslations.gettext(message)
 
-   .. method:: lgettext(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:`lgettext` to the
-      fallback. Otherwise, return the translated message.  Overridden in derived
-      classes.
 
-   .. method:: ugettext(message)
+        .. method:: NullTranslations.lgettext(message)
 
-      If a fallback has been set, forward :meth:`ugettext` to the
-      fallback. Otherwise, return the translated message as a string. 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:: ngettext(singular, plural, n)
+        .. method:: NullTranslations.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:: 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.
+        .. method:: NullTranslations.lngettext(singular, plural, n)
 
-   .. method:: ungettext(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:`ungettext` to the fallback.
-      Otherwise, return the translated message as a string. Overridden in
-      derived classes.
 
-   .. method:: info()
+        .. method:: NullTranslations.info()
 
-      Return the "protected" :attr:`_info` variable.
+           Return the "protected" :attr:`_info` variable.
 
 
-   .. method:: charset()
+        .. method:: NullTranslations.charset()
 
-      Return the "protected" :attr:`_charset` variable.
+           Return the "protected" :attr:`_charset` variable.
 
 
-   .. method:: output_charset()
+        .. method:: NullTranslations.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.
 
 
-   .. method:: set_output_charset(charset)
+        .. method:: NullTranslations.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:: install([unicode [, names]])
+        .. method:: NullTranslations.install([names])
 
-      If the *unicode* flag is false, this method installs :meth:`self.gettext`
-      into the built-in namespace, binding it to ``_``.  If *unicode* is true,
-      it binds :meth:`self.ugettext` instead.  By default, *unicode* is false.
+           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` or :meth:`self.ugettext` according to the *unicode*
-      flag), ``'ngettext'`` (bound to :meth:`self.ngettext` or
-      :meth:`self.ungettext` according to the *unicode* flag), ``'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
@@ -336,8 +319,7 @@ The :class:`GNUTranslations` class
 The :mod:`gettext` module provides one additional class derived from
 :class:`NullTranslations`: :class:`GNUTranslations`.  This class overrides
 :meth:`_parse` to enable reading GNU :program:`gettext` format :file:`.mo` files
-in both big-endian and little-endian format. It also coerces both message ids
-and message strings to Unicode.
+in both big-endian and little-endian format.
 
 :class:`GNUTranslations` parses optional meta-data out of the translation
 catalog.  It is convention with GNU :program:`gettext` to include meta-data as
@@ -347,12 +329,7 @@ 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.  The :meth:`ugettext` method always returns a Unicode, while the
-:meth:`gettext` returns an encoded bytestring.  For the message id arguments
-of both methods, either Unicode strings or bytestrings containing only
-US-ASCII characters are acceptable.  Note that the Unicode version of the
-methods (i.e. :meth:`ugettext` and :meth:`ungettext`) are the recommended
-interface to use for internationalized Python programs.
+this encoding.
 
 The entire set of key/value pairs are placed into a dictionary and set as the
 "protected" :attr:`_info` instance variable.
@@ -380,14 +357,6 @@ The following methods are overridden from the base class implementation:
    :meth:`set_output_charset`.
 
 
-.. method:: GNUTranslations.ugettext(message)
-
-   Look up the *message* id in the catalog and return the corresponding message
-   string, as a 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:`ugettext` method.  Otherwise, the *message* id is returned.
-
-
 .. method:: GNUTranslations.ngettext(singular, plural, n)
 
    Do a plural-forms lookup of a message id.  *singular* is used as the message id
@@ -398,36 +367,24 @@ The following methods are overridden from the base class implementation:
    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
    *n* is 1 *singular* is returned, and *plural* is returned in all other cases.
-
-
-.. 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`.
-
-
-.. method:: GNUTranslations.ungettext(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 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:`ungettext` method.  Otherwise,
-   when *n* is 1 *singular* is returned, and *plural* is returned in all other
-   cases.
-
+   
    Here is an example::
 
       n = len(os.listdir('.'))
       cat = GNUTranslations(somefile)
-      message = cat.ungettext(
+      message = cat.ngettext(
           'There is %(num)d file in this directory',
           'There are %(num)d files in this directory',
           n) % {'num': n}
 
 
+.. 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`.
+
+
 Solaris message catalog support
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -538,13 +495,6 @@ module::
    t = gettext.translation('spam', '/usr/share/locale')
    _ = t.lgettext
 
-If your translators were providing you with Unicode strings in their :file:`.po`
-files, you'd instead do::
-
-   import gettext
-   t = gettext.translation('spam', '/usr/share/locale')
-   _ = t.ugettext
-
 
 Localizing your application
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -560,11 +510,11 @@ driver file of your application::
    import gettext
    gettext.install('myapplication')
 
-If you need to set the locale directory or the *unicode* flag, you can pass
-these into the :func:`install` function::
+If you need to set the locale directory, you can pass these into the
+:func:`install` function::
 
    import gettext
-   gettext.install('myapplication', '/usr/share/locale', unicode=1)
+   gettext.install('myapplication', '/usr/share/locale')
 
 
 Changing languages on the fly