poetry-monoranger-plugin 0.4.1
Monoranger is a plugin for Poetry that helps you manage your monorepo, enabling shared lockfiles and virtual environments.
License: Apache-2.0
Requires Python: <4.0,>=3.9
Keywords: packaging, poetry, monorepo, lockfile, virtualenv

# Poetry Monoranger Plugin

![PyPI - Version](https://img.shields.io/pypi/v/poetry-monoranger-plugin)
![GitHub License](https://img.shields.io/github/license/ag14774/poetry-monoranger-plugin)
[![Tests](https://github.com/ag14774/poetry-monoranger-plugin/actions/workflows/main.yml/badge.svg)](https://github.com/ag14774/poetry-monoranger-plugin/actions/workflows/main.yml)

**Monoranger** is a plugin for [Poetry](https://python-poetry.org/) that helps you manage your monorepo.

**Main Features**:
- Shared `poetry.lock` file across multiple projects in a monorepo
- Shared virtual environment across multiple projects in a monorepo
- Replace path dependencies during `poetry build` and `poetry export` with pinned versions
- Compatible with both Poetry v1 and v2

## Installation

```bash
poetry self add poetry-monoranger-plugin
```

## Usage

### Expected project structure
The plugin is generally flexible when it comes to the structure of the repository. However, it is expected that each project will have its own `pyproject.toml` file and that the root of the repository will also have a central `pyproject.toml` file including all projects as a path dependency.
```
monorepo/
├── library-one/
│   ├── pyproject.toml
│   └── library_one/
├── library-two/
│   ├── pyproject.toml
│   └── library_two/
├── poetry.lock
└── pyproject.toml
```

The root `pyproject.toml` file should include all projects as a path dependency:
```toml
# ...
[tool.poetry.dependencies]
python = "^3.9"
library-one = { path = "library-one", develop = true }
library-two = { path = "library-two", develop = true }
# ...
```

Each project's `pyproject.toml` file should include the dependencies it needs (including path dependencies to other projects) as well as enabling the plugin:
```toml
# ...
[tool.poetry.dependencies]
python = "^3.9"
numpy = "^1.21.0"
library-two = { path = "../library-two", develop = true }

[tool.poetry-monoranger-plugin]
enabled = true
monorepo-root = "../"
version-pinning-rule = '=='  # Choose between "==", "~", "^", ">=,<"
# ...
```
The plugin by default is disabled in order to avoid having undesired consequences on other projects (as plugins are installed globally). To enable it, set `enabled = true` in each project's `pyproject.toml` file.

### Commands
The plugin modifies the following commands:

- `poetry lock`:

Ensures that the shared lock file (located at the root) is up-to-date irrespective of the directory from which the command is run. This is convenient since it avoids accidentally creating a per-project lock file when running from within a project directory. It also eliminated the need to switch to the root directory to update the lock file.

- `poetry install`:

Installs dependencies for all projects in the monorepo, ensuring that the shared virtual environment is used. As before, this command can be run from any directory within the monorepo without needing to switch to the root directory.

- `poetry sync` (v2 only):

Installs dependencies for all projects in the monorepo, ensuring that the shared virtual environment is used, removing any dependencies that do not exist in the lockfile. As before, this command can be run from any directory within the monorepo without needing to switch to the root directory.

- `poetry update`:

Updates the provided dependency (or all dependencies of **current** project if none provided). This will update the shared lock file as well as installing the updated dependencies in the shared virtual environment.

- `poetry add`:

Adds a new dependency to the `pyproject.toml` of the **current** project, updates the shared lock file, and installs the new dependency in the shared virtual environment. This is equivalent to manually modifying a project's `pyproject.toml` file, followed by running `poetry lock` and `poetry install` from the root directory.

- `poetry remove`:

Removes a dependency from the specified project, updates the shared lockfile, and removes the dependency from the shared virtual environment if it is no longer required by any other project.

- `poetry build`:

Builds the **current** project, replacing editable path dependencies with the current version of the package. This is useful when building a project that depends on another project in the monorepo, as it ensures that the built package can be installed (e.g. as a wheel file) without expecting the other project to be present in a specific location.

- `poetry export`:

Export the requirements of the **current** project, replacing editable path dependencies with the current version of the packages. This is useful when exporting the requirements of a project that depends on another project in the monorepo, as it ensures that the exported requirements can be installed without expecting the other project to be present in a specific location.

### Configuration
The plugin can be configured in the `pyproject.toml` file of each project. The following options are available:

- `enabled` (bool): Whether the plugin is enabled for the current project. Default: `false`
- `monorepo-root` (str): The path to the root of the monorepo. Default: `../`
- `version-pinning-rule` (str): The version pinning rule to apply when building the project. Default: `==`

## License
This project is licensed under the Apache 2.0 license - see the [LICENSE](LICENSE) file for details.