flake8-lazy 0.1.0

Detect imports that can be lazy

flake8-lazy

flake8-lazy is a flake8 plugin that finds imports which can be made lazy.

flake8-lazy helps keep import-time overhead low by detecting imports that can be declared as lazy in __lazy_modules__. For this package itself, flake8-lazy --help runs roughly twice as fast when using Python 3.15's new lazy import system.

Error messages will mention __lazy_modules__, but the lazy keyword is supported too.

Install

python -m pip install flake8-lazy

Usually you would include this in some sort of dependency-group in your project, e.g. dev or lint.

flake8 will automatically discover the plugin. There's also a standalone flake8-lazy runner.

Rule codes

1xx: Missing lazy declarations

• LZY101: Missing lazy stdlib module in __lazy_modules__
• LZY102: Missing lazy third-party or local module in __lazy_modules__

2xx: __lazy_modules__ validation

• LZY201: __lazy_modules__ list is not sorted
• LZY202: Module listed in __lazy_modules__ is never imported
• LZY203: Module listed in __lazy_modules__ appears more than once
• LZY204: __lazy_modules__ is assigned after importing modules it names

3xx: Native lazy keyword (Python 3.15+)

• LZY301: Lazy import inside suppress(ImportError) is misleading
• LZY302: Module is declared lazy by both lazy keyword and __lazy_modules__
• LZY303: Module is imported both eagerly and lazily

4xx: Lazy import safety and semantics

• LZY401: Module is declared lazy but accessed at the top level

Basic example

__lazy_modules__ = ["argparse", "pathlib"]

import argparse
import pathlib
import numpy


def run() -> None:
    print(argparse.ArgumentParser)

In this example, numpy is never used at module runtime, so the checker expects it in __lazy_modules__ and emits LZY102.

How detection works

flake8-lazy inspects module-scope imports and module runtime usage.

• Counts top-level import and from ... import ... statements.
• Ignores imports inside functions and classes.
• Treats annotation-only usage as lazy-capable.
• Treats usage inside if TYPE_CHECKING: as type-only.
• Skips from __future__ import ....
• Requires exact module entries for nested imports.

Nested import note:

import email.header

__lazy_modules__ = ["email"]  # Not enough

This emits LZY101; the required entry is "email.header". PEP 810 requires full module names.

Missing relative imports are mentioned as .name, but you need to list the full name, or generate the full name dynamically if you support embedding.

CLI

The project also provides a direct CLI runner:

flake8-lazy path/to/file.py another_file.py
# or
uvx flake8-lazy path/to/file.py another_file.py

Output format matches flake8-style diagnostics:

path/to/file.py:12:0: LZY102 module 'numpy' should be listed in __lazy_modules__

The command exits with status code 1 if any error is found.

Authoring __lazy_modules__

Use a static, sorted list of strings:

__lazy_modules__ = [
    "argparse",
    "numpy",
    "pathlib",
]

Dynamic values are intentionally ignored for now.

Local development

Run tests:

nox -s tests
# or
uv run pytest

Run linting:

nox -s lint
# or
prek -a

Build docs:

nox -s docs --non-interactive

Serve docs locally:

nox -s docs

Acknowledgements

GitHub Copilot in VS Code was used to help develop this package. The Scientific Python Development Guide template was used as a starting point.