nab-python 0.0.1__py3-none-any.whl

nab_python/lockfile.py

@@ -0,0 +1,238 @@
+"""PEP 751 lockfile (``pylock.toml``) emission for nab-python.
+
+Public surface for producing lockfiles from a resolve. The three
+emitters are :func:`write_lock` (PEP 751 ``pylock.toml``),
+:func:`write_requirements_with_hashes`, and
+:func:`write_requirements_without_hashes`. Per-tuple pins from a
+universal resolve are collapsed into one ``Package`` per distinct
+``(name, version, source)`` with a marker disjoining the matching
+tuples; same-version tuples emit a single entry with no marker.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+from ._lockfile.builder import (
+    MissingHashError,
+    build_lock_input_from_provider,
+    read_lockfile_anchor,
+)
+from ._lockfile.disjointness import DisjointnessError
+from ._lockfile.pylock import build_pylock, write_lock
+from ._lockfile.requirements import (
+    write_requirements_with_hashes,
+    write_requirements_without_hashes,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+    from datetime import datetime
+
+    from ._vendor.packaging.markers import Marker
+
+
+__all__ = [
+    "ACCEPTED_HASH_ALGORITHMS",
+    "LOCK_VERSION",
+    "DisjointnessError",
+    "IndexPin",
+    "LocalPin",
+    "LockInput",
+    "MissingHashError",
+    "PinShape",
+    "Provenance",
+    "SdistArtifact",
+    "VcsPin",
+    "WheelArtifact",
+    "build_lock_input_from_provider",
+    "build_pylock",
+    "read_lockfile_anchor",
+    "write_lock",
+    "write_requirements_with_hashes",
+    "write_requirements_without_hashes",
+]
+
+
+logger = logging.getLogger(__name__)
+
+LOCK_VERSION = "1.0"
+ACCEPTED_HASH_ALGORITHMS: tuple[str, ...] = ("sha256", "sha384", "sha512")
+
+
+def _select_primary_digest(
+    hashes: tuple[tuple[str, str], ...],
+) -> tuple[str, str] | None:
+    by_algo = dict(hashes)
+    for algo in ACCEPTED_HASH_ALGORITHMS:
+        if algo in by_algo:
+            return algo, by_algo[algo]
+    return None
+
+
+@dataclass(frozen=True, slots=True)
+class WheelArtifact:
+    """A single wheel file to record in the lockfile.
+
+    ``hashes`` is the set of (algorithm, digest) pairs the index
+    published.  PEP 751 mandates at least one hash per artefact;
+    nab requires at least one of ``sha256``, ``sha384``, ``sha512``
+    so the lockfile is consumable by pip's hash-checking mode.
+    """
+
+    filename: str
+    url: str
+    hashes: tuple[tuple[str, str], ...]
+    size: int | None = None
+
+    @property
+    def primary_digest(self) -> tuple[str, str]:
+        """Return ``(algo, digest)`` of the strongest acceptable hash."""
+        chosen = _select_primary_digest(self.hashes)
+        if chosen is None:
+            msg = f"{self.filename} has no acceptable hash"
+            raise ValueError(msg)
+        return chosen
+
+
+@dataclass(frozen=True, slots=True)
+class SdistArtifact:
+    """An sdist tarball to record in the lockfile.
+
+    See :class:`WheelArtifact` for the meaning of ``hashes``.
+    """
+
+    filename: str
+    url: str
+    hashes: tuple[tuple[str, str], ...]
+    size: int | None = None
+
+    @property
+    def primary_digest(self) -> tuple[str, str]:
+        """Return ``(algo, digest)`` of the strongest acceptable hash."""
+        chosen = _select_primary_digest(self.hashes)
+        if chosen is None:
+            msg = f"{self.filename} has no acceptable hash"
+            raise ValueError(msg)
+        return chosen
+
+
+@dataclass(frozen=True, slots=True)
+class IndexPin:
+    """A package resolved from a Simple-API index.
+
+    ``index`` is the URL of the Simple-API root that served the
+    package, matching what PEP 751 expects for ``packages.index``.
+    """
+
+    name: str
+    version: str
+    index: str
+    sdist: SdistArtifact | None = None
+    wheels: tuple[WheelArtifact, ...] = ()
+    requires_python: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class LocalPin:
+    """A package resolved from a local checkout.
+
+    ``path`` is the absolute filesystem path the resolver was pointed
+    at.  Lockfile consumers walk the same tree to install.
+    """
+
+    name: str
+    version: str
+    path: str
+
+
+@dataclass(frozen=True, slots=True)
+class VcsPin:
+    """A package resolved from a VCS clone."""
+
+    name: str
+    version: str
+    repo_url: str
+    commit_id: str
+    subdirectory: str | None = None
+
+
+PinShape = IndexPin | LocalPin | VcsPin
+
+
+@dataclass(frozen=True, slots=True)
+class Provenance:
+    """Optional ``[tool.nab]`` provenance block written into the lock.
+
+    PEP 751 lets tools record any additional metadata under
+    ``[tool.<name>]`` so long as it does not affect installation.
+    nab uses the slot to record the inputs that produced the lock:
+    a reader can audit a committed lockfile without re-running.
+
+    Every field is informational.  The lockfile reader MUST NOT
+    feed any of it into the install path.
+    """
+
+    nab_version: str
+    created_at: datetime
+    command_line: tuple[str, ...]
+    input_path: str
+    mode: str
+    python_specifier: str | None = None
+    platforms: tuple[str, ...] = ()
+
+    def to_block(self) -> dict[str, Any]:
+        """Render to the dict the TOML writer drops under ``[tool.nab]``."""
+        block: dict[str, Any] = {
+            "nab-version": self.nab_version,
+            "created-at": self.created_at,
+            "command-line": list(self.command_line),
+            "input-path": self.input_path,
+            "mode": self.mode,
+        }
+        if self.python_specifier is not None:
+            block["python-specifier"] = self.python_specifier
+        if self.platforms:
+            block["platforms"] = list(self.platforms)
+        return block
+
+
+@dataclass
+class LockInput:
+    """Everything the writer needs to produce a Pylock.
+
+    ``pins`` is keyed by canonical package name; each value is the
+    single pin chosen for that package across the resolve.
+
+    ``per_tuple_pins`` is the per-tuple expansion when a universal
+    resolve produced different pins for different environments.  The
+    writer collapses these into one or more ``Package`` entries with
+    markers attached.  When ``per_tuple_pins`` is empty, ``pins`` is
+    used directly with no markers.
+
+    ``tuple_markers`` maps each tuple label (the keys of
+    ``per_tuple_pins``) to the PEP 508 marker that selects that
+    tuple.  The writer uses these to build per-package markers.
+
+    ``environments`` is the lockfile-level set of permitted
+    environments (PEP 751 ``environments``).  Independent from
+    ``tuple_markers``; intended for declaring the universe.
+
+    ``provenance`` is optional metadata about the inputs that
+    produced this lock.  When present, it lands in the ``[tool.nab]``
+    block of the emitted ``pylock.toml``.
+    """
+
+    pins: Mapping[str, PinShape] = field(default_factory=dict)
+    per_tuple_pins: Mapping[str, Mapping[str, PinShape]] = field(default_factory=dict)
+    tuple_markers: Mapping[str, Marker] = field(default_factory=dict)
+    tuple_environments: Mapping[str, Mapping[str, str]] = field(default_factory=dict)
+    environments: list[Marker] = field(default_factory=list)
+    requires_python: str | None = None
+    created_by: str = "nab"
+    extras: tuple[str, ...] = ()
+    dependency_groups: tuple[str, ...] = ()
+    default_groups: tuple[str, ...] = ()
+    provenance: Provenance | None = None

nab_python/metadata.py

@@ -0,0 +1,145 @@
+"""Minimal METADATA parser for nab-python.
+
+Extracts only the fields needed for dependency resolution from PEP
+566/643 METADATA files (RFC 822 format).  Lighter than
+:class:`packaging.metadata.Metadata` (no validation pass) and reuses
+:class:`packaging.requirements.Requirement` parsing through an
+LRU cache so repeated dep strings parse once.
+"""
+
+from __future__ import annotations
+
+import email.parser
+from dataclasses import dataclass, field
+from functools import lru_cache
+from typing import Any
+
+import tomli
+
+from ._vendor.packaging.requirements import Requirement
+from ._vendor.packaging.specifiers import SpecifierSet
+from ._vendor.packaging.version import Version
+
+__all__ = [
+    "DEPENDENCY_FIELDS",
+    "WheelMetadata",
+    "intern_version",
+    "load_static_project",
+    "parse_metadata",
+]
+
+
+# ``[project].dynamic`` keys that disqualify the static reader.
+# When either appears the build backend may override the declared
+# values, so PEP 621 does not guarantee the table is authoritative.
+_DYNAMIC_FIELD_BLOCKERS = frozenset({"dependencies", "optional-dependencies"})
+
+
+def load_static_project(text: str) -> dict[str, Any] | None:
+    """Return the ``[project]`` table when it can be trusted as static.
+
+    Returns ``None`` when the TOML cannot be parsed, the
+    ``[project]`` table is missing or malformed, or
+    ``project.dynamic`` includes ``dependencies`` /
+    ``optional-dependencies`` (in which case the static reader can
+    not provide either).
+    """
+    try:
+        data = tomli.loads(text)
+    except tomli.TOMLDecodeError:
+        return None
+    project = data.get("project")
+    if not isinstance(project, dict):
+        return None
+    dynamic_raw = project.get("dynamic")
+    if isinstance(dynamic_raw, list):
+        dynamic_set = {d for d in dynamic_raw if isinstance(d, str)}
+        if _DYNAMIC_FIELD_BLOCKERS & dynamic_set:
+            return None
+    return project
+
+
+# PEP 643 dependency-affecting METADATA fields, lowercased.
+# Intersect with WheelMetadata.dynamic to detect wheels whose dep
+# declarations may change at build time.
+DEPENDENCY_FIELDS = frozenset({"requires-dist", "provides-extra"})
+
+
+@lru_cache(maxsize=16384)
+def _parse_requirement_cached(req_str: str) -> Requirement:
+    """Cache ``Requirement(req_str)`` parsing across wheel metadata.
+
+    The same dep strings (``numpy>=1.26``, ``pydantic<3``, etc.) recur
+    across many wheels in a dependency graph.  ``Requirement`` exposes
+    only read operations (specifier, marker, extras, name) so sharing
+    parsed objects is safe.
+    """
+    return Requirement(req_str)
+
+
+@lru_cache(maxsize=65536)
+def intern_version(version_str: str) -> Version:
+    """Return a shared :class:`Version` for ``version_str``.
+
+    The same version string recurs across the per-platform wheels of a
+    project (and across projects that publish the same number).  Sharing
+    the parsed object saves the PEP 440 regex walk on every duplicate.
+    ``Version`` is immutable in ``packaging``, so the shared instance
+    is safe.
+    """
+    return Version(version_str)
+
+
+@dataclass
+class WheelMetadata:
+    """Parsed fields from a wheel's METADATA file."""
+
+    name: str
+    version: Version
+    requires_python: SpecifierSet | None = None
+    requires_dist: list[Requirement] = field(default_factory=list)
+    provides_extra: list[str] = field(default_factory=list)
+    metadata_version: str | None = None
+    dynamic: frozenset[str] = field(default_factory=frozenset)
+
+
+def parse_metadata(data: str | bytes) -> WheelMetadata:
+    """Parse a METADATA file and return the fields needed for resolution."""
+    if isinstance(data, bytes):
+        data = data.decode("utf-8")
+
+    msg = email.parser.Parser().parsestr(data)
+
+    name = msg.get("Name")
+    if name is None:
+        err = "METADATA missing required Name field"
+        raise ValueError(err)
+
+    version_str = msg.get("Version")
+    if version_str is None:
+        err = "METADATA missing required Version field"
+        raise ValueError(err)
+
+    requires_python_str = msg.get("Requires-Python")
+    requires_python = SpecifierSet(requires_python_str) if requires_python_str else None
+
+    requires_dist = [
+        _parse_requirement_cached(r) for r in msg.get_all("Requires-Dist") or []
+    ]
+
+    provides_extra = list(msg.get_all("Provides-Extra") or [])
+
+    metadata_version = msg.get("Metadata-Version")
+    # PEP 643 field names are case-insensitive per RFC 822; normalise so
+    # downstream lookups don't depend on the producer's capitalisation.
+    dynamic = frozenset(d.lower() for d in msg.get_all("Dynamic") or [])
+
+    return WheelMetadata(
+        name=name,
+        version=intern_version(version_str),
+        requires_python=requires_python,
+        requires_dist=requires_dist,
+        provides_extra=provides_extra,
+        metadata_version=metadata_version,
+        dynamic=dynamic,
+    )