nab 0.0.1__tar.gz

nab-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-0.0.1/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: nab
+Version: 0.0.1
+Summary: PubGrub-based dependency resolver for Python packages
+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: nab-index==0.0.1
+Requires-Dist: nab-python==0.0.1
+Requires-Dist: nab-resolver==0.0.1
+Requires-Dist: tyro>=1.0
+Provides-Extra: httpx
+Requires-Dist: nab-index[httpx]==0.0.1; extra == 'httpx'
+Provides-Extra: niquests
+Requires-Dist: nab-index[niquests]==0.0.1; extra == 'niquests'
+Description-Content-Type: text/markdown
+
+# nab
+
+nab is an experimental Python packaging lock and package download tool,
+aiming to have similar resolver performance to uv, while being written
+in Python.
+
+nab reads a `pyproject.toml`, resolves the dependency tree, and
+writes a pinned set of versions or a PEP 751 lockfile. It does not
+install. Hand the lockfile to whatever installer you trust.
+
+## Install
+
+For package hygiene, and security reasons, the preference is to install nab itself
+as a tool, e.g.
+
+Via pipx:
+
+```bash
+pipx install nab
+```
+
+Or via uv:
+
+```bash
+uv tool install nab
+```
+
+
+## Quick start
+
+```toml
+# pyproject.toml
+[project]
+name = "example"
+version = "0.1.0"
+dependencies = [
+    "starlette<=0.36.0",
+    "fastapi<=0.115.2",
+]
+```
+
+```bash
+nab lock pyproject.toml
+```
+
+Writes `pylock.toml` next to the project. For a sorted
+`name==version` list instead, use
+`nab lock --format requirements-without-hashes --output -`.
+
+# Security
+
+nab makes some opinionated choices to be secure first
+
+## Build policy
+
+By default nab tries to extract static metadata, even from sdists,
+but sometimes that is not possible and you have to build a package
+to extract the dependency metadata. There are three build policies:
+
+ * never: Never builds a Python package
+ * build-local (default): Builds only your local workspace packages
+   if they have dynamic versions or dependencies
+ * build-remote: Builds packages sourced from indexes or VCS, it is
+   recommended that this only be turned on via per-package override
+
+## Indexes
+
+nab does not currently support sourcing the same package from
+distinct indexes. Indexes are processed in the order they are given
+to nab, and the first index that has a package is the only index
+that nab will source that package.
+
+You can override this behavior by pinning specific packages to
+specific behavior.
+
+You can also list different urls as a mirror for the same index.
+When a lockfile is written the primary url will always be used
+so that the lockfile will be stable, even if mirrors are used
+(this feature is a work in progress).
+
+## VCS policy
+
+By default nab only allows git URLs that point to a specific
+commit. Using a floating branch as a dependency must be
+enabled in the configuration.
+
+# Standards first behavior
+
+## Pre-releases
+
+Pre-release versions are selected if there are no stable
+versions to select given the requirements, even for transitive
+dependencies. A user option to force allow or block
+pre-releases per-package is a work in progress.
+
+## Validate per-distribution dependencies
+
+By default when a distribution is chosen the dependencies from
+that distribution are used, nab does not assume two different
+distributions for the same package version will have the same
+dependencies.
+
+However, sometimes you may want the lock file to produce an
+sdist, that sdist may not have static metadata, and you don't
+want to wait for the sdist to build on every lock, there is
+a distribution policy of "sdist-install", that is the metadata
+will be taken from an appropriate wheel, but the sdist will
+be selected for the install.
+
+
+# Libraries
+
+This project includes multiple libraries that can be used by
+other tools:
+
+ * `nab-resolver`: An agnostic resolver library based on PubGrub, but with
+   extensions that make it compatible with Python packaging standards
+ * `nab-python`: A Python packaging provider that drives the nab-resolver
+   with lots of specific features and optimizations for the Python packaging
+   ecosystem
+ * `nab-index`: Provides APIs for nab-python to interact with Python package
+   indexes, abstracts HTTP library interface so different HTTP libraries can
+   be plugged in
+
+All 3 libraries are in experimental mode, I currently recommend pinning them,
+e.g. `nab-resolver==0.0.1`, as APIs may change at any point.
+
+Once we reach `0.1.0` we will only break API stability on each minor update,
+so you will be able to pin to `==0.1.*` or `~=0.1.0`.

nab-0.0.1/README.md

