Title: gh-161708: Document the __lazy_import__ built-in function by RoryGlenn · Pull Request #161762 · python/cpython · GitHub
Open Graph Title: gh-161708: Document the __lazy_import__ built-in function by RoryGlenn · Pull Request #161762 · python/cpython
X Title: gh-161708: Document the __lazy_import__ built-in function by RoryGlenn · Pull Request #161762 · python/cpython
Description: Document __lazy_import__ for programmatic lazy imports at module scope, including its arguments, namespace requirements, lazy proxy behavior and eager fallback. Link the entry from the language reference and built-in functions table.
Use a direct function reference in the table, widen its fourth column and remove the obsolete lazy-import substitution. Preserve the local type links and describe the eager result as __import__ would return it.
Sphinx lint, a fresh HTML build with warnings treated as errors, and rendered wording/table/link checks passed. Runtime tests were not run for this documentation-only change.
Related PR #161716 covers the C docstring; this PR covers the reference documentation.
Prepared with OpenAI Codex assistance.
Issue: gh-161708
Validation
GIT_NO_LAZY_FETCH=1 git --no-optional-locks diff --check 039658b302bb0bf4caca95671cc8008741d466de HEAD -- Doc/builtins/functions.rst — exit 0
/cache/cpython-pr-161762-docs/bin/sphinx-lint --enable=default-role Doc/builtins/functions.rst Doc/reference/simple_stmts.rst — exit 0
make -C Doc html VENVDIR=/cache/cpython-pr-161762-docs JOBS=4 SPHINXOPTS='--fresh-env --write-all' — exit 0
`python3 -B - <<'PY'
import html
from pathlib import Path
import re
root = Path('Doc/build/html')
functions_path = root / 'builtins/functions.html'
reference_path = root / 'reference/simple_stmts.html'
functions = functions_path.read_text(encoding='utf-8')
reference = reference_path.read_text(encoding='utf-8')
for anchor in ('func-lazy-import', 'lazy_import__'):
assert functions.count(f'id="{anchor}"') == 1, anchor
table = re.search(r' Open Graph Description: Document __lazy_import__ for programmatic lazy imports at module scope, including its arguments, namespace requirements, lazy proxy behavior and eager fallback. Link the entry from the language ref...
X Description: Document __lazy_import__ for programmatic lazy imports at module scope, including its arguments, namespace requirements, lazy proxy behavior and eager fallback. Link the entry from the language ref...
Opengraph URL: https://github.com/python/cpython/pull/161762
X: @github
Domain: github.com
Links:
Viewport: width=device-width
]*>', '', cells[3]))
assert last_column.index('import()') < last_column.index('lazy_import()')
for anchor in re.findall(r'href="#([^"]+)"', table):
assert functions.count(f'id="{anchor}"') == 1, anchor
for anchor in ('func-dict', 'func-list', 'func-range'):
assert f'href="#{anchor}"' in table, anchor
section = functions.split('id="lazy_import__"', 1)[1].split('', 1)[0]
visible = ' '.join(html.unescape(re.sub(r'<[^>]>', '', section)).split())
for wording in (
'Use this function for programmatic lazy imports.',
'Otherwise, use a lazy import statement.',
'The function must be called at module scope.',
'Calling it from a function or class body raises SyntaxError.',
'dictionary containing a builtins entry.',
'If locals is omitted or None, it defaults to globals.',
'result as import() would do.',
):
assert wording in visible, wording
assert 'normally a types.ModuleType instance' not in visible
assert 'Use a substitution because' not in html.unescape(re.sub(r'<[^>]>', '', functions))
assert 'id="lazy-imports"' in reference
for origin, href in (
(functions_path, '../reference/simple_stmts.html#lazy-imports'),
(functions_path, '../library/types.html#types.LazyImportType'),
(functions_path, '../library/sys.html#sys.set_lazy_imports_filter'),
(reference_path, '../builtins/functions.html#lazy_import__'),
):
assert f'href="{href}"' in origin.read_text(encoding='utf-8'), href
target, anchor = href.split('#', 1)
assert (origin.parent / target).read_text(encoding='utf-8').count(f'id="{anchor}"') == 1, href
print('Rendered wording, table, anchors and links passed')
PY` — exit 0
`python3 -B - <<'PY'
import html
from pathlib import Path
import re
root = Path('Doc/build/html')
functions_path = root / 'builtins/functions.html'
reference_path = root / 'reference/simple_stmts.html'
functions = functions_path.read_text(encoding='utf-8')
reference = reference_path.read_text(encoding='utf-8')
for anchor in ('func-lazy-import', 'lazy_import__'):
assert functions.count(f'id="{anchor}"') == 1, anchor
table = re.search(r'
]*>', '', cells[3]))
assert last_column.index('import()') < last_column.index('lazy_import()')
for anchor in re.findall(r'href="#([^"]+)"', table):
assert functions.count(f'id="{anchor}"') == 1, anchor
for anchor in ('func-dict', 'func-list', 'func-range'):
assert f'href="#{anchor}"' in table, anchor
section = functions.split('id="lazy_import__"', 1)[1].split('', 1)[0]
visible = ' '.join(html.unescape(re.sub(r'<[^>]>', '', section)).split())
for wording in (
'Use this function for programmatic lazy imports.',
'Otherwise, use a lazy import statement.',
'The function must be called at module scope.',
'Calling it from a function or class body raises SyntaxError.',
'dictionary containing a builtins entry.',
'If locals is omitted or None, it defaults to globals.',
'result as import() would do.',
):
assert wording in visible, wording
assert 'normally a types.ModuleType instance' not in visible
assert 'Use a substitution because' not in html.unescape(re.sub(r'<[^>]>', '', functions))
assert 'id="lazy-imports"' in reference
for origin, href in (
(functions_path, '../reference/simple_stmts.html#lazy-imports'),
(functions_path, '../library/types.html#types.LazyImportType'),
(functions_path, '../library/sys.html#sys.set_lazy_imports_filter'),
(reference_path, '../builtins/functions.html#lazy_import__'),
):
assert f'href="{href}"' in origin.read_text(encoding='utf-8'), href
target, anchor = href.split('#', 1)
assert (origin.parent / target).read_text(encoding='utf-8').count(f'id="{anchor}"') == 1, href
print('PASS: direct function link, four-column table, all local table links, retained anchors and namespace guidance, eager-result wording and language-reference links')
PY` — exit 0
Prepared with AI assistance (Codex gpt-6.1-sol). Independent automated review and verification passed for source tree f7aa0e966cb039f01b1880a5b7bd34efcabed90f. This is automated review. Upstream CI is pending until GitHub reports its result.
react-profiling 0 react-import-map react,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322 route-pattern /:user_id/:repository/pull/:id/files(.:format) route-controller pull_requests route-action files fetch-nonce v2:1e912c12-fc27-baf2-4ff6-8b764b922dd6 current-catalog-service-hash ae870bc5e265a340912cde392f23dad3671a0a881730ffdadd82f2f57d81641b request-id CE1A:14EB6E:141E0D5:1A79060:6B01EFD4 html-safe-nonce 0cba44166af30a47d4d29e4a8f5f2ade9ce03d888c558be17a19ff87befbe230 visitor-payload eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJDRTFBOjE0RUI2RToxNDFFMEQ1OjFBNzkwNjA6NkIwMUVGRDQiLCJ2aXNpdG9yX2lkIjoiNzQ1MTk4NDEyMTExNjYxODcwOSIsInJlZ2lvbl9lZGdlIjoiaWFkIiwicmVnaW9uX3JlbmRlciI6ImlhZCJ9 visitor-hmac 29e0bc9d907e013c8d9e812c3bc0807730c2bb49e50c9b637346e0b8b8102843 hovercard-subject-tag pull_request:5245876450 github-keyboard-shortcuts repository,pull-request-list,pull-request-conversation,pull-request-files-changed,copilot google-site-verification Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I octolytics-url https://collector.github.com/github/collect analytics-location / fb:app_id 1401488693436528 apple-itunes-app app-id=1477376905, app-argument=https://github.com/python/cpython/pull/161762/files twitter:image https://avatars.githubusercontent.com/u/32777747?s=400&v=4 twitter:card summary_large_image og:image https://avatars.githubusercontent.com/u/32777747?s=400&v=4 og:image:alt Document __lazy_import__ for programmatic lazy imports at module scope, including its arguments, namespace requirements, lazy proxy behavior and eager fallback. Link the entry from the language ref... og:site_name GitHub og:type object hostname github.com expected-hostname github.com None 87e774ee7c6b3bee0490394e4d3e57ec9dbc956f74b87ea685dc8996c1676456 turbo-cache-control no-preview diff-view unified go-import github.com/python/cpython git https://github.com/python/cpython.git octolytics-dimension-user_id 1525981 octolytics-dimension-user_login python octolytics-dimension-repository_id 81598961 octolytics-dimension-repository_nwo python/cpython octolytics-dimension-repository_public true octolytics-dimension-repository_is_fork false octolytics-dimension-repository_network_root_id 81598961 octolytics-dimension-repository_network_root_nwo python/cpython turbo-body-classes logged-out env-production page-responsive full-width disable-turbo true browser-stats-url https://api.github.com/_private/browser/stats browser-errors-url https://api.github.com/_private/browser/errors release 423dbb54c5e7bfecc838eb387c1435eb3d0e760d ui-target full theme-color #1e2327 color-scheme light dark
URLs of crawlers that visited me.