Metadata-Version: 2.5
Name: importcost
Version: 0.1.0
Summary: Measure what your imports actually cost, make the safe ones lazy (PEP 810), and stop regressions in CI.
Project-URL: Homepage, https://github.com/aviseth/importcost
Project-URL: Repository, https://github.com/aviseth/importcost
Project-URL: Changelog, https://github.com/aviseth/importcost/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/aviseth/importcost/issues
Author-email: Avi Seth <avi@crispa.ai>
License-Expression: MIT
License-File: LICENSE
Keywords: ci,cold-start,import,importtime,lazy-imports,pep810,performance,profiling,startup
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: System :: Benchmark
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: tomli>=2.0; python_version < '3.11'
Description-Content-Type: text/markdown

# importcost

Find out which imports are actually costing you startup time, defer the ones that can be
deferred, and stop the slow ones from coming back.

Python 3.15 adds `lazy import` ([PEP 810](https://peps.python.org/pep-0810/)). That's the easy
part. The hard part is knowing which of your imports are worth deferring, which ones get loaded
a millisecond later anyway, and which ones quietly break something because they had a side
effect you forgot about. importcost answers all three by running your code, not by reading it.

```shell
pip install importcost
```

## Where is my startup time going

```text
$ importcost profile "import mypkg"
import mypkg  418.3 ms of imports across 261 modules (wall 471.2 ms, median of 5)

self ms  cumul ms  module
   61.4     181.9  pandas
   38.2      38.2  pandas._libs.tslibs.timestamps
   22.7      94.1  requests
   19.8      19.8  numpy.core._multiarray_umath
    9.1      31.4  rich.console
```

`--tree` gives you the nesting if you need to know who pulled in what. `--json` if you want to
pipe it somewhere.

This is `-X importtime` with the interpreter's own baseline subtracted, run five times and
median-ed, because a single run of anything on a laptop is noise.

## Which imports should be lazy

```text
$ importcost audit src --target "import mypkg" --test "pytest -q"

saves ms  verdict  module          why
   181.9  safe     pandas
    94.1  safe     requests
       -  no-win   rich.console    loaded anyway during startup, so deferring it changes nothing
       -  unsafe   mypkg.plugins   deferring this breaks the test command; something depends on
                                   its import side effect
       -  safe     tomllib

418.3 ms of imports today. Deferring the safe ones skips 137 module(s), worth about 276.0 ms
at what they cost now.
3 import(s) clear the 0 ms bar.
```

The `no-win` and `unsafe` rows are the whole point. Static analysis will happily tell you all
five of those imports can be deferred. Two of them can't, and you'd only find out from a
production traceback.

Here's how each verdict is reached:

- **safe**: the module stayed unloaded for the entire run, and the test command still passed
  with it deferred. The saving is what the modules it avoided actually cost in the ordinary
  profile, so it's measured rather than guessed at.
- **no-win**: `sys.set_lazy_imports_filter` approved the deferral, but the module ended up in
  `sys.modules` before the process exited. Something else on the startup path needed it. You'd
  be adding a keyword for nothing.
- **unsafe**: the test command passes normally and fails with this module deferred. When the
  whole set fails, importcost bisects to find which modules are responsible rather than making
  you delete entries one at a time.

The runtime checks need a 3.15 interpreter. `uv python install 3.15` and pass `--python`.
Without one you get static analysis only, and it says so.

## Make the change

```text
$ importcost apply src --target "import mypkg" --min-saving-ms 5 --write
updated src/mypkg/io.py: pandas
updated src/mypkg/http.py: requests
```

Prints a diff by default; `--write` edits in place. Only touches imports that cleared
`--min-saving-ms`, so you don't end up with forty `lazy` keywords that buy you 3 ms total.

Two output styles:

`--style lazy` writes `lazy import pandas`. Needs 3.15.

`--style lazy-modules` writes a `__lazy_modules__` set above the imports and leaves the import
statements alone. That's PEP 810's own migration shim: it's ordinary syntax on 3.9, and it only
does anything on 3.15+. Use it for a library that still supports old Pythons. The set comes out
sorted and deduplicated so [flake8-lazy](https://pypi.org/project/flake8-lazy/) doesn't complain
about it.

## Keep it from creeping back

The reason import time regresses isn't usually a bad commit. It's a dependency upgrade that adds
an at-import metadata fetch, or a new logging integration that costs 50 ms on load. Nothing in
that shows up in code review.

```toml
[tool.importcost]
target = "import mypkg"
max_import_ms = 150
max_modules = 200
```

```text
$ importcost check
ok   import mypkg  118.4 ms, 173 modules
```

`importcost check --update` also writes an `import.lock` next to your pyproject.toml recording
exactly which modules get imported. Commit it. After that, a dependency that starts pulling in
something new fails the check with a diff:

```text
$ importcost check
fail import mypkg  204.7 ms, 189 modules
     import time 204.7 ms is over the 150 ms budget by 54.7 ms
     imported modules no longer match import.lock (16 new: cryptography, cryptography.fernet,
     cryptography.hazmat, ... +13 more). Run 'importcost check --update' if this is intended.
     + cryptography, cryptography.fernet, cryptography.hazmat
```

Times vary by machine, so only the numeric budgets are machine-dependent; the module set isn't,
which is why that's the part that gets pinned.

Several entry points with different budgets:

```toml
[tool.importcost]
trials = 7

[[tool.importcost.budget]]
target = "import mypkg"
max_import_ms = 150

[[tool.importcost.budget]]
target = "-m mypkg.cli"
max_import_ms = 400
```

In GitHub Actions:

```yaml
- run: pip install importcost
- run: importcost check
```

Or as a normal test, if you'd rather keep it with everything else:

```python
def test_import_stays_cheap(import_budget):
    import_budget("import mypkg", max_ms=150, max_modules=200)
```

## How this relates to the other tools

[`flake8-lazy`](https://pypi.org/project/flake8-lazy/) is a linter and a good one. It finds
imports that are unused at module scope and writes `__lazy_modules__` for them. It doesn't
measure anything or run your code, which its author is upfront about. Keep using it. importcost
reads and writes the same `__lazy_modules__` convention, and adds the measurement, the runtime
verification, and the CI guard.

`-X importtime` and [`tuna`](https://pypi.org/project/tuna/) show you where the time goes and
leave the rest to you.

## Notes and caveats

`profile` and `check` work on 3.10+. `audit` and `apply` need a 3.15 interpreter for the runtime
pass; below that they fall back to static analysis and warn.

The audit's safety check is only as good as the command you give `--test`. If your test suite
doesn't touch the code path that relies on an import side effect, neither will importcost.

Savings are priced from the eager profile rather than by subtracting the two runs. Verifying a
proposal means running the interpreter with a Python-level filter callback on every single
import, and that overhead is about the same size as the saving on a small target, so
subtracting the two just gives you noise. Counting the modules that were genuinely skipped, at what they cost when
they ran, is both stable and closer to what you'll see after the change lands.

Verification is scoped to the file the import came from, not to the module name globally.
Writing `lazy import x` in one file doesn't defer `x` for the rest of the program, and neither
does the check. Otherwise auditing a package would defer the package itself and cheerfully
report that everything got faster.

Imports inside `if TYPE_CHECKING:` are skipped: they already cost nothing. Wildcard imports,
`__future__` imports, and imports inside `try`/`except ImportError` are skipped because PEP 810
doesn't allow deferring them. Names in `__all__` are skipped as a conservative default.

Annotations count as import-time uses unless the file has `from __future__ import annotations`.
On 3.14+ with PEP 649 that's stricter than it needs to be; pass the flag if it's costing you
candidates.

importcost has no runtime dependencies on 3.11+ and enforces its own import budget in CI. A
startup-time tool that takes 200 ms to start isn't a good look.

MIT.
