Skip to content

gh-87281: Improve documentation for locale.setlocale() and locale.getlocale() #137313

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
merged 6 commits into from
Aug 13, 2025
Merged

gh-87281: Improve documentation for locale.setlocale() and locale.getlocale() #137313

Changes from 2 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
60a26f7
gh-87281: Improve documentation for locale.setlocale() and locale.get…
serhiy-storchaka Aug 1, 2025
b78ca1b
Apply suggestions from code review
serhiy-storchaka Aug 1, 2025
10228bc
Add a section for locale names.
serhiy-storchaka Aug 4, 2025
53d7bcb
Apply suggestions from code review
serhiy-storchaka Aug 4, 2025
1a16363
Update Doc/library/locale.rst
serhiy-storchaka Aug 4, 2025
d3aa0bd
Add more links.
serhiy-storchaka Aug 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 19 additions & 9 deletions Doc/library/locale.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,12 +34,18 @@ The :mod:`locale` module defines the following exception and functions:

If *locale* is given and not ``None``, :func:`setlocale` modifies the locale
setting for the *category*. The available categories are listed in the data
description below. *locale* may be a string, or an iterable of two strings
(language code and encoding). If it's an iterable, it's converted to a locale
description below. *locale* may be a string, or a pair,
language code and encoding. If it is a pair, it is converted to a locale
name using the locale aliasing engine. An empty string specifies the user's
default settings. If the modification of the locale fails, the exception
:exc:`Error` is raised. If successful, the new locale setting is returned.

The format of the *locale* and the language code strings is platform
dependent, but the forms ``language[_territory][.encoding][@modifier]``
and ``language[_territory]`` respectively are typically accepted on all
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
and ``language[_territory]`` respectively are typically accepted on all
and ``language[_territory]`` are typically accepted on all

I'm not sure what this is referring to?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It refers to the locale and the language code strings.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If this is not clear, we can only specify format for locale, and then say that the language code has the same format, but without encoding and modifier (support for modifiers will be added in #137253).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd write: "the form language[_territory][.encoding][@modifier] is typically accepted".

The second version you mention is already included in this.

platforms.
The language code and encoding can be ``None``.

If *locale* is omitted or ``None``, the current setting for *category* is
returned.

Expand Down Expand Up @@ -345,22 +351,26 @@ The :mod:`locale` module defines the following exception and functions:
``'LANG'``. The GNU gettext search path contains ``'LC_ALL'``,
``'LC_CTYPE'``, ``'LANG'`` and ``'LANGUAGE'``, in that order.

Except for the code ``'C'``, the language code corresponds to :rfc:`1766`.
*language code* and *encoding* may be ``None`` if their values cannot be
The format of the language code is platform depended, but on Posix
platforms it usually looks like ``language[_territory]``.
The language code and encoding may be ``None`` if their values cannot be
determined.
The "C" locale is represented as ``(None, None)``.

.. deprecated-removed:: 3.11 3.15


.. function:: getlocale(category=LC_CTYPE)

Returns the current setting for the given locale category as sequence containing
*language code*, *encoding*. *category* may be one of the :const:`!LC_\*` values
except :const:`LC_ALL`. It defaults to :const:`LC_CTYPE`.
Returns the current setting for the given locale category as a tuple containing
the language code and encoding. *category* may be one of the :const:`!LC_\*`
values except :const:`LC_ALL`. It defaults to :const:`LC_CTYPE`.

Except for the code ``'C'``, the language code corresponds to :rfc:`1766`.
*language code* and *encoding* may be ``None`` if their values cannot be
The format of the language code is platform dependent, but on Posix
platforms it usually looks like ``language[_territory]``.
The language code and encoding may be ``None`` if their values cannot be
determined.
The "C" locale is represented as ``(None, None)``.


.. function:: getpreferredencoding(do_setlocale=True)
Expand Down
Loading