Metadata-Version: 2.4
Name: proviso
Version: 0.4.0
Summary: Proviso requirements.txt management
Author-email: Ross McFarland <rwmcfa1@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/octodns/proviso
Project-URL: Source, https://github.com/octodns/proviso
Project-URL: Issues, https://github.com/octodns/proviso/issues
Keywords: octodns,requirements,dependency-resolution,packaging
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Build Tools
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
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: build>=0.7.0
Requires-Dist: hishel[httpx2]<3.0.0,>=2.0.0
Requires-Dist: httpx2<3.0.0,>=2.9.1
Requires-Dist: resolvelib>=1.0.0
Requires-Dist: setuptools>=40.8.0
Requires-Dist: unearth<0.20.0,>=0.19.0
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: pytest-network; extra == "test"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: pytest-network; extra == "dev"
Requires-Dist: black<27.0.0,>=26.0.0; extra == "dev"
Requires-Dist: changelet; extra == "dev"
Requires-Dist: isort>=5.11.5; extra == "dev"
Requires-Dist: pyflakes>=2.2.0; extra == "dev"
Requires-Dist: readme_renderer[md]>=26.0; extra == "dev"
Requires-Dist: twine>=3.4.2; extra == "dev"
Dynamic: license-file

## Proviso requirements.txt management

A tool for managing requirements.txt version pinning and updating. Proviso extracts dependencies from your project's setup.py or pyproject.toml, resolves all transitive dependencies using PyPI, and generates a fully pinned requirements.txt file that works across multiple Python versions.

### Installation

#### Command line

```
pip install proviso
```

#### requirements.txt/setup.py

Pinning specific versions or SHAs is recommended to avoid unplanned upgrades.

##### Versions

```
# Start with the latest versions and don't just copy what's here
proviso==0.0.1
```

##### SHAs

```
# Start with the latest/specific versions and don't just copy what's here
-e git+https://git@github.com/octodns/proviso.git@ec9661f8b335241ae4746eea467a8509205e6a30#egg=proviso
```

### Usage

#### Basic usage

Generate a requirements.txt for all currently active Python versions:

```bash
proviso
```

This will:
1. Read dependencies from your project's setup.py or pyproject.toml
2. Resolve all transitive dependencies from PyPI
3. Generate a requirements.txt with pinned versions that work across all currently active Python versions (queried from endoflife.date)

#### Common options

Generate requirements for specific Python versions:

```bash
proviso --python-versions 3.10,3.11,3.12
```

Include specific extras (e.g., dev dependencies):

```bash
proviso --extras dev,test
```

Specify a custom output file:

```bash
proviso --filename requirements-dev.txt
```

Customize the header comment:

```bash
proviso --header "# Generated requirements - do not edit"
```

By default proviso ignores anything published in the last 7 days, so a
brand-new release doesn't get pinned the moment it lands. Adjust the window:

```bash
proviso --cooldown-days 14
```

Or turn it off entirely to always take the newest releases:

```bash
proviso --cooldown-days 0
```

#### Full command-line reference

```console
usage: proviso [-h] [--directory DIRECTORY] [--extras EXTRAS] [--python-versions PYTHON_VERSIONS] [--filename FILENAME]
               [--level {DEBUG,ERROR,INFO,WARNING,debug,error,info,warning}] [--header HEADER] [--cache-db CACHE_DB]
               [--cooldown-days COOLDOWN_DAYS]

Extract project requirements, resolve dependencies, and manage requirements.txt

options:
  -h, --help            show this help message and exit
  --directory DIRECTORY
                        Project root directory (default: current directory)
  --extras EXTRAS       Comma-separated list of extras to include (e.g., "dev,test"). Defaults to all defined extras.
  --python-versions PYTHON_VERSIONS
                        Comma-separated list of Python versions (e.g., "3.9,3.10,3.11"). Defaults to currently active
                        versions per endoflife.date.
  --filename FILENAME   Output filename or path for requirements (default: requirements.txt). If just a filename, will be
                        placed in --directory; if a path, will be used as-is.
  --level {DEBUG,ERROR,INFO,WARNING,debug,error,info,warning}
                        Logging level (default: WARNING)
  --header HEADER       Header comment to place at the top of the requirements file. Use the string "[command line]" to
                        insert the actual command that was run. (default: "# DO NOT EDIT THIS FILE DIRECTLY - use [command
                        line]")
  --cache-db CACHE_DB   Path to SQLite database for persistent HTTP caching. If not specified, checks PROVISO_CACHE_DB
                        environment variable. If neither is set, uses in-memory caching.
  --cooldown-days COOLDOWN_DAYS
                        Exclude packages uploaded within this many days (dependency cooldown). Default: 7. Use 0 to
                        disable.
```

#### Features

- **Multi-version support**: Generates a single requirements.txt that works across multiple Python versions, using environment markers (e.g., `package==1.0.0; python_version=='3.10'`) when different versions are needed
- **Complete dependency resolution**: Recursively resolves all transitive dependencies from PyPI
- **Dependency cooldown**: Skips releases published within the last 7 days by default so brand-new releases don't get pinned immediately, configurable with `--cooldown-days` (`0` disables it)
- **Automatic Python version detection**: Uses endoflife.date API to determine currently active Python versions
- **Extras support**: Include optional dependency groups (dev, test, etc.) from your setup.py or pyproject.toml
- **Flexible output**: Generate requirements files with custom names and locations

### Development

See the [/script/](/script/) directory for some tools to help with the development process. They generally follow the [Script to rule them all](https://github.com/github/scripts-to-rule-them-all) pattern. Most useful is `./script/bootstrap` which will create a venv and install both the runtime and development related requirements. It will also hook up a pre-commit hook that covers most of what's run by CI.
