FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

[3.12] GH-101100: Fix reference warnings for ``gettext`` (GH-110115) by miss-islington · Pull Request #110140 · python/cpython · GitHub

  1. python
  2. cpython

Repository navigation

[3.12] GH-101100: Fix reference warnings for gettext (GH-110115) #110140

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Yhg1s merged 1 commit into from
Oct 2, 2023
Conversation 0 Commits 1 Checks 0 Files changed
Merged

[3.12] GH-101100: Fix reference warnings for gettext (GH-110115) #110140

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension .rst  (1) All 1 file type selected
Viewed files
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Unified
Split
Hide whitespace
Diff view
Unified
Split
Hide whitespace
55 changes: 26 additions & 29 deletions Doc/library/gettext.rst
Show comments
View file
Open in desktop
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Show hidden characters
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ class-based API instead.

Return the localized translation of *message*, based on the current global
domain, language, and locale directory. This function is usually aliased as
:func:`_` in the local namespace (see examples below).
:func:`!_` in the local namespace (see examples below).


.. function:: dgettext(domain, message)
Expand Down Expand Up @@ -98,7 +98,7 @@ class-based API instead.
.. versionadded:: 3.8


Note that GNU :program:`gettext` also defines a :func:`dcgettext` method, but
Note that GNU :program:`gettext` also defines a :func:`!dcgettext` method, but
this was deemed not useful and so it is currently unimplemented.

Here's an example of typical usage for this API::
Expand All @@ -119,7 +119,7 @@ greater convenience than the GNU :program:`gettext` API. It is the recommended
way of localizing your Python applications and modules. :mod:`!gettext` defines
a :class:`GNUTranslations` class which implements the parsing of GNU :file:`.mo` format
files, and has methods for returning strings. Instances of this class can also
install themselves in the built-in namespace as the function :func:`_`.
install themselves in the built-in namespace as the function :func:`!_`.


.. function:: find(domain, localedir=None, languages=None, all=False)
Expand Down Expand Up @@ -150,15 +150,12 @@ install themselves in the built-in namespace as the function :func:`_`.

.. function:: translation(domain, localedir=None, languages=None, class_=None, fallback=False)

Return a :class:`*Translations` instance based on the *domain*, *localedir*,
Return a ``*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 *class_* if
provided, otherwise :class:`GNUTranslations`. The class's constructor must
take a single :term:`file object` argument. If provided, *codeset* will change
the charset used to encode translated strings in the
:meth:`~NullTranslations.lgettext` and :meth:`~NullTranslations.lngettext`
methods.
take a single :term:`file object` argument.

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
Expand All @@ -177,19 +174,19 @@ install themselves in the built-in namespace as the function :func:`_`.

.. function:: install(domain, localedir=None, *, names=None)

This installs the function :func:`_` in Python's builtins namespace, based on
This installs the function :func:`!_` in Python's builtins namespace, based on
*domain* and *localedir* which are passed to the function :func:`translation`.

For the *names* parameter, please see the description of the translation
object's :meth:`~NullTranslations.install` method.

As seen below, you usually mark the strings in your application that are
candidates for translation, by wrapping them in a call to the :func:`_`
candidates for translation, by wrapping them in a call to the :func:`!_`
function, like this::

print(_('This string will be translated.'))

For convenience, you want the :func:`_` function to be installed in Python's
For convenience, you want the :func:`!_` function to be installed in Python's
builtins namespace, so it is easily accessible in all modules of your
application.

Expand Down Expand Up @@ -276,20 +273,20 @@ 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'``,
``'pgettext'``, ``'npgettext'``, ``'lgettext'``, and ``'lngettext'``.
addition to :func:`!_`. Supported names are ``'gettext'``, ``'ngettext'``,
``'pgettext'``, and ``'npgettext'``.

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 :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::
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

This puts :func:`_` only in the module's global namespace and so only
This puts :func:`!_` only in the module's global namespace and so only
affects calls within this module.

.. versionchanged:: 3.8
Expand All @@ -314,7 +311,7 @@ initialize the "protected" :attr:`_charset` instance variable, defaulting to
ids and message strings read from the catalog are converted to Unicode using
this encoding, else ASCII is assumed.

Since message ids are read as Unicode strings too, all :meth:`*gettext` methods
Since message ids are read as Unicode strings too, all ``*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
Expand Down Expand Up @@ -404,7 +401,7 @@ version has a slightly different API. Its documented usage was::
_ = cat.gettext
print(_('hello world'))

For compatibility with this older module, the function :func:`Catalog` is an
For compatibility with this older module, the function :func:`!Catalog` is an
alias for the :func:`translation` function described above.

One difference between this module and Henstridge's: his catalog objects
Expand Down Expand Up @@ -432,7 +429,7 @@ take the following steps:

In order to prepare your code for I18N, you need to look at all the strings in
your files. Any string that needs to be translated should be marked by wrapping
it in ``_('...')`` --- that is, a call to the function :func:`_`. For example::
it in ``_('...')`` --- that is, a call to the function :func:`_ <gettext>`. For example::

filename = 'mylog.txt'
message = _('writing a log message')
Expand Down Expand Up @@ -504,7 +501,7 @@ module::
Localizing your application
^^^^^^^^^^^^^^^^^^^^^^^^^^^

If you are localizing your application, you can install the :func:`_` function
If you are localizing your application, you can install the :func:`!_` function
globally into the built-in namespace, usually in the main driver file of your
application. This will let all your application-specific files just use
``_('...')`` without having to explicitly install it in each file.
Expand Down Expand Up @@ -581,13 +578,13 @@ Here is one way you can handle this situation::
for a in animals:
print(_(a))

This works because the dummy definition of :func:`_` simply returns the string
This works because the dummy definition of :func:`!_` simply returns the string
unchanged. And this dummy definition will temporarily override any definition
of :func:`_` in the built-in namespace (until the :keyword:`del` command). Take
care, though if you have a previous definition of :func:`_` in the local
of :func:`!_` in the built-in namespace (until the :keyword:`del` command). Take
care, though if you have a previous definition of :func:`!_` in the local
namespace.

Note that the second use of :func:`_` will not identify "a" as being
Note that the second use of :func:`!_` will not identify "a" as being
translatable to the :program:`gettext` program, because the parameter
is not a string literal.

Expand All @@ -606,13 +603,13 @@ Another way to handle this is with the following example::
print(_(a))

In this case, you are marking translatable strings with the function
:func:`N_`, which won't conflict with any definition of :func:`_`.
:func:`!N_`, which won't conflict with any definition of :func:`!_`.
However, you will need to teach your message extraction program to
look for translatable strings marked with :func:`N_`. :program:`xgettext`,
look for translatable strings marked with :func:`!N_`. :program:`xgettext`,
:program:`pygettext`, ``pybabel extract``, and :program:`xpot` all
support this through the use of the :option:`!-k` command-line switch.
The choice of :func:`N_` here is totally arbitrary; it could have just
as easily been :func:`MarkThisStringForTranslation`.
The choice of :func:`!N_` here is totally arbitrary; it could have just
as easily been :func:`!MarkThisStringForTranslation`.


Acknowledgements
Expand Down
Back | FazBrowse Home | New Git URL