bpo-2504: Add pgettext() and variants to gettext

Author: csabella

Doc/library/gettext.rst

@@ -49,8 +49,9 @@ class-based API instead.
 .. function:: bind_textdomain_codeset(domain, codeset=None)
 
    Bind the *domain* to *codeset*, changing the encoding of byte strings
-   returned by the :func:`lgettext`, :func:`ldgettext`, :func:`lngettext`
-   and :func:`ldngettext` functions.
+   returned by the :func:`lgettext`, :func:`ldgettext`, :func:`lngettext`,
+   :func:`ldngettext`, :func:`lpgettext`, :func:`ldpgettext`,
+   :func:`lnpgettext`, and :func:`ldnpgettext` functions.
    If *codeset* is omitted, then the current binding is returned.
 
 
@@ -93,16 +94,33 @@ class-based API instead.
    Like :func:`ngettext`, but look the message up in the specified *domain*.
 
 
+.. function:: pgettext(context, message)
+.. function:: dpgettext(domain, context, message)
+.. function:: npgettext(context, singular, plural, n)
+.. function:: dnpgettext(domain, context, singular, plural, n)
+
+   Similar to the corresponding functions without the ``p`` in the prefix (that
+   is, :func:`gettext`, :func:`dgettext`, :func:`ngettext`, :func:`dngettext`),
+   but the translation is restricted to the given message *context*.
+
+   .. versionadded:: 3.8
+
+
 .. function:: lgettext(message)
 .. function:: ldgettext(domain, message)
 .. function:: lngettext(singular, plural, n)
 .. function:: ldngettext(domain, singular, plural, n)
+.. function:: lpgettext(context, message)
+.. function:: ldpgettext(domain, context, message)
+.. function:: lnpgettext(context, singular, plural, n)
+.. function:: ldnpgettext(domain, context, singular, plural, n)
 
    Equivalent to the corresponding functions without the ``l`` prefix
-   (:func:`.gettext`, :func:`dgettext`, :func:`ngettext` and :func:`dngettext`),
-   but the translation is returned as a byte string encoded in the preferred
-   system encoding if no other encoding was explicitly set with
-   :func:`bind_textdomain_codeset`.
+   (:func:`.gettext`, :func:`dgettext`, :func:`ngettext`, :func:`dngettext`,
+   :func:`pgettext`, :func:`dpgettext`, :func:`npgettext`, and
+   :func:`dnpgettext`), but the translation is returned as a byte string
+   encoded in the preferred system encoding if no other encoding was
+   explicitly set with :func:`bind_textdomain_codeset`.
 
    .. warning::
 
@@ -258,12 +276,31 @@ are the methods of :class:`!NullTranslations`:
       Overridden in derived classes.
 
 
+   .. method:: pgettext(context, message)
+
+      If a fallback has been set, forward :meth:`pgettext` to the fallback.
+      Otherwise, return the translated message.  Overridden in derived classes.
+
+      .. versionadded:: 3.8
+
+
+   .. method:: npgettext(context, singular, plural, n)
+
+      If a fallback has been set, forward :meth:`npgettext` to the fallback.
+      Otherwise, return the translated message.  Overridden in derived classes.
+
+      .. versionadded:: 3.8
+
+
    .. method:: lgettext(message)
    .. method:: lngettext(singular, plural, n)
+   .. method:: lpgettext(context, message)
+   .. method:: lnpgettext(context, singular, plural, n)
 
-      Equivalent to :meth:`.gettext` and :meth:`.ngettext`, but the translation
-      is returned as a byte string encoded in the preferred system encoding
-      if no encoding was explicitly set with :meth:`set_output_charset`.
+      Equivalent to :meth:`.gettext`, :meth:`.ngettext`, :meth:`.pgettext`,
+      and :meth:`npgettext`, but the translation is returned as a byte string
+      encoded in the preferred system encoding if no encoding was explicitly
+      set with :meth:`set_output_charset`.
       Overridden in derived classes.
 
       .. warning::
@@ -284,8 +321,9 @@ are the methods of :class:`!NullTranslations`:
 
    .. method:: output_charset()
 
-      Return the encoding used to return translated messages in :meth:`.lgettext`
-      and :meth:`.lngettext`.
+      Return the encoding used to return translated messages in
+      :meth:`.lgettext`, :meth:`.lngettext`, :meth:`.lpgettext`, and
+      :meth:`.lnpgettext`.
 
 
    .. method:: set_output_charset(charset)
@@ -301,7 +339,8 @@ are the methods of :class:`!NullTranslations`:
       If the *names* parameter is given, it must be a sequence containing the
       names of functions you want to install in the builtins namespace in
       addition to :func:`_`.  Supported names are ``'gettext'``, ``'ngettext'``,
-      ``'lgettext'`` and ``'lngettext'``.
+      ``'pgettext'``, ``'lgettext'``, ``'lngettext'``, ``'lpgettext'``,  and
+      ``'lnpgettext'``.
 
       Note that this is only one way, albeit the most convenient way, to make
       the :func:`_` function available to your application.  Because it affects
