nab-python 0.0.1__py3-none-any.whl

nab_python/_provider/priority.py

@@ -0,0 +1,174 @@
+"""Priority computation for :class:`nab_python.provider.Provider`.
+
+Owns the tier/matching/culprit logic that backs ``prioritize``.
+Affected packages with high conflict counts get tier 0 (decide
+first inside a conflict cluster); runaway top culprits get tier 2
+(uv's deprioritise-on-conflict); everything else gets tier 1.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from nab_resolver.types import RangeProtocol
+
+    from .._vendor.packaging.version import Version
+    from ..provider import Provider
+
+
+CONFLICT_THRESHOLD = 5
+
+# Demotion requires a runaway gap to the second-highest culprit, so
+# co-dominant culprits keep standard ordering.
+CULPRIT_DEMOTE_THRESHOLD = 5
+
+# Lower number = higher priority.
+TIER_AFFECTED = 0
+TIER_NORMAL = 1
+TIER_CULPRIT = 2
+
+# Matching count used while a listing is in flight, so not-yet-fetched
+# packages sort behind ready ones.
+_NO_LISTING_PRIOR = 1000
+
+
+def compute_tier(
+    normalized: str,
+    affected_count: int,
+    culprit_count: int,
+    culprit_counts: Mapping[str, int] | None,
+    *,
+    force_backtracked: bool = False,
+) -> int:
+    """Decide the priority tier from conflict and culprit counts.
+
+    ``force_backtracked`` short-circuits the gap rule: the look-ahead
+    abort is a precise enough culprit signal on its own.
+    """
+    if affected_count >= CONFLICT_THRESHOLD:
+        return TIER_AFFECTED
+    if force_backtracked:
+        return TIER_CULPRIT
+    if is_dominant_culprit(normalized, culprit_count, culprit_counts):
+        return TIER_CULPRIT
+    return TIER_NORMAL
+
+
+def compute_matching(
+    provider: Provider,
+    normalized: str,
+    version_range: RangeProtocol[Version],
+) -> int:
+    """Return the count of cached versions of ``normalized`` in ``version_range``.
+
+    Also fires speculative metadata prefetch when this is the first time we
+    notice the listing has arrived in the coordinator index.  Returns
+    :data:`_NO_LISTING_PRIOR` while the listing is still in flight.
+    """
+    per_pkg = provider.matching_cache.get(normalized)
+    if per_pkg is not None:
+        cached = per_pkg.get(version_range)
+        if cached is not None:
+            return cached
+
+    # Local/VCS sources short-circuit the listing path; their synthetic
+    # listing is materialised lazily by fetch_versions.
+    has_local_source = (
+        normalized in provider.local_sources or normalized in provider.vcs_sources
+    )
+    if normalized not in provider.versions_cache and not has_local_source:
+        files = provider.coordinator.index.get_listing(normalized)
+        if files is not None:
+            versions = provider.filter_distributions(normalized, files)
+            provider.versions_cache[normalized] = versions
+            provider.stats.listings_fetched += 1
+            provider.speculative_prefetch(normalized, versions)
+
+    if normalized in provider.versions_cache:
+        versions = provider.versions_cache[normalized]
+        matching = sum(1 for v, _ in versions if v in version_range)
+    elif has_local_source:
+        matching = 1
+    else:
+        matching = _NO_LISTING_PRIOR
+
+    if per_pkg is None:
+        per_pkg = provider.matching_cache[normalized] = {}
+    per_pkg[version_range] = matching
+    return matching
+
+
+def is_dominant_culprit(
+    package: str,
+    package_count: int,
+    culprit_counts: Mapping[str, int] | None,
+) -> bool:
+    """Return True when ``package`` is the runaway top culprit.
+
+    Demote only when the gap to the next culprit is >= CULPRIT_DEMOTE_THRESHOLD;
+    co-dominant culprits stay within ~1 of each other so the standard ordering
+    wins.
+    """
+    if culprit_counts is None or package_count < CULPRIT_DEMOTE_THRESHOLD:
+        return False
+    second_highest = max(
+        (count for other, count in culprit_counts.items() if other != package),
+        default=0,
+    )
+    return package_count - second_highest >= CULPRIT_DEMOTE_THRESHOLD
+
+
+def prioritize(
+    provider: Provider,
+    package: str,
+    version_range: RangeProtocol[Version],
+    conflict_counts: Mapping[str, int],
+    culprit_counts: Mapping[str, int] | None = None,
+) -> tuple[int, int, bool]:
+    """Prioritize packages for resolution order.
+
+    Returns ``(tier, matching_count, is_base)``.  Extras proxies sort before
+    their base at equal tier so they pin the base version directly (avoids
+    the backtrack storm when the base is decided before the extras proxy).
+
+    Never blocks on I/O.
+    """
+    provider.stats.prioritize_calls += 1
+    _, extra, normalized = provider.split_and_normalize(package)
+    affected_count = conflict_counts.get(normalized, 0)
+    culprit_count = (
+        culprit_counts.get(normalized, 0) if culprit_counts is not None else 0
+    )
+    force_backtracked = provider.force_backtrack_count(normalized) > 0
+
+    # Fast path: when culprit_count is below the demote threshold AND the
+    # package was not force-backtracked, the tier depends only on
+    # affected_count and is safe to cache by Range identity.
+    cacheable = culprit_count < CULPRIT_DEMOTE_THRESHOLD and not force_backtracked
+    if cacheable:
+        cached = provider.priority_cache.get(package)
+        if (
+            cached is not None
+            and cached[0] is version_range
+            and cached[1] == affected_count
+        ):
+            return cached[2]
+
+    tier = compute_tier(
+        normalized,
+        affected_count,
+        culprit_count,
+        culprit_counts,
+        force_backtracked=force_backtracked,
+    )
+    matching = compute_matching(provider, normalized, version_range)
+    priority = (tier, matching, extra is None)
+
+    # Don't cache the in-flight placeholder; compute_matching's listing-arrival
+    # side effect (speculative prefetch) lives in the cache-miss branch.
+    if cacheable and normalized in provider.versions_cache:
+        provider.priority_cache[package] = (version_range, affected_count, priority)
+    return priority

nab_python/_provider/sources.py

@@ -0,0 +1,215 @@
+"""Local-source and VCS-source materialisation for the provider.
+
+A ``LocalSource`` becomes the only candidate for a package: PyPI is
+not consulted.  A ``VcsSource`` clones the repo and reuses the
+``LocalSource`` extraction path.  Both produce a single synthetic
+``SdistFile`` whose version is read from ``[project].version``.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from nab_index.client import SdistFile
+from nab_index.vcs import VcsCloneError, VcsRequest
+
+from .._vendor.packaging.utils import canonicalize_name
+
+if TYPE_CHECKING:
+    from .._vendor.packaging.version import Version
+    from ..metadata import WheelMetadata
+    from ..provider import LocalSource, Provider, VcsSource
+
+
+def index_local_sources(
+    provider: Provider,  # noqa: ARG001  (signature parity with index_vcs_sources)
+    sources: list[LocalSource],
+) -> dict[str, LocalSource]:
+    """Validate ``LocalSource`` entries and return a canonical-name map.
+
+    Admitted at every :class:`~nab_python.provider.BuildPolicy` level; the
+    policy only governs whether the backend may run when the static
+    pyproject read returns nothing usable (see
+    :func:`extract_source_metadata`).
+    """
+    if not sources:
+        return {}
+    out: dict[str, LocalSource] = {}
+    for src in sources:
+        canonical = canonicalize_name(src.name)
+        if canonical in out:
+            msg = f"duplicate local source for {src.name!r}"
+            raise ValueError(msg)
+        out[canonical] = src
+    return out
+
+
+def materialize_local_source(
+    provider: Provider,
+    normalized: str,
+    source: LocalSource,
+) -> list[tuple[Version, SdistFile]]:
+    """Read metadata from ``source`` and seed caches with one synthetic version.
+
+    Static path: ``extract_static_metadata`` reads ``pyproject.toml``
+    directly.  Backend path: requires :attr:`BuildPolicy.BUILD_LOCAL`
+    or looser; raises :class:`UnsupportedSdistError` otherwise.
+    """
+    path = Path(source.path)
+    metadata = extract_source_metadata(
+        provider,
+        path,
+        descriptor=f"local source {source.name!r}",
+        package=canonicalize_name(source.name),
+        kind="local",
+    )
+    return seed_synthetic_listing(provider, normalized, path, metadata)
+
+
+def extract_source_metadata(
+    provider: Provider,
+    path: Path,
+    *,
+    descriptor: str,
+    package: str,
+    kind: str,
+) -> WheelMetadata:
+    """Read metadata from a directory; gates the backend path on policy.
+
+    ``kind`` is ``"local"`` for :class:`LocalSource` directories
+    (admitted at :attr:`BuildPolicy.BUILD_LOCAL` and above) or
+    ``"vcs"`` for :class:`VcsSource` clones (admitted only at
+    :attr:`BuildPolicy.BUILD_REMOTE`).
+    """
+    # Module-level attribute access lets tests patch
+    # ``nab_python.build_backend.extract_metadata`` from the source.
+    from .. import build_backend
+    from ..build_backend import BuildBackendError, extract_static_metadata
+    from ..provider import BuildPolicy, UnsupportedSdistError
+
+    metadata = extract_static_metadata(path)
+    if metadata is not None:
+        return metadata
+    effective = provider.effective_build_policy(package)
+    if kind == "local":
+        allowed = {BuildPolicy.BUILD_LOCAL, BuildPolicy.BUILD_REMOTE}
+        minimum = BuildPolicy.BUILD_LOCAL
+    else:
+        allowed = {BuildPolicy.BUILD_REMOTE}
+        minimum = BuildPolicy.BUILD_REMOTE
+    if effective not in allowed:
+        provider.stats.excluded_by_build_policy += 1
+        msg = (
+            f"{descriptor} at {path} has dynamic metadata; building requires"
+            f" BuildPolicy.{minimum.name} but the effective policy is"
+            f" {effective.value}"
+        )
+        raise UnsupportedSdistError(msg)
+    try:
+        return build_backend.extract_metadata(
+            path,
+            config=provider.build_config,
+            python_version=provider.python_version,
+        )
+    except BuildBackendError as exc:
+        msg = f"{descriptor}: {exc}"
+        raise UnsupportedSdistError(msg) from exc
+
+
+def seed_synthetic_listing(
+    provider: Provider,
+    normalized: str,
+    path: Path,
+    metadata: WheelMetadata,
+) -> list[tuple[Version, SdistFile]]:
+    """Produce a one-version listing for a materialised source."""
+    synthetic_file = SdistFile(
+        filename=f"{normalized}-{metadata.version}.tar.gz",
+        url=path.as_uri(),
+        version=str(metadata.version),
+        requires_python=(
+            str(metadata.requires_python)
+            if metadata.requires_python is not None
+            else None
+        ),
+        upload_time=None,
+    )
+    version = metadata.version
+    provider.metadata_cache[(normalized, version)] = metadata
+    return [(version, synthetic_file)]
+
+
+def index_vcs_sources(
+    provider: Provider,
+    sources: list[VcsSource],
+) -> dict[str, VcsSource]:
+    """Validate VCS sources and return a canonical-name map.
+
+    Admitted at every :class:`~nab_python.provider.BuildPolicy` level; the
+    policy only governs whether the backend may run on the clone (see
+    :func:`extract_source_metadata`).  ``VcsPolicy.BLOCK`` still refuses
+    any declaration up-front because that is an independent decision
+    about whether VCS fetching is permitted at all.
+    """
+    # Late import: ``pypi`` imports this module at module load.
+    from ..provider import VcsPolicy
+
+    if not sources:
+        return {}
+
+    if provider.vcs_config.policy is VcsPolicy.BLOCK:
+        msg = (
+            "vcs_sources require VcsPolicy.ALLOW; current policy is"
+            f" {provider.vcs_config.policy.value}.  Set vcs_config to"
+            " a permissive VcsConfig before declaring sources."
+        )
+        raise ValueError(msg)
+
+    out: dict[str, VcsSource] = {}
+    for src in sources:
+        canonical = canonicalize_name(src.name)
+        if canonical in out or canonical in provider.local_sources:
+            msg = f"duplicate source declared for {src.name!r}"
+            raise ValueError(msg)
+        out[canonical] = src
+    return out
+
+
+def materialize_vcs_source(
+    provider: Provider,
+    normalized: str,
+    source: VcsSource,
+) -> list[tuple[Version, SdistFile]]:
+    """Clone ``source`` and materialise it via the same path as a LocalSource."""
+    # Module-level attribute access lets tests patch
+    # ``nab_index.vcs.prepare_clone`` from the source.
+    from nab_index import vcs as _vcs
+
+    from ..provider import UnsupportedSdistError
+
+    if provider.vcs_cache_dir is None:
+        msg = (
+            f"vcs source {source.name!r} declared but no"
+            f" vcs_cache_dir was supplied to Provider"
+        )
+        raise UnsupportedSdistError(msg)
+    try:
+        request = VcsRequest.parse(source.url)
+        clone = _vcs.prepare_clone(
+            provider.vcs_cache_dir,
+            request,
+            require_pin=provider.vcs_config.require_pin,
+        )
+    except VcsCloneError as exc:
+        msg = f"vcs source {source.name!r}: {exc}"
+        raise UnsupportedSdistError(msg) from exc
+    path = clone.path / clone.subdirectory if clone.subdirectory else clone.path
+    metadata = extract_source_metadata(
+        provider,
+        path,
+        descriptor=f"vcs source {source.name!r}",
+        package=canonicalize_name(source.name),
+        kind="vcs",
+    )
+    return seed_synthetic_listing(provider, normalized, path, metadata)

