GV

GeezerVison

The World Wide Web, restored to 800 pixels of glory.

Home|About|Gaming cabinet|Archives|How it works|Starter sites

On this site

  • Sign in
  • ActionsCI/CD and automation
  • CodespacesCloud development environments
  • All Features
  • Documentation
  • Training
  • Certifications
  • Build with Copilot
  • Customize Copilot
  • Integrations
  • Trending repos
  • GitHub Sponsors
  • Developer articles
  • Enterprises

This view

  • Original page
  • New address

GeezerVison is showing github.com — gh-148641: Implement PEP 829 - startup configuration files by warsaw · Pull Request #149109 · python/cpython

Conversation

@warsaw

@warsaw warsaw commented Apr 28, 2026 •
edited by github-actions Bot
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Member
  • Issue: Implement PEP 829 - Package Startup Configuration #148641

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions
warsaw added 23 commits March 31, 2026 17:13
@warsaw
Prototype of package.site.toml files
f05e9f6
@warsaw
Merge branch 'main' into pth2toml
1f697e6
@warsaw
Validate [metadata].schema_version
594f347
It's okay to be missing, but if it's given it must be an expected
version (i.e. currently, 1).
@warsaw
Added PEP 829 draft
ca6e4ed
@warsaw
Update and refine PEP 829
508f493
@warsaw
Merge branch 'main' into pth2toml
72b4d9a
@warsaw
Checkpointing reference implementation updates
390de9f
* Add _print_error() helper function for printing exceptions to sys.stderr.  These are not hidden
  behind -v
* `warnings` can be lazy imported.
* Since the site.toml file is no longer proposed, rewrite how .pth and .start files are parsed and
  processed.
* addpackage() -- which was never documented -- is deprecated; there are a few usages in the wild so
  we can't get rid of it, but it's generally unnecessary now, has different semantics.
* Update tests
@warsaw
Fix phase ordering
8454716
@warsaw
Fix docs and tests for PEP 829
3e99f25
@warsaw
Trim the out-of-date site.py docstring
e1eaffb
@warsaw
Fix some tests
caab85c
@warsaw
A couple more improvements
e393af0
@warsaw
Merge branch 'main' into pth2toml
bc92325
@warsaw
Remove unused import
9b0b977
@warsaw
Blurb It
1804f68
@warsaw
Merge branch 'main' into pth2toml
1bc0ac4
@warsaw
Add a migration guide for pth->start files
cdcd9cd
@warsaw
Merge branch 'main' into pth2toml
88465c1
@warsaw
Update site.rst documentation
d969ae6
@warsaw
Merge branch 'python:main' into pth2toml
d5eb74d
@warsaw
Merge branch 'pth2toml' into warsaw/829
981d42b
@warsaw
Implement PEP 829 - startup configuration files
6eb25da
@warsaw
Add comment for the future
77e73c2
@warsaw warsaw self-assigned this Apr 28, 2026
@warsaw
warsaw requested a review from FFY00 as a code owner April 28, 2026 16:55
@bedevere-app bedevere-app Bot added the awaiting core review label Apr 28, 2026
@bedevere-app bedevere-app Bot mentioned this pull request Apr 28, 2026
Implement PEP 829 - Package Startup Configuration #148641
Closed
warsaw added 2 commits April 28, 2026 09:55
@warsaw
Merge branch 'main' into warsaw/829
c6c4252
@warsaw
Remove accidental PEP file
e3be2af
@read-the-docs-community

read-the-docs-community Bot commented Apr 28, 2026 •
edited
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown

Documentation build overview

📚 cpython-previews | 🛠️ Build #32516357 | 📁 Comparing 5019131 against main (2b6a137)

  🔍 Preview build  

54 files changed · ± 54 modified

± Modified

  • contents.html
  • genindex-B.html
  • genindex-C.html
  • genindex-D.html
  • genindex-E.html
  • genindex-H.html
  • genindex-I.html
  • genindex-L.html
  • genindex-O.html
  • genindex-P.html
  • and 44 more...
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

warsaw added 5 commits May 2, 2026 10:29
@warsaw
Merge branch 'main' into warsaw/829
e4a1271
@warsaw
Checkpointing review changes
615c6e6
* flush_pth_start() -> process_startup_files()
* Move around some versionchanged and deprecated-removed sections
* Add: kw-only arg `defer_processing_start_files` in several places to ensure that the
  reverse-engineered semantics of the undocumented functions are preserved.
@warsaw
Clean up some tests since the semantics have been updated
7b7795a
@warsaw
Make PthFile.create() a context manager for cleaner code
e8edb52
@warsaw
Clean up some comments
92d4fab
@warsaw

warsaw commented May 3, 2026

Copy link
Copy Markdown
Member Author

I have made the requested changes; please review again

@ncoghlan

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@bedevere-app bedevere-app Bot added awaiting change review and removed awaiting changes labels May 3, 2026
@bedevere-app

bedevere-app Bot commented May 3, 2026

Copy link
Copy Markdown

Thanks for making the requested changes!

@brettcannon, @ncoghlan: please review the changes made to this pull request.

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@bedevere-app
bedevere-app Bot requested a review from ncoghlan May 3, 2026 02:15
@warsaw
Merge branch 'main' into warsaw/829
e34dd6f
@warsaw

warsaw commented May 3, 2026 via email

