Deprecate gettext.lgettext()

[serhiy-storchaka]

BPO	33710
Nosy	@warsaw, @serhiy-storchaka, @tirkarthi, @bradengroom
PRs	bpo-33710: Deprecate l*gettext() and related functions in the gettext module. #10139

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/serhiy-storchaka'
closed_at = <Date 2018-10-27.05:22:19.236>
created_at = <Date 2018-05-31.11:00:56.663>
labels = ['3.8', 'library']
title = 'Deprecate gettext.lgettext()'
updated_at = <Date 2021-08-24.10:06:46.394>
user = 'https://github.com/serhiy-storchaka'

bugs.python.org fields:

activity = <Date 2021-08-24.10:06:46.394>
actor = 'xtreak'
assignee = 'serhiy.storchaka'
closed = True
closed_date = <Date 2018-10-27.05:22:19.236>
closer = 'serhiy.storchaka'
components = ['Library (Lib)']
creation = <Date 2018-05-31.11:00:56.663>
creator = 'serhiy.storchaka'
dependencies = []
files = []
hgrepos = []
issue_num = 33710
keywords = ['patch']
message_count = 11.0
messages = ['318283', '318342', '328468', '328584', '328585', '328589', '328635', '328636', '328639', '328644', '400201']
nosy_count = 4.0
nosy_names = ['barry', 'serhiy.storchaka', 'xtreak', 'bradengroom']
pr_nums = ['10139']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue33710'
versions = ['Python 3.8']

[serhiy-storchaka]

Using gettext.lgettext() is the one of two right ways of doing translation in Python 2. In Python 2, gettext.gettext() returns a raw 8-bit string as it was written in the translation file. Since different translation files can use different encodings, and the locale encoding can be different from them, gettext.gettext() usually is not appropriate. gettext.lgettext() re-encodes all translated messages from file encodings to the specified one (or to the locale encoding by default). It works properly for str-based messages. Other right way is using gettext.ugettext() which returns a Unicode string.

In Python 3 gettext.gettext() was removed, and gettext.ugettext() was renamed to gettext.gettext(). This is the single right way. gettext.lgettext() still returns messages encoded to bytes, but since virtually all messages are Unicode strings in Python 3, it is virtually useless. At least I don't know any proper use case for it. In addition, gettext.lgettext() was half-broken up to recent times (see bpo-29755).

Seems gettext.lgettext() was not removed in Python 3.0 just due to an oversight. I suggest to deprecate it in 3.8 and remove it in future versions.

[warsaw]

+1 - I'm actually surprise it's still there. ;) Given that the docs have a big red warning to avoid these in Python 3, let's start the process of removal.

Don't forget to also deprecate ldgettext(), lngettext(), and ldngettext()

https://docs.python.org/3/library/gettext.html#gettext.lgettext

[bradengroom]

What's the process for deprecating functions? Do we just start by adding a note in the docs?

[serhiy-storchaka]

It includes three parts:

• Add the code that emits a DeprecationWarning when corresponding functions and arguments are used. It is important to specify the correct stacklevel argument.

• Add tests and/or modify existing test for catching or silencing a DeprecationWarning.

• Document this change: in the module documentation, in the What's New document, and add a news entry.

PR 10139 implements all this.

[serhiy-storchaka]

Sometime we starts with deprecating just in the documentation, if it is hard to add deprecation in the code or adding it will break a lot of working code. But this is not the case. lgettext() was inherently broken in Python 3.

[tirkarthi]

The deprecation notice is added to the docs and deprecation warnings are raised during usage of the functions. As per the PR some of them are deprecated with 3.8 (master) and will be removed by 3.10. But this depends on the discussion over the deprecation cycle. There were cases in the past where issues were raised in bpo for undeprecation (bpo-27172) after being deprecated for several versions. There are also cases where the functions that had to be removed were postponed for removal to a later version instead of the one initially shown in warnings.

# Python 3.7 no warnings

$ python3.7
Python 3.7.1rc2 (v3.7.1rc2:6c06ef7dc3, Oct 13 2018, 05:10:29)
[Clang 6.0 (clang-600.0.57)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> from gettext import NullTranslations
>>> NullTranslations().lgettext("test")
b'test'

# PR branch

(pr_10139) ./python.exe
Python 3.8.0a0 (heads/master:4e3a53bcee, Oct 26 2018, 23:44:23)
[Clang 7.0.2 (clang-700.1.81)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> from gettext import NullTranslations
>>> NullTranslations().lgettext("test")
<stdin>:1: DeprecationWarning: lgettext() is deprecated, use gettext() instead
b'test'

Hope it helps

[bradengroom]

Thanks! I'll check out the linked PR. I've seen a few deprecation issues that I couldn't pick up just because I wasn't clear on the deprecation process. Is this documented anywhere in the development guides? I wasn't able to find it if it exists. Is there any interest in adding a section for this?

[serhiy-storchaka]

New changeset fec35c9 by Serhiy Storchaka in branch 'master':
bpo-33710: Deprecate l*gettext() and related functions in the gettext module. (GH-10139)
fec35c9

[serhiy-storchaka]

See PEP-4.

[bradengroom]

Ah. Thank you

[tirkarthi]

It seems like the docs have a note that these functions were removed in Python 3.10 but they probably missed the release. Doc : https://docs.python.org/3.10/library/gettext.html#gettext.lgettext