Skip to main content

pep810

Find, apply and measure PEP 810 lazy imports.

Python 3.15 adds a lazy soft keyword that defers a module's loading until its name is first used. The PEP cites 50–70% off startup and 30–40% off memory on real workloads. What it does not give you is a way to tell which of your imports are safe to defer — and getting that wrong is silent:

import readline   # nothing in this file ever mentions `readline`

Make that lazy and the import never happens at all, because nothing ever touches the name. Interactive line editing quietly stops working. No error, no warning.

PEP 810 anticipates the gap in its own text:

Static analysis tools could detect modules with side effects and automatically configure filters.

pep810 is that tool, plus the two things you need on either side of it: a codemod that applies the answer, and a benchmark that checks the answer was worth applying.

$ pep810 analyze src/
src/myapp/core.py
      4  safe                   import subprocess
         S500: no import-time side effects found; safe to defer
      8  risky                  from . import plugins
         W301: importing myapp.plugins calls atexit.register()

src/myapp/__init__.py
      3  unsafe                 import readline
         E201: `readline` is never used in this module, so the import exists for its
               side effect -- deferring it would cancel the effect, not delay it

3 files, 12 import statements
  safe                   6
  risky                  1
  unsafe                 2
  low-benefit            3

Install

$ pip install pep810

No dependencies. Runs on Python 3.9+ — you do not need 3.15 to analyse or rewrite code for 3.15, only to benchmark it.

The five commands

$ pep810 analyze src/                     # what could be lazy, and what must not be
$ pep810 hotspots src/ -e "import myapp"  # what is actually expensive
$ pep810 apply src/ --write               # rewrite the safe ones
$ pep810 bench -e "import myapp"          # prove it worked
$ pep810 filter src/ -o sitecustomize.py  # or skip the codemod entirely

Plus pep810 check for CI, which fails the build when an import that could be lazy still is not.

analyze

Every import statement gets one of seven decisions:

decision meaning
safe Deferring changes nothing observable. Convert it.
risky Legal, but importing the target has side effects. Read the reason.
unsafe Deferring would change behaviour. Do not convert.
low-benefit Legal and safe, but the name is used at module level anyway.
ineligible PEP 810 does not allow lazy here.
skipped Inside if TYPE_CHECKING: or a __main__ guard; never runs.
already-lazy Nothing to do.

Reasons carry stable codes you can silence like lint rules — E blocks the rewrite, W marks it risky, I is informational:

$ pep810 analyze src/ --ignore W311 --ignore I403

or in pyproject.toml:

[tool.pep810]
ignore = ["W311"]
exclude = ["vendor"]

--format json and --format markdown are there for editors and PR comments.

apply

The rewrite inserts five characters — lazy — before the import or from keyword, and touches nothing else:

