# 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