Skip to content

gh-137337: Clarify import statement namespace binding#144607

Merged
serhiy-storchaka merged 2 commits intopython:mainfrom
kovan:gh-137337-import-namespace
May 4, 2026
Merged

gh-137337: Clarify import statement namespace binding#144607
serhiy-storchaka merged 2 commits intopython:mainfrom
kovan:gh-137337-import-namespace

Conversation

@kovan
Copy link
Copy Markdown
Contributor

@kovan kovan commented Feb 8, 2026

Summary

The import statement documentation says names are defined "in the local namespace," which is inaccurate when the imported name has been declared global or nonlocal:

x = None
def f():
    global x
    import os as x  # Assigns to global namespace, not local

Updates two places in Doc/reference/simple_stmts.rst:

  • The basic import description (step 2): "local namespace" -> "current namespace... just as an assignment statement would, including global, local, and nonlocal semantics"
  • The from ... import description (step 2.d): "local namespace" -> "current namespace"

This follows the wording proposed by @nedbat and discussed with @serhiy-storchaka and @terryjreedy in the issue thread.

Test plan

  • make -C Doc check passes
  • make -C Doc html passes (no warnings)

🤖 Generated with Claude Code


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

The import statement docs said names are defined "in the local
namespace", which is inaccurate when the name has been declared
global or nonlocal.  Update to say "current namespace... just as
an assignment statement would", per discussion with nedbat,
serhiy-storchaka, and terryjreedy.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Copy link
Copy Markdown
Member

@johnslavik johnslavik left a comment

Choose a reason for hiding this comment

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

Cool!

Comment thread Doc/reference/simple_stmts.rst Outdated
the :keyword:`import` statement occurs.
#. define a name or names in the current namespace for the scope where
the :keyword:`import` statement occurs, just as an assignment statement
would, including global, local, and nonlocal semantics.
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Maybe this would be a little clearer?

Suggested change
would, including global, local, and nonlocal semantics.
would (including :keyword:`global` and :keyword:`nonlocal` semantics).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@kovan
Copy link
Copy Markdown
Contributor Author

kovan commented Feb 10, 2026

I have made the requested changes; please review again

@bedevere-app
Copy link
Copy Markdown

bedevere-app Bot commented Feb 10, 2026

Thanks for making the requested changes!

@nedbat: please review the changes made to this pull request.

@bedevere-app bedevere-app Bot requested a review from nedbat February 10, 2026 15:42
@serhiy-storchaka serhiy-storchaka added needs backport to 3.13 bugs and security fixes needs backport to 3.14 bugs and security fixes labels May 4, 2026
@serhiy-storchaka serhiy-storchaka merged commit b8ebd07 into python:main May 4, 2026
39 of 41 checks passed
@github-project-automation github-project-automation Bot moved this from Todo to Done in Docs PRs May 4, 2026
@miss-islington-app
Copy link
Copy Markdown

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

@bedevere-app
Copy link
Copy Markdown

bedevere-app Bot commented May 4, 2026

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

@bedevere-app bedevere-app Bot removed the needs backport to 3.14 bugs and security fixes label May 4, 2026
@bedevere-app
Copy link
Copy Markdown

bedevere-app Bot commented May 4, 2026

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

@bedevere-app bedevere-app Bot removed the needs backport to 3.13 bugs and security fixes label May 4, 2026
serhiy-storchaka pushed a commit that referenced this pull request May 4, 2026
…) (GH-149370)

It is not always in the local namespace.
(cherry picked from commit b8ebd07)

Co-authored-by: Kit Dallege <xaum.io@gmail.com>
serhiy-storchaka pushed a commit that referenced this pull request May 4, 2026
…) (GH-149369)

It is not always in the local namespace.
(cherry picked from commit b8ebd07)

Co-authored-by: Kit Dallege <xaum.io@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs Documentation in the Doc dir skip news

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

4 participants