@@ -379,8 +418,37 @@ unexpected, or if other problems occur while reading the file, instantiating a
              n) % {'num': n}
 
 
+   .. method:: pgettext(context, message)
+
+      Look up the *context* and *message* id in the catalog and return the
+      corresponding message string, as an 8-bit string encoded with the
+      catalog's encoding, if known.  If there is no entry in the catalog
+      for the *message* id and *context*, and a fallback has been set, the
+      look up is forwarded to the fallback's :meth:`pgettext` method.
+      Otherwise, the *message* id is returned.
+
+      .. versionadded:: 3.8
+
+
+   .. method:: npgettext(context, 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 an
+      8-bit string encoded with the catalog's encoding, if known.
+
+      If the message id for *context* is not found in the catalog, and a
+      fallback is specified, the request is forwarded to the fallback's
+      :meth:`npgettext` method.  Otherwise, when *n* is 1 *singular* is
+      returned, and *plural* is returned in all other cases.
+
+      .. versionadded:: 3.8
+
+
    .. method:: lgettext(message)
    .. method:: lngettext(singular, plural, n)
+   .. method:: lpgettext(context, message)
+   .. method:: lnpgettext(context, singular, plural, n)
 
       Equivalent to :meth:`.gettext` and :meth:`.ngettext`, but the translation
       is returned as a byte string encoded in the preferred system encoding

Lib/gettext.py

@@ -57,6 +57,8 @@
            'bind_textdomain_codeset',
            'dgettext', 'dngettext', 'gettext', 'lgettext', 'ldgettext',
            'ldngettext', 'lngettext', 'ngettext',
+           'pgettext', 'dpgettext', 'npgettext', 'dnpgettext',
+           'lpgettext', 'ldpgettext', 'lnpgettext', 'ldnpgettext',
            ]
 
 _default_localedir = os.path.join(sys.base_prefix, 'share', 'locale')
@@ -299,6 +301,37 @@ def lngettext(self, msgid1, msgid2, n):
             return tmsg.encode(self._output_charset)
         return tmsg.encode(locale.getpreferredencoding())
 
+    def pgettext(self, context, message):
+        if self._fallback:
+            return self._fallback.pgettext(context, message)
+        return message
+
+    def lpgettext(self, context, message):
+        if self._fallback:
+            return self._fallback.lpgettext(context, message)
+        if self._output_charset:
+            return message.encode(self._output_charset)
+        return message.encode(locale.getpreferredencoding())
+
+    def npgettext(self, context, msgid1, msgid2, n):
+        if self._fallback:
+            return self._fallback.npgettext(context, msgid1, msgid2, n)
+        if n == 1:
+            return msgid1
+        else:
+            return msgid2
+
+    def lnpgettext(self, context, msgid1, msgid2, n):
+        if self._fallback:
+            return self._fallback.lnpgettext(context, msgid1, msgid2, n)
+        if n == 1:
+            tmsg = msgid1
+        else:
+            tmsg = msgid2
+        if self._output_charset:
+            return tmsg.encode(self._output_charset)
+        return tmsg.encode(locale.getpreferredencoding())
+
     def info(self):
         return self._info
 
@@ -314,22 +347,22 @@ def set_output_charset(self, charset):
     def install(self, names=None):
         import builtins
         builtins.__dict__['_'] = self.gettext
-        if hasattr(names, "__contains__"):
-            if "gettext" in names:
-                builtins.__dict__['gettext'] = builtins.__dict__['_']
-            if "ngettext" in names:
-                builtins.__dict__['ngettext'] = self.ngettext
-            if "lgettext" in names:
-                builtins.__dict__['lgettext'] = self.lgettext
-            if "lngettext" in names:
-                builtins.__dict__['lngettext'] = self.lngettext
+        if names is not None:
+            allowed = {'gettext', 'lgettext', 'lngettext', 'lnpgettext',
+                       'lpgettext', 'ngettext', 'npgettext', 'pgettext'}
+            for name in allowed & set(names):
+                builtins.__dict__[name] = getattr(self, name)
 
 
 class GNUTranslations(NullTranslations):
     # Magic number of .mo files
     LE_MAGIC = 0x950412de
     BE_MAGIC = 0xde120495
 
+    # The encoding of a msgctxt and a msgid in a .mo file is
+    # msgctxt + "\x04" + msgid (gettext version >= 0.15)
+    CONTEXT = "%s\x04%s"
+
     # Acceptable .mo versions
     VERSIONS = (0, 1)
 
@@ -469,6 +502,56 @@ def ngettext(self, msgid1, msgid2, n):
                 tmsg = msgid2
         return tmsg
 
