Skip to content

livery.extensions.python._declared

livery.extensions.python._declared

The declared-imports rule: a package's source imports what its manifest declares.

At import time, a module under a package's src imports only the standard library, the workspace's own members, and the distributions the package's pyproject.toml declares in [project.dependencies]. Inside a function or a method it may also import a distribution an optional extra declares, since importing the module does not run that import. An import under TYPE_CHECKING, or in a try that handles ImportError, is not judged: no run makes the first, and the source runs without the second.

A module a program loads as a plugin, named in one of the program's entry-point groups (footman.tasks and footman.builtin for the runner, pytest11 for pytest), may also import what that program brings: its distribution and the distributions it requires. The program is present whenever such a module runs. A name another member owns is left to the sibling-references step, which judges the edges between members.

Which distribution provides a module is read from the metadata of the distributions the workspace's environment installed, so a module that no installed distribution provides refuses, naming it.

The rule is a step of the layering phase, [phases.layering.declared-imports], over each python package's references answer: the sources a narrowed run reaches, every one otherwise.

Classes:

Name Description
Manifest

What a package's pyproject.toml declares, as the rule reads it.

Functions:

Name Description
declared_imports

The step: refuse each import that no declaration of its package accounts for.

manifest

What package's pyproject.toml declares that the rule reads.

problems

Each import no declaration accounts for, in package and source order.

judged

What source imports that declared does not account for, one line each.

Attributes:

Name Type Description
DEPENDENCIES

DEPENDENCIES module-attribute

DEPENDENCIES = '[project.dependencies]'

Manifest dataclass

Manifest(path: str, dependencies: frozenset[str], extras: Mapping[str, frozenset[str]], plugins: Mapping[str, frozenset[str]])

What a package's pyproject.toml declares, as the rule reads it.

Attributes:

Name Type Description
path str

The file, relative to the workspace root, posix.

dependencies frozenset[str]

The distributions [project.dependencies] names, normalized.

extras Mapping[str, frozenset[str]]

Each optional extra, to the distributions it names, normalized.

plugins Mapping[str, frozenset[str]]

Each module the package names in a plugin entry-point group, to the distributions of the programs that load it.

Methods:

Name Description
loaded_by

The programs that load module as a plugin, or a package above it.

extra_naming

The first optional extra naming one of distributions; empty for none.

path instance-attribute

path: str

dependencies instance-attribute

dependencies: frozenset[str]

extras instance-attribute

extras: Mapping[str, frozenset[str]]

plugins instance-attribute

plugins: Mapping[str, frozenset[str]]

loaded_by

loaded_by(module: str) -> frozenset[str]

The programs that load module as a plugin, or a package above it.

Source code in packages/extensions/python/src/livery/extensions/python/_declared.py
def loaded_by(self, module: str) -> frozenset[str]:
    """The programs that load *module* as a plugin, or a package above it."""
    found: set[str] = set()
    for plugin, programs in self.plugins.items():
        if module == plugin or module.startswith(plugin + "."):
            found |= programs
    return frozenset(found)

extra_naming

extra_naming(distributions: frozenset[str]) -> str

The first optional extra naming one of distributions; empty for none.

Source code in packages/extensions/python/src/livery/extensions/python/_declared.py
def extra_naming(self, distributions: frozenset[str]) -> str:
    """The first optional extra naming one of *distributions*; empty for none."""
    return next(
        (extra for extra, names in self.extras.items() if names & distributions),
        "",
    )

declared_imports

declared_imports(ctx: PhaseContext) -> None

The step: refuse each import that no declaration of its package accounts for.

The sources the run reaches (livery.workshop.selected_files) are judged; every source when the run knows nothing of what changed.

Source code in packages/extensions/python/src/livery/extensions/python/_declared.py
def declared_imports(ctx: PhaseContext) -> None:
    """The step: refuse each import that no declaration of its package accounts for.

    The sources the run reaches ([livery.workshop.selected_files][])
    are judged; every source when the run knows nothing of what changed.
    """
    from livery.extensions.python._parse import RuleContext

    context = RuleContext(
        root=ctx.root, packages=ctx.packages, files=selected_files(ctx)
    )
    found = problems(context)
    if found:
        fail("the sources break the declared-imports rule:\n  " + "\n  ".join(found))

manifest

manifest(package: Package) -> Manifest

What package's pyproject.toml declares that the rule reads.

Source code in packages/extensions/python/src/livery/extensions/python/_declared.py
def manifest(package: Package) -> Manifest:
    """What *package*'s ``pyproject.toml`` declares that the rule reads."""
    from livery.extensions.python._backend import plugin_hosts
    from livery.extensions.python._installed import requirement_name

    pyproject = package.directory / "pyproject.toml"
    data = tomllib.loads(pyproject.read_text("utf-8")) if pyproject.is_file() else {}
    project = cast("dict[str, Any]", data.get("project", {}))
    dependencies = cast("list[str]", project.get("dependencies", []))
    extras = cast("dict[str, list[str]]", project.get("optional-dependencies", {}))
    return Manifest(
        path=f"{package.path}/pyproject.toml",
        dependencies=frozenset(map(requirement_name, dependencies)),
        extras={
            extra: frozenset(map(requirement_name, requirements))
            for extra, requirements in extras.items()
        },
        plugins=plugin_hosts(package),
    )

problems

problems(context: RuleContext) -> list[str]

Each import no declaration accounts for, in package and source order.

A package that holds the python extension is judged, each of its sources under src that the run reaches, as this extension's references answer records them.

Source code in packages/extensions/python/src/livery/extensions/python/_declared.py
def problems(context: RuleContext) -> list[str]:
    """Each import no declaration accounts for, in package and source order.

    A package that holds the python extension is judged, each of its
    sources under ``src`` that the run reaches, as this extension's
    ``references`` answer records them.
    """
    from livery.extensions.python._backend import references
    from livery.workshop import extension_set, neighbours

    around = neighbours(context.packages)
    found: list[str] = []
    for package in context.packages_in_scope():
        if "python" not in extension_set(package):
            continue
        declared = manifest(package)
        shipped = f"{package.path}/src/"
        for source in references(package):
            if not source.path.startswith(shipped):
                continue
            if context.files is not None and source.path not in context.files:
                continue
            found += judged(source, declared, around)
    return found

judged

judged(source: SourceReferences, declared: Manifest, around: Neighbours) -> list[str]

What source imports that declared does not account for, one line each.

Import-time references are judged before lazy ones, and each distribution is named once per source, at the first reference that needs it. A namespace several distributions share is judged through the names under it that the source references, since those decide which distribution the source needs.

Source code in packages/extensions/python/src/livery/extensions/python/_declared.py
def judged(
    source: SourceReferences, declared: Manifest, around: Neighbours
) -> list[str]:
    """What *source* imports that *declared* does not account for, one line each.

    Import-time references are judged before lazy ones, and each
    distribution is named once per source, at the first reference that
    needs it. A namespace several distributions share is judged through
    the names under it that the source references, since those decide
    which distribution the source needs.
    """
    from livery.extensions.python._installed import installed

    judgeable = [
        reference
        for reference in source.references
        if not reference.type_checking and not reference.optional
    ]
    ordered = [
        *(reference for reference in judgeable if not reference.lazy),
        *(reference for reference in judgeable if reference.lazy),
    ]
    names = {reference.name for reference in judgeable}
    programs = declared.loaded_by(source.module)
    reported: set[object] = set()
    found: list[str] = []
    for reference in ordered:
        name = reference.name
        if _standard(name) or _member(name, around):
            continue
        environment = installed()
        providers = environment.providers(name)
        if not providers:
            top = name.partition(".")[0]
            if top not in reported:
                reported.add(top)
                found.append(
                    f"{source.path} imports {name}, and no distribution installed"
                    " in the workspace's environment provides it: declare the"
                    f" distribution that does in {declared.path}, then"
                    f" `{prog()} sync` installs it; one an optional extra declares"
                    " installs once the package's dev-extras lists that extra"
                )
            continue
        if len(providers) > 1 and any(other.startswith(name + ".") for other in names):
            continue
        allowed = set(declared.dependencies)
        for program in programs:
            allowed |= environment.brings(program)
        if reference.lazy:
            for extra in declared.extras.values():
                allowed |= extra
        if providers & allowed or providers in reported:
            continue
        reported.add(providers)
        found.append(_refusal(source, reference, providers, declared))
    return found