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
serhiy-storchaka merged 6 commits into from
Aug 13, 2025
+74 −10
Merged

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

Changes from 1 commit
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
26 changes: 18 additions & 8 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
depended, but the forms ``language[_territory][.encoding][@modifier]``
Comment thread
serhiy-storchaka marked this conversation as resolved.
Outdated
and ``language[_territory]`` respectively are typically accepted on all
Copy link
Copy Markdown
Member

@StanFromIreland StanFromIreland Aug 1, 2025

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
Copy Markdown
Member Author

@serhiy-storchaka serhiy-storchaka Aug 1, 2025

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
Copy Markdown
Member Author

@serhiy-storchaka serhiy-storchaka Aug 2, 2025

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
Copy Markdown
Member

@malemburg malemburg Aug 3, 2025

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
Comment thread
StanFromIreland marked this conversation as resolved.
Outdated
platforms it usually looks like ``language[_territory]``.
The language code and encoding may be ``None`` if their values cannot be
Comment thread
malemburg marked this conversation as resolved.
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
Returns the current setting for the given locale category as a tuple containing
language code and encoding. *category* may be one of the :const:`!LC_\*` values
except :const:`LC_ALL`. It defaults to :const:`LC_CTYPE`.
Comment thread
serhiy-storchaka marked this conversation as resolved.
Outdated

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
Comment thread
serhiy-storchaka marked this conversation as resolved.
Outdated
platforms it usually looks like ``language[_territory]``.
Comment thread
malemburg marked this conversation as resolved.
Outdated
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