poetry-monoranger-plugin 0.4.1

Monoranger is a plugin for Poetry that helps you manage your monorepo, enabling shared lockfiles and virtual environments.

Poetry Monoranger Plugin

Monoranger is a plugin for Poetry 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

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:

# ...
[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:

# ...
[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 file for details.