Metadata-Version: 2.5
Name: nab
Version: 0.0.20
Summary: PubGrub-based dependency resolver for Python packages
Project-URL: Homepage, https://github.com/notatallshaw/nab
Project-URL: Documentation, https://nab.readthedocs.io/en/stable/
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/releases
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: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: nab-index==0.0.20
Requires-Dist: nab-markersets==0.0.20
Requires-Dist: nab-project==0.0.20
Requires-Dist: nab-provider==0.0.20
Requires-Dist: nab-resolver==0.0.20
Requires-Dist: tomli>=2.2
Requires-Dist: typing-extensions>=4.6
Provides-Extra: httpx
Requires-Dist: nab-index[httpx]==0.0.20; extra == 'httpx'
Provides-Extra: httpx2
Requires-Dist: nab-index[httpx2]==0.0.20; extra == 'httpx2'
Description-Content-Type: text/markdown

# nab

nab is an experimental dependency locker and download tool for Python packages, written in Python
but aiming to have similar performance to uv on cold resolves.

It reads your `pyproject.toml`, finds compatible versions of your dependencies, and writes a PEP 751
`pylock.toml` or pinned requirements. An installer such as pip then installs from that file.

Documentation: <https://nab.readthedocs.io/en/stable/>

## Install

Install nab in an isolated tool environment:

```bash
uv tool install nab
# or
pipx install nab
```

Confirm the command is available with `nab --version`. nab runs on CPython 3.10 and newer.

## Quick start