+    def pgettext(self, context, message):
+        ctxt_msg_id = self.CONTEXT % (context, message)
+        missing = object()
+        tmsg = self._catalog.get(ctxt_msg_id, missing)
+        if tmsg is missing:
+            if self._fallback:
+                return self._fallback.pgettext(context, message)
+            return message
+        return tmsg
+
+    def npgettext(self, context, msgid1, msgid2, n):
+        ctxt_msg_id = self.CONTEXT % (context, msgid1)
+        try:
+            tmsg = self._catalog[(ctxt_msg_id, self.plural(n))]
+        except KeyError:
+            if self._fallback:
+                return self._fallback.npgettext(context, msgid1, msgid2, n)
+            if n == 1:
+                tmsg = msgid1
+            else:
+                tmsg = msgid2
+        return tmsg
+
+    def lpgettext(self, context, message):
+        ctxt_msg_id = self.CONTEXT % (context, message)
+        missing = object()
+        tmsg = self._catalog.get(ctxt_msg_id, missing)
+        if tmsg is missing:
+            if self._fallback:
+                return self._fallback.lpgettext(context, message)
+            tmsg = message
+        if self._output_charset:
+            return tmsg.encode(self._output_charset)
+        return tmsg.encode(locale.getpreferredencoding())
+
+    def lnpgettext(self, context, msgid1, msgid2, n):
+        ctxt_msg_id = self.CONTEXT % (context, msgid1)
+        try:
+            tmsg = self._catalog[(ctxt_msg_id, self.plural(n))]
+        except KeyError:
+            if self._fallback:
+                return self._fallback.lnpgettext(context, msgid1, msgid2, n)
+            if n == 1:
+                tmsg = msgid1
+            else:
+                tmsg = msgid2
+        if self._output_charset:
+            return tmsg.encode(self._output_charset)
+        return tmsg.encode(locale.getpreferredencoding())
+
 
 # Locate a .mo file using the gettext strategy
 def find(domain, localedir=None, languages=None, all=False):
@@ -590,6 +673,7 @@ def dgettext(domain, message):
         return message
     return t.gettext(message)
 
+
 def ldgettext(domain, message):
     codeset = _localecodesets.get(domain)
     try:
@@ -598,6 +682,7 @@ def ldgettext(domain, message):
         return message.encode(codeset or locale.getpreferredencoding())
     return t.lgettext(message)
 
+
 def dngettext(domain, msgid1, msgid2, n):
     try:
         t = translation(domain, _localedirs.get(domain, None),
@@ -609,6 +694,7 @@ def dngettext(domain, msgid1, msgid2, n):
             return msgid2
     return t.ngettext(msgid1, msgid2, n)
 
+
 def ldngettext(domain, msgid1, msgid2, n):
     codeset = _localecodesets.get(domain)
     try:
@@ -621,18 +707,82 @@ def ldngettext(domain, msgid1, msgid2, n):
         return tmsg.encode(codeset or locale.getpreferredencoding())
     return t.lngettext(msgid1, msgid2, n)
 
+
+def dpgettext(domain, context, message):
+    try:
+        t = translation(domain, _localedirs.get(domain, None),
+                        codeset=_localecodesets.get(domain))
+    except OSError:
+        return message
+    return t.pgettext(context, message)
+
+
+def ldpgettext(domain, context, message):
+    codeset = _localecodesets.get(domain)
+    try:
+        t = translation(domain, _localedirs.get(domain, None), codeset=codeset)
+    except OSError:
+        return message.encode(codeset or locale.getpreferredencoding())
+    return t.lpgettext(context, message)
+
+
+def dnpgettext(domain, context, msgid1, msgid2, n):
+    try:
+        t = translation(domain, _localedirs.get(domain, None),
+                        codeset=_localecodesets.get(domain))
+    except OSError:
+        if n == 1:
+            return msgid1
+        else:
+            return msgid2
+    return t.npgettext(context, msgid1, msgid2, n)
+
+
+def ldnpgettext(domain, context, msgid1, msgid2, n):
+    codeset = _localecodesets.get(domain)
+    try:
+        t = translation(domain, _localedirs.get(domain, None), codeset=codeset)
+    except OSError:
+        if n == 1:
+            tmsg = msgid1
+        else:
+            tmsg = msgid2
+        return tmsg.encode(codeset or locale.getpreferredencoding())
+    return t.lnpgettext(context, msgid1, msgid2, n)
+
+
 def gettext(message):
     return dgettext(_current_domain, message)
 
+
 def lgettext(message):
     return ldgettext(_current_domain, message)
 
+
 def ngettext(msgid1, msgid2, n):
     return dngettext(_current_domain, msgid1, msgid2, n)
 
+
 def lngettext(msgid1, msgid2, n):
     return ldngettext(_current_domain, msgid1, msgid2, n)
 
+
+def pgettext(context, message):
+    return dpgettext(_current_domain, context, message)
+
+
+def lpgettext(context, message):
+    return ldpgettext(_current_domain, context, message)
+
+
+def npgettext(context, msgid1, msgid2, n):
+    return dnpgettext(_current_domain, context, msgid1, msgid2, n)
+
+
+def lnpgettext(context, msgid1, msgid2, n):
+    return ldnpgettext(_current_domain, context, msgid1, msgid2, n)
+
+
 # dcgettext() has been deemed unnecessary and is not implemented.
 
 # James Henstridge's Catalog constructor from GNOME gettext.  Documented usage