@@ -0,0 +1,129 @@
+# nab
+
+nab is an experimental Python packaging lock and package download tool,
+aiming to have similar resolver performance to uv, while being written
+in Python.
+
+nab reads a `pyproject.toml`, resolves the dependency tree, and
+writes a pinned set of versions or a PEP 751 lockfile. It does not
+install. Hand the lockfile to whatever installer you trust.
+
+## Install
+
+For package hygiene, and security reasons, the preference is to install nab itself
+as a tool, e.g.
+
+Via pipx:
+
+```bash
+pipx install nab
+```
+
+Or via uv:
+
+```bash
+uv tool install nab
+```
+
+
+## Quick start
+
+```toml
+# pyproject.toml
+[project]
+name = "example"
+version = "0.1.0"
+dependencies = [
+    "starlette<=0.36.0",
+    "fastapi<=0.115.2",
+]
+```
+
+```bash
+nab lock pyproject.toml
+```
+
+Writes `pylock.toml` next to the project. For a sorted
+`name==version` list instead, use
+`nab lock --format requirements-without-hashes --output -`.
+
+# Security
+
+nab makes some opinionated choices to be secure first
+
+## Build policy
+
+By default nab tries to extract static metadata, even from sdists,
+but sometimes that is not possible and you have to build a package
+to extract the dependency metadata. There are three build policies:
+
+ * never: Never builds a Python package
+ * build-local (default): Builds only your local workspace packages
+   if they have dynamic versions or dependencies
+ * build-remote: Builds packages sourced from indexes or VCS, it is
+   recommended that this only be turned on via per-package override
+
+## Indexes
+
+nab does not currently support sourcing the same package from
+distinct indexes. Indexes are processed in the order they are given
+to nab, and the first index that has a package is the only index
+that nab will source that package.
+
+You can override this behavior by pinning specific packages to
+specific behavior.
+
+You can also list different urls as a mirror for the same index.
+When a lockfile is written the primary url will always be used
+so that the lockfile will be stable, even if mirrors are used
+(this feature is a work in progress).
+
+## VCS policy
+
+By default nab only allows git URLs that point to a specific
+commit. Using a floating branch as a dependency must be
+enabled in the configuration.
+
+# Standards first behavior
+
+## Pre-releases
+
+Pre-release versions are selected if there are no stable
+versions to select given the requirements, even for transitive
+dependencies. A user option to force allow or block
+pre-releases per-package is a work in progress.
+
+## Validate per-distribution dependencies
+
+By default when a distribution is chosen the dependencies from
+that distribution are used, nab does not assume two different
+distributions for the same package version will have the same
+dependencies.
+
+However, sometimes you may want the lock file to produce an
+sdist, that sdist may not have static metadata, and you don't
+want to wait for the sdist to build on every lock, there is
+a distribution policy of "sdist-install", that is the metadata
+will be taken from an appropriate wheel, but the sdist will
+be selected for the install.
+
+
+# Libraries
+
+This project includes multiple libraries that can be used by
+other tools:
+
+ * `nab-resolver`: An agnostic resolver library based on PubGrub, but with
+   extensions that make it compatible with Python packaging standards
+ * `nab-python`: A Python packaging provider that drives the nab-resolver
+   with lots of specific features and optimizations for the Python packaging
+   ecosystem
+ * `nab-index`: Provides APIs for nab-python to interact with Python package
+   indexes, abstracts HTTP library interface so different HTTP libraries can
+   be plugged in
+
+All 3 libraries are in experimental mode, I currently recommend pinning them,
+e.g. `nab-resolver==0.0.1`, as APIs may change at any point.
+
+Once we reach `0.1.0` we will only break API stability on each minor update,
+so you will be able to pin to `==0.1.*` or `~=0.1.0`.

nab-0.0.1/pyproject.toml