nab_python/_testing/__init__.py

@@ -0,0 +1 @@
+"""Internal test helpers for nab-python."""

nab_python/_testing/coordinator_fake.py

@@ -0,0 +1,240 @@
+"""Shared mock-coordinator builder for the nab-python test suite.
+
+A ``FetchCoordinator``-shaped :class:`unittest.mock.MagicMock` wrapped
+around a real :class:`~nab_python.fetch.InMemoryIndex`.  The mock's
+request methods write to the index and return an already-set
+:class:`threading.Event`, so the synchronous provider code under test
+sees fetches resolve immediately.
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import TYPE_CHECKING
+from unittest.mock import MagicMock
+
+from nab_python.fetch import InMemoryIndex
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Mapping, Sequence
+
+    from nab_index.client import SdistFile, WheelFile
+
+
+_MINIMAL_METADATA = "Metadata-Version: 2.1\nName: {name}\nVersion: {version}\n\n"
+
+
+def _done_event() -> threading.Event:
+    """Return an already-set :class:`threading.Event`."""
+    ev = threading.Event()
+    ev.set()
+    return ev
+
+
+def _pre_populate_index(
+    index: InMemoryIndex,
+    listings_map: Mapping[str, Sequence[WheelFile | SdistFile]],
+    *,
+    baseline_metadata: Mapping[str, str] | None,
+    per_wheel_metadata: Mapping[str, str] | None,
+    sdist_pyproject: Mapping[str, str] | None,
+) -> None:
+    """Load listings and pre-store validator-visible slots into ``index``."""
+    for pkg_name, pkg_wheels in listings_map.items():
+        index.store_listing(pkg_name, pkg_wheels)
+        if baseline_metadata is not None and pkg_name in baseline_metadata:
+            for w in pkg_wheels:
+                index.store_metadata(pkg_name, w.version, baseline_metadata[pkg_name])
+                break
+        if per_wheel_metadata is not None:
+            for w in pkg_wheels:
+                if w.filename in per_wheel_metadata:
+                    index.store_metadata(
+                        pkg_name,
+                        f"{w.version}#{w.filename}",
+                        per_wheel_metadata[w.filename],
+                    )
+        if sdist_pyproject is not None and pkg_name in sdist_pyproject:
+            for w in pkg_wheels:
+                index.store_sdist_pyproject(
+                    pkg_name, w.version, sdist_pyproject[pkg_name]
+                )
+                break
+
+
+def _resolve_listings(
+    wheels: Sequence[WheelFile | SdistFile] | None,
+    package: str,
+    listings: Mapping[str, Sequence[WheelFile | SdistFile]] | None,
+) -> Mapping[str, Sequence[WheelFile | SdistFile]]:
+    """Pick the listings map: explicit ``listings`` wins over ``wheels``."""
+    if listings is not None:
+        return listings
+    if wheels is not None:
+        return {package: wheels}
+    return {}
+
+
+def _make_metadata_resolver(
+    *,
+    metadata_text: str | None,
+    metadata_by_version: Mapping[str, str | None] | None,
+    auto_metadata: bool,
+) -> Callable[[str, str], str | None]:
+    """Return a callable that picks metadata text for ``(pkg, version)``."""
+
+    def _resolve(pkg: str, ver: str) -> str | None:
+        if metadata_by_version is not None:
+            return metadata_by_version.get(ver)
+        if metadata_text is not None:
+            return metadata_text
+        if auto_metadata:
+            return _MINIMAL_METADATA.format(name=pkg, version=ver)
+        return None
+
+    return _resolve
+
+
+def _wire_metadata_side_effects(
+    coordinator: MagicMock,
+    index: InMemoryIndex,
+    resolve_metadata: Callable[[str, str], str | None],
+) -> None:
+    """Attach ``request_listing``/``request_metadata``/batch side effects."""
+
+    def _request_listing(_pkg: str) -> threading.Event:
+        return _done_event()
+
+    def _request_metadata(pkg: str, ver: str, _url: str) -> threading.Event:
+        text = resolve_metadata(pkg, ver)
+        if text is not None:
+            index.store_metadata(pkg, ver, text)
+        return _done_event()
+
+    def _request_metadata_batch(
+        items: list[tuple[str, str, str]],
+    ) -> list[tuple[str, str, threading.Event]]:
+        results: list[tuple[str, str, threading.Event]] = []
+        for pkg, ver, _url in items:
+            text = resolve_metadata(pkg, ver)
+            if text is not None:
+                index.store_metadata(pkg, ver, text)
+            results.append((pkg, ver, _done_event()))
+        return results
+
+    coordinator.request_listing.side_effect = _request_listing
+    coordinator.request_metadata.side_effect = _request_metadata
+    coordinator.request_metadata_batch.side_effect = _request_metadata_batch
+
+
+def _wire_sdist_side_effects(
+    coordinator: MagicMock,
+    index: InMemoryIndex,
+    *,
+    sdist_pkg_info: str | None,
+    sdist_pyproject_toml: str | None,
+    failures: set[str],
+) -> None:
+    """Attach ``request_sdist`` and ``request_wheel_metadata`` side effects."""
+
+    def _request_sdist(pkg: str, ver: str, _url: str) -> threading.Event:
+        # ``store_sdist_metadata`` is always called; passing ``None``
+        # poisons the cache slot, matching the original test_provider
+        # helper's contract for sdist-fetch failures.
+        index.store_sdist_metadata(pkg, ver, sdist_pkg_info)
+        if sdist_pyproject_toml is not None:
+            index.store_sdist_pyproject(pkg, ver, sdist_pyproject_toml)
+        return _done_event()
+
+    def _request_wheel_metadata(
+        pkg: str, ver: str, filename: str, _url: str
+    ) -> threading.Event:
+        if filename in failures:
+            index.store_metadata(pkg, f"{ver}#{filename}", None)
+        return _done_event()
+
+    coordinator.request_sdist.side_effect = _request_sdist
+    coordinator.request_wheel_metadata.side_effect = _request_wheel_metadata
+
+
+def make_coordinator(  # noqa: PLR0913
+    wheels: Sequence[WheelFile | SdistFile] | None = None,
+    *,
+    package: str = "pkg",
+    listings: Mapping[str, Sequence[WheelFile | SdistFile]] | None = None,
+    metadata_text: str | None = None,
+    metadata_by_version: Mapping[str, str | None] | None = None,
+    auto_metadata: bool = False,
+    sdist_pkg_info: str | None = None,
+    sdist_pyproject_toml: str | None = None,
+    baseline_metadata: Mapping[str, str] | None = None,
+    per_wheel_metadata: Mapping[str, str] | None = None,
+    sdist_pyproject: Mapping[str, str] | None = None,
+    fetch_failures: set[str] | None = None,
+) -> MagicMock:
+    """Build a mock :class:`FetchCoordinator` backed by an :class:`InMemoryIndex`.
+
+    Listing setup (one of):
+
+    * ``wheels`` + ``package``: pre-load ``wheels`` under ``package``.
+      Passing ``None`` skips listing setup, e.g. for tests that only
+      need the coordinator handle.
+    * ``listings``: pre-load each ``(package, wheels)`` pair.  Overrides
+      ``wheels``/``package``.
+
+    Request side effects:
+
+    * ``request_listing`` and ``request_wheel_metadata`` always return a
+      set event.  ``request_wheel_metadata`` honours ``fetch_failures``:
+      filenames in the set store ``None`` at the sentinel
+      ``f"{version}#{filename}"`` key.
+    * ``request_metadata`` and ``request_metadata_batch`` write
+      ``metadata_text`` (or the entry from ``metadata_by_version``, or
+      auto-generated minimal METADATA when ``auto_metadata`` is true).
+    * ``request_sdist`` writes ``sdist_pkg_info`` and, if not ``None``,
+      ``sdist_pyproject_toml``.
+
+    Pre-stores written directly to the index before the coordinator
+    fires:
+
+    * ``baseline_metadata`` keys on package name and writes once per
+      package using the first wheel's version.
+    * ``per_wheel_metadata`` keys on wheel filename and writes at the
+      validator's ``f"{version}#{filename}"`` sentinel.
+    * ``sdist_pyproject`` keys on package name and writes the
+      pyproject.toml text used by the PEP 621 fast path.
+
+    Call sites that need request side effects beyond what this helper
+    wires up (for example ``request_sdist_archive``) can reassign
+    ``.side_effect`` on the returned mock; the index is exposed at
+    ``coordinator.index`` for direct manipulation.
+    """
+    index = InMemoryIndex()
+    failures = fetch_failures if fetch_failures is not None else set()
+
+    listings_map = _resolve_listings(wheels, package, listings)
+    _pre_populate_index(
+        index,
+        listings_map,
+        baseline_metadata=baseline_metadata,
+        per_wheel_metadata=per_wheel_metadata,
+        sdist_pyproject=sdist_pyproject,
+    )
+
+    coordinator = MagicMock()
+    coordinator.index = index
+
+    resolve_metadata = _make_metadata_resolver(
+        metadata_text=metadata_text,
+        metadata_by_version=metadata_by_version,
+        auto_metadata=auto_metadata,
+    )
+    _wire_metadata_side_effects(coordinator, index, resolve_metadata)
+    _wire_sdist_side_effects(
+        coordinator,
+        index,
+        sdist_pkg_info=sdist_pkg_info,
+        sdist_pyproject_toml=sdist_pyproject_toml,
+        failures=failures,
+    )
+    return coordinator