Skip to content

livery.extensions.python._installed

livery.extensions.python._installed

Read what the environment's installed distributions ship and require.

The declared-imports rule asks the environment two questions: which installed distribution ships the module a source imports, and what a distribution brings with it. Both answers come from the distributions' own metadata (importlib.metadata) beside the running interpreter, which is the workspace's environment when the gate runs, read once per process. The answer reads the same files on every platform: a regular install's RECORD, and the path an editable install's .pth file adds, so a workspace member installed for development and the same distribution installed from its wheel ship the same modules.

Classes:

Name Description
Installed

What the environment's distributions ship, and what each requires.

Functions:

Name Description
normalized

name as distributions are compared: lower case, each run of -_. a dash.

requirement_name

The normalized distribution name a requirement string names; empty for none.

installed

The environment's distributions, read from their metadata once per process.

read_installed

What distributions ship and require, read from their metadata.

Installed dataclass

Installed(modules: Mapping[str, frozenset[str]], requires: Mapping[str, frozenset[str]])

What the environment's distributions ship, and what each requires.

Attributes:

Name Type Description
modules Mapping[str, frozenset[str]]

Each module path a distribution ships, and each package path above it, to the distributions shipping it, by normalized name.

requires Mapping[str, frozenset[str]]

Each installed distribution, by normalized name, to the distributions it requires outside its optional extras.

Methods:

Name Description
providers

The distributions shipping the module that name names; empty for none.

brings

distribution and every distribution it requires, transitively.

modules instance-attribute

modules: Mapping[str, frozenset[str]]

requires instance-attribute

requires: Mapping[str, frozenset[str]]

providers

providers(name: str) -> frozenset[str]

The distributions shipping the module that name names; empty for none.

The longest dotted prefix of name that is a module decides, so yaml.safe_load resolves to the distribution that ships yaml, and a namespace several distributions share to all of them.

Source code in packages/extensions/python/src/livery/extensions/python/_installed.py
def providers(self, name: str) -> frozenset[str]:
    """The distributions shipping the module that *name* names; empty for none.

    The longest dotted prefix of *name* that is a module decides,
    so ``yaml.safe_load`` resolves to the distribution that ships
    ``yaml``, and a namespace several distributions share to all
    of them.
    """
    parts = name.split(".")
    for end in range(len(parts), 0, -1):
        found = self.modules.get(".".join(parts[:end]))
        if found:
            return found
    return frozenset()

brings

brings(distribution: str) -> frozenset[str]

distribution and every distribution it requires, transitively.

A requirement under any marker but an extra's counts, whatever the platform, so the answer is the same on every machine.

Source code in packages/extensions/python/src/livery/extensions/python/_installed.py
def brings(self, distribution: str) -> frozenset[str]:
    """*distribution* and every distribution it requires, transitively.

    A requirement under any marker but an extra's counts, whatever
    the platform, so the answer is the same on every machine.
    """
    found: set[str] = set()
    pending = [normalized(distribution)]
    while pending:
        name = pending.pop()
        if name not in found:
            found.add(name)
            pending.extend(self.requires.get(name, ()))
    return frozenset(found)

normalized

normalized(name: str) -> str

name as distributions are compared: lower case, each run of -_. a dash.

Source code in packages/extensions/python/src/livery/extensions/python/_installed.py
def normalized(name: str) -> str:
    """*name* as distributions are compared: lower case, each run of ``-_.`` a dash."""
    return re.sub(r"[-_.]+", "-", name).lower()

requirement_name

requirement_name(requirement: str) -> str

The normalized distribution name a requirement string names; empty for none.

Source code in packages/extensions/python/src/livery/extensions/python/_installed.py
def requirement_name(requirement: str) -> str:
    """The normalized distribution name a requirement string names; empty for none."""
    match = _NAME.match(requirement)
    return normalized(match.group(1)) if match else ""

installed cached

installed() -> Installed

The environment's distributions, read from their metadata once per process.

Source code in packages/extensions/python/src/livery/extensions/python/_installed.py
@functools.cache
def installed() -> Installed:
    """The environment's distributions, read from their metadata once per process."""
    return read_installed(metadata.distributions())

read_installed

read_installed(distributions: Iterable[Distribution]) -> Installed

What distributions ship and require, read from their metadata.

Source code in packages/extensions/python/src/livery/extensions/python/_installed.py
def read_installed(distributions: Iterable[metadata.Distribution]) -> Installed:
    """What *distributions* ship and require, read from their metadata."""
    modules: dict[str, set[str]] = {}
    requires: dict[str, frozenset[str]] = {}
    for distribution in distributions:
        about = distribution.metadata
        name = normalized(about["Name"]) if "Name" in about else ""
        if not name:
            continue
        requires[name] = requires.get(name, frozenset()) | _required(distribution)
        for module in _shipped(distribution):
            for end in range(1, len(module) + 1):
                modules.setdefault(".".join(module[:end]), set()).add(name)
    return Installed(
        modules={module: frozenset(names) for module, names in modules.items()},
        requires=requires,
    )