gh-87281: Improve documentation for locale.setlocale() and locale.getlocale() by serhiy-storchaka · Pull Request #137313 · python/cpython

serhiy-storchaka · 2025-08-01T18:35:10Z

Issue: locale.getlocale fails if locale is set #87281

📚 Documentation preview 📚: https://cpython-previews--137313.org.readthedocs.build/

…le.getlocale()

serhiy-storchaka · 2025-08-01T18:45:07Z

Reference to RFC 1766 was incorrect -- RFC 1766 specifies language and territory separated by a minus instead of underscore, and it does not contain much useful information anyway. Also, getlocale() returns the language code in other format on Windows and some other platforms.

getlocale() does not return code "C", it returns (None, None) for the "C" locale.

Added specification of universally accepted formats. Late @modifier will be added for the language code. This will be made less vague when we guarantee these formats.

Doc/library/locale.rst

StanFromIreland · 2025-08-01T18:44:35Z

Doc/library/locale.rst


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


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?

It refers to the locale and the language code strings.

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).

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

The second version you mention is already included in this.

Doc/library/locale.rst

Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>

serhiy-storchaka

Thank you for your grammar fixes @StanFromIreland.

Doc/library/locale.rst

serhiy-storchaka · 2025-08-01T19:48:27Z

Doc/library/locale.rst


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


It refers to the locale and the language code strings.

malemburg

LGTM modulo the small change requests.

malemburg · 2025-08-03T20:45:07Z

Doc/library/locale.rst


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


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

The second version you mention is already included in this.

Doc/library/locale.rst

Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>

Doc/library/locale.rst

Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>

StanFromIreland

LGTM

serhiy-storchaka · 2025-08-12T05:10:09Z

I am going to merge this PR tomorrow if there are no new comments.

miss-islington-app · 2025-08-13T17:49:37Z

Thanks @serhiy-storchaka for the PR 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14.
🐍🍒⛏🤖

…le.getlocale() (pythonGH-137313) Add a section explaining the locale name formats. (cherry picked from commit 15ab457) Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>

bedevere-app · 2025-08-13T17:49:50Z

GH-137722 is a backport of this pull request to the 3.14 branch.

bedevere-app · 2025-08-13T17:49:55Z

GH-137723 is a backport of this pull request to the 3.13 branch.

…ale.getlocale() (GH-137313) (GH-137723) Add a section explaining the locale name formats. (cherry picked from commit 15ab457) Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>

…le.getlocale() (pythonGH-137313) Add a section explaining the locale name formats.

…ale.getlocale() (GH-137313) (#137722) Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>

pythongh-87281: Improve documentation for locale.setlocale() and loca…

60a26f7

…le.getlocale()

serhiy-storchaka requested a review from malemburg August 1, 2025 18:35

serhiy-storchaka added docs Documentation in the Doc dir skip news needs backport to 3.13 bugs and security fixes needs backport to 3.14 bugs and security fixes labels Aug 1, 2025

github-project-automation bot added this to Docs PRs Aug 1, 2025

github-project-automation bot moved this to Todo in Docs PRs Aug 1, 2025

bedevere-app bot added the awaiting core review label Aug 1, 2025

bedevere-app bot mentioned this pull request Aug 1, 2025

locale.getlocale fails if locale is set #87281

Open

StanFromIreland reviewed Aug 1, 2025

View reviewed changes

Apply suggestions from code review

b78ca1b

Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>

serhiy-storchaka commented Aug 1, 2025

View reviewed changes

malemburg approved these changes Aug 3, 2025

View reviewed changes

bedevere-app bot added awaiting merge and removed awaiting core review labels Aug 3, 2025

Add a section for locale names.

10228bc

StanFromIreland reviewed Aug 4, 2025

View reviewed changes

Apply suggestions from code review

53d7bcb

Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>

StanFromIreland reviewed Aug 4, 2025

View reviewed changes

Doc/library/locale.rst Outdated Show resolved Hide resolved

Update Doc/library/locale.rst

1a16363

Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>

StanFromIreland approved these changes Aug 4, 2025

View reviewed changes

Add more links.

d3aa0bd

serhiy-storchaka merged commit 15ab457 into python:main Aug 13, 2025
25 checks passed

github-project-automation bot moved this from Todo to Done in Docs PRs Aug 13, 2025

bedevere-app bot removed the awaiting merge label Aug 13, 2025

serhiy-storchaka deleted the locale-docs branch August 13, 2025 17:49

bedevere-app bot removed the needs backport to 3.14 bugs and security fixes label Aug 13, 2025

bedevere-app bot removed the needs backport to 3.13 bugs and security fixes label Aug 13, 2025

Agent-Hellboy pushed a commit to Agent-Hellboy/cpython that referenced this pull request Aug 19, 2025

pythongh-87281: Improve documentation for locale.setlocale() and loca…

4059f2d

…le.getlocale() (pythonGH-137313) Add a section explaining the locale name formats.

hugovk pushed a commit that referenced this pull request Sep 11, 2025

[3.14] gh-87281: Improve documentation for locale.setlocale() and loc…

374b242

…ale.getlocale() (GH-137313) (#137722) Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>

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

Uh oh!

Conversation

serhiy-storchaka commented Aug 1, 2025 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

serhiy-storchaka commented Aug 1, 2025

Uh oh!

Uh oh!

StanFromIreland Aug 1, 2025

Choose a reason for hiding this comment

Uh oh!

serhiy-storchaka Aug 1, 2025

Choose a reason for hiding this comment

Uh oh!

serhiy-storchaka Aug 2, 2025

Choose a reason for hiding this comment

Uh oh!

malemburg Aug 3, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

serhiy-storchaka left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

serhiy-storchaka Aug 1, 2025

Choose a reason for hiding this comment

Uh oh!

malemburg left a comment

Choose a reason for hiding this comment

Uh oh!

malemburg Aug 3, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

StanFromIreland left a comment

Choose a reason for hiding this comment

Uh oh!

serhiy-storchaka commented Aug 12, 2025

Uh oh!

Uh oh!

miss-islington-app bot commented Aug 13, 2025

Uh oh!

bedevere-app bot commented Aug 13, 2025

Uh oh!

bedevere-app bot commented Aug 13, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

serhiy-storchaka commented Aug 1, 2025 •

edited by github-actions bot

Loading