polylith-cli

Python tooling for Polylith

A command line interface that adds tooling support for the Polylith Architecture in Python.

Documentation

Have a look at the documentation. You will find installation, setup, usage guides and more.

Quick start

Poetry user? For Poetry, the recommended setup is to install the poetry-polylith-plugin. Read more about Poetry in the documentation.

Setup for Hatch users

Create a directory for your code, initialize it with git and setup the basics with hatch:

git init

hatch new --init

Add the Polylith CLI as a dev dependency in pyproject.toml:

[tool.hatch.envs.default]
dependencies = ["polylith-cli"]

Add configuration for a local virtual environment in the pyproject.toml:

[tool.hatch.envs.default]
type = "virtual"
path = ".venv"
python = "3.12"  # your preferred version here

Make Hatch aware of the Polylith structure, by adding this to the pyproject.toml:

[tool.hatch.build]
dev-mode-dirs = ["components", "bases", "development", "."]

Next: create a Polylith workspace, with a basic Polylith folder structure. The poly command is now available in the local virtual environment. You can run commands in the context of hatch run to make Polylith aware of the development environment.

hatch run poly create workspace --name my_namespace --theme loose

Ready for coding!

Add components, bases and projects:

hatch run poly create component --name my_component

hatch run poly create base --name my_example_endpoint

hatch run poly create project --name my_example_project

For details, have a look at the documentation. There, you will find guides for setup, migration, packaging, available commands, code examples and more.

Setup for PDM users

Create a directory for your code, initialize it with git and setup the basics with PDM.

git init

pdm init -n --backend pdm-backend minimal

Add a workspace hook

Make PDM aware of the Polylith structure, by adding the pdm-polylith-workspace hook to the newly created pyproject.toml.

The build hook will add an additional pth file to the virtual environment, with paths to the Polylith source code folders (bases, components).

[build-system]
requires = ["pdm-backend", "pdm-polylith-workspace"]
build-backend = "pdm.backend"

Add the polylith-cli

Add the Polylith CLI as a dev dependency and setup the virtual environment paths.

touch README.md

pdm add -d polylith-cli

pdm install

Next: create a Polylith workspace, with a basic Polylith folder structure. The poly command is now available in the local virtual environment. You can run commands in the context of pdm run to make Polylith aware of the development environment.

pdm run poly create workspace --name my_namespace --theme loose

Ready for coding!

Add components, bases and projects:

pdm run poly create component --name my_component

pdm run poly create base --name my_example_endpoint

pdm run poly create project --name my_example_project

Setup for Rye users

rye init my_repo  # name your repo

cd my_repo

rye add polylith-cli --dev

rye sync  # create a virtual environment and lock files

Create a workspace, with a basic Polylith folder structure.

rye run poly create workspace --name my_namespace --theme loose

Setup for uv users

uv init -name my_repo  # name your repo

cd my_repo

uv add polylith-cli --dev

uv sync  # create a virtual environment and lock files

Create a workspace, with a basic Polylith folder structure.

uv run poly create workspace --name my_namespace --theme loose

Rye and uv users: edit the configuration

The default build backend for Rye and uv is Hatch. Make Rye and uv (and Hatch) aware of the way Polylith organizes source code:

[tool.hatch.build]
dev-mode-dirs = ["components", "bases", "development", "."]

Run the sync command to update the virtual environment:

Rye:

rye sync

uv:

uv sync

Finally, remove the src boilerplate code that was added by Rye and uv in the first step:

rm -r src

Rye and uv users: ready for coding!

Add components, bases and projects:

Rye:

rye run poly create component --name my_component

rye run poly create base --name my_example_endpoint

rye run poly create project --name my_example_project

uv:

uv run poly create component --name my_component

uv run poly create base --name my_example_endpoint

uv run poly create project --name my_example_project

For details, have a look at the documentation. There, you will find guides for setup, migration, packaging, available commands, code examples and more.