PEP 829: `KeyError: "local variable ''sitedir'' is not defined"`

[hugovk]

Bug report

Bug description:

Re-posting from sphinx-doc/sphinx#14426 (comment).

Reproducible with CPython docs:

Details

❯ make -C Doc clean venv html PYTHON=3.15
rm -rf ./venv
rm -rf build/*
Creating venv in ./venv
Using CPython 3.15.0b1 interpreter at: /Library/Frameworks/Python.framework/Versions/3.15/bin/python3.15
Creating virtual environment at: ./venv
Activate with: source venv/bin/activate
warning: The `--pylock` option is experimental and may change without warning. Pass `--preview-features pylock` to disable this warning.
Using Python 3.15.0b1 environment at: venv
Prepared 28 packages in 6ms
Installed 28 packages in 91ms
 + alabaster==1.0.0
 + babel==2.18.0
 + blurb==2.0.0
 + certifi==2026.4.22
 + charset-normalizer==3.4.7
 + docutils==0.21.2
 + idna==3.13
 + imagesize==1.5.0
 + jinja2==3.1.6
 + linklint==1.0.0
 + markupsafe==2.1.5
 + packaging==24.2
 + pygments==2.20.0
 + python-docs-theme==2026.4
 + requests==2.33.1
 + roman-numerals==4.1.0
 + roman-numerals-py==4.1.0
 + snowballstemmer==2.2.0
 + sphinx==8.2.3
 + sphinx-notfound-page==1.0.4
 + sphinxcontrib-applehelp==2.0.0
 + sphinxcontrib-devhelp==2.0.0
 + sphinxcontrib-htmlhelp==2.1.0
 + sphinxcontrib-jsmath==1.0.1
 + sphinxcontrib-qthelp==2.0.0
 + sphinxcontrib-serializinghtml==2.0.0
 + sphinxext-opengraph==0.13.0
 + urllib3==2.6.3
The venv has been created in the ./venv directory
mkdir -p build
Error in import line from /Users/hugo/github/python/cpython/main/Doc/venv/lib/python3.15/site-packages/sphinxcontrib_jsmath-1.0.1-py3.7-nspkg.pth: import sys, types, os;has_mfs = sys.version_info > (3, 5);p = os.path.join(sys._getframe(1).f_locals['sitedir'], *('sphinxcontrib',));importlib = has_mfs and __import__('importlib.util');has_mfs and __import__('importlib.machinery');m = has_mfs and sys.modules.setdefault('sphinxcontrib', importlib.util.module_from_spec(importlib.machinery.PathFinder.find_spec('sphinxcontrib', [os.path.dirname(p)])));m = m or sys.modules.setdefault('sphinxcontrib', types.ModuleType('sphinxcontrib'));mp = (m or []) and m.__dict__.setdefault('__path__',[]);(p not in mp) and mp.append(p)
  Traceback (most recent call last):
    File "<frozen site>", line 319, in _exec_imports
    File "<string>", line 1, in <module>
  KeyError: "local variable ''sitedir'' is not defined"
Error in import line from /Users/hugo/github/python/cpython/main/Doc/venv/lib/python3.15/site-packages/sphinxcontrib_jsmath-1.0.1-py3.7-nspkg.pth: import sys, types, os;has_mfs = sys.version_info > (3, 5);p = os.path.join(sys._getframe(1).f_locals['sitedir'], *('sphinxcontrib',));importlib = has_mfs and __import__('importlib.util');has_mfs and __import__('importlib.machinery');m = has_mfs and sys.modules.setdefault('sphinxcontrib', importlib.util.module_from_spec(importlib.machinery.PathFinder.find_spec('sphinxcontrib', [os.path.dirname(p)])));m = m or sys.modules.setdefault('sphinxcontrib', types.ModuleType('sphinxcontrib'));mp = (m or []) and m.__dict__.setdefault('__path__',[]);(p not in mp) and mp.append(p)
  Traceback (most recent call last):
    File "<frozen site>", line 319, in _exec_imports
    File "<string>", line 1, in <module>
  KeyError: "local variable ''sitedir'' is not defined"
blurb version 2.0.0
Error in import line from /Users/hugo/github/python/cpython/main/Doc/venv/lib/python3.15/site-packages/sphinxcontrib_jsmath-1.0.1-py3.7-nspkg.pth: import sys, types, os;has_mfs = sys.version_info > (3, 5);p = os.path.join(sys._getframe(1).f_locals['sitedir'], *('sphinxcontrib',));importlib = has_mfs and __import__('importlib.util');has_mfs and __import__('importlib.machinery');m = has_mfs and sys.modules.setdefault('sphinxcontrib', importlib.util.module_from_spec(importlib.machinery.PathFinder.find_spec('sphinxcontrib', [os.path.dirname(p)])));m = m or sys.modules.setdefault('sphinxcontrib', types.ModuleType('sphinxcontrib'));mp = (m or []) and m.__dict__.setdefault('__path__',[]);(p not in mp) and mp.append(p)
  Traceback (most recent call last):
    File "<frozen site>", line 319, in _exec_imports
    File "<string>", line 1, in <module>
  KeyError: "local variable ''sitedir'' is not defined"
Error in import line from /Users/hugo/github/python/cpython/main/Doc/venv/lib/python3.15/site-packages/sphinxcontrib_jsmath-1.0.1-py3.7-nspkg.pth: import sys, types, os;has_mfs = sys.version_info > (3, 5);p = os.path.join(sys._getframe(1).f_locals['sitedir'], *('sphinxcontrib',));importlib = has_mfs and __import__('importlib.util');has_mfs and __import__('importlib.machinery');m = has_mfs and sys.modules.setdefault('sphinxcontrib', importlib.util.module_from_spec(importlib.machinery.PathFinder.find_spec('sphinxcontrib', [os.path.dirname(p)])));m = m or sys.modules.setdefault('sphinxcontrib', types.ModuleType('sphinxcontrib'));mp = (m or []) and m.__dict__.setdefault('__path__',[]);(p not in mp) and mp.append(p)
  Traceback (most recent call last):
    File "<frozen site>", line 319, in _exec_imports
    File "<string>", line 1, in <module>
  KeyError: "local variable ''sitedir'' is not defined"
sphinx-build 8.2.3
Building NEWS from Misc/NEWS.d with blurb
Error in import line from /Users/hugo/github/python/cpython/main/Doc/venv/lib/python3.15/site-packages/sphinxcontrib_jsmath-1.0.1-py3.7-nspkg.pth: import sys, types, os;has_mfs = sys.version_info > (3, 5);p = os.path.join(sys._getframe(1).f_locals['sitedir'], *('sphinxcontrib',));importlib = has_mfs and __import__('importlib.util');has_mfs and __import__('importlib.machinery');m = has_mfs and sys.modules.setdefault('sphinxcontrib', importlib.util.module_from_spec(importlib.machinery.PathFinder.find_spec('sphinxcontrib', [os.path.dirname(p)])));m = m or sys.modules.setdefault('sphinxcontrib', types.ModuleType('sphinxcontrib'));mp = (m or []) and m.__dict__.setdefault('__path__',[]);(p not in mp) and mp.append(p)
  Traceback (most recent call last):
    File "<frozen site>", line 319, in _exec_imports
    File "<string>", line 1, in <module>
  KeyError: "local variable ''sitedir'' is not defined"
Error in import line from /Users/hugo/github/python/cpython/main/Doc/venv/lib/python3.15/site-packages/sphinxcontrib_jsmath-1.0.1-py3.7-nspkg.pth: import sys, types, os;has_mfs = sys.version_info > (3, 5);p = os.path.join(sys._getframe(1).f_locals['sitedir'], *('sphinxcontrib',));importlib = has_mfs and __import__('importlib.util');has_mfs and __import__('importlib.machinery');m = has_mfs and sys.modules.setdefault('sphinxcontrib', importlib.util.module_from_spec(importlib.machinery.PathFinder.find_spec('sphinxcontrib', [os.path.dirname(p)])));m = m or sys.modules.setdefault('sphinxcontrib', types.ModuleType('sphinxcontrib'));mp = (m or []) and m.__dict__.setdefault('__path__',[]);(p not in mp) and mp.append(p)
  Traceback (most recent call last):
    File "<frozen site>", line 319, in _exec_imports
    File "<string>", line 1, in <module>
  KeyError: "local variable ''sitedir'' is not defined"
PATH=./venv/bin:$PATH sphinx-build --builder html --doctree-dir build/doctrees --jobs auto   --fail-on-warning . build/html
Error in import line from /Users/hugo/github/python/cpython/main/Doc/venv/lib/python3.15/site-packages/sphinxcontrib_jsmath-1.0.1-py3.7-nspkg.pth: import sys, types, os;has_mfs = sys.version_info > (3, 5);p = os.path.join(sys._getframe(1).f_locals['sitedir'], *('sphinxcontrib',));importlib = has_mfs and __import__('importlib.util');has_mfs and __import__('importlib.machinery');m = has_mfs and sys.modules.setdefault('sphinxcontrib', importlib.util.module_from_spec(importlib.machinery.PathFinder.find_spec('sphinxcontrib', [os.path.dirname(p)])));m = m or sys.modules.setdefault('sphinxcontrib', types.ModuleType('sphinxcontrib'));mp = (m or []) and m.__dict__.setdefault('__path__',[]);(p not in mp) and mp.append(p)
  Traceback (most recent call last):
    File "<frozen site>", line 319, in _exec_imports
    File "<string>", line 1, in <module>
  KeyError: "local variable ''sitedir'' is not defined"
Error in import line from /Users/hugo/github/python/cpython/main/Doc/venv/lib/python3.15/site-packages/sphinxcontrib_jsmath-1.0.1-py3.7-nspkg.pth: import sys, types, os;has_mfs = sys.version_info > (3, 5);p = os.path.join(sys._getframe(1).f_locals['sitedir'], *('sphinxcontrib',));importlib = has_mfs and __import__('importlib.util');has_mfs and __import__('importlib.machinery');m = has_mfs and sys.modules.setdefault('sphinxcontrib', importlib.util.module_from_spec(importlib.machinery.PathFinder.find_spec('sphinxcontrib', [os.path.dirname(p)])));m = m or sys.modules.setdefault('sphinxcontrib', types.ModuleType('sphinxcontrib'));mp = (m or []) and m.__dict__.setdefault('__path__',[]);(p not in mp) and mp.append(p)
  Traceback (most recent call last):
    File "<frozen site>", line 319, in _exec_imports
    File "<string>", line 1, in <module>
  KeyError: "local variable ''sitedir'' is not defined"
Running Sphinx v8.2.3
loading translations [en]... done
matplotlib is not installed, social cards will not be generated
making output directory... done
building [mo]: targets for 0 po files that are out of date
writing output...
building [html]: targets for 548 source files that are out of date
updating environment: [new config] 548 added, 0 changed, 0 removed
reading sources... [100%] whatsnew/changelog .. whatsnew/index
looking for now-outdated files... none found
pickling environment... done
checking consistency... /Users/hugo/github/python/cpython/main/Doc/howto/argparse.rst: document is referenced in multiple toctrees: ['howto/index', 'library/argparse'], selecting: library/argparse <- howto/argparse
done
preparing documents... done
copying assets...
copying downloadable files... [100%] includes/tzinfo_examples.py
copying static files...
Writing evaluated template result to /Users/hugo/github/python/cpython/main/Doc/build/html/_static/basic.css
Writing evaluated template result to /Users/hugo/github/python/cpython/main/Doc/build/html/_static/language_data.js
Writing evaluated template result to /Users/hugo/github/python/cpython/main/Doc/build/html/_static/documentation_options.js
Writing evaluated template result to /Users/hugo/github/python/cpython/main/Doc/build/html/_static/classic.css
Writing evaluated template result to /Users/hugo/github/python/cpython/main/Doc/build/html/_static/sidebar.js
copying static files: done
copying extra files...
copying extra files: done
copying assets: done
writing output... [100%] whatsnew/3.5 .. whatsnew/index
generating indices... genindex py-modindex done
writing additional pages... download index search opensearch done
copying images... [100%] using/win_install_freethreaded.png
dumping search index in English (code: en)... done
dumping object inventory... done
Writing glossary.json
profiling_trace: Injected 38 trace events into profiling-sampling-visualization.js
Linklint: unlinked 3584 refs: 2000 duplicate, 1584 self
build succeeded.

The HTML pages are in build/html.

Build finished. The HTML pages are in build/html.

Minimal repro:

❯ echo "import sys; sys._getframe(1).f_locals['sitedir']" > legacy.pth

❯ python3.14 -c "import site; site.addsitedir('.')"

❯ python3.15 -c "import site; site.addsitedir('.')"
Found existing alias for "python3.15". You should use: "p5"
Error in import line from /Users/hugo/github/python/cpython/main/legacy.pth: import sys; sys._getframe(1).f_locals['sitedir']
  Traceback (most recent call last):
    File "<frozen site>", line 319, in _exec_imports
    File "<string>", line 1, in <module>
      import site; site.addsitedir('.')
                  ~~~~~~~~~~~~~~~~^^^^^
  KeyError: "local variable ''sitedir'' is not defined"

Not reproducible in a8, but is in b1.

Bisects to PEP 829: #149109, cc @warsaw.

CPython versions tested on:

3.15

Operating systems tested on:

macOS

[warsaw]

Given that this is poking into internal undocumented implementation details, I don't consider this a breaking change. Once the fix for #149504 lands, you can use sys._getframe(3), but even that is subject to change, so I wouldn't rely on it. Also, if someone calls addsitedir(..., defer_processing_start_files=True) you might not get the sitedir you think you're getting.

I'd like to understand the use case in more detail so that we can possibly design an API we can make guarantees about. For example, one of the things I've thought about is calling entry points with arguments (currently they're called with no arguments).

That said, I'm tempted to close this as won't fix for 3.15 and we can work out a more principled fix for 3.16.