Skip to content

⚡ perf(import): defer pyproject-api modules - #377

Merged
gaborbernat merged 2 commits into
mainfrom
perf/lazy-imports
Nov 18, 2026
Merged

gaborbernat merged 2 commits into
mainfrom
perf/lazy-imports

Conversation

@gaborbernat

@gaborbernat gaborbernat commented Nov 18, 2026 •

Copy link
Copy Markdown
Member

Importing pyproject-api or opening its CLI help previously loaded frontend modules that those paths did not use. In a paired 60-run Python 3.15 hyperfine benchmark, package import measured 39.9 → 7.5 ms.

The public API, CLI, frontend transport, and backend script declare eligible lazy imports, so build operations load their dependencies when called. flake8-lazy checks those declarations. The backend script retains Python 2.7 compatible syntax, and earlier Python versions ignore the declarations.

Benchmarks

Each workload and Python version has one hyperfine 2.0.0 --warmup 5 --runs 60 --metrics time_wall_clock:ms,memory_peak_resident:MiB invocation comparing the PR with its merge base. Raw output reports wall time and peak resident memory. Both commands used the same interpreter and dependencies in a tox environment; PYTHONPATH selected the source tree. Python 3.14 ignores the lazy declarations.

Python 3.15

Package import

Benchmark 1: Before (60 runs)
                mean     ±       σ          min     …     max
  Wall Time     39.9 ms  ±     1.4 ms      36.4 ms  …    43.5 ms
  Memory        18.5 MiB ±     0.5 MiB     17.2 MiB …    19.5 MiB
 
Benchmark 2: After (60 runs)
                mean     ±       σ          min     …     max
  Wall Time      7.5 ms  ±     0.5 ms       6.6 ms  …     9.1 ms           -81.2%  (5.3x faster)
  Memory         9.4 MiB ±     0.3 MiB      8.5 MiB …     9.8 MiB          -49.1%  (2.0x less)

CLI help

Benchmark 1: Before (60 runs)
                mean     ±       σ          min     …     max
  Wall Time     47.4 ms  ±     1.7 ms      44.0 ms  …    50.9 ms
  Memory        19.9 MiB ±     0.4 MiB     18.6 MiB …    20.8 MiB
 
Benchmark 2: After (60 runs)
                mean     ±       σ          min     …     max
  Wall Time     27.0 ms  ±     1.3 ms      24.4 ms  …    30.2 ms           -43.1%  (1.8x faster)
  Memory        14.8 MiB ±     0.5 MiB     13.0 MiB …    15.5 MiB          -25.7%

Python 3.14

Package import

Benchmark 1: Before (60 runs)
                mean     ±       σ          min     …     max
  Wall Time     39.2 ms  ±     1.7 ms      36.6 ms  …    44.4 ms
  Memory        19.5 MiB ±     0.6 MiB     17.7 MiB …    20.4 MiB
 
Benchmark 2: After (60 runs)
                mean     ±       σ          min     …     max
  Wall Time     38.0 ms  ±     2.0 ms      35.4 ms  …    44.9 ms            -2.9%
  Memory        19.6 MiB ±     0.5 MiB     18.4 MiB …    20.4 MiB           +0.8%

CLI help

Benchmark 1: Before (60 runs)
                mean     ±       σ          min     …     max
  Wall Time     39.1 ms  ±     1.8 ms      36.6 ms  …    43.5 ms
  Memory        19.9 MiB ±     0.6 MiB     18.3 MiB …    20.7 MiB
 
Benchmark 2: After (60 runs)
                mean     ±       σ          min     …     max
  Wall Time     39.5 ms  ±     1.7 ms      36.2 ms  …    47.7 ms            +1.0%
  Memory        19.8 MiB ±     0.7 MiB     18.4 MiB …    20.7 MiB           -0.4%

Import-time profile

Lifeguard scanned the source tree with --python-version 3.15. I also imported 6 modules separately with python -X importtime.

These are one-run cumulative import timings for the modules with the largest reductions:

Module Before After
pyproject_api._backend 46.3 ms 2.0 ms

The Python 3.15 package import diagrams use python -X importtime -c "import pyproject_api" 2> import.log and tuna.

Before

Before import tree

After

After import tree

Importing the public API and opening CLI help load frontend dependencies
before either path uses them on Python 3.15. Defer eligible modules until
their operations run.
@gaborbernat gaborbernat added the enhancement New feature or request label Nov 18, 2026
@gaborbernat
gaborbernat marked this pull request as draft November 18, 2026 07:46
@gaborbernat
gaborbernat marked this pull request as ready for review November 18, 2026 08:45
@gaborbernat
gaborbernat merged commit 42aae2b into main Nov 18, 2026
30 checks passed
@gaborbernat
gaborbernat deleted the perf/lazy-imports branch November 18, 2026 21:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant