Skip to content

livery.extensions.python._reaches

livery.extensions.python._reaches

The private-reaches rule: a source reaching another distribution's privates.

A private is a module or a name with a leading underscore under another distribution's root, imported (guarded or under TYPE_CHECKING alike) or read as an attribute of something imported from there. A test may reach one; a package's source may not, except through the root contract's [[python.private-reaches]], each entry with its reason. An entry no source uses any more refuses, so the list only shrinks. Each distribution's roots are what its build ships, so the roots one wheel ships are one distribution's.

The rule is a step of the layering phase, [phases.layering.private-reaches], judged over the one parse of the python sources (parsed_modules): the files a narrowed run reaches, every source otherwise.

The scan reads names, not types: a private read through a value (current()._x) or named in a string (an entry point, import_module) is not seen.

Functions:

Name Description
private_reaches

The step: refuse each reach outside the allowance, and each unused entry.

problems

Each reach outside the allowance, by its place; each allowance entry unused.

scan

Every reach in modules' sources, by distribution and private, to its places.

allowance

The root contract's allowed reaches: each distribution and private, to why.

Attributes:

Name Type Description
ALLOWANCE

ALLOWANCE module-attribute

ALLOWANCE = '[[python.private-reaches]]'

private_reaches

private_reaches(ctx: PhaseContext) -> None

The step: refuse each reach outside the allowance, and each unused entry.

The files the run reaches (livery.workshop.selected_files) are judged over the one parse; an unused entry is judged on a run over every source alone.

Source code in packages/extensions/python/src/livery/extensions/python/_reaches.py
def private_reaches(ctx: PhaseContext) -> None:
    """The step: refuse each reach outside the allowance, and each unused entry.

    The files the run reaches ([livery.workshop.selected_files][]) are
    judged over the one parse; an unused entry is judged on a run over
    every source alone.
    """
    from livery.extensions.python._parse import RuleContext, parsed_modules

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

problems

problems(modules: tuple[ParsedModule, ...], context: RuleContext) -> list[str]

Each reach outside the allowance, by its place; each allowance entry unused.

An unused entry is judged only when the run reads every source: a narrowed run cannot tell an entry nothing uses from one its scope leaves out.

Source code in packages/extensions/python/src/livery/extensions/python/_reaches.py
def problems(modules: tuple[ParsedModule, ...], context: RuleContext) -> list[str]:
    """Each reach outside the allowance, by its place; each allowance entry unused.

    An unused entry is judged only when the run reads every source: a
    narrowed run cannot tell an entry nothing uses from one its scope
    leaves out.
    """
    reaches = scan(modules, context.packages)
    allowed = allowance(context.root)
    problems = [
        f"{place}: {source} reaches {name}, another distribution's private; make"
        f" the name public where it lives, or allow the reach in the root"
        f" contract's {ALLOWANCE} with its reason"
        for (source, name), places in sorted(reaches.items())
        if (source, name) not in allowed
        for place in places
    ]
    if context.files is None:
        problems += [
            f"workshop.toml: {ALLOWANCE} allows {source} to reach {name}, and no"
            " source reaches it any more; delete the entry"
            for source, name in sorted(allowed)
            if (source, name) not in reaches
        ]
    return problems

scan

scan(modules: tuple[ParsedModule, ...], packages: tuple[Package, ...]) -> dict[tuple[str, str], list[str]]

Every reach in modules' sources, by distribution and private, to its places.

Source code in packages/extensions/python/src/livery/extensions/python/_reaches.py
def scan(
    modules: tuple[ParsedModule, ...], packages: tuple[Package, ...]
) -> dict[tuple[str, str], list[str]]:
    """Every reach in *modules*' sources, by distribution and private, to its places."""
    owners = _owners(packages)
    reaches: dict[tuple[str, str], list[str]] = {}
    for module in modules:
        if module.package is None or module.area != "src":
            continue
        source = module.package.name
        for name, line in _named(module.tree):
            roots = [
                root for root in owners if name == root or name.startswith(root + ".")
            ]
            if not roots:
                continue
            owner = max(roots, key=len)
            below = name[len(owner) :].split(".")
            if owners[owner] == source or not any(map(_private, below)):
                continue
            reaches.setdefault((source, name), []).append(f"{module.relative}:{line}")
    return reaches

allowance

allowance(root: Path) -> dict[tuple[str, str], str]

The root contract's allowed reaches: each distribution and private, to why.

Source code in packages/extensions/python/src/livery/extensions/python/_reaches.py
def allowance(root: Path) -> dict[tuple[str, str], str]:
    """The root contract's allowed reaches: each distribution and private, to why."""
    from livery.workshop import read_contract

    table = read_contract(root).get("python", {})
    entries = table.get("private-reaches", []) if isinstance(table, dict) else []
    return {
        (str(entry["from"]), str(entry["reaches"])): str(entry.get("reason", ""))
        for entry in entries
        if isinstance(entry, dict)
    }