nab-python 0.0.1__tar.gz

nab_python-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Damian Shaw
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nab_python-0.0.1/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.4
+Name: nab-python
+Version: 0.0.1
+Summary: Index-backed provider, lockfile emitter, and downloader for nab
+Project-URL: Homepage, https://github.com/notatallshaw/nab
+Project-URL: Documentation, https://nab.readthedocs.io/
+Project-URL: Issues, https://github.com/notatallshaw/nab/issues
+Project-URL: Source, https://github.com/notatallshaw/nab
+Project-URL: Changelog, https://github.com/notatallshaw/nab/blob/main/CHANGELOG.md
+Author-email: Damian Shaw <damian.peter.shaw@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: build>=1.2
+Requires-Dist: installer>=0.7
+Requires-Dist: nab-index==0.0.1
+Requires-Dist: nab-resolver==0.0.1
+Requires-Dist: pyproject-hooks>=1.2
+Requires-Dist: tomli-w>=1.2
+Requires-Dist: tomli>=2.0
+Requires-Dist: typing-extensions>=4.6
+Description-Content-Type: text/markdown
+
+# nab-python
+
+The Python package index provider that drives [`nab-resolver`](https://pypi.org/project/nab-resolver/)
+for Python packages.
+
+It owns all the mechanics of how the resolver needs to interact with standards
+based Python package indexes and packages.
+
+It implements build and distribution policies to allow the user to control
+resolver and install behavior.
+
+## When to use it
+
+Use `nab-python` if you need to embed Python package resolution in
+another tool and want the resolver, provider, and lockfile emitter
+without the CLI.
+
+The API is currently under rapid experimentation, use exact version
+pinning.

nab_python-0.0.1/README.md

@@ -0,0 +1,19 @@
+# nab-python
+
+The Python package index provider that drives [`nab-resolver`](https://pypi.org/project/nab-resolver/)
+for Python packages.
+
+It owns all the mechanics of how the resolver needs to interact with standards
+based Python package indexes and packages.
+
+It implements build and distribution policies to allow the user to control
+resolver and install behavior.
+
+## When to use it
+
+Use `nab-python` if you need to embed Python package resolution in
+another tool and want the resolver, provider, and lockfile emitter
+without the CLI.
+
+The API is currently under rapid experimentation, use exact version
+pinning.

nab_python-0.0.1/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "nab-python"
+version = "0.0.1"
+description = "Index-backed provider, lockfile emitter, and downloader for nab"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Damian Shaw", email = "damian.peter.shaw@gmail.com" },
+]
+requires-python = ">=3.10"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "nab-resolver==0.0.1",
+    "nab-index==0.0.1",
+    "tomli>=2.0",
+    "tomli_w>=1.2",
+    "build>=1.2",
+    "installer>=0.7",
+    "pyproject_hooks>=1.2",
+    "typing_extensions>=4.6",
+]
+
+[project.urls]
+Homepage = "https://github.com/notatallshaw/nab"
+Documentation = "https://nab.readthedocs.io/"
+Issues = "https://github.com/notatallshaw/nab/issues"
+Source = "https://github.com/notatallshaw/nab"
+Changelog = "https://github.com/notatallshaw/nab/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

nab_python-0.0.1/src/nab_python/__init__.py

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

nab_python-0.0.1/src/nab_python/_build/__init__.py

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

nab_python-0.0.1/src/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-0.0.1/src/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."""