From a directory containing your `pyproject.toml` (or the [example below](#example-project)),
resolve and write the lock:

```bash
nab lock pyproject.toml
```

Open `pylock.toml` to see the selected versions and distribution hashes.

In a virtual environment matching the lock's Python and platform, install with pip 26.1 or newer:

```bash
python -m pip install -r pylock.toml
```

pip's `pylock.toml` support is experimental. This installs the locked dependencies; installing your
own project is a separate step. The [getting-started tutorial][getting-started] includes environment
setup, and [Use a lock][use-lock] explains pip's selection limits.

## Why nab?

### Keep dependency choices in a file

Locking is a separate step from changing your environment. `nab lock` records exact dependency
versions for the environments you resolve, so you can review and commit the result before installing
it.

For a single-environment lock, you can also [check the committed file in CI][check-lock].

### Use standard packaging formats

Keep your dependency declarations in the standard `[project]` table of `pyproject.toml`. nab reads
Python packaging versions, requirements, and environment markers, and produces a
[cross-tool PEP 751 lockfile][lockfiles]. You can also write hashed requirements for pip.

### Choose your target environments explicitly

By default, nab resolves for the Python and platform running nab. You can
[declare a different target][resolve-environment], such as the Python used in production, or a
matrix of targets for several platforms. Dependency markers and wheel compatibility are evaluated
for those targets, and the lock records where it applies. If any declared target cannot be resolved,
nab fails without writing a lock.

### Security via build and VCS policies

Reading dependency metadata can require running a package's build backend. nab
[reads remote sources without building them by default][build-policy]; local checkouts may build
when their metadata needs it. If a remote package requires a build, you can opt in for that package.
[Direct archives][archive-sources] also require a verified digest.

nab blocks [VCS dependencies][vcs] by default and supports only Git. To allow them, set
`policy = "allow"` under `[tool.nab.vcs]` and list both the permitted URL schemes and repository
prefixes in `allowed-schemes` and `allowed-repos`. By default, `require-pin = true` requires a full
40-character commit SHA; branch and tag references are rejected. Declare dependencies in
`[[tool.nab.vcs-sources]]`. Allowing a repository permits cloning and reading static metadata;
running its build backend still requires opting in to remote builds.

### Override global policies for specific packages and indexes

To keep global policies strict and secure while allowing exceptions for specific needs, you can
[override global policies][policy-overrides] for a package, a version range such as `numpy > 2`, or
every package served by a named index.

For example, allow remote builds for one package, require wheels for selected versions, or set a
different upload cutoff for an internal index. Use `[tool.nab.packages."numpy > 2"]` for one
selector, `[[tool.nab.package-rules]]` to share a policy across several, or
`[tool.nab.index.<name>]` for an index.

Requirement selectors accept package names and version specifiers. Fields without an override retain
their global defaults.

## Example project

If you do not have a project yet, save this small example as `pyproject.toml` in a new directory:

```toml
# pyproject.toml
[project]
name = "example"
version = "0.1.0"
dependencies = [
    "starlette<=0.36.0",
    "fastapi<=0.115.2",
]
```

Run `nab lock pyproject.toml` from that directory. The constraints above must hold together: nab may
choose an older FastAPI release to satisfy the Starlette limit.

## Write hashed requirements

For a single-environment project using only index packages, the hashed-requirements alternative is:

```bash
nab lock --format requirements pyproject.toml
python -m pip install --require-hashes -r requirements.txt
```

This performs a fresh resolve and writes `requirements.txt`.

`--format requirements-without-hashes` omits separate hash lines from index pins; archive URLs keep
their digest. See [Output formats][output-formats] before using local, VCS, archive, or multi-target
inputs.

## Lock for your deployment targets

If your application uses Python 3.12 on the same platform as nab, select it explicitly:

```bash
nab lock --python 3.12 pyproject.toml
```

`--python` changes the resolve target; it does not install or switch interpreters. Use an
environment matching the lock when installing.

To cover Python 3.11 and 3.12 on Linux x86-64 and macOS ARM64, add these tables to your project:

```toml
[tool.nab]
mode = "universal"

[tool.nab.matrix]
python = ">=3.11,<3.13"
platforms = ["linux_x86_64", "macos_arm64"]
```

Run `nab lock pyproject.toml` again to write one lock covering those four targets. Versions can
differ between targets when compatibility requires it. The multi-target lock format is experimental;
[Universal resolution][universal] explains the matrix and how to set minimum operating-system
versions.

## Libraries

nab publishes five component libraries for other tools:

- `nab-resolver`: a generic PubGrub resolver.
- `nab-markersets`: a PEP 508 marker algebra.
- `nab-provider`: Python packaging policy and resolution logic without I/O.
- `nab-index`: package-index and source clients with caching.
- `nab-project`: resolve orchestration plus lock and download workflows.

`nab-resolver` has stable public module paths. The other component APIs are experimental. See
[how the distributions fit together][packages].

To explore the code, start with the [package overview](docs/explanation/packages.md) and the
[CLI walkthrough](src/nab/_cli/README.md).

## Project status

nab is under active development. See the [status summary][status] for supported inputs and
experimental features.

[archive-sources]: https://nab.readthedocs.io/en/stable/how-to/archive-sources.html
[build-policy]: https://nab.readthedocs.io/en/stable/reference/build-policy.html
[check-lock]: https://nab.readthedocs.io/en/stable/reference/lockfile.html#checking-the-lock-in-ci
[getting-started]: https://nab.readthedocs.io/en/stable/tutorial/getting-started.html
[lockfiles]: https://nab.readthedocs.io/en/stable/reference/lockfile.html
[output-formats]: https://nab.readthedocs.io/en/stable/reference/formats.html
[packages]: https://nab.readthedocs.io/en/stable/explanation/packages.html
[policy-overrides]: https://nab.readthedocs.io/en/stable/reference/configuration.html#overrides
[resolve-environment]: https://nab.readthedocs.io/en/stable/reference/configuration.html#the-resolve-environment
[status]: https://nab.readthedocs.io/en/stable/#status
[universal]: https://nab.readthedocs.io/en/stable/explanation/universal.html
[use-lock]: https://nab.readthedocs.io/en/stable/how-to/use-the-lock.html
[vcs]: https://nab.readthedocs.io/en/stable/how-to/vcs.html
