nab-python 0.0.1__py3-none-any.whl

nab_python/__init__.py

@@ -0,0 +1 @@
+"""Python package resolver built on the nab resolver core."""

nab_python/_build/__init__.py

@@ -0,0 +1 @@
+"""PEP 517 build-backend invocation for dynamic metadata."""

nab_python/_build/env.py

@@ -0,0 +1,364 @@
+"""Isolated build env that uses nab itself plus the PyPA ``installer``.
+
+``NabBuildEnv`` implements ``build.env.IsolatedEnv`` so it slots into
+``build.ProjectBuilder.from_isolated_env``.  The pieces:
+
+* ``venv.EnvBuilder`` (stdlib) creates an empty interpreter at a temp
+  path, ``with_pip=False``; nab does not need pip in there.
+* nab's own resolver picks versions for ``[build-system].requires``
+  using the same indexes / ``exclude-newer`` window as the outer
+  resolve.
+* ``download_lock`` from :mod:`nab_python.download` fetches the
+  resolved wheels into a temp directory.
+* :func:`installer.install` writes each wheel into the venv via
+  ``installer.SchemeDictionaryDestination``, configured from the
+  venv's own ``sysconfig.get_paths()``.
+
+The env is a context manager.  Entering it builds the venv and
+installs the requirements; exiting removes the temp tree.  The
+``python_executable`` and ``make_extra_environ`` properties come
+from ``build.env.IsolatedEnv``.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import subprocess
+import sys
+import tempfile
+import venv
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from installer import install as installer_install
+from installer.destinations import SchemeDictionaryDestination
+from installer.sources import WheelFile
+from nab_index.urllib3_async_transport import Urllib3AsyncTransport
+
+from ..config import NabProjectConfig
+from ..download import download_lock
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Mapping
+    from typing_extensions import Self
+
+    from installer.records import RecordEntry
+    from installer.utils import Scheme
+    from nab_index.transport import AsyncHttpTransport
+
+__all__ = [
+    "NabBuildEnv",
+]
+
+
+class _FastSchemeDictionaryDestination(SchemeDictionaryDestination):
+    """``SchemeDictionaryDestination`` that skips bytecode-compile work.
+
+    The stock ``_compile_bytecode`` always resolves the target file's
+    real path before checking ``bytecode_optimization_levels``; with
+    an empty levels tuple, the loop body never runs but the resolve
+    still hits the filesystem twice per record.  Skipping the early
+    work when the levels tuple is empty is safe because the body
+    would have been a no-op.
+    """
+
+    def _compile_bytecode(self, scheme: Scheme, record: RecordEntry) -> None:
+        if not self.bytecode_optimization_levels:
+            return
+        super()._compile_bytecode(scheme, record)
+
+
+logger = logging.getLogger(__name__)
+
+
+_LAUNCHER_KIND = (
+    "win-amd64"
+    if sys.platform == "win32" and sys.maxsize > 2**32
+    else "win-ia32"
+    if sys.platform == "win32"
+    else "posix"
+)
+
+
+class BuildEnvError(Exception):
+    """The build env could not be set up (resolve, download, or install)."""
+
+
+class NabBuildEnv:
+    """An isolated PEP 518 build environment driven by nab.
+
+    Implements ``build.env.IsolatedEnv`` so it can be passed to
+    ``build.ProjectBuilder.from_isolated_env``. The runtime cost
+    is one venv creation, one inner resolve over
+    ``[build-system].requires``, one wheel download per dep, and
+    one ``installer.install`` per wheel.
+
+    ``requires`` is the PEP 508 string list from
+    ``[build-system].requires``. ``config`` carries the indexes,
+    ``exclude-newer`` window and other nab inputs from the outer
+    resolve; it is pruned (no local sources, no workspace, no
+    marker overlay) before the inner resolve so the build env is
+    computed against PyPI alone.
+
+    Construction is cheap; the work happens in ``__enter__``.
+    """
+
+    def __init__(
+        self,
+        requires: list[str],
+        *,
+        config: NabProjectConfig,
+        python_version: str | None = None,
+        transport_factory: Callable[[], AsyncHttpTransport] = Urllib3AsyncTransport,
+    ) -> None:
+        """Capture inputs; the venv and inner resolve happen in __enter__."""
+        self._requires = list(requires)
+        self._config = config
+        self._python_version = python_version
+        self._transport = transport_factory()
+
+        self._tmpdir: tempfile.TemporaryDirectory[str] | None = None
+        self._venv_path: Path | None = None
+        self._python_executable: Path | None = None
+        self._scripts_dir: Path | None = None
+
+    def __enter__(self) -> Self:
+        """Build the venv, run the inner resolve, install build requirements."""
+        self._tmpdir = tempfile.TemporaryDirectory(prefix="nab-build-env-")
+        try:
+            self._provision(Path(self._tmpdir.name))
+        except BaseException:
+            self._tmpdir.cleanup()
+            self._tmpdir = None
+            raise
+        return self
+
+    def _provision(self, root: Path) -> None:
+        """Lay out the venv, install build requirements, populate paths."""
+        self._venv_path = root / "venv"
+        wheel_dir = root / "wheels"
+        wheel_dir.mkdir()
+
+        logger.debug("creating build venv at %s", self._venv_path)
+        builder = venv.EnvBuilder(
+            with_pip=False, symlinks=_supports_symlinks(), clear=False
+        )
+        builder.create(self._venv_path)
+
+        self._python_executable = _venv_python(self._venv_path)
+        self._scripts_dir = self._python_executable.parent
+
+        scheme_dict = _venv_scheme_paths(self._python_executable)
+
+        if not self._requires:
+            return
+        wheel_paths = self._resolve_and_download(wheel_dir)
+        destination = _FastSchemeDictionaryDestination(
+            scheme_dict=scheme_dict,
+            interpreter=str(self._python_executable),
+            script_kind=_LAUNCHER_KIND,
+            bytecode_optimization_levels=(),
+            overwrite_existing=True,
+        )
+        for wheel_path in wheel_paths:
+            logger.debug("installing %s", wheel_path.name)
+            with WheelFile.open(wheel_path) as source:
+                installer_install(
+                    source=source,
+                    destination=destination,
+                    additional_metadata={"INSTALLER": b"nab\n"},
+                )
+
+    def __exit__(self, *args: object) -> None:
+        """Remove the temp tree that holds the venv and downloaded wheels."""
+        if self._tmpdir is not None:
+            self._tmpdir.cleanup()
+            self._tmpdir = None
+
+    @property
+    def python_executable(self) -> str:
+        """Path to the venv's interpreter (str, per ``IsolatedEnv``)."""
+        if self._python_executable is None:
+            msg = "NabBuildEnv used outside its context-manager scope"
+            raise BuildEnvError(msg)
+        return str(self._python_executable)
+
+    def make_extra_environ(self) -> Mapping[str, str]:
+        """PATH / PYTHONPATH overrides for the build subprocess.
+
+        Prepends the venv's scripts dir so build backends find their
+        installed entry points; clears ``PYTHONPATH`` so the host's
+        ``sys.path`` does not leak in (matches the convention used by
+        ``build.env.DefaultIsolatedEnv``).
+        """
+        if self._scripts_dir is None:
+            msg = "NabBuildEnv used outside its context-manager scope"
+            raise BuildEnvError(msg)
+        host_path = os.environ.get("PATH")
+        new_path = (
+            f"{self._scripts_dir}{os.pathsep}{host_path}"
+            if host_path
+            else str(self._scripts_dir)
+        )
+        return {"PATH": new_path, "PYTHONPATH": ""}
+
+    def install(self, requirements: list[str]) -> None:
+        """Install additional requirements into the live env.
+
+        Used for ``get_requires_for_build_wheel`` follow-up requests
+        (the backend asks for additional deps after the env is
+        already up).  Same code path as the constructor's install,
+        targeting the same venv.
+        """
+        if self._venv_path is None or self._python_executable is None:
+            msg = "NabBuildEnv used outside its context-manager scope"
+            raise BuildEnvError(msg)
+        if not requirements:
+            return
+        wheel_dir = self._venv_path.parent / "wheels"
+        # Append a fresh subdir so a re-install does not re-download
+        # the same wheel into the same path under a different version.
+        sub = wheel_dir / f"_extra_{len(list(wheel_dir.iterdir()))}"
+        sub.mkdir(parents=True, exist_ok=True)
+        wheel_paths = self._resolve_and_download(sub, extra=requirements)
+        scheme_dict = _venv_scheme_paths(self._python_executable)
+        destination = SchemeDictionaryDestination(
+            scheme_dict=scheme_dict,
+            interpreter=str(self._python_executable),
+            script_kind=_LAUNCHER_KIND,
+            bytecode_optimization_levels=(),
+            overwrite_existing=True,
+        )
+        for wheel_path in wheel_paths:
+            with WheelFile.open(wheel_path) as source:
+                installer_install(
+                    source=source,
+                    destination=destination,
+                    additional_metadata={"INSTALLER": b"nab\n"},
+                )
+
+    def _resolve_and_download(
+        self,
+        wheel_dir: Path,
+        *,
+        extra: list[str] | None = None,
+    ) -> list[Path]:
+        """Resolve ``requires`` (+ ``extra``) and write wheels under ``wheel_dir``.
+
+        The inner resolve runs against a synthetic pyproject so it
+        can reuse :func:`nab_python.resolve.resolve_pyproject` and
+        :func:`nab_python.download.download_lock` end-to-end.  No
+        local sources / workspace / marker overlay; build deps
+        come from the configured indexes only.
+        """
+        # Late import: avoids a cycle through ``resolve.py`` which
+        # itself imports ``pypi.py`` which imports ``build_backend``
+        # which imports this module.
+        from ..resolve import resolve_pyproject
+
+        requires = list(self._requires)
+        if extra:
+            requires.extend(extra)
+
+        synthetic_dir = wheel_dir.parent / "_inner_project"
+        synthetic_dir.mkdir(parents=True, exist_ok=True)
+        synthetic = synthetic_dir / "pyproject.toml"
+        synthetic.write_text(_render_synthetic_pyproject(requires), encoding="utf-8")
+
+        inner_config = NabProjectConfig(
+            indexes=self._config.indexes,
+            index_overrides=self._config.index_overrides,
+            uploaded_prior_to=self._config.uploaded_prior_to,
+            uploaded_prior_to_overrides=self._config.uploaded_prior_to_overrides,
+        )
+        result = resolve_pyproject(
+            synthetic,
+            self._transport,
+            config=inner_config,
+            python_version=self._python_version,
+        )
+
+        # Reject sdist-only pins early: build deps that ship only an
+        # sdist trigger a recursive backend invocation that this
+        # builder does not handle.  Most build tools (hatchling,
+        # setuptools, flit, pdm-backend) publish wheels.
+        from ..lockfile import IndexPin
+
+        sdist_only: list[str] = []
+        for canonical, pin in result.lock_input.pins.items():
+            if isinstance(pin, IndexPin) and not pin.wheels:
+                sdist_only.append(f"{canonical}=={pin.version}")
+        if sdist_only:
+            msg = (
+                "build env requires sdist-only packages which nab cannot"
+                " install without recursing through the build path: "
+                + ", ".join(sdist_only)
+            )
+            raise BuildEnvError(msg)
+
+        download_result = download_lock(result.lock_input, self._transport, wheel_dir)
+        # Both wheels and sdists are downloaded; only wheels feed
+        # ``installer.install``.  The sdists are inert clutter under
+        # the temp dir, cleaned up with the env.
+        all_paths = list(download_result.written) + list(download_result.skipped)
+        return [p for p in all_paths if p.suffix == ".whl"]
+
+
+def _venv_python(venv_path: Path) -> Path:
+    r"""Return the venv interpreter path (``Scripts\python.exe`` on Windows)."""
+    if sys.platform == "win32":
+        return venv_path / "Scripts" / "python.exe"  # pragma: no cover
+    return venv_path / "bin" / "python"
+
+
+def _venv_scheme_paths(python_executable: Path) -> dict[str, str]:
+    """Ask the venv's interpreter for its own ``sysconfig.get_paths()``.
+
+    Subprocessing the venv guarantees the returned paths reflect the
+    venv's layout (``site-packages`` under the venv root, scripts in
+    its ``bin``/``Scripts`` dir, etc.) regardless of how nab itself
+    was installed.  One subprocess per env construction; negligible.
+    """
+    result = subprocess.run(  # noqa: S603 - controlled command, no shell
+        [
+            str(python_executable),
+            "-c",
+            "import json, sysconfig; print(json.dumps(sysconfig.get_paths()))",
+        ],
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    return dict(json.loads(result.stdout))
+
+
+def _supports_symlinks() -> bool:
+    """``venv.EnvBuilder(symlinks=...)`` heuristic; avoids Windows traps."""
+    return sys.platform != "win32"
+
+
+def _render_synthetic_pyproject(requires: list[str]) -> str:
+    """Render a tiny pyproject.toml whose deps are ``requires``.
+
+    Used as input to the inner resolve; the on-disk file is
+    discarded with the rest of the temp tree.  The dummy name and
+    version make the inner resolver happy without depending on the
+    outer project's name/version.
+    """
+    deps_block = ",\n    ".join(_toml_str(s) for s in requires)
+    if deps_block:
+        deps_block = f"\n    {deps_block},\n"
+    return (
+        "[project]\n"
+        'name = "_nab_build_env"\n'
+        'version = "0.0.0"\n'
+        f"dependencies = [{deps_block}]\n"
+    )
+
+
+def _toml_str(value: str) -> str:
+    """Single-line TOML string literal escape."""
+    escaped = value.replace("\\", "\\\\").replace('"', '\\"')
+    return f'"{escaped}"'

nab_python/_build/errors.py

@@ -0,0 +1,17 @@
+"""Errors shared between the build runner and its callers.
+
+Lives in its own module so :mod:`nab_python.build_backend` can
+import the exception without pulling in :mod:`build`,
+:mod:`pyproject_hooks`, and the rest of the runner module at module
+load time.  The runner re-exports the class for back-compat.
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "BuildBackendError",
+]
+
+
+class BuildBackendError(Exception):
+    """A build-backend operation failed or returned unparseable metadata."""

nab_python/_build/runner.py

@@ -0,0 +1,254 @@
+"""Orchestrate ``[build-system]`` setup and metadata extraction.
+
+The entry point is :func:`run_build_backend`.  Given a source
+directory with a ``pyproject.toml`` whose ``project.dynamic``
+contains fields nab cannot read statically, run_build_backend:
+
+1. Reads ``[build-system].requires`` and ``[build-system].build-backend``
+   (defaulting to ``setuptools.build_meta:__legacy__`` per PEP 517).
+2. Opens a :class:`~nab_python._build.env.NabBuildEnv` populated with
+   those requirements.
+3. Hands the env to ``build.ProjectBuilder.from_isolated_env`` and
+   asks it for the wheel metadata via ``metadata_path()``, which
+   tries ``prepare_metadata_for_build_wheel`` and falls back to a
+   full ``build_wheel`` when the backend lacks that hook.
+4. Parses the resulting ``METADATA`` file into
+   :class:`~nab_python.metadata.WheelMetadata`.
+
+The hatchling-with-dynamic-deps quirk uv documents (the prepare
+hook can return data that does not match the eventual wheel) is
+covered by skipping the prepare step for that combination; see
+:func:`_should_skip_prepare`.
+"""
+
+from __future__ import annotations
+
+import logging
+import tempfile
+from email import message_from_string
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import build
+import pyproject_hooks
+import tomli
+
+from .._vendor.packaging.requirements import Requirement
+from .._vendor.packaging.specifiers import SpecifierSet
+from .._vendor.packaging.utils import canonicalize_name
+from .._vendor.packaging.version import InvalidVersion, Version
+from ..metadata import WheelMetadata
+from .env import NabBuildEnv
+from .errors import BuildBackendError
+
+if TYPE_CHECKING:
+    from ..config import NabProjectConfig
+
+__all__ = [
+    "BuildBackendError",
+    "run_build_backend",
+]
+
+logger = logging.getLogger(__name__)
+
+
+_DEFAULT_BACKEND = "setuptools.build_meta:__legacy__"
+_DEFAULT_REQUIRES = ("setuptools >= 40.8.0",)
+
+
+def run_build_backend(
+    source_dir: Path,
+    *,
+    config: NabProjectConfig,
+    python_version: str | None = None,
+) -> WheelMetadata:
+    """Extract wheel metadata for ``source_dir`` via the build backend.
+
+    Returns a :class:`~nab_python.metadata.WheelMetadata` parsed from
+    the ``METADATA`` file the backend produces.  Raises
+    :class:`BuildBackendError` on any failure: backend import
+    error, hook crash, malformed METADATA, or sdist-only build deps.
+
+    The build runs in an isolated venv driven by
+    :class:`NabBuildEnv`; nothing in the user's main environment is
+    perturbed.  The build env owns its own HTTP transport (see
+    :class:`NabBuildEnv` for why) so callers do not pass one in.
+    """
+    pyproject = source_dir / "pyproject.toml"
+    if pyproject.is_file():
+        try:
+            data = tomli.loads(pyproject.read_text(encoding="utf-8"))
+        except (OSError, tomli.TOMLDecodeError) as exc:
+            msg = f"could not read pyproject.toml at {source_dir}: {exc}"
+            raise BuildBackendError(msg) from exc
+    elif (source_dir / "setup.py").is_file():
+        # PEP 517 fallback for legacy setup.py projects: treat the
+        # missing ``[build-system]`` as the documented default
+        # (setuptools.build_meta:__legacy__).
+        data = {}
+    else:
+        msg = f"no pyproject.toml or setup.py at {source_dir}"
+        raise BuildBackendError(msg)
+
+    backend, requires, _backend_path = _read_build_system(data)
+
+    skip_prepare = _should_skip_prepare(backend, data)
+
+    try:
+        with NabBuildEnv(
+            requires=list(requires),
+            config=config,
+            python_version=python_version,
+        ) as env:
+            project = build.ProjectBuilder.from_isolated_env(
+                env,
+                source_dir=str(source_dir),
+                runner=pyproject_hooks.quiet_subprocess_runner,
+            )
+
+            extra = list(project.get_requires_for_build("wheel"))
+            if extra:
+                logger.debug("build backend asked for extras: %s", extra)
+                env.install(extra)
+
+            with tempfile.TemporaryDirectory(prefix="nab-build-meta-") as out_str:
+                output_dir = Path(out_str)
+                if skip_prepare:
+                    metadata_dir = _build_wheel_and_extract(project, output_dir)
+                else:
+                    metadata_dir = Path(project.metadata_path(output_dir))
+                return _parse_metadata(metadata_dir / "METADATA")
+    except build.BuildBackendException as exc:
+        msg = f"build backend {backend!r} failed: {exc}"
+        raise BuildBackendError(msg) from exc
+
+
+def _read_build_system(
+    data: dict,
+) -> tuple[str, tuple[str, ...], tuple[str, ...] | None]:
+    """Return ``(backend, requires, backend_path)`` per PEP 517 / 518."""
+    table = data.get("build-system")
+    if not isinstance(table, dict):
+        return _DEFAULT_BACKEND, _DEFAULT_REQUIRES, None
+    backend = table.get("build-backend")
+    if not isinstance(backend, str):
+        backend = _DEFAULT_BACKEND
+    raw_requires = table.get("requires")
+    requires: tuple[str, ...]
+    if isinstance(raw_requires, list) and all(isinstance(r, str) for r in raw_requires):
+        requires = tuple(raw_requires)
+    else:
+        requires = _DEFAULT_REQUIRES
+    raw_path = table.get("backend-path")
+    backend_path: tuple[str, ...] | None = None
+    if isinstance(raw_path, list) and all(isinstance(p, str) for p in raw_path):
+        backend_path = tuple(raw_path)
+    return backend, requires, backend_path
+
+
+def _should_skip_prepare(backend: str, data: dict) -> bool:
+    """Skip ``prepare_metadata_for_build_wheel`` when it would lie.
+
+    uv documents one specific quirk: hatchling's prepare-metadata
+    hook can return a metadata that does not match the eventual
+    ``build_wheel`` output when ``project.dynamic`` includes
+    ``dependencies`` (or ``optional-dependencies``).  Mirror that.
+    """
+    if not backend.startswith("hatchling."):
+        return False
+    project = data.get("project")
+    if not isinstance(project, dict):
+        return False
+    dynamic = project.get("dynamic")
+    if not isinstance(dynamic, list):
+        return False
+    dyn = {d for d in dynamic if isinstance(d, str)}
+    return bool(dyn & {"dependencies", "optional-dependencies"})
+
+
+def _build_wheel_and_extract(
+    project: build.ProjectBuilder, output_directory: Path
+) -> Path:
+    """Build a wheel and extract its dist-info directory.
+
+    The built wheel ends up in ``output_directory``; this helper
+    pulls out its ``*.dist-info/`` and returns the path so the
+    caller can read ``METADATA``.  Mirrors what
+    :meth:`build.ProjectBuilder.metadata_path` does internally
+    when the prepare hook is missing; we just call it
+    unconditionally for the hatchling+dynamic-deps case.
+    """
+    wheel = project.build("wheel", str(output_directory))
+    wheel_path = Path(wheel)
+    # zipfile is only needed for the build path; deferred to keep
+    # import-time work minimal.
+    import zipfile
+
+    with zipfile.ZipFile(wheel_path) as zf:
+        dist_info_members = [
+            n
+            for n in zf.namelist()
+            if "/" in n and n.split("/")[0].endswith(".dist-info")
+        ]
+        if not dist_info_members:
+            msg = f"built wheel {wheel_path.name} has no .dist-info directory"
+            raise BuildBackendError(msg)
+        distinfo_dir = dist_info_members[0].split("/")[0]
+        zf.extractall(
+            output_directory,
+            (
+                m
+                for m in zf.namelist()
+                if m == distinfo_dir or m.startswith(distinfo_dir + "/")
+            ),
+        )
+    return output_directory / distinfo_dir
+
+
+def _parse_metadata(metadata_path: Path) -> WheelMetadata:
+    """Parse a ``METADATA`` file into :class:`WheelMetadata`."""
+    if not metadata_path.is_file():
+        msg = f"backend produced no METADATA file at {metadata_path}"
+        raise BuildBackendError(msg)
+    text = metadata_path.read_text(encoding="utf-8")
+    msg_obj = message_from_string(text)
+
+    name_raw = msg_obj.get("Name")
+    version_raw = msg_obj.get("Version")
+    if not name_raw or not version_raw:
+        msg = (
+            f"backend METADATA at {metadata_path} is missing Name or Version"
+            f" (Name={name_raw!r}, Version={version_raw!r})"
+        )
+        raise BuildBackendError(msg)
+    try:
+        version = Version(version_raw)
+    except InvalidVersion as exc:
+        msg = f"backend METADATA has invalid Version {version_raw!r}: {exc}"
+        raise BuildBackendError(msg) from exc
+
+    requires_python_raw = msg_obj.get("Requires-Python")
+    requires_python = SpecifierSet(requires_python_raw) if requires_python_raw else None
+
+    requires_dist: list[Requirement] = []
+    for raw in msg_obj.get_all("Requires-Dist") or ():
+        try:
+            requires_dist.append(Requirement(raw))
+        except (ValueError, TypeError):  # noqa: PERF203
+            logger.warning("skipping unparseable Requires-Dist: %s", raw)
+
+    provides_extra: list[str] = sorted(
+        {
+            canonicalize_name(extra)
+            for extra in msg_obj.get_all("Provides-Extra") or ()
+            if extra
+        }
+    )
+
+    return WheelMetadata(
+        name=canonicalize_name(name_raw),
+        version=version,
+        requires_python=requires_python,
+        requires_dist=requires_dist,
+        provides_extra=provides_extra,
+    )

nab_python/_lockfile/__init__.py

@@ -0,0 +1 @@
+"""Internal helpers backing :mod:`nab_python.lockfile`."""