Skip to content

Commands

poly info example

Create a workspace

This will create a Polylith workspace, with a basic Polylith folder structure.

Poetry

poetry poly create workspace --name my_example_namespace --theme loose

Hatch

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

PDM

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

Rye

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

uv

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

Options

--name (required) the workspace name, that will be used as the single top namespace for all bricks. Choose the name wisely. Have a look in PEP-423 for naming guidelines.

--theme the structure of the workspace (see below).

Themes

Themes are an exclusive Python Polylith feature, and defines what kind of workspace structure to use.

A theme to use for a more familiar structure for Python: components/namespace/package and will put a test folder at the root of the repository.

tdd

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.

What's the deal with the .keep files?

When creating a new workspace, the Polylith tool will add .keep files in the newly created folders. These are added for any initial commits of the folder structure, and can safely be removed when adding source files.

Create a component

This command will create a component - i.e. a Python package in a namespaced folder.

Poetry

poetry poly create component --name my_example_component

Hatch

hatch run poly create component --name my_example_component

PDM

pdm run poly create component --name my_example_component

Rye

rye run poly create component --name my_example_component

uv

uv run poly create component --name my_example_component

Options

--name (required) the name of the component.

--description adding a docstring to the base. It will also be added in the README, when enabled in the configuration. See configuration.

Create a base

This command will create a base - i.e. a Python package in a namespaced folder.

Poetry

poetry poly create base --name my_example_base

Hatch

hatch run poly create base --name my_example_base

PDM

pdm run poly create base --name my_example_base

Rye

rye run poly create base --name my_example_base

uv

uv run poly create base --name my_example_base

Options

--name (required) the name of the base.

--description adding a docstring to the base. It will also be added in the README, when enabled in the configuration. See configuration.

Create a project

This command will create a project - i.e. a pyproject.toml in a project folder.

Poetry

poetry poly create project --name my_example_project

Hatch

hatch run poly create project --name my_example_project

PDM

pdm run poly create project --name my_example_project

Rye

rye run poly create project --name my_example_project

uv

uv run poly create project --name my_example_project

Options

--name (required) the name of the project.

--description adding a pyproject.toml description.

Info

Show info about the workspace:

Poetry

poetry poly info

Hatch

hatch run poly info

PDM

pdm run poly info

Rye

rye run poly info

uv

uv run poly info

Options

--short Display a view that is better adjusted to Workspaces with many projects.

Diff

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

Poetry

poetry poly diff

Hatch

hatch run poly diff

PDM

pdm run poly diff

Rye

rye run poly diff

uv

uv run 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 the Workspace configuration.

The diff command is useful in a CI environment, to determine if a project should be deployed or not. It is also useful when running tests for changed bricks only.

Example:

Poetry

poetry poly diff --since release

Hatch

hatch run poly diff --since release

PDM

pdm run poly diff --since release

Rye

rye run poly diff --since release

Rye

uv run poly diff --since release

Options

--short Useful for determining what projects has been affected by the changes in CI.

--bricks Useful for displaying changed bricks only. It will print a comma-separated list of bricks when using it with the --short option.

--since Useful for displaying changes since a stable or release tag. The tag patterns are defined in the Workspace configuration. This option also support using a specific commit hash.

--deps Useful for displaying the bricks that are used by the changed bricks. Use it with the --bricks option.

Libs

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

Poetry

poetry poly libs

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

Hatch

hatch run poly libs

PDM

pdm run poly libs

Rye

rye run poly libs

uv

uv run poly libs

Options

--directory Show info about libraries used in a specific project.

--strict A more narrow way of comparing third-party libraries and the actual imports. This is useful to rule out possible false positives.

--alias Useful when an import differ from the library name.

Example: the library "opencv-python" and the actual import "cv2". The poly libs command will likely report the "cv2" as a missing dependency.

Using --alias opencv-python=cv2 will make the command treat the alias as a third-party import.

Check

Validates the Polylith workspace, checking for any missing dependencies (bricks and third-party libraries):

Poetry

poetry poly check

This feature is built on top of the poly libs command, and for expects a poetry.lock of a Poetry project to be present.

Hatch

hatch run poly check

PDM

pdm run poly check

Rye

rye run poly check

uv

uv run poly check

Options

--directory Show info about libraries used in a specific project.

--strict A more narrow way of comparing third-party libraries, versions and the actual imports. This is useful to rule out possible false positives, and to ensure using the same version strings for the libraries across the workspace.

--alias Useful when an import differ from the library name.

Example: the library "opencv-python" and the actual import "cv2". The poly check command will likely report the "cv2" as a missing dependency.

Using --alias opencv-python=cv2 will make the command treat the alias as a third-party import.

Sync

Keep projects in sync with the actual usage of bricks in source code.

Poetry

poetry poly sync

Hatch

hatch run poly sync

PDM

pdm run poly sync

Rye

rye run poly sync

uv

uv run poly sync

This feature is useful for keeping projects in sync. The command will analyze code and add any missing bricks to the projects, including the development project.

  • projects: will add missing bricks to the project specific pyproject.toml, when imported by any of the already added bricks.
  • development: will add all missing bricks to the development pyproject.toml.

Options

--directory Synchronize a specific project.

Deps

Show dependencies between bricks.

Poetry

poetry poly deps

Hatch

hatch run poly deps

PDM

pdm run poly deps

Rye

rye run poly deps

uv

uv run poly deps

Options

--directory Show brick depencencies for a specific project.

--brick A detailed view for a single brick and the dependent bricks: used by, and uses.

Testing

Example, how to run pytest for changed bricks only.

Poetry

# store the comma-separated list of bricks in a bash variable
changes="$(poetry poly diff --bricks --short)"

# transform it into a pytest query,
# i.e. from "hello,world,something" to "hello or world or something"
query="${changes//,/ or }"

Run the test, filtered by keyword expression

poetry run pytest -k <<< echo "$query"

or run the test, filtered by pytest markers

poetry run pytest -m <<< echo "$query"

Hatch

# store the comma-separated list of bricks in a bash variable
changes="$(hatch run poly diff --bricks --short)"

# transform it into a pytest query,
# i.e. from "hello,world,something" to "hello or world or something"
query="${changes//,/ or }"

Run the test, filtered by keyword expression

hatch run pytest -k <<< echo "$query"

or run the test, filtered by pytest markers

hatch run pytest -m <<< echo "$query"

PDM

# store the comma-separated list of bricks in a bash variable
changes="$(pdm run poly diff --bricks --short)"

# transform it into a pytest query,
# i.e. from "hello,world,something" to "hello or world or something"
query="${changes//,/ or }"

Run the test, filtered by keyword expression

pdm run pytest -k <<< echo "$query"

or run the test, filtered by pytest markers

pdm run pytest -m <<< echo "$query"

Rye

# store the comma-separated list of bricks in a bash variable
changes="$(rye run poly diff --bricks --short)"

# transform it into a pytest query,
# i.e. from "hello,world,something" to "hello or world or something"
query="${changes//,/ or }"

Run the test, filtered by keyword expression

rye run pytest -k <<< echo "$query"

or run the test, filtered by pytest markers

rye run pytest -m <<< echo "$query"

uv

# store the comma-separated list of bricks in a bash variable
changes="$(uv run poly diff --bricks --short)"

# transform it into a pytest query,
# i.e. from "hello,world,something" to "hello or world or something"
query="${changes//,/ or }"

Run the test, filtered by keyword expression

uv run pytest -k <<< echo "$query"

or run the test, filtered by pytest markers

uv run pytest -m <<< echo "$query"