nab-python 0.0.1__py3-none-any.whl

nab_python/universal/matrix.py

@@ -0,0 +1,235 @@
+"""Matrix expansion for user-declared universal resolution.
+
+Expands a python version range plus a platform list into a finite
+list of tuples, each a complete PEP 508 marker environment the
+single-environment resolver can run against. Every PEP 508 variable
+appearing in any marker on the dep graph must have a value in every
+tuple. Wheel-tag and ``Requires-Python`` filtering happens elsewhere.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from .._vendor.packaging.specifiers import SpecifierSet
+from .._vendor.packaging.version import Version
+from .wheel_selection import PlatformSpec
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+# Common Python minor releases. An unrecognized minor declared in the
+# user range raises.
+__all__ = [
+    "Matrix",
+    "MatrixTuple",
+]
+
+
+_KNOWN_PYTHON_MINORS: tuple[str, ...] = (
+    "3.8",
+    "3.9",
+    "3.10",
+    "3.11",
+    "3.12",
+    "3.13",
+    "3.14",
+)
+
+
+# Defaults filled in for marker keys the user did not specify.  These
+# come from the most common PEP 508 environment values for the named
+# OS/arch.  They are used only for marker *evaluation*; the resolver
+# does not consume them as constraints on its own.
+_PLATFORM_DEFAULTS: dict[str, dict[str, str]] = {
+    "linux_x86_64": {
+        "sys_platform": "linux",
+        "platform_system": "Linux",
+        "platform_machine": "x86_64",
+        "os_name": "posix",
+        "platform_python_implementation": "CPython",
+        "implementation_name": "cpython",
+    },
+    "linux_aarch64": {
+        "sys_platform": "linux",
+        "platform_system": "Linux",
+        "platform_machine": "aarch64",
+        "os_name": "posix",
+        "platform_python_implementation": "CPython",
+        "implementation_name": "cpython",
+    },
+    "macos_arm64": {
+        "sys_platform": "darwin",
+        "platform_system": "Darwin",
+        "platform_machine": "arm64",
+        "os_name": "posix",
+        "platform_python_implementation": "CPython",
+        "implementation_name": "cpython",
+    },
+    "macos_x86_64": {
+        "sys_platform": "darwin",
+        "platform_system": "Darwin",
+        "platform_machine": "x86_64",
+        "os_name": "posix",
+        "platform_python_implementation": "CPython",
+        "implementation_name": "cpython",
+    },
+    "windows_amd64": {
+        "sys_platform": "win32",
+        "platform_system": "Windows",
+        "platform_machine": "AMD64",
+        "os_name": "nt",
+        "platform_python_implementation": "CPython",
+        "implementation_name": "cpython",
+    },
+}
+
+
+@dataclass(frozen=True)
+class MatrixTuple:
+    """A single point in the universal-resolution matrix."""
+
+    python_version: str
+    platform_id: str
+    environment: dict[str, str] = field(hash=False, compare=False)
+    platform_spec: PlatformSpec = field(
+        hash=False,
+        compare=False,
+        default_factory=lambda: PlatformSpec("linux_x86_64"),
+    )
+
+    @property
+    def label(self) -> str:
+        """Return a short human-readable id like ``py311-linux_x86_64``."""
+        return f"py{self.python_version.replace('.', '')}-{self.platform_id}"
+
+    @property
+    def marker_string(self) -> str:
+        """Return a PEP 508 marker that selects this tuple.
+
+        Combines ``python_version``, ``sys_platform``, and
+        ``platform_machine`` into a conjunction.  Universal lockfiles
+        attach this to each per-tuple ``Package`` entry so an installer
+        on a matching environment picks the right pin.
+        """
+        env = self.environment
+        return (
+            f'python_version == "{self.python_version}"'
+            f' and sys_platform == "{env["sys_platform"]}"'
+            f' and platform_machine == "{env["platform_machine"]}"'
+        )
+
+
+@dataclass
+class Matrix:
+    """User-declared universal resolution matrix.
+
+    ``python_order``: ``"asc"`` (default, 3.9 first) or ``"desc"`` (3.13
+    first).  Combined with cross-tuple alignment in the resolver this
+    selects between ``fork-strategy=fewest`` (asc: oldest-Python pin
+    propagates forward, the lowest common version wins) and
+    ``fork-strategy=requires-python`` (desc: newest-Python pin
+    propagates, older Pythons diverge only when the new version is
+    incompatible).
+
+    ``python_patches``: optional ``{minor: full_version}`` mapping that
+    sets the per-tuple ``python_full_version`` marker.  Defaults to
+    ``{minor}.0`` per tuple, which makes markers like
+    ``python_full_version >= "3.11.4"`` evaluate to False on a 3.11
+    tuple.  Users with deployments on later patch releases should
+    declare them here so marker evaluation matches reality.  Example:
+    ``python_patches={"3.11": "3.11.4", "3.12": "3.12.1"}``.
+    See ``universal_open_questions.md`` section 1.1 for the design
+    discussion.
+    """
+
+    python: str
+    platforms: tuple[str | PlatformSpec, ...]
+    python_order: str = "asc"
+    python_patches: dict[str, str] | None = None
+
+    def expand(self) -> list[MatrixTuple]:
+        """Expand the matrix into concrete tuples.
+
+        Validates inputs eagerly: unknown platform ids, an empty
+        python range, or an invalid ``python_order`` each raise a
+        ``ValueError`` before any work happens.
+
+        ``platforms`` accepts either bare platform-id strings (use
+        default tag floors) or :class:`PlatformSpec` instances for
+        per-platform glibc/musl/macOS overrides.
+        """
+        if self.python_order not in {"asc", "desc"}:
+            msg = f"python_order must be 'asc' or 'desc'; got {self.python_order!r}"
+            raise ValueError(msg)
+        specs = [
+            p if isinstance(p, PlatformSpec) else PlatformSpec(p)
+            for p in self.platforms
+        ]
+        unknown = [
+            s.platform_id for s in specs if s.platform_id not in _PLATFORM_DEFAULTS
+        ]
+        if unknown:
+            msg = f"Unknown platform ids: {unknown!r}"
+            raise ValueError(msg)
+        py_versions = list(_pythons_in_range(self.python))
+        if not py_versions:
+            msg = f"No known Python versions match {self.python!r}"
+            raise ValueError(msg)
+        if self.python_order == "desc":
+            py_versions.reverse()
+        patches = self.python_patches or {}
+        return [
+            MatrixTuple(
+                python_version=py,
+                platform_id=spec.platform_id,
+                environment=_build_environment(py, spec, patches.get(py)),
+                platform_spec=spec,
+            )
+            for py in py_versions
+            for spec in specs
+        ]
+
+
+def _build_environment(
+    python_version: str,
+    spec: PlatformSpec,
+    python_full_version: str | None = None,
+) -> dict[str, str]:
+    """Build a complete PEP 508 marker environment for one tuple.
+
+    Combines the platform's OS/arch defaults with python-axis values
+    derived from ``python_version``.  ``platform_release`` and
+    ``platform_version`` come from the :class:`PlatformSpec`; both
+    default to ``""`` so kernel-conditioned markers evaluate False
+    unless the user declares a target kernel/OS version.
+
+    ``python_full_version`` overrides the default ``{minor}.0`` value.
+    Used when the matrix declares ``python_patches`` to make
+    patch-bound markers (``python_full_version >= "3.11.4"``)
+    evaluate against the user's actual deployment patch release.
+    """
+    full = python_full_version or f"{python_version}.0"
+    return {
+        **_PLATFORM_DEFAULTS[spec.platform_id],
+        "python_version": python_version,
+        "python_full_version": full,
+        "implementation_version": full,
+        "platform_release": spec.platform_release,
+        "platform_version": spec.platform_version,
+    }
+
+
+def _pythons_in_range(spec: str) -> Iterable[str]:
+    """Yield known Python minors that satisfy ``spec``.
+
+    ``spec`` is a PEP 440 specifier set, e.g. ``">=3.11, <3.14"``.
+    """
+    parsed = SpecifierSet(spec)
+    for minor in _KNOWN_PYTHON_MINORS:
+        # Use the .0 patch for membership testing so that a >=3.11
+        # specifier admits "3.11" via "3.11.0".
+        candidate = Version(f"{minor}.0")
+        if candidate in parsed:
+            yield minor

nab_python/universal/provider.py

@@ -0,0 +1,214 @@
+"""Provider subclass that accepts a full PEP 508 marker environment.
+
+The stock :class:`nab_python.provider.Provider` only accepts a
+``python_version`` override and inherits everything else from
+``default_environment()`` (the host environment).  Universal resolution
+needs to swap the entire environment per tuple, so this subclass
+overlays a user-supplied dict on top.
+
+Also adds a ``preferences`` knob: a ``{package_name: Version}`` dict
+tried first when choosing a version.  Used for cross-tuple alignment
+("if tuple A picked numpy 2.2.6, ask tuple B to try 2.2.6 first").
+
+Resolution strategy (``highest``/``lowest``/``lowest-direct``) is
+inherited from :class:`Provider` and threaded through via the
+parent's ``resolution_strategy`` and ``direct_packages`` kwargs.
+
+When ``platform_spec`` is supplied, the provider also filters wheel
+candidates by tag compatibility at resolve time (hole 2 in
+``universal_open_questions.md``).  Versions whose only wheels are
+above the spec's manylinux/musllinux/macOS floor become unavailable
+unless an sdist is present and ``build_policy`` allows building.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from nab_index.client import SdistFile, WheelFile
+
+from .._vendor.packaging.markers import default_environment
+from .._vendor.packaging.ranges import VersionRange
+from .._vendor.packaging.utils import canonicalize_name
+from ..provider import (
+    BuildPolicy,
+    DistPolicy,
+    ExtrasMode,
+    LocalSource,
+    Provider,
+    ResolutionStrategy,
+    VcsConfig,
+    VcsSource,
+)
+from .wheel_selection import compatible_tags_for_tuple, wheel_tag_set
+
+__all__ = [
+    "DistFile",
+    "UniversalProvider",
+]
+
+
+DistFile = WheelFile | SdistFile
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+    from datetime import datetime
+    from pathlib import Path
+
+    from nab_resolver.types import RangeProtocol
+
+    from .._vendor.packaging.version import Version
+    from ..config import NabProjectConfig
+    from ..fetch import FetchCoordinator
+    from .wheel_selection import PlatformSpec
+
+
+class UniversalProvider(Provider):
+    """Provider with a user-supplied marker environment + preferences."""
+
+    def __init__(  # noqa: PLR0913 - matches Provider signature
+        self,
+        coordinator: FetchCoordinator,
+        marker_environment: dict[str, str],
+        *,
+        root_requirements: dict[str, VersionRange] | None = None,
+        uploaded_prior_to: datetime | None = None,
+        uploaded_prior_to_overrides: Mapping[str, datetime | None] | None = None,
+        extras_mode: ExtrasMode = ExtrasMode.ERROR_USER,
+        root_extras: set[tuple[str, str]] | None = None,
+        dist_policy: DistPolicy = DistPolicy.WHEEL_OR_SDIST,
+        dist_policy_overrides: Mapping[str, DistPolicy] | None = None,
+        build_policy: BuildPolicy = BuildPolicy.BUILD_LOCAL,
+        build_policy_overrides: Mapping[str, BuildPolicy] | None = None,
+        vcs_config: VcsConfig | None = None,
+        vcs_cache_dir: Path | None = None,
+        local_sources: list[LocalSource] | None = None,
+        vcs_sources: list[VcsSource] | None = None,
+        build_config: NabProjectConfig | None = None,
+        preferences: dict[str, Version] | None = None,
+        resolution_strategy: ResolutionStrategy | str = ResolutionStrategy.HIGHEST,
+        direct_packages: frozenset[str] | None = None,
+        platform_spec: PlatformSpec | None = None,
+    ) -> None:
+        """Create a provider with overlay environment + uv-style preferences."""
+        if isinstance(resolution_strategy, str):
+            try:
+                resolution_strategy = ResolutionStrategy(resolution_strategy)
+            except ValueError as exc:
+                valid = sorted(s.value for s in ResolutionStrategy)
+                msg = (
+                    f"resolution_strategy must be one of {valid!r};"
+                    f" got {resolution_strategy!r}"
+                )
+                raise ValueError(msg) from exc
+        super().__init__(
+            coordinator,
+            python_version=marker_environment.get("python_version"),
+            root_requirements=root_requirements,
+            uploaded_prior_to=uploaded_prior_to,
+            uploaded_prior_to_overrides=uploaded_prior_to_overrides,
+            extras_mode=extras_mode,
+            root_extras=root_extras,
+            dist_policy=dist_policy,
+            dist_policy_overrides=dist_policy_overrides,
+            build_policy=build_policy,
+            build_policy_overrides=build_policy_overrides,
+            vcs_config=vcs_config,
+            local_sources=local_sources,
+            vcs_sources=vcs_sources,
+            vcs_cache_dir=vcs_cache_dir,
+            build_config=build_config,
+            resolution_strategy=resolution_strategy,
+            direct_packages=direct_packages,
+        )
+        merged: dict[str, str] = {
+            key: value
+            for key, value in default_environment().items()
+            if isinstance(value, str)
+        }
+        merged.update(marker_environment)
+        self.environment = merged
+        self.env_with_extra = dict(merged)
+        # Normalize preferences keys so lookup matches the provider's
+        # canonical naming scheme.
+        self._preferences: dict[str, Version] = {
+            canonicalize_name(k): v for k, v in (preferences or {}).items()
+        }
+        self._platform_spec = platform_spec
+        self._py_minor = marker_environment.get("python_version")
+        self.excluded_by_wheel_tags = 0
+        self.excluded_versions_no_compatible_wheel = 0
+
+    def choose_version(
+        self, package: str, version_range: RangeProtocol[Version]
+    ) -> Version | None:
+        """Pick a version under the configured strategy, honoring preferences."""
+        assert isinstance(version_range, VersionRange)
+        _, _, normalized = self.split_and_normalize(package)
+
+        # Preferences win when the version is still in range AND its metadata
+        # is extractable in this tuple; the look-ahead gate matters for
+        # cross-tuple alignment (a candidate that worked elsewhere may be
+        # tag-incompatible or unbuildable here).
+        preferred = self._preferences.get(normalized)
+        if preferred is not None:
+            all_versions = self.versions_only(normalized, self.fetch_versions(package))
+            if preferred in set(version_range.filter(all_versions)) and (
+                self.split_and_normalize(package)[1] is not None
+                or self._look_ahead_ok(normalized, preferred, check_decisions=True)
+            ):
+                self._flush_pending_blocks()
+                return preferred
+
+        return super().choose_version(package, version_range)
+
+    def filter_distributions(
+        self, normalized: str, files: Sequence[WheelFile | SdistFile]
+    ) -> list[tuple[Version, DistFile]]:
+        """Filter parent's result by wheel-tag compatibility.
+
+        Hole 2 plug: a version is unavailable to the resolver if its
+        only wheels are tag-incompatible with this tuple's
+        ``platform_spec``.  Sdists keep the version alive at every
+        :class:`BuildPolicy` level because static PKG-INFO and the
+        bundled ``pyproject.toml`` fallback are read unconditionally;
+        ``BUILD_LOCAL`` adds backend invocation on local checkouts and
+        ``BUILD_REMOTE`` adds it on VCS clones and remote sdists.  The
+        resolver's ``look_ahead_ok`` rejects per-version if metadata
+        extraction actually fails (e.g. dynamic deps with no static
+        fallback under :attr:`BuildPolicy.NEVER`).
+
+        When ``platform_spec`` is unset (legacy callers) the override
+        is a no-op.
+        """
+        base = super().filter_distributions(normalized, files)
+        if self._platform_spec is None or self._py_minor is None:
+            return base
+
+        spec = self._platform_spec
+        py_minor = self._py_minor
+        # Look up the per-tuple compat tag set once outside the per-wheel
+        # loop and inline the membership check; this loop runs for every
+        # wheel of every package on every tuple, so the hoist matters on
+        # large workloads.
+        compat = compatible_tags_for_tuple(python_version=py_minor, spec=spec)
+        kept: list[tuple[Version, DistFile]] = []
+        versions_with_wheel: set[Version] = set()
+        versions_with_sdist: set[Version] = set()
+        for version, dist in base:
+            if isinstance(dist, WheelFile):
+                wheel_tags = wheel_tag_set(dist.filename)
+                if wheel_tags is not None and not wheel_tags.isdisjoint(compat):
+                    kept.append((version, dist))
+                    versions_with_wheel.add(version)
+                else:
+                    self.excluded_by_wheel_tags += 1
+            else:
+                kept.append((version, dist))
+                versions_with_sdist.add(version)
+
+        build_allowed = self.build_policy != BuildPolicy.NEVER
+        usable = versions_with_wheel | (versions_with_sdist if build_allowed else set())
+        all_versions = {v for v, _ in base}
+        self.excluded_versions_no_compatible_wheel += len(all_versions) - len(usable)
+        return [pair for pair in kept if pair[0] in usable]