-import json
-import subprocess  # for the shell-out
-from xml.etree import (
+lazy import json
+lazy import subprocess  # for the shell-out
+lazy from xml.etree import (
     ElementTree,
 )

Comments, quote styles and parenthesised import lists survive, because the codemod edits bytes rather than round-tripping through an AST. Running it twice is a no-op. Every rewritten file is compiled before it is written; a file that would not compile is left alone and reported.

Without --write you get the diff. With --style lazy-modules you get PEP 810's __lazy_modules__ declaration instead, which is inert before 3.15 — one release that is fast on new Pythons and unchanged on old ones.

filter

The other half of PEP 810. Instead of editing sources, run the whole application with -X lazy_imports=all and let a generated deny-list force back to eager exactly the modules the analysis found unsafe:

$ pep810 filter src/ -o sitecustomize.py --lazy-only myapp
$ python -X lazy_imports=all -m myapp

The generated module installs sys.set_lazy_imports_filter and documents why each module is on the list. Note that PEP 810 consults the filter when an import statement runs, so it has to be installed before your entry point — from sitecustomize or a wrapper, not from the top of main.py.

hotspots and bench

hotspots ranks measured import cost against the analysis, so you know what to do first:

$ pep810 hotspots src/ -e "import myapp"
      cost  verdict        module
   41.2 ms  safe           pandas
   18.7 ms  risky          myapp.plugins
    5.4 ms  low-benefit    myapp.config

312.8 ms of import cost; 214.1 ms sits behind imports the analysis found safe to defer

bench measures the real thing. It uses the interpreter's own switch rather than two copies of your tree — -X lazy_imports=none forces every lazy import back to eager — so both sides run the same files on the same interpreter and differ in exactly one variable:

$ pep810 bench -e "import myapp" --runs 15
eager (-X lazy_imports=none)     412.6 ms process    331.0 ms import  (range 401.2-433.8)  1284 modules  84.2 MiB
lazy (as written)                168.3 ms process     92.4 ms import  (range 161.9-179.4)   412 modules  51.7 MiB

process -59.2%   import -72.1%   memory -38.6%   modules -872
  61 imports still unreified at exit

Startup benchmarks are noisy, so the report carries the spread and says so outright when the two sample ranges overlap. Benchmarking needs a Python 3.15+ interpreter; point --python at one if it is not the interpreter running the tool. pep810 refuses to report a comparison it cannot actually make.

How the analysis decides

Four questions, in this order.

1. Is lazy legal here? PEP 810 restricts it to module scope. Inside a function, a class body, or a try/except/finally block it is a SyntaxError, as are lazy from x import * and lazy from __future__ import.

2. Would deferring change behaviour? The important case is an import whose bound name is never used: it exists for its side effect, and deferring it does not delay the effect, it cancels it. A name that is deleted or rebound at module level is treated the same way. A package __init__ with no __all__ is the exception — there, an unused name is an implicit re-export.

3. What does importing the target do? The target module's top level is scanned for registration, monkeypatching, I/O, global configuration, threads and process exit. Because deferring an import defers everything it pulls in, the walk is transitive, and each finding carries the chain that produced it:

W301: importing myapp.api -> myapp.db reaches myapp.registry, which calls
      atexit.register() (myapp/registry.py:41)

4. Is it worth it? A lazy import reifies the moment its name is touched, so an import used at module level saves nothing. The win is names used only in function bodies — and, since PEP 649, annotations.

Everything is a heuristic, and the tool says which ones it is confident about. --confidence low widens what counts as risky; --confidence high narrows it.

Working on 3.15 source from an older interpreter

lazy import json is a SyntaxError on every Python before 3.15, which would otherwise stop the tool from running on the interpreter most projects are migrating from. pep810 reads and writes PEP 810 source on 3.9+ by finding the soft keywords with tokenize — which knows about strings and comments, so lazy = 1 and "lazy import x" in a docstring are not mistaken for keywords — stripping them for parsing, and mapping the AST's offsets back onto the original bytes.

Library use

from pathlib import Path
from pep810 import analyze_paths, Decision, Policy

result = analyze_paths([Path("src")], Policy(include_low_benefit=True))
for file, verdict in result.verdicts(Decision.SAFE):
    print(f"{file.path}:{verdict.site.lineno} {verdict.site.source_line.strip()}")

The layers underneath are independently useful: pep810.analyzer for import sites and usage, pep810.effects for import-time side effects, pep810.importtime for parsing -X importtime, pep810.codemod for the minimal-diff rewrite.

Limitations

  • Import-time side effects are undecidable in general. The knowledge base covers the calls that show up at the top level of real code; anything unrecognised is reported at low confidence rather than guessed at.
  • Compiled extension modules cannot be analysed. They are reported as opaque.
  • Non-path importers — zipimport, frozen modules, packages that extend __path__ at runtime — resolve as unknown rather than as safe.
  • Star-imported names are invisible to the usage analysis, so a module using from x import * may show false unsafe verdicts. Those imports are ineligible anyway.
  • --include-risky exists, but the name is the recommendation.

Licence

0BSD -- public-domain-equivalent. Use it for anything, with no attribution required.

Metadata

Release files for pep810 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pep810 0.1.0
File Size Uploaded Provenance Actions
pep810-0.1.0.tar.gz 64.4 kB Without provenance Details for pep810-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pep810 0.1.0
File Interpreter ABI Platform Actions
pep810-0.1.0-py3-none-any.whl Python 3 none any Details for pep810-0.1.0-py3-none-any.whl

Total release size: 124.5 kB

Release files / pep810-0.1.0.tar.gz

Download URL pep810-0.1.0.tar.gz
Size 64.4 kB
Tags Source
SHA-256 checksum
How to use checksums
0e04c8a83f4ed04615996df395984d0c5ec7c12e36b3811a88d6351ee0f9dd18
BLAKE2b-256 checksum
How to use checksums
9c21c4c4e64ea368b5e04e863180a5be3958c9521a044928389bc191e97258de
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.6

Release files / pep810-0.1.0-py3-none-any.whl

Download URL pep810-0.1.0-py3-none-any.whl
Size 60.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
07ba1ae2112b09acb5e8cb41abbe8dac6e74fa13b4bdd76a44c26f7bf4fa4d06
BLAKE2b-256 checksum
How to use checksums
8e989c78262ce6b9ae10bf99d93081c6975a50825f6124f580ec1013ef733553
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.6

Security for pep810 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page