@@ -0,0 +1,222 @@
+[project]
+name = "nab"
+version = "0.0.1"
+description = "PubGrub-based dependency resolver for Python packages"
+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-python==0.0.1",
+    "nab-index==0.0.1",
+    "tyro>=1.0",
+]
+
+[project.optional-dependencies]
+httpx = ["nab-index[httpx]==0.0.1"]
+niquests = ["nab-index[niquests]==0.0.1"]
+
+[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"
+
+[project.scripts]
+nab = "nab.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+# https://docs.pytest.org/en/stable/reference/reference.html#confval-addopts
+[tool.pytest.ini_options]
+minversion = "9.0"
+addopts = [
+    "-ra",
+    "--strict-markers",
+    "--strict-config",
+    "--import-mode=importlib",
+    "--showlocals",
+    "-m",
+    "not property and not crosshair and not network",
+]
+testpaths = [
+    "nab-resolver/tests",
+    "nab-python/tests",
+    "tests",
+]
+xfail_strict = true
+filterwarnings = ["error"]
+markers = [
+    "slow: scenarios that take more than a second",
+    "network: hits a real network endpoint (skipped by default in CI)",
+    "property: Hypothesis property tests (opt-in; run with -m property)",
+    "crosshair: CrossHair-backed property tests (opt-in; very slow; -m crosshair)",
+]
+
+# https://coverage.readthedocs.io/en/latest/config.html#run
+[tool.coverage.run]
+branch = true
+relative_files = true
+parallel = true
+concurrency = ["thread", "multiprocessing"]
+sigterm = true
+source_pkgs = [
+    "nab_resolver",
+    "nab_python",
+    "nab",
+]
+source = []
+omit = [
+    "*/tests/property/*",
+    "*/tests/property_python/*",
+    "*/tests/universal/property_universal/*",
+    "*/test_crosshair_*.py",
+    "*/_vendor/*",
+    "*/nab_python/_testing/*",
+]
+
+# https://coverage.readthedocs.io/en/latest/config.html#report
+[tool.coverage.report]
+fail_under = 100
+show_missing = true
+skip_covered = true
+skip_empty = true
+exclude_also = [
+    "def __repr__",
+    "raise NotImplementedError",
+    "raise RuntimeError.*unreachable",
+    "if __name__ == .__main__.:",
+    "class .*\\bProtocol\\):",
+    "@(abc\\.)?abstractmethod",
+    "^\\s+pass$",
+    "if TYPE_CHECKING:",
+]
+
+# https://coverage.readthedocs.io/en/latest/config.html#paths
+[tool.coverage.paths]
+nab_resolver = [
+    "nab-resolver/src/nab_resolver",
+    "*/nab_resolver",
+]
+nab_python = [
+    "nab-python/src/nab_python",
+    "*/nab_python",
+]
+nab = [
+    "src/nab",
+    "*/nab",
+]
+
+# https://docs.astral.sh/ruff/settings/
+[tool.ruff]
+target-version = "py310"
+extend-exclude = ["**/_vendor/**"]
+
+# https://docs.astral.sh/ruff/settings/#lint_per-file-ignores
+[tool.ruff.lint.per-file-ignores]
+
+# Benchmarks intentionally print, lack docstrings, run subprocesses, and
+# carry many scenario knobs.
+"**/benchmarks/**" = [
+    "T201",     # Print statements (benchmark output)
+    "D103",     # Missing docstring in public function
+    "INP001",   # Implicit namespace package (scripts live outside packages)
+    "S607",     # subprocess with partial executable path
+    "BLE001",   # Blind exception catch (surface every failure mode)
+    "C901",     # mccabe complexity (scenario knobs add branches)
+    "PLR0912",  # Too many branches (same reason as C901)
+    "PLR0915",  # Too many statements (long main()s)
+    "PLR2004",  # Magic value in comparison (benchmark thresholds)
+    "SLF001",   # Private member access (sibling scripts share helpers)
+    "N818",     # Exception name not Error-suffixed (private signal types)
+]
+
+# Tests use their own per-directory ruff.toml that extends this config.
+# See tests/ruff.toml and the per-package tests/ruff.toml files.
+
+# docs/conf.py sits outside any Python package by Sphinx convention.
+"docs/conf.py" = ["INP001"]
+
+# Subpackages defer imports to break cycles with their parent modules.
+"nab-python/src/nab_python/_provider/*.py" = ["PLC0415"]
+"nab-python/src/nab_python/_build/*.py" = ["PLC0415"]
+"nab-python/src/nab_python/_lockfile/*.py" = ["PLC0415"]
+
+# https://docs.astral.sh/ruff/settings/#lint
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    # Frameworks we don't use.
+    "AIR",     # Airflow
+    "DJ",      # Django
+    "FAST",    # FastAPI
+    "NPY",     # NumPy
+    "PD",      # Pandas
+
+    # Conflicts with the formatter.
+    "COM812",  # Trailing comma
+    "COM819",  # Prohibited trailing comma
+    "ISC001",  # Implicit string concatenation (single line)
+    "ISC002",  # Implicit string concatenation (multi-line)
+
+    # Mutually-exclusive pairs; pick one of each.
+    "D203",    # one-blank-line-before-class (we use D211)
+    "D212",    # multi-line-summary-first-line (we use D213)
+
+    # Individual rules.
+    "ANN401",  # Disallows Any (needed for generic library)
+    "S101",    # Assert usage (needed for type narrowing and tests)
+    "TID252",  # Bans relative imports; the project prefers them.
+]
+
+# https://docs.astral.sh/ruff/settings/#lintpylint
+[tool.ruff.lint.pylint]
+max-args = 8
+
+# https://docs.astral.sh/ruff/settings/#lintpydocstyle
+[tool.ruff.lint.pydocstyle]
+convention = "pep257"
+
+# https://docs.astral.sh/ruff/settings/#lintisort
+[tool.ruff.lint.isort]
+known-first-party = ["nab", "nab_index", "nab_python", "nab_resolver"]
+
+# https://microsoft.github.io/pyright/#/configuration?id=main-pyright-settings
+[tool.pyright]
+pythonVersion = "3.10"
+typeCheckingMode = "standard"
+include = [
+    "nab-resolver/src",
+    "nab-resolver/tests",
+]
+
+# https://mypy.readthedocs.io/en/stable/config_file.html#using-a-pyproject-toml-file
+[tool.mypy]
+python_version = "3.10"
+strict = true
+namespace_packages = true
+explicit_package_bases = true
+mypy_path = ["nab-resolver/src"]
+enable_error_code = [
+    "redundant-expr",
+    "truthy-bool",
+    "possibly-undefined",
+    "explicit-override",
+    "mutable-override",
+]

nab-0.0.1/src/nab/__init__.py

@@ -0,0 +1 @@
+"""nab: a PubGrub-based dependency resolver for Python packages."""

nab-0.0.1/src/nab/__main__.py

