Metadata-Version: 2.4
Name: bump-minimum-dependencies
Version: 0.5.1
Summary: Command line tool to bump minimum dependencies in pyproject.toml
Author: Nick Murphy
Author-email: Nick Murphy <namurphy@cfa.harvard.edu>
License-File: LICENSE
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: charset-normalizer==3.3.2
Requires-Dist: click>=8.4.2,<9
Requires-Dist: dep-logic>=0.7.1
Requires-Dist: requests>=2.34.2
Requires-Dist: rich>=15
Requires-Dist: uv>=0.12.5
Requires-Python: >=3.13
Project-URL: Source, https://github.com/namurphy/bump-minimum-dependencies
Description-Content-Type: text/markdown

# bump-minimum-dependencies

Automatically bump the minimum allowed versions of dependencies in `pyproject.toml` based on the time since first release, with a cooldown period. ⬆️

Inspired by [SPEC 0]. 🧪

## Motivation

Determining the minimum requirements of a Python package requires balancing competing tradeoffs.
Lengthy support windows increase maintenance burden, prevent developers from using new features and assuming bugfixes, and lead to more complicated code.
Short support windows increase the risk of dependency conflicts.
Automatically bumping minimum requirements in a predictable way saves time and balances these tradeoffs.

## Usage

```groff
Usage: bump-minimum-dependencies [OPTIONS]

  Bump minimum versions of dependencies in pyproject.toml.

  This tool updates pyproject.toml via `uv add --frozen` to drop support for
  minor versions of package dependencies based on the time since the minor
  version was first released, where package versions may be given by
  `<MAJOR>.<MINOR>` or `<MAJOR>.<MINOR>.<MICRO>`. Exact version specifiers and
  upper limits are preserved.

  For pre-1.0 version numbers or when a `<MAJOR>.<MINOR>` release has numerous
  micro releases, `<MICRO>` will be bumped to the last micro release prior to
  the drop date.

  Existing requirements will not be changed when the new minimum version is
  incompatible with old requirements, a requirement has markers, or there are
  multiple `!=` exclusions in the combined requirement.

  "Groups" refers to dependency groups while "extras" refers to categories of
  optional dependencies.

Options:
  --pyproject-file FILE           Path to pyproject.toml.  [default:
                                  pyproject.toml]
  --drop-months FLOAT RANGE       Drop minor releases older than this many
                                  months ago.  [default: 24; x>=0]
  --cooldown-months FLOAT RANGE   Keep at least one minor release this old
                                  when possible.  [default: 21; x>=0]
  --only-package TEXT             Name of a package to update. May be provided
                                  multiple times. When this option is used,
                                  all other packages will be skipped.
  --skip-package TEXT             A package to skip when performing updates.
                                  Can be used multiple times.
  --no-extras                     Do not update extras, except if specified by
                                  --only-extra.
  --only-extra TEXT               An extra to update. Can be used multiple
                                  times. Implies --no-extras, --no-groups, and
                                  --skip-core.
  --skip-extra TEXT               An extra to not be updated. Can use multiple
                                  times.
  --only-group TEXT               A dependency group to update. Can use
                                  multiple times. Implies --no-groups, --no-
                                  extras, and --skip-core.
  --no-groups                     Do not update dependency groups, except if
                                  specified by --only-group.
  --skip-group TEXT               A dependency group to skip. Can use multiple
                                  times.
  --skip-core                     Do not update core project dependencies.
  --dry-run                       Instead of performing updates, print the uv
                                  commands that would be run.
  --verbosity [DEBUG|INFO|WARNING|ERROR|CRITICAL|NOTSET]
                                  Logging verbosity level.  [default: WARNING]
  --version                       Show the version and exit.
  --help                          Show this message and exit.
```

## Examples

To bump core project dependencies, optional dependencies, and dependency groups with the default settings, run:

```shell
bump-minimum-dependencies
```

To bump only plasmapy, run:

```shell
bump-minimum-dependencies --only-package plasmapy
```

To skip updates for numpy and plasmapy, run:

```shell
bump-minimum-dependencies --skip-package numpy --skip-package plasmapy
```

To drop minor versions older than 36 months with a cooldown of 24 months, run:

```shell
bump-minimum-dependencies --drop-months 36 --cooldown-months 24
```

To bump core project dependencies but skip bumping optional dependencies and dependency groups, run:

```shell
bump-minimum-dependencies --no-extras --no-groups
```

To bump project dependencies, optional dependencies, and all but the `doc` dependency group, run:

```shell
bump-minimum-dependencies --skip-group doc
```

To bump only dependency groups, run:

```shell
bump-minimum-dependencies --skip-core --no-extras
```

To bump only the `test` dependency group and skip updates to core project dependencies, optional dependencies, and other dependency groups, run:

```shell
bump-minimum-dependencies --only-group=test
```

## Usage notes

- Please review and test all updates to `pyproject.toml` before accepting them.

  - Use uv's `lowest-direct` [resolution strategy] to run tests in an environment containing the minimum versions of direct dependencies.

- This tool invokes `uv add --frozen` to update dependencies in `pyproject.toml` without updating lock files or syncing virtual environments. Requirements may be normalized upon updates.

- Using [dep-logic] allows bump-minimum-dependencies to handle a wide variety of requirements specifiers and perform logical operations to combine multiple requirements specifiers. For example, `>=4.1,<5` and `>=4.2` will be combined into `>=4.2,<5`.

  - If the time-based requirement is mutually exclusive with the original requirement, the original requirement will be preserved.

- Requirements that cannot be updated will be skipped.

## Limitations and caveats

- This tool does not guarantee that an environment can be created that includes the minimum allowed versions of all direct dependencies, but this can be tested with `uv lock --resolution=lowest-direct --dry-run`.

- Requirements that use `==`, `~=`, or multiple `!=` comparisons or non-standard [version specifiers] might not be updated.

- This tool does not update `build-system.requires` or requirements with markers (such as `'setuptools; python_version > "3.11"'`).

## Feature requests and bug reports

To make a feature request, please [raise an issue].

If you discover a bug, please [raise an issue] with a minimal reproducible example (i.e., the `pyproject.toml` file and the `bump-minimum-dependencies` command that was used).

## Related projects

- [scientific-python/spec0-action](https://github.com/scientific-python/spec0-action) — a GitHub action to create quarterly pull requests to perform SPEC 0 updates using a published drop schedule. Unlike `bump-minimum-dependencies`, this tool distinguishes between SPEC 0 core packages and other packages.

- [cgordberg/bump-dependencies](https://github.com/cgoldberg/bump-dependencies) — updates dependency specifiers in `pyproject.toml` to latest compatible versions.

- [hmaarrfk/nep29](https://github.com/hmaarrfk/nep29) — calculator tools for [NEP 29], a precursor to SPEC 0. `nep29` can be used to check the results of `bump-minimum-dependencies`, as in the following example (if uv is installed):

  ```shell
  uvx --python=3.14 --with=setuptools nep29 --n_minor=1 --n_months=12 scipy
  ```

[dep-logic]: https://github.com/pdm-project/dep-logic
[nep 29]: https://github.com/hmaarrfk/nep29
[raise an issue]: https://github.com/namurphy/bump-minimum-dependencies/issues/new
[resolution strategy]: https://docs.astral.sh/uv/concepts/resolution/#resolution-strategy
[spec 0]: https://scientific-python.org/specs/spec-0000
[version specifiers]: https://packaging.python.org/en/latest/specifications/version-specifiers/#version-specifiers