Copy link
Copy Markdown
Member Author
I just saw this after resolving all the previous comments. Please take a look at the updates I just pushed. I see what you’re suggesting, although that does seem like a larger change to make. See what you think of the current PR branch.
…
On May 2, 2026, at 18:38, Alyssa Coghlan ***@***.***> wrote: @ncoghlan commented on this pull request. In Lib/site.py: > if reset: + flush_pth_start() Yeah, I didn't see a way to reliably infer the intent from the existing args, hence suggesting a new keyword arg. That has the benefit of letting sitecustomize and usercustomize authors invoke similar batch processing behaviour. The other way we could do it is instead of passing in a keyword boolean and updating global variables, we could instead define a StartupFiles helper class with the pending sets on each instance, and accept a pending_startup: StartupFiles | None parameter on each of the functions that modify the pending sets. Then actually running the startup files would be a StartupFiles.process instance method rather than a new module level function. (I only thought of that approach just now, otherwise I would have suggested it in my review comments) — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you authored the thread.Message ID: ***@***.***>
ncoghlan reacted with rocket emoji
All reactions
  • 🚀 1 reaction

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

ncoghlan
ncoghlan approved these changes May 3, 2026
View reviewed changes

@ncoghlan ncoghlan left a comment

Copy link
Copy Markdown
Contributor

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

Thanks @warsaw, this iteration looks good for 3.15b1 to me (one minor parameter naming nitpick, but it's in an API detail I'd like to revisit in more depth for 3.15b2 anyway, hence I don't think it's a merge blocker)

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions
Comment thread Doc/library/site.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.

@bedevere-app bedevere-app Bot added awaiting merge and removed awaiting change review labels May 3, 2026
@warsaw
Merge branch 'main' into warsaw/829
5019131
@warsaw
warsaw enabled auto-merge (squash) May 3, 2026 16:51
@warsaw
warsaw dismissed brettcannon’s stale review May 3, 2026 16:51

Got approval from @NCoughlan

@warsaw

warsaw commented May 3, 2026 •
edited
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Member Author

Argh! Sorry for the typo in the review dismissal. GH doesn't actually autocomplete in that dialog and it can't be edited. Approval was received from @ncoghlan

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@warsaw
warsaw merged commit 24c4aec into python:main May 3, 2026
51 checks passed

Uh oh!

There was an error while loading. Please reload this page.

@bedevere-app bedevere-app Bot removed the awaiting merge label May 3, 2026
@warsaw
warsaw deleted the warsaw/829 branch May 3, 2026 17:21
@rgommers rgommers mentioned this pull request May 5, 2026
Update editable install support for PEP 829 (.start files) mesonbuild/meson-python#846
Closed
This was referenced May 10, 2026
Local variable "sitedir" is not defined since Python 3.15.0-beta.1 sphinx-doc/sphinx#14426
Open
PEP 829: KeyError: "local variable ''sitedir'' is not defined" #149671
Closed
This was referenced May 11, 2026
🧪 test(conftest): strip broken nspkg.pth files under py3.15 tox-dev/tox#3937
Merged
Drop legacy pkg_resources namespace, use PEP 420 Pylons/pastedeploy#52
Closed
Drop legacy pkg_resources namespace, use PEP 420 repoze/repoze.lru#33
Closed
gaborbernat added a commit to tox-dev/tox that referenced this pull request May 12, 2026
@gaborbernat
🧪 test(conftest): strip broken nspkg.pth files under py3.15 (#3937)
1ad47dd
Six tests in the local subprocess and parallel suites fail on the weekly
Python 3.15 check (run
[25667044284](https://github.com/tox-dev/tox/actions/runs/25667044284))
because every spawned interpreter prints a `KeyError` to stderr before
user code runs, and the assertions compare stderr byte-for-byte.

The noise originates in the legacy `*-nspkg.pth` files shipped by
`PasteDeploy 3.1.0` and `repoze.lru 0.7`, both pulled in transitively by
`devpi-server` → `pyramid`. Those pth files call
`sys._getframe(1).f_locals['sitedir']`, which worked when `site.py`
walked its own frame. PEP 829 (CPython
[#149109](python/cpython#149109)) replaced that
machinery with a deferred `_exec_imports()` that has no `sitedir` local,
so every interpreter startup raises `KeyError: "local variable
''sitedir'' is not defined"`. The regression is tracked upstream in
CPython [#149671](python/cpython#149671).

This is genuinely an upstream problem: the proper fix lives either in
CPython (restoring compatibility with legacy `.pth` hacks, or providing
a migration path) or in `setuptools` (which still generates these pth
files for `namespace_packages=` declarations even though `pkg_resources`
was removed in 82.0.0). The `paste` and `repoze` namespaces would still
resolve via PEP 420 without the `.pth` shim, so the affected packages
could also drop `namespace_packages=` upstream.

Until any of those land, this patch removes the offending pth files at
conftest import — gated by the broken `f_locals['sitedir']` substring so
unrelated namespace pth files are untouched, and wrapped in
`contextlib.suppress(OSError)` to stay idempotent under `xdist` workers
racing on the same file. Revert once the upstream fix is available.
@ncoghlan ncoghlan mentioned this pull request May 22, 2026
PEP 829: resolve the design of the site dir batch processing API #150228
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@StanFromIreland StanFromIreland StanFromIreland left review comments
@ncoghlan ncoghlan ncoghlan approved these changes
@FFY00 FFY00 Awaiting requested review from FFY00 FFY00 is a code owner
@ericsnowcurrently ericsnowcurrently Awaiting requested review from ericsnowcurrently ericsnowcurrently is a code owner
@AA-Turner AA-Turner Awaiting requested review from AA-Turner AA-Turner is a code owner
@brettcannon brettcannon Awaiting requested review from brettcannon

Uh oh!

There was an error while loading. Please reload this page.

Assignees

@warsaw warsaw

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Uh oh!

There was an error while loading. Please reload this page.

4 participants

@warsaw @brettcannon @ncoghlan @StanFromIreland
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.