@@ -0,0 +1,6 @@
+"""Allow ``python -m nab ...`` to drive the CLI."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

nab-0.0.1/src/nab/_download.py

@@ -0,0 +1,84 @@
+"""``nab download`` subcommand.
+
+Resolves a project once with the single-environment resolver and
+fetches every wheel and sdist into a local directory.  Universal
+mode is rejected: the per-tuple lock is the install-time contract,
+so a one-environment download would not represent the resolved
+universe.
+
+External callers (the resolver entry point and the download
+helper) are accessed through :mod:`nab.cli` so the test suite's
+``patch("nab.cli.download_lock")`` style of monkey patches keeps
+working after the per-command split.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from nab_python.config import ResolveMode
+from nab_python.download import DownloadError
+
+from . import cli as _cli
+from .cli import (
+    HttpBackend,
+    PathArg,
+    app,
+)
+
+
+@app.command
+def download(
+    path: PathArg = Path("pyproject.toml"),
+    *,
+    output: Path = Path("wheels"),
+    http_backend: HttpBackend = "urllib3",
+    cache_dir: Path | None = None,
+    no_cache: bool = False,
+    offline: bool = False,
+    max_concurrency: int = 8,
+    no_workspace_discovery: bool = False,
+) -> None:
+    """Resolve and download every wheel/sdist into a local directory.
+
+    Output files are named after the recorded artefact filename.  The
+    download is idempotent: files whose sha256 already matches are
+    left alone.  Local and VCS pins are skipped.
+    """
+    config = _cli._load_config(  # noqa: SLF001
+        path, discover_workspace=not no_workspace_discovery
+    )
+    if config.mode is ResolveMode.UNIVERSAL:
+        sys.stderr.write("Error: `nab download` is single-environment only.\n")
+        sys.exit(1)
+
+    effective_cache_dir = _cli._resolve_effective_cache_dir(  # noqa: SLF001
+        cache_dir, no_cache=no_cache
+    )
+    transport = _cli._make_transport(http_backend)  # noqa: SLF001
+    result = _cli._resolve_specific(  # noqa: SLF001
+        path,
+        config=config,
+        cache_dir=effective_cache_dir,
+        offline=offline,
+        transport=transport,
+        failure_prefix="Cannot download",
+    )
+
+    download_transport = _cli._make_transport(http_backend)  # noqa: SLF001
+    try:
+        outcome = _cli.download_lock(
+            result.lock_input,
+            download_transport,
+            output,
+            max_concurrency=max_concurrency,
+        )
+    except DownloadError as e:
+        sys.stderr.write(f"Download failed: {e}\n")
+        sys.exit(1)
+
+    sys.stderr.write(
+        f"Downloaded {len(outcome.written)} files,"
+        f" {len(outcome.skipped)} already present, into {output}\n"
+    )

nab-0.0.1/src/nab/_lock.py

@@ -0,0 +1,476 @@
+"""``nab lock`` subcommand and its lockfile-emission helpers.
+
+Wires :func:`resolve_pyproject` / :func:`resolve_universal_pyproject`
+to the writers in :mod:`nab_python.lockfile`, plus the universal-mode
+per-tuple emission shapes (single-tuple file, templated per-tuple
+files, multi-block stdout).
+
+External callers (the resolver entry points, the lockfile writers,
+the merge helper) are accessed through :mod:`nab.cli` so the test
+suite's ``patch("nab.cli.resolve_pyproject")`` style of monkey
+patches keeps working after the per-command split.
+"""
+
+from __future__ import annotations
+
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from nab._version import __version__
+from nab_python.config import (
+    NabProjectConfig,
+    ResolveMode,
+)
+from nab_python.lockfile import (
+    Provenance,
+    read_lockfile_anchor,
+)
+from nab_python.provider import ResolutionStrategy
+from nab_python.requirements_file import (
+    read_pyproject_groups,
+    read_pyproject_optional_dependencies,
+)
+
+from . import cli as _cli
+from .cli import (
+    HttpBackend,
+    LockFormat,
+    PathArg,
+    ResolutionFlag,
+    app,
+)
+
+if TYPE_CHECKING:
+    from nab_index.transport import AsyncHttpTransport
+    from nab_python.resolve import ResolutionResult
+    from nab_python.universal.resolve import TupleResult, UniversalResult
+
+
+@app.command
+def lock(  # noqa: PLR0913 - tyro maps each kwarg to a CLI flag so a config object would hide the user-facing surface
+    path: PathArg = Path("pyproject.toml"),
+    *,
+    output: Path | None = None,
+    format: LockFormat = "pylock",  # noqa: A002 - shadows builtin by convention
+    http_backend: HttpBackend = "urllib3",
+    cache_dir: Path | None = None,
+    no_cache: bool = False,
+    offline: bool = False,
+    groups: tuple[str, ...] = (),
+    all_groups: bool = False,
+    extras: tuple[str, ...] = (),
+    all_extras: bool = False,
+    no_workspace_discovery: bool = False,
+    resolution: ResolutionFlag | None = None,
+    upgrade: bool = False,
+) -> None:
+    """Resolve dependencies and emit a lockfile or pin list.
+
+    Formats: ``pylock`` (PEP 751), ``requirements`` (pip-style with
+    ``--hash`` lines), ``requirements-without-hashes`` (plain
+    ``name==version``).  ``--output`` defaults to ``pylock.toml`` or
+    ``requirements.txt``; ``--output -`` writes to stdout.
+
+    ``--groups`` / ``--all-groups`` select PEP 735 dependency groups;
+    ``--extras`` / ``--all-extras`` select entries from
+    ``[project.optional-dependencies]``.  Selected names are folded into
+    the resolve and recorded in the lockfile.
+
+    Universal mode (``[tool.nab].mode = "universal"``) supports all
+    three formats.  For requirements formats, an ``--output`` template
+    containing ``{python_version}`` or ``{platform_id}`` writes one
+    file per matrix tuple; a plain path is rejected when multiple
+    tuples would collide.
+
+    ``--resolution`` overrides ``[tool.nab].resolution`` for this run.
+    ``--upgrade`` re-anchors the ``P<n>D`` cutoff to ``datetime.now(UTC)``
+    instead of reusing the timestamp recorded in any existing lockfile.
+    """
+    anchor = _determine_lock_anchor(output=output, format=format, upgrade=upgrade)
+    config = _cli._load_config(  # noqa: SLF001
+        path, discover_workspace=not no_workspace_discovery, anchor=anchor
+    )
+    effective_cache_dir = _cli._resolve_effective_cache_dir(  # noqa: SLF001
+        cache_dir, no_cache=no_cache
+    )
+    provenance = _build_provenance(path, config=config, anchor=anchor)
+    selected_groups = _resolve_group_selection(
+        path, groups=groups, all_groups=all_groups
+    )
+    selected_extras = _resolve_extra_selection(
+        path, extras=extras, all_extras=all_extras
+    )
+    strategy_override = (
+        ResolutionStrategy(resolution) if resolution is not None else None
+    )
+
+    transport = _cli._make_transport(http_backend)  # noqa: SLF001
+    if config.mode is ResolveMode.UNIVERSAL:
+        _emit_universal(
+            path,
+            config=config,
+            cache_dir=effective_cache_dir,
+            transport=transport,
+            offline=offline,
+            output=output,
+            format=format,
+            provenance=provenance,
+            groups=selected_groups,
+            extras=selected_extras,
+            resolution_strategy=strategy_override,
+        )
+        return
+
+    result = _cli._resolve_specific(  # noqa: SLF001
+        path,
+        config=config,
+        cache_dir=effective_cache_dir,
+        offline=offline,
+        transport=transport,
+        failure_prefix="Cannot lock",
+        groups=selected_groups,
+        extras=selected_extras,
+        resolution_strategy=strategy_override,
+    )
+    _emit_specific(result, format=format, output=output, provenance=provenance)
+
+
+def _emit_specific(
+    result: ResolutionResult,
+    *,
+    format: str,  # noqa: A002 - shadows builtin by convention
+    output: Path | None,
+    provenance: Provenance | None = None,
+) -> None:
+    """Write a single-environment resolution in the requested format."""
+    lock_input = result.lock_input
+    if provenance is not None:
+        lock_input.provenance = provenance
+
+    if _cli._is_stdout(output):  # noqa: SLF001
+        if format == "pylock":
+            sys.stdout.write(_cli.write_lock(lock_input))
+        elif format == "requirements":
+            sys.stdout.write(_cli.write_requirements_with_hashes(lock_input))
+        else:
+            sys.stdout.write(_cli.write_requirements_without_hashes(lock_input))
+        return
+
+    target = output if output is not None else Path(_cli._DEFAULT_OUTPUT[format])  # noqa: SLF001
+    if format == "pylock":
+        _cli.write_lock(lock_input, output_path=target)
+    elif format == "requirements":
+        _cli.write_requirements_with_hashes(lock_input, output_path=target)
+    else:
+        _cli.write_requirements_without_hashes(lock_input, output_path=target)
+    sys.stderr.write(f"Wrote {target} ({len(result.pins)} packages)\n")
+
+
+def _emit_universal(  # noqa: PLR0913 - one wrapper per resolve_universal_pyproject kwarg
+    path: Path,
+    *,
+    config: NabProjectConfig,
+    cache_dir: Path | None,
+    transport: AsyncHttpTransport,
+    offline: bool,
+    output: Path | None,
+    format: str,  # noqa: A002 - shadows builtin by convention
+    provenance: Provenance | None = None,
+    groups: tuple[str, ...] = (),
+    extras: tuple[str, ...] = (),
+    resolution_strategy: ResolutionStrategy | None = None,
+) -> None:
+    """Run the universal resolver and emit the requested artefact."""
+    sys.stderr.write(
+        "warning: mode = 'universal' is experimental; output format may"
+        " change without notice\n"
+    )
+
+    try:
+        result = _cli.resolve_universal_pyproject(
+            path,
+            config=config,
+            cache_dir=cache_dir,
+            transport=transport,
+            offline=offline,
+            groups=groups,
+            extras=extras,
+            resolution_strategy=resolution_strategy,
+        )
+    except KeyError:
+        sys.stderr.write(f"Error: {path} has no [project].dependencies\n")
+        sys.exit(1)
+    except LookupError as e:
+        sys.stderr.write(f"Error: {e}\n")
+        sys.exit(1)
+
+    if not result.success:
+        # Always print per-tuple blocks on failure so the user sees
+        # which tuple(s) failed and why; the resolved tuples still
+        # appear so partial progress is visible.
+        _print_universal_blocks(result)
+        sys.exit(1)
+
+    if format == "pylock":
+        _emit_universal_pylock(
+            result,
+            output=output,
+            provenance=provenance,
+            groups=groups,
+            extras=extras,
+        )
+    else:
+        _emit_universal_requirements(
+            result, output=output, with_hashes=format == "requirements"
+        )
+
+
+def _emit_universal_pylock(
+    result: UniversalResult,
+    *,
+    output: Path | None,
+    provenance: Provenance | None = None,
+    groups: tuple[str, ...] = (),
+    extras: tuple[str, ...] = (),
+) -> None:
+    """Merge per-tuple LockInputs into one pylock and write/print it."""
+    lock_input = _cli.merge_universal_lock_inputs(
+        result,
+        extras=extras,
+        dependency_groups=groups,
+        default_groups=groups,
+    )
+    if provenance is not None:
+        lock_input.provenance = provenance
+
+    try:
+        text = _cli.write_lock(lock_input)
+    except _cli.MissingHashError as e:
+        sys.stderr.write(f"Cannot lock: {e}\n")
+        sys.exit(1)
+
+    if _cli._is_stdout(output):  # noqa: SLF001
+        sys.stdout.write(text)
+        return
+    target = output if output is not None else Path(_cli._DEFAULT_OUTPUT["pylock"])  # noqa: SLF001
+    target.write_text(text, encoding="utf-8")
+    sys.stderr.write(f"Wrote {target} ({len(result.tuple_results)} tuples)\n")
+
+
+def _emit_universal_requirements(
+    result: UniversalResult, *, output: Path | None, with_hashes: bool
+) -> None:
+    """Emit one requirements file per matrix tuple.
+
+    Three output shapes:
+
+    * ``output`` is ``None`` or ``-``: write one stdout dump with
+      ``# label`` blocks separating each tuple's pins.  Inspection /
+      piping shape; pip cannot install a multi-block file directly.
+    * ``output`` contains ``{python_version}`` or ``{platform_id}``:
+      write one file per successful tuple, substituting the tuple's
+      values into the template.  This is the constraints-per-
+      Python-version shape (e.g. ``constraints-{python_version}.txt``).
+    * ``output`` is a plain path AND the matrix has exactly one tuple:
+      write that tuple's pins to ``output`` directly.
+
+    A plain path with multiple tuples errors clearly: there is no
+    one-file shape that pip can install from across all tuples.
+    """
+    if output is None or _cli._is_stdout(output):  # noqa: SLF001
+        _emit_universal_requirements_stdout(result, with_hashes=with_hashes)
+        return
+
+    template = str(output)
+    successful = [tr for tr in result.tuple_results if tr.success]
+    if not any(var in template for var in _cli._TUPLE_TEMPLATE_VARS):  # noqa: SLF001
+        if len(successful) > 1:
+            sys.stderr.write(
+                "Error: universal mode produced multiple tuples but"
+                f" --output {output} has no template variable to"
+                " disambiguate.  Use {python_version} and/or"
+                " {platform_id} in the path, e.g.:\n"
+                "  --output 'constraints-{python_version}.txt'\n"
+            )
+            sys.exit(1)
+        # Single successful tuple: write directly to the fixed path.
+        _write_one_tuple_requirements(successful[0], output, with_hashes=with_hashes)
+        return
+
+    for tr in successful:
+        substituted = template.format(
+            python_version=tr.tuple_.python_version,
+            platform_id=tr.tuple_.platform_id,
+        )
+        _write_one_tuple_requirements(tr, Path(substituted), with_hashes=with_hashes)
+
+
+def _emit_universal_requirements_stdout(
+    result: UniversalResult, *, with_hashes: bool
+) -> None:
+    """Stdout shape: per-tuple ``# label`` blocks merged into one stream."""
+    lock_input = _cli.merge_universal_lock_inputs(result)
+    try:
+        if with_hashes:
+            text = _cli.write_requirements_with_hashes(lock_input)
+        else:
+            text = _cli.write_requirements_without_hashes(lock_input)
+    except _cli.MissingHashError as e:
+        sys.stderr.write(f"Cannot lock: {e}\n")
+        sys.exit(1)
+    sys.stdout.write(text)
+
+
+def _write_one_tuple_requirements(
+    tr: TupleResult, output: Path, *, with_hashes: bool
+) -> None:
+    """Write a single TupleResult's pins to ``output``."""
+    if tr.lock_input is None:  # pragma: no cover - successful tuples carry one
+        return
+
+    try:
+        if with_hashes:
+            text = _cli.write_requirements_with_hashes(tr.lock_input)
+        else:
+            text = _cli.write_requirements_without_hashes(tr.lock_input)
+    except _cli.MissingHashError as e:
+        sys.stderr.write(f"Cannot lock: {e}\n")
+        sys.exit(1)
+
+    output.write_text(text, encoding="utf-8")
+    sys.stderr.write(
+        f"Wrote {output} ({len(tr.lock_input.pins)} packages,"
+        f" tuple {tr.tuple_.label})\n"
+    )
+
+
+def _resolve_group_selection(
+    path: Path,
+    *,
+    groups: tuple[str, ...],
+    all_groups: bool,
+) -> tuple[str, ...]:
+    """Return the canonical, deduplicated group selection for this run.
+
+    ``groups`` is the user-supplied list (already split by tyro on
+    commas).  ``all_groups`` overrides it: when set, every group
+    defined in the project's ``[dependency-groups]`` table is
+    selected.  An ``--all-groups`` paired with a non-empty
+    ``--groups`` list raises a clean error rather than silently
+    preferring one over the other.
+    """
+    if all_groups and groups:
+        sys.stderr.write("Error: --all-groups and --groups are mutually exclusive\n")
+        sys.exit(1)
+    if not all_groups:
+        return tuple(dict.fromkeys(groups))
+
+    try:
+        defined = read_pyproject_groups(path)
+    except FileNotFoundError:
+        sys.stderr.write(f"Error: {path} not found\n")
+        sys.exit(1)
+    return tuple(defined.keys())
+
+
+def _resolve_extra_selection(
+    path: Path,
+    *,
+    extras: tuple[str, ...],
+    all_extras: bool,
+) -> tuple[str, ...]:
+    """Return the canonical, deduplicated extras selection for this run."""
+    if all_extras and extras:
+        sys.stderr.write("Error: --all-extras and --extras are mutually exclusive\n")
+        sys.exit(1)
+    if not all_extras:
+        return tuple(dict.fromkeys(extras))
+
+    try:
+        defined = read_pyproject_optional_dependencies(path)
+    except FileNotFoundError:
+        sys.stderr.write(f"Error: {path} not found\n")
+        sys.exit(1)
+    return tuple(defined.keys())
+
+
+def _build_provenance(
+    path: Path, *, config: NabProjectConfig, anchor: datetime
+) -> Provenance:
+    """Capture the inputs that produced this run for the lockfile.
+
+    The block lands under ``[tool.nab]`` and is informational only.
+
+    ``anchor`` is the timestamp used as ``now`` when resolving relative
+    ``P<n>D`` durations on this run.  Recording it as ``created-at``
+    lets the next ``nab lock`` reuse the same anchor and reproduce the
+    same cutoff.
+    """
+    python_specifier: str | None
+    platforms: tuple[str, ...]
+    if config.mode is ResolveMode.UNIVERSAL and config.matrix is not None:
+        python_specifier = config.matrix.python
+        platforms = tuple(config.matrix.platforms)
+    else:
+        python_specifier = config.requires_python
+        platforms = ()
+
+    return Provenance(
+        nab_version=__version__,
+        created_at=anchor,
+        command_line=tuple(sys.argv),
+        input_path=str(path),
+        mode=config.mode.value,
+        python_specifier=python_specifier,
+        platforms=platforms,
+    )
+
+
+def _determine_lock_anchor(
+    *,
+    output: Path | None,
+    format: str,  # noqa: A002 - shadows builtin by convention
+    upgrade: bool,
+) -> datetime:
+    """Pick the ``P<n>D`` anchor for ``nab lock``.
+
+    Returns ``datetime.now(UTC)`` (a fresh anchor) when:
+
+    - ``--upgrade`` is set: the user is opting into a calendar refresh.
+    - Output is stdout (``-``): there is no file to read back later, so
+      no point preserving an anchor that nothing will reuse.
+    - Format is not ``pylock``: requirements files do not carry the
+      ``[tool.nab]`` block we read the anchor from.
+    - The expected pylock does not exist or has no recorded anchor:
+      first lock or a damaged file.
+
+    Otherwise returns the ``[tool.nab].created-at`` from the existing
+    pylock, so a re-lock against the same project produces the same
+    cutoff for ``P<n>D`` durations.
+    """
+    fresh = datetime.now(timezone.utc)
+    if upgrade:
+        return fresh
+    if _cli._is_stdout(output):  # noqa: SLF001
+        return fresh
+    if format != "pylock":
+        return fresh
+    target = output if output is not None else Path(_cli._DEFAULT_OUTPUT[format])  # noqa: SLF001
+    prior = read_lockfile_anchor(target)
+    return prior if prior is not None else fresh
+
+
+def _print_universal_blocks(result: UniversalResult) -> None:
+    """Write per-tuple pin blocks (with FAILED markers) to stdout."""
+    blocks: list[str] = []
+    for tr in result.tuple_results:
+        label = tr.tuple_.label
+        if not tr.success:
+            blocks.append(f"# {label}: FAILED")
+            blocks.extend(f"#   {raw}" for raw in (tr.error or "").splitlines())
+            continue
+        blocks.append(f"# {label}")
+        blocks.extend(f"{name}=={tr.pins[name]}" for name in sorted(tr.pins))
+    sys.stdout.write("\n".join(blocks) + "\n")

