nab-python 0.0.1__py3-none-any.whl

nab_python/_lockfile/builder.py

@@ -0,0 +1,339 @@
+"""Build a :class:`LockInput` from a finished resolve.
+
+The provider's caches still hold the listings the resolver consumed
+when this runs, so artefact hashes and per-file Requires-Python can
+be read directly without a second fetch.  This module also owns the
+``read_lockfile_anchor`` helper used by ``nab lock`` to keep
+``P<n>D`` durations stable across re-locks.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import TYPE_CHECKING, Protocol, overload
+
+import tomli
+
+from nab_index.client import SdistFile, WheelFile
+
+from .._vendor.packaging.utils import canonicalize_name
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Mapping, Sequence
+
+    from nab_index.multi_index import IndexConfig
+
+    from .._vendor.packaging.version import Version
+    from ..lockfile import (
+        IndexPin,
+        LockInput,
+        PinShape,
+        SdistArtifact,
+        VcsPin,
+        WheelArtifact,
+    )
+    from ..provider import DistPolicy, LocalSource, VcsSource
+
+
+__all__ = [
+    "MissingHashError",
+    "build_lock_input_from_provider",
+    "read_lockfile_anchor",
+]
+
+
+class _LockInputIndex(Protocol):
+    """Protocol for the InMemoryIndex slice the builder reads."""
+
+    def get_listing_index(self, package: str) -> str | None:
+        """Return the configured index name that served ``package``."""
+        ...
+
+
+class _LockInputCoordinator(Protocol):
+    """Protocol for the FetchCoordinator slice the builder reads."""
+
+    @property
+    def index(self) -> _LockInputIndex:
+        """The underlying index used to look up serving-index labels."""
+        ...
+
+
+class LockInputProvider(Protocol):
+    """Structural protocol for the provider slice the builder reads.
+
+    Mirrors the public surface :class:`~nab_python.provider.Provider`
+    exposes that :func:`build_lock_input_from_provider` consumes; tests
+    may supply a stub without inheriting the full Provider class.
+    """
+
+    @property
+    def coordinator(self) -> _LockInputCoordinator:
+        """Coordinator used to look up the index that served a listing."""
+        ...
+
+    def local_source_for(self, canonical_name: str, /) -> LocalSource | None:
+        """Return the configured LocalSource for ``canonical_name`` or None."""
+        ...
+
+    def vcs_source_for(self, canonical_name: str, /) -> VcsSource | None:
+        """Return the configured VcsSource for ``canonical_name`` or None."""
+        ...
+
+    def dist_files_for(
+        self, canonical_name: str, version: Version, /
+    ) -> list[WheelFile | SdistFile]:
+        """Return the listing slice that matches ``(canonical_name, version)``."""
+        ...
+
+    def effective_dist_policy(self, canonical_name: str, /) -> DistPolicy:
+        """Return the effective :class:`DistPolicy` for ``canonical_name``."""
+        ...
+
+
+class MissingHashError(ValueError):
+    """A distribution chosen by the resolver has no usable hash.
+
+    PEP 751 requires at least one hash per artefact.  When an index
+    serves a wheel or sdist without a ``hashes`` map (rare on PyPI,
+    common on file:// indexes), the lock writer cannot emit a
+    spec-compliant entry.  Surface the failure with the offending
+    package and filename so the user can either add a hash to their
+    local index or exclude the package.
+    """
+
+
+def read_lockfile_anchor(path: Path) -> datetime | None:
+    """Return the ``[tool.nab].created-at`` timestamp from ``path`` if any.
+
+    Used by ``nab lock`` to keep ``P<n>D`` durations stable across
+    re-locks: the anchor used for the previous resolve is read back
+    and reused unless the user passes ``--upgrade``.
+
+    Returns ``None`` when ``path`` does not exist, is not valid TOML,
+    is not a PEP 751-shaped pylock, or is missing the ``[tool.nab]``
+    block.  Naive timestamps (no timezone offset) are coerced to UTC
+    for symmetry with the writer; this is informational provenance, so
+    a missing offset is recoverable rather than fatal.
+    """
+    if not path.is_file():
+        return None
+    try:
+        with path.open("rb") as f:
+            data = tomli.load(f)
+    except (OSError, tomli.TOMLDecodeError):
+        return None
+    raw = data.get("tool", {}).get("nab", {}).get("created-at")
+    if isinstance(raw, datetime):
+        return raw if raw.tzinfo else raw.replace(tzinfo=timezone.utc)
+    if isinstance(raw, str):
+        try:
+            dt = datetime.fromisoformat(raw)
+        except ValueError:
+            return None
+        return dt if dt.tzinfo else dt.replace(tzinfo=timezone.utc)
+    return None
+
+
+def build_lock_input_from_provider(
+    provider: LockInputProvider,
+    pins: Mapping[str, Version],
+    *,
+    requires_python: str | None = None,
+    extras: Sequence[str] = (),
+    dependency_groups: Sequence[str] = (),
+    default_groups: Sequence[str] = (),
+    created_by: str = "nab",
+    indexes: Sequence[IndexConfig] = (),
+) -> LockInput:
+    """Build a :class:`LockInput` from a finished resolve.
+
+    ``provider`` is the :class:`Provider` that drove the resolve;
+    its caches still hold the listings the resolver consumed.  ``pins``
+    is the canonical-name -> :class:`Version` mapping returned by the
+    resolver after extras keys have been stripped.
+
+    ``dependency_groups`` lists the PEP 735 groups whose requirements
+    were folded into this resolve; ``default_groups`` is the subset
+    that a default install (no ``--group`` flag) should apply.
+
+    All wheels and the sdist for each pinned version are recorded so
+    the lockfile is portable across architectures of the same Python.
+    """
+    from ..lockfile import LocalPin, LockInput
+
+    lock_pins: dict[str, PinShape] = {}
+    for raw_name, version in pins.items():
+        canonical = canonicalize_name(raw_name)
+        local_source = provider.local_source_for(canonical)
+        if local_source is not None:
+            lock_pins[canonical] = LocalPin(
+                name=canonical,
+                version=str(version),
+                path=str(Path(local_source.path).resolve()),
+            )
+            continue
+        vcs_source = provider.vcs_source_for(canonical)
+        if vcs_source is not None:
+            lock_pins[canonical] = _vcs_pin_from_source(canonical, version, vcs_source)
+            continue
+        lock_pins[canonical] = _index_pin_from_listing(
+            provider, canonical, version, indexes
+        )
+    return LockInput(
+        pins=lock_pins,
+        requires_python=requires_python,
+        created_by=created_by,
+        extras=tuple(extras),
+        dependency_groups=tuple(dependency_groups),
+        default_groups=tuple(default_groups),
+    )
+
+
+def _index_pin_from_listing(
+    provider: LockInputProvider,
+    canonical: str,
+    version: Version,
+    indexes: Sequence[IndexConfig],
+) -> IndexPin:
+    """Construct an :class:`IndexPin` for an index-served package.
+
+    The recorded ``index`` is the URL of the configured index that
+    served the package's listing during the resolve, looked up from
+    the coordinator's :class:`InMemoryIndex` (which records the
+    serving index by name) and resolved against ``indexes`` for the
+    URL.  When ``indexes`` is empty or the route is unknown the URL
+    falls back to the default Simple-API root.
+
+    Under :attr:`~nab_python.provider.DistPolicy.SDIST_INSTALL` the
+    package's wheels stayed in ``versions_cache`` as a possible
+    metadata source for the resolver; only the sdist is emitted
+    into the lock so installers download and build that archive.
+    """
+    from ..fetch import DEFAULT_INDEX_URL
+    from ..lockfile import IndexPin, SdistArtifact, WheelArtifact
+    from ..provider import DistPolicy
+
+    files = list(provider.dist_files_for(canonical, version))
+    if provider.effective_dist_policy(canonical) is DistPolicy.SDIST_INSTALL:
+        files = [f for f in files if not isinstance(f, WheelFile)]
+
+    wheels = tuple(
+        _build_artifact(canonical, f, WheelArtifact)
+        for f in files
+        if isinstance(f, WheelFile)
+    )
+    sdist_file = next((f for f in files if isinstance(f, SdistFile)), None)
+    sdist = (
+        _build_artifact(canonical, sdist_file, SdistArtifact)
+        if sdist_file is not None
+        else None
+    )
+    requires_python = _common_requires_python(files)
+    serving_name = provider.coordinator.index.get_listing_index(canonical)
+    by_name = {ix.name: ix.url for ix in indexes}
+
+    if serving_name is not None and serving_name in by_name:
+        index_url = by_name[serving_name]
+    elif indexes:
+        index_url = indexes[0].url
+    else:
+        index_url = DEFAULT_INDEX_URL
+    return IndexPin(
+        name=canonical,
+        version=str(version),
+        index=index_url,
+        sdist=sdist,
+        wheels=wheels,
+        requires_python=requires_python,
+    )
+
+
+@overload
+def _build_artifact(
+    canonical: str,
+    source: WheelFile | SdistFile,
+    cls: type[WheelArtifact],
+) -> WheelArtifact: ...
+@overload
+def _build_artifact(
+    canonical: str,
+    source: WheelFile | SdistFile,
+    cls: type[SdistArtifact],
+) -> SdistArtifact: ...
+def _build_artifact(
+    canonical: str,
+    source: WheelFile | SdistFile,
+    cls: type[WheelArtifact | SdistArtifact],
+) -> WheelArtifact | SdistArtifact:
+    hashes = _filter_acceptable_hashes(canonical, source.filename, source.hashes)
+    return cls(
+        filename=source.filename,
+        url=source.url,
+        hashes=hashes,
+        size=source.size,
+    )
+
+
+def _filter_acceptable_hashes(
+    canonical: str, filename: str, hashes: tuple[tuple[str, str], ...]
+) -> tuple[tuple[str, str], ...]:
+    """Return the subset of ``hashes`` whose algorithm is consumable.
+
+    Pip's hash-checking mode and PEP 751 both accept any of sha256,
+    sha384, or sha512; nab forwards every recorded entry so consumers
+    can pick.  Raise :class:`MissingHashError` when none of the
+    acceptable algorithms are present.
+    """
+    from ..lockfile import ACCEPTED_HASH_ALGORITHMS
+
+    accepted = tuple(
+        (algo, digest)
+        for algo, digest in sorted(hashes)
+        if algo in ACCEPTED_HASH_ALGORITHMS
+    )
+    if not accepted:
+        algos = sorted({algo for algo, _ in hashes})
+        msg = (
+            f"{canonical}: artefact {filename!r} has no acceptable hash"
+            f" (need one of {list(ACCEPTED_HASH_ALGORITHMS)!r}, got {algos!r})"
+        )
+        raise MissingHashError(msg)
+    return accepted
+
+
+def _common_requires_python(files: Iterable[WheelFile | SdistFile]) -> str | None:
+    """Return a single Requires-Python value if all files agree, else ``None``."""
+    seen: set[str] = set()
+    for f in files:
+        if f.requires_python is not None:
+            seen.add(f.requires_python)
+    if len(seen) == 1:
+        return next(iter(seen))
+    return None
+
+
+def _vcs_pin_from_source(canonical: str, version: Version, source: VcsSource) -> VcsPin:
+    """Build a :class:`VcsPin` from a :class:`VcsSource`.
+
+    The commit id is the ``@<ref>`` portion of the source URL when
+    present, parsed via :class:`nab_index.vcs.VcsRequest`.  Unparseable
+    URLs fall through to an empty commit id; the source URL itself is
+    recorded verbatim.
+    """
+    from nab_index.vcs import VcsCloneError, VcsRequest
+
+    from ..lockfile import VcsPin
+
+    try:
+        parsed = VcsRequest.parse(source.url)
+        commit_id = parsed.ref
+    except VcsCloneError:
+        commit_id = ""
+    return VcsPin(
+        name=canonical,
+        version=str(version),
+        repo_url=source.url,
+        commit_id=commit_id,
+    )

nab_python/_lockfile/disjointness.py

@@ -0,0 +1,207 @@
+"""Per-name marker disjointness validation for the PEP 751 emitter.
+
+PEP 751 forbids two ``[[packages]]`` entries with the same name from
+firing under one install context.  This module owns the validator
+that enumerates the install-context universe (environments x extras
+powerset x dependency-groups powerset) and reports any pair that
+collide, plus the bookkeeping helpers that prune the powerset axes
+to the marker variables a same-name candidate actually references.
+"""
+
+from __future__ import annotations
+
+import functools
+import itertools
+import re
+from collections import defaultdict
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Mapping, Sequence
+    from collections.abc import Set as AbstractSet
+
+    from .._vendor.packaging.markers import Marker
+    from .._vendor.packaging.pylock import Package
+
+
+__all__ = [
+    "DisjointnessError",
+]
+
+
+class DisjointnessError(ValueError):
+    """Two same-name ``[[packages]]`` entries can fire under one context.
+
+    PEP 751 forbids ambiguous installer matches.  When more than one
+    same-name entry has a marker that holds for the same install
+    context, the consumer cannot pick deterministically.  The
+    validator surfaces the colliding name, the witness context
+    (environment + extras + groups), and the colliding versions so
+    the producer can either change the resolution or declare a
+    conflict.
+    """
+
+
+def validate_marker_disjointness(
+    packages: Sequence[Package],
+    *,
+    environments: Mapping[str, Mapping[str, str]],
+    extras: Sequence[str],
+    groups: Sequence[str],
+) -> None:
+    """Confirm same-name ``[[packages]]`` entries are pairwise disjoint.
+
+    Builds the universe of install contexts as the cartesian product
+    of declared environments, the powerset of declared ``extras``,
+    and the powerset of declared ``dependency_groups``.  For every
+    point in that universe and every package name, evaluates each
+    candidate entry's marker.  When two or more entries hold for the
+    same point, raises :class:`DisjointnessError` with the witness.
+
+    The empty-environments path skips validation: a producer that
+    does not declare a universe cannot specify what "all envs" means
+    and the validator would over-report when entries have ``marker
+    is None``.  Callers that emit per-tuple markers (universal
+    mode) populate ``LockInput.tuple_environments`` from the
+    matrix.
+
+    Powerset pruning: ``extras`` and ``dependency_groups`` are PEP
+    685 / PEP 735 marker variables that markers may or may not
+    reference.  Materialising the full ``2**N`` powerset is
+    intractable for projects that declare many extras.  Inspect each
+    marker's string form via :func:`_referenced_membership_names`
+    and only iterate the powerset over names that any marker
+    actually mentions.  When no marker references a variable, that
+    powerset collapses to ``{()}`` and the cartesian explosion
+    disappears.
+    """
+    if not environments:
+        return
+    by_name: defaultdict[str, list[Package]] = defaultdict(list)
+    for pkg in packages:
+        by_name[str(pkg.name)].append(pkg)
+    same_name_entries = [entries for entries in by_name.values() if len(entries) > 1]
+    if not same_name_entries:
+        return
+    candidate_markers = [pkg.marker for entries in same_name_entries for pkg in entries]
+    relevant_extras = _restrict_to_referenced(extras, candidate_markers, "extras")
+    relevant_groups = _restrict_to_referenced(
+        groups, candidate_markers, "dependency_groups"
+    )
+    extras_subsets = list(_powerset(relevant_extras))
+    group_subsets = list(_powerset(relevant_groups))
+    for entries in same_name_entries:
+        name = str(entries[0].name)
+        for env_label, env_dict in environments.items():
+            for extra_subset in extras_subsets:
+                for group_subset in group_subsets:
+                    context: dict[str, str | AbstractSet[str]] = dict(env_dict)
+                    context["extras"] = frozenset(extra_subset)
+                    context["dependency_groups"] = frozenset(group_subset)
+                    matching = [
+                        pkg for pkg in entries if _marker_holds(pkg.marker, context)
+                    ]
+                    if len(matching) <= 1:
+                        continue
+                    versions = sorted(
+                        str(p.version) if p.version else "" for p in matching
+                    )
+                    msg = (
+                        f"{name}: {len(matching)} entries fire under"
+                        f" env={env_label!r} extras={sorted(extra_subset)!r}"
+                        f" groups={sorted(group_subset)!r}: versions={versions}"
+                    )
+                    raise DisjointnessError(msg)
+
+
+@functools.cache
+def _membership_name_pattern(variable: str) -> re.Pattern[str]:
+    """Compile (and cache) the regex matching ``"NAME" [not] in <variable>``.
+
+    Used to detect which extras / dependency-group names a marker
+    references.  PEP 508 reserves ``extras`` (PEP 685) and
+    ``dependency_groups`` (PEP 735) as bare-token marker variables,
+    so a literal-vs-variable membership test always serialises as
+    ``"<lit>" [not] in <var>`` after :func:`Marker.__str__`
+    normalisation.  Rejected alternatives: walking
+    ``Marker._markers`` (private packaging API) or vendoring
+    ``Marker.as_ast()`` from packaging PR #1145 (still open; loses
+    operand-vs-variable distinction in the proposed shape).
+    """
+    return re.compile(
+        r"""(['"])([^'"]*)\1\s+(?:not\s+)?in\s+""" + re.escape(variable) + r"\b",
+        re.IGNORECASE,
+    )
+
+
+def _referenced_membership_names(
+    markers: Iterable[Marker | None], variable: str
+) -> tuple[frozenset[str], bool]:
+    """Return the literals any marker tests for membership in ``variable``.
+
+    ``variable`` is one of ``"extras"`` or ``"dependency_groups"``;
+    a literal ``"foo"`` referenced as ``"foo" in extras`` (or its
+    ``not in`` form) lands in the result.  The regex matches
+    ``str(marker)`` because :class:`Marker` re-emits a canonical
+    form where the literal is always quoted and the variable is
+    always a bare token.
+
+    Also returns a flag set when *any* marker contains the bare
+    ``variable`` token; callers can use it to detect unusual marker
+    shapes that mention the variable but did not match the regex
+    (a future PEP form, a comparison flipped to put the variable
+    on the LHS, etc.) and fall back to a safe over-approximation.
+    """
+    pattern = _membership_name_pattern(variable)
+    bare_token = re.compile(r"\b" + re.escape(variable) + r"\b")
+    found: set[str] = set()
+    has_bare_reference = False
+    for marker in markers:
+        if marker is None:
+            continue
+        text = str(marker)
+        if bare_token.search(text):
+            has_bare_reference = True
+        for match in pattern.finditer(text):
+            found.add(match.group(2))
+    return frozenset(found), has_bare_reference
+
+
+def _restrict_to_referenced(
+    declared: Sequence[str],
+    markers: Sequence[Marker | None],
+    variable: str,
+) -> tuple[str, ...]:
+    """Restrict ``declared`` to the subset that any marker references.
+
+    ``variable`` is the marker token (``"extras"`` or
+    ``"dependency_groups"``).  The intersection of declared names
+    and regex-matched literals shrinks the powerset axis to what
+    the markers actually depend on.  When the bare token appears
+    in some marker but no literals were extracted (an unusual form
+    the regex did not anticipate), fall back to the full declared
+    list so the validator over-approximates rather than silently
+    misses a collision.
+    """
+    referenced, has_bare = _referenced_membership_names(markers, variable)
+    if not has_bare:
+        return ()
+    if not referenced:
+        return tuple(declared)
+    return tuple(name for name in declared if name in referenced)
+
+
+def _marker_holds(
+    marker: Marker | None, context: Mapping[str, str | AbstractSet[str]]
+) -> bool:
+    """Return True when ``marker`` is absent or evaluates True under ``context``."""
+    if marker is None:
+        return True
+    return bool(marker.evaluate(dict(context)))
+
+
+def _powerset(items: Sequence[str]) -> Iterable[tuple[str, ...]]:
+    """Yield every subset of ``items`` as a sorted tuple, including ``()``."""
+    seen = sorted(set(items))
+    for r in range(len(seen) + 1):
+        yield from itertools.combinations(seen, r)