Metadata-Version: 2.4
Name: torchannex
Version: 0.0.0
Summary: Curated distribution of PyTorch-compatible Python sub-libraries (the PyTorch annex)
Author-email: PyTorch Team <packages@pytorch.org>
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/pytorch/annex
Project-URL: Issues, https://github.com/pytorch/annex/issues
Keywords: pytorch,torch,metapackage,distribution
Classifier: Development Status :: 1 - Planning
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# torchannex

`torchannex` is a curated distribution ("annex") of small, pure-Python
libraries that extend PyTorch. Installing `torchannex` gives you a set of
sub-libraries pinned to versions that are known to be compatible with a
specific PyTorch release, although these libraries are intended to be loosely
coupled with PyTorch and therefore compatible with a variety of releases.

The annex is designed to be *cheap*: every package in it is a lightweight pure
Python package that installs instantly and pulls in no heavy native
dependencies of its own beyond PyTorch.

## When should I use `torchannex`?

You do **not** have to depend on `torchannex` directly. Two patterns are
supported:

1. **Batteries-included.** Depend on `torchannex`. You get the full curated
   set, versioned in lockstep with the PyTorch release you have installed.
2. **Hand-picked.** Depend on the individual annex packages you care about and
   pin them yourself. Useful when you have an opinion about a specific
   sub-library's version and do not want the whole set.

The annex packages are ordinary PyPI packages. The metapackage is a
convenience, not a gate.

## Installation

```bash
pip install torchannex
# or
uv pip install torchannex
```

If `torch` is already installed (or pinned elsewhere in your environment),
the resolver will select the `torchannex` version whose PyTorch pin matches:

```bash
pip install "torch==2.5.3" torchannex   # resolves to torchannex 2.5.x
```

## Versioning

`torchannex` versions track PyTorch on the `X.Y` components only:

| Component | Meaning                                                         |
|-----------|-----------------------------------------------------------------|
| `X`       | PyTorch major version (lockstep)                                |
| `Y`       | PyTorch minor version (lockstep)                                |
| `Z`       | Independent annex bugfix counter for the `X.Y` series            |

A `torchannex X.Y.Z` release depends on `torch ~= X.Y.0` (i.e.
`>= X.Y.0, < X.(Y+1).0`). This means:

- Any `torch X.Y.*` patch release is compatible with any `torchannex X.Y.*`.
- If we ship a fix to an annex sub-library without a new PyTorch release, we
  bump only the annex `Z`. For example, for the PyTorch 2.5 series:
  - `torchannex 2.5.0` — first annex release for torch 2.5
  - `torchannex 2.5.1` — bugfix to an annex sub-library (torch unchanged)
  - `torchannex 2.5.2` — another annex bugfix
- When PyTorch 2.6 ships we start a new series at `torchannex 2.6.0`.

### Relationship between `torch` Z and `torchannex` Z

They are **independent**. `torchannex 2.5.7` does **not** imply `torch 2.5.7`;
it simply means the 8th annex release cut for the 2.5 series. Whatever `torch
2.5.*` you have installed is fine.

## What's in the annex?

In the short term, we plan to put `spmd_types` in the annex to allow for some
closer integration with DTensor local map.

## Building and releasing

`torchannex` is a pure metapackage — no Python source — built with
setuptools. The empty `py-modules` / `packages` entries in `pyproject.toml`
tell setuptools there is nothing to find.

```bash
uv build       # produces sdist and wheel
uv publish     # uploads to PyPI (requires credentials)
```

See `TESTING.md` for the manual acceptance tests to run before a release.

## License

BSD-3-Clause.