nab-0.0.1/src/nab/_version.py

@@ -0,0 +1,6 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("nab")
+except PackageNotFoundError:
+    __version__ = "0.0.0+unknown"

nab-0.0.1/src/nab/cli.py

@@ -0,0 +1,218 @@
+"""Entry point for the nab command.
+
+Holds the tyro :class:`SubcommandApp` registration plus the helpers
+shared between :mod:`nab._lock` and :mod:`nab._download`: HTTP
+transport selection, cache-directory defaults, config loading, and
+the resolver-error-to-exit-code translation.
+
+The two subcommands live in :mod:`nab._lock` and :mod:`nab._download`;
+this module imports them so their ``@app.command`` decorators run
+before :func:`main` calls ``app.cli()``.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING, Annotated, Literal
+
+import tyro
+from tyro.extras import SubcommandApp
+
+from nab._version import __version__
+from nab_index.urllib3_async_transport import Urllib3AsyncTransport
+from nab_python.config import (
+    ConfigError,
+    NabProjectConfig,
+    read_pyproject_config,
+)
+from nab_python.download import download_lock  # noqa: F401 - re-exported for tests
+from nab_python.lockfile import (
+    MissingHashError,
+    write_lock,  # noqa: F401 - re-exported for tests
+    write_requirements_with_hashes,  # noqa: F401 - re-exported for tests
+    write_requirements_without_hashes,  # noqa: F401 - re-exported for tests
+)
+from nab_python.resolve import (
+    resolve_pyproject,
+    resolve_universal_pyproject,  # noqa: F401 - re-exported for tests
+)
+from nab_python.universal.resolve import (
+    merge_universal_lock_inputs,  # noqa: F401 - re-exported for tests
+)
+from nab_python.workspace import WorkspaceDiscoveryError
+from nab_resolver.resolver import ResolutionError
+
+if TYPE_CHECKING:
+    from datetime import datetime
+
+    from nab_index.transport import AsyncHttpTransport
+    from nab_python.provider import ResolutionStrategy
+    from nab_python.resolve import ResolutionResult
+
+__all__ = [
+    "main",
+]
+
+
+# A pyproject.toml positional that may also be omitted to default to ./pyproject.toml.
+PathArg = Annotated[Path, tyro.conf.Positional]
+
+# Lowercase Literal types so --http-backend and --format render lowercase
+# choices in --help rather than the uppercase enum names.
+HttpBackend = Literal["urllib3", "httpx", "niquests"]
+LockFormat = Literal["pylock", "requirements", "requirements-without-hashes"]
+ResolutionFlag = Literal["highest", "lowest", "lowest-direct"]
+
+_DEFAULT_OUTPUT: dict[str, str] = {
+    "pylock": "pylock.toml",
+    "requirements": "requirements.txt",
+    "requirements-without-hashes": "requirements.txt",
+}
+
+_TUPLE_TEMPLATE_VARS = ("{python_version}", "{platform_id}")
+
+# Conventional KeyboardInterrupt exit code: 128 + SIGINT(2).
+_SIGINT_EXIT_CODE = 130
+
+app = SubcommandApp()
+
+
+def _make_transport(backend: HttpBackend) -> AsyncHttpTransport:
+    # httpx and niquests are optional extras; import lazily so a
+    # urllib3-only install doesn't need them.
+    if backend == "httpx":
+        try:
+            from nab_index.httpx_async_transport import (  # noqa: PLC0415
+                HttpxAsyncTransport,
+            )
+        except ImportError:
+            sys.stderr.write(
+                "Error: httpx is not installed; run `pip install nab[httpx]`\n"
+            )
+            sys.exit(1)
+        return HttpxAsyncTransport()
+
+    if backend == "niquests":
+        try:
+            from nab_index.niquests_async_transport import (  # noqa: PLC0415
+                NiquestsAsyncTransport,
+            )
+        except ImportError:
+            sys.stderr.write(
+                "Error: niquests is not installed; run `pip install nab[niquests]`\n"
+            )
+            sys.exit(1)
+        return NiquestsAsyncTransport()
+
+    return Urllib3AsyncTransport()
+
+
+def _default_cache_dir() -> Path:
+    """Return the default per-user cache root.
+
+    Mirrors ``platformdirs.user_cache_path("nab")`` without the
+    dependency: ``$XDG_CACHE_HOME/nab`` or ``~/.cache/nab``.
+    """
+    base = os.environ.get("XDG_CACHE_HOME")
+    if base:
+        return Path(base) / "nab"
+    return Path.home() / ".cache" / "nab"
+
+
+def _resolve_effective_cache_dir(
+    cache_dir: Path | None, *, no_cache: bool
+) -> Path | None:
+    if no_cache:
+        return None
+    if cache_dir is not None:
+        return cache_dir
+    return _default_cache_dir()
+
+
+def _load_config(
+    path: Path,
+    *,
+    discover_workspace: bool = True,
+    anchor: datetime | None = None,
+) -> NabProjectConfig:
+    if not path.exists():
+        sys.stderr.write(f"Error: {path} not found\n")
+        sys.exit(1)
+
+    try:
+        return read_pyproject_config(
+            path, discover_workspace=discover_workspace, anchor=anchor
+        )
+    except ConfigError as exc:
+        sys.stderr.write(f"Error in [tool.nab]: {exc}\n")
+        sys.exit(1)
+    except WorkspaceDiscoveryError as exc:
+        sys.stderr.write(f"Workspace discovery error: {exc}\n")
+        sys.exit(1)
+
+
+def _is_stdout(output: Path | None) -> bool:
+    return output is not None and str(output) == "-"
+
+
+def _resolve_specific(  # noqa: PLR0913 - one wrapper per resolve_pyproject kwarg
+    path: Path,
+    *,
+    config: NabProjectConfig,
+    cache_dir: Path | None,
+    offline: bool,
+    transport: AsyncHttpTransport,
+    failure_prefix: str,
+    groups: tuple[str, ...] = (),
+    extras: tuple[str, ...] = (),
+    resolution_strategy: ResolutionStrategy | None = None,
+) -> ResolutionResult:
+    """Run the single-environment resolver and translate errors to exits."""
+    try:
+        return resolve_pyproject(
+            path,
+            transport,
+            config=config,
+            cache_dir=cache_dir,
+            offline=offline,
+            groups=groups,
+            extras=extras,
+            resolution_strategy=resolution_strategy,
+        )
+    except ResolutionError as e:
+        sys.stderr.write(f"Resolution failed: {e}\n")
+        sys.exit(1)
+    except KeyError:
+        sys.stderr.write(f"Error: {path} has no [project].dependencies\n")
+        sys.exit(1)
+    except LookupError as e:
+        sys.stderr.write(f"Error: {e}\n")
+        sys.exit(1)
+    except MissingHashError as e:
+        sys.stderr.write(f"{failure_prefix}: {e}\n")
+        sys.exit(1)
+
+
+# Side-effect imports: each module's @app.command decorators register the
+# subcommand.  Placed at the bottom so helpers above bind before
+# nab._lock / nab._download import back from this module.
+from . import _download as _download_module  # noqa: E402, F401 - side-effect
+from . import _lock as _lock_module  # noqa: E402, F401 - side-effect
+
+
+def main() -> None:
+    """Entry point for the nab command."""
+    # Tyro's SubcommandApp does not surface a global ``--version`` flag,
+    # so the check runs before ``app.cli()`` parses the sub-command.
+    argv = sys.argv[1:]
+    if argv and argv[0] in {"--version", "-V"}:
+        sys.stdout.write(f"nab {__version__}\n")
+        return
+
+    try:
+        app.cli(prog="nab")
+    except KeyboardInterrupt:
+        sys.stderr.write("Aborted.\n")
+        sys.exit(_SIGINT_EXIT_CODE)