poetry-polylith-plugin 1.3.1

A Poetry plugin that adds tooling support for the Polylith Architecture

Poetry Polylith Plugin

This is a Python Poetry plugin, adding CLI support for the Polylith Architecture.

Usage

Install Poetry & plugins

With the Poetry version 1.2 or later installed, you can add plugins.

Add the Multiproject plugin, that will enable the very important workspace support (i.e. relative package includes) to Poetry.

poetry self add poetry-multiproject-plugin

Add the Polylith plugin:

poetry self add poetry-polylith-plugin

Create a repository

Create a directory for your code, initialize it with git and create a basic Poetry setup:

git init

poetry init

Commands

The create workspace command will create a Polylith workspace, with a basic Polylith folder structure.

Create

poetry poly create workspace --name my_namespace --theme <tdd or loose>

New: theme is a new Python Polylith feature and defines what kind of component structure - or theme - to use.

tdd is the default and will set the structure according to the original Polylith Clojure implementation, such as: components/<package>/src/<namespace>/<package> with a corresponding test folder.

loose is a new theme, for a more familiar structure for Python: components/<namespace>/<package> and will put a test folder at the root of the repository.

Add a component:

# This command will create a component - i.e. a Python package in a namespaced folder.
poetry poly create component --name my_component

Add a base:

# This command will create a base - i.e. a Python package in a namespaced folder.
poetry poly create base --name my_example_aws_lambda

Add a project:

# This command will create a project - i.e. a pyproject.toml in a project folder. No code in this folder.
poetry poly create project --name my_example_aws_lambada_project

Options

--description Add a brick description. The description will be added as a docstring. Also in the brick-specific README (when set to enabled in the resources section of the workspace config).

Info

Show info about the workspace:

poetry poly info

Diff

Shows what has changed since the most recent stable point in time:

poetry poly diff

The diff command will compare the current state of the repository, compared to a git tag. The tool will look for the latest tag according to a certain pattern, such as stable-*. The pattern can be configured in workspace.toml.

The diff command is useful in a CI environment, to determine if a project should be deployed or not. The command has a --short flag to only print a comma separated list of changed projects to the standard output.

Useful for CI:

poetry poly diff --short

Libs

Show info about the third-party libraries used in the workspace:

poetry poly libs

NOTE: this feature relies on installed project dependencies, and expects a poetry.lock of a project to be present. If missing, there is a Poetry command available: poetry lock --directory path/to-project.

The very nice dependency lookup features of Poetry is used behind the scenes by the poly libs command.

Options

--directory or -C

Show info about libraries used in a specific project.

Check

Validates the Polylith workspace:

poetry poly check

NOTE: this feature is built on top of the poetry check-project command from the Multiproject plugin. Make sure that you have the latest version of poetry-multiproject-plugin installed to be able to use the poly check command.

Testing

The create commands will also create corresponding unit tests. It is possible to disable thi behaviour by setting enabled = false in the workspace.toml file.

Workspace configuration

An example of a workspace configuration:

[tool.polylith]
namespace = "my_namespace"
git_tag_pattern = "stable-*"

[tool.polylith.structure]
theme = "loose"

[tool.polylith.resources]
brick_docs_enabled = false

[tool.polylith.test]
enabled = true