Metadata-Version: 2.4
Name: poetry-dynamic-caching
Version: 0.2.2
Summary: Plugin for Poetry to dynamically use one or more repositories based on availability.
License: MIT
License-File: LICENSE
Keywords: poetry,plugin,cache,caching,dynamic,devpi
Author: Sebastian Karius
Author-email: sebastian.karius@informatik.uni-halle.de
Requires-Python: >=3.12,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: poetry (>=2.3.1,<3.0.0)
Requires-Dist: requests (>=2.32.5,<3.0.0)
Project-URL: Changelog, https://codeberg.org/rndxelement/poetry-dynamic-caching/src/branch/main/CHANGELOG.md
Project-URL: Issues, https://codeberg.org/rndxelement/poetry-dynamic-caching/issues
Project-URL: Repository, https://codeberg.org/rndxelement/poetry-dynamic-caching
Description-Content-Type: text/markdown

# poetry-dynamic-caching

A plugin for [Poetry](https://python-poetry.org/) that automatically
switches to a package cache (like [devpi](https://devpi.net/)) when
it's available, falling back to PyPI when it's not.

## Why?

Poetry allows specifying a custom primary repository. However if that
repository isn't available Poetry will hang during `poetry install` or
similar commands.
This plugin checks if your cache is reachable before each
install command and routes traffic accordingly.

> [!NOTE]
> This plugin has been developed and tested for [devpi](https://devpi.net/) only.
> Other cache/repository implementations _might_ work as well.
> If not,let us know and we can look for a solution!

## Installation

To install the plugin system wide use:

```bash
poetry self add poetry-dynamic-caching
```

You can also use the plugin only in the context of another Poetry project by adding
the following to the `pyproject.toml`:

```bash
[tool.poetry.requires-plugins]
poetry-dynamic-caching = { version = "*" }
```

After that you can run `poetry install --dry-run` to install the plugins and not the
dependencies.

## Configuration

Add the following to your project's `pyproject.toml`:

```toml
[tool.poetry-dynamic-caching]
cache = [
   { type = "devpi", url = "https://my-cache-server.example" },
   { type = "devpi", url = "https://my-cache-server.invalid:1234" }
]
```

The first available entry in the list will be used.

Alternatively, you can set the `DEVPI_URL` environment variable.

> [!NOTE]
> The environment variable `DEVPI_URL` overshadows the `cache` setting
> in the `pyproject.toml` file.

## How it works

When you run any installer command (`poetry install`, `poetry add`,
`poetry lock`, etc.), the plugin:

1. Sends a request to `<devpi_url>/+status`
2. If the cache responds with 200, removes any PyPI repositories from the
   internal state of Poetry
3. Adds the configured cache as a repository to the interal state of Poetry
4. If the cache isn't responding with 200, do nothing

Enable debug output to see what's happening:

```bash
poetry install -vvv
```

## Requirements

- Python >= 3.12
- Poetry >= 2.3.1

## License

MIT
