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

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

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

…le.getlocale()

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.

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.

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

Thank you for your grammar fixes @StanFromIreland.

It refers to the locale and the language code strings.

LGTM modulo the small change requests.

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

The second version you mention is already included in this.

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

LGTM

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

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>

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

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

Comment thread Doc/library/locale.rst Outdated

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

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

+                 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

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

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

Repository navigation

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

gh-87281: Improve documentation for locale.setlocale() and locale.getlocale()#137313serhiy-storchaka merged 6 commits intopython:mainpython/cpython:mainfrom serhiy-storchaka:locale-docsserhiy-storchaka/cpython:locale-docsCopy head branch name to clipboard

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!

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

gh-87281: Improve documentation for locale.setlocale() and locale.getlocale()#137313
serhiy-storchaka merged 6 commits into
python:mainfrom
serhiy-storchaka:locale-docs

serhiy-storchaka commented Aug 1, 2025 •
edited by github-actions Bot
Loading