### Build and Install Commands with PDM

Source: https://context7.com/davidvujic/python-polylith/llms.txt

Commands to build a package with PDM and install it in development mode.

```bash
# Build with PDM
cd projects/my_service
pdm build
```

```bash
# Install in development mode
pdm install
```

--------------------------------

### Example Poetry Project Configuration

Source: https://context7.com/davidvujic/python-polylith/llms.txt

An example `pyproject.toml` for a Poetry project integrated with Polylith, specifying packages, dependencies, and build system.

```toml
# projects/my_service/pyproject.toml
[tool.poetry]
name = "my_service"
version = "0.1.0"
description = "My microservice"
packages = [
    {include = "myorg/web_api", from = "../../bases/web_api/src"},
    {include = "myorg/user_service", from = "../../components/user_service/src"},
]

[tool.poetry.dependencies]
python = "^3.9"
fastapi = "^0.100.0"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"
```

--------------------------------

### Install Poetry Polylith Plugin

Source: https://context7.com/davidvujic/python-polylith/llms.txt

Install the `poetry-polylith-plugin` to use Polylith commands directly within Poetry.

```bash
# Install the plugin
poetry self add poetry-polylith-plugin
```

--------------------------------

### Example Workflow for Creating and Syncing a Component

Source: https://context7.com/davidvujic/python-polylith/llms.txt

This workflow demonstrates creating a new component, using it in a base, and then syncing the project dependencies to include the new component.

```bash
# 1. Create a new component
poly create component --name=email_service

# 2. Use it in your base
# bases/web_api/src/myorg/web_api/core.py
# from myorg.email_service import send_email

# 3. Sync to update project dependencies
poly sync --directory=projects/my_service

# Output: Added email_service to my_service
```

--------------------------------

### Example Component Implementation

Source: https://context7.com/davidvujic/python-polylith/llms.txt

A Python implementation for a user service component, including functions for creating and retrieving users. Requires validation for user creation.

```python
# components/user_service/src/myorg/user_service/core.py
from typing import Optional

def create_user(name: str, email: str) -> dict:
    """Create a new user with validation."""
    if not name or not email:
        raise ValueError("Name and email are required")
    return {"name": name, "email": email, "id": generate_id()}

def get_user(user_id: str) -> Optional[dict]:
    """Retrieve a user by ID."""
    # Implementation here
    pass
```

--------------------------------

### Add Polylith CLI and Install Dependencies with PDM

Source: https://github.com/davidvujic/python-polylith/blob/main/projects/polylith_cli/README.md

Adds the 'polylith-cli' as a development dependency and installs all project dependencies using PDM. A README.md is touched to ensure a file exists for PDM initialization.

```shell
touch README.md

pdm add -d polylith-cli

pdm install

```

--------------------------------

### Add Polylith Plugin

Source: https://github.com/davidvujic/python-polylith/blob/main/projects/poetry_polylith_plugin/README.md

Installs the Poetry Polylith Plugin. Ensure Poetry 1.2 or later is installed.

```shell
poetry self add poetry-polylith-plugin
```

--------------------------------

### Add Multiproject Plugin

Source: https://github.com/davidvujic/python-polylith/blob/main/projects/poetry_polylith_plugin/README.md

Installs the Multiproject plugin for Poetry, enabling workspace support. Requires Poetry 1.2 or later.

```shell
poetry self add poetry-multiproject-plugin
```

--------------------------------

### Display Polylith Workspace Info

Source: https://context7.com/davidvujic/python-polylith/llms.txt

Use the `info` command to get a comprehensive overview of your Polylith workspace, including bases, components, projects, and their relationships. Options include short format, saving output, and filtering by project groups.

```bash
# Using the standalone CLI
poly info

# Using Poetry plugin
poetry poly info

# Short format (compact view)
poly info --short

# Save output to file
poly info --save

# Filter by project groups
poly info --group=backend,api
```

--------------------------------

### Python Import Before Namespace Rewrite

Source: https://github.com/davidvujic/python-polylith/blob/main/projects/pdm_polylith_bricks/README.md

Example of a standard Python import statement before applying a custom top namespace.

```python
from my_namespace.my_package import my_function

```

--------------------------------

### Example Base Implementation (FastAPI)

Source: https://context7.com/davidvujic/python-polylith/llms.txt

A FastAPI application implementing a REST API for user management, utilizing the `create_user` and `get_user` functions from the user service component. Handles potential ValueErrors during user creation.

```python
# bases/web_api/src/myorg/web_api/core.py
from fastapi import FastAPI, HTTPException
from myorg.user_service import create_user, get_user

app = FastAPI()

@app.post("/users")
def create_user_endpoint(name: str, email: str):
    try:
        user = create_user(name, email)
        return {"status": "created", "user": user}
    except ValueError as e:
        raise HTTPException(status_code=400, detail=str(e))

@app.get("/users/{user_id}")
def get_user_endpoint(user_id: str):
    user = get_user(user_id)
    if not user:
        raise HTTPException(status_code=404, detail="User not found")
    return user
```

--------------------------------

### Example Polylith Project pyproject.toml

Source: https://context7.com/davidvujic/python-polylith/llms.txt

This TOML file configures a Polylith project using Hatch as the build backend. It specifies project metadata, dependencies, and Polylith brick mappings.

```toml
[project]
name = "my_service"
version = "0.1.0"
description = "Main microservice"
requires-python = ">=3.9"
dependencies = [
    "fastapi>=0.100.0",
    "uvicorn>=0.23.0",
]

[build-system]
requires = ["hatchling", "hatch-polylith-bricks"]
build-backend = "hatchling.build"

[tool.polylith.bricks]
"../../bases/web_api/src/myorg/web_api" = "myorg/web_api"
"../../components/user_service/src/myorg/user_service" = "myorg/user_service"

[tool.hatch.build.hooks.polylith-bricks]
```

--------------------------------

### Generated workspace.toml Configuration

Source: https://context7.com/davidvujic/python-polylith/llms.txt

Example configuration file for a Polylith workspace, defining namespace, git tag patterns, structure theme, and resource settings.

```toml
[tool.polylith]
namespace = "myorg"
git_tag_pattern = "stable-*"

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

[tool.polylith.tag.patterns]
stable = "stable-*"
release = "v[0-9]*"

[tool.polylith.resources]
brick_docs_enabled = false

[tool.polylith.test]
enabled = true
```

--------------------------------

### Create Polylith Component with uv

Source: https://github.com/davidvujic/python-polylith/blob/main/projects/polylith_cli/README.md

Use this command with uv to add a new component to your Polylith workspace. Ensure uv is installed and configured for your project.

```shell
uv run poly create component --name my_component
```

--------------------------------

### Create Polylith Component with Rye

Source: https://github.com/davidvujic/python-polylith/blob/main/projects/polylith_cli/README.md

Use this command with Rye to add a new component to your Polylith workspace. Ensure Rye is installed and configured for your project.

```shell
rye run poly create component --name my_component
```

--------------------------------

### Install PDM Polylith Workspace Plugin

Source: https://github.com/davidvujic/python-polylith/blob/main/projects/pdm_polylith_workspace/README.md

Add this to your Polylith workspace's `pyproject.toml` to enable the PDM build hook. This is required for the virtual environment to correctly recognize the Polylith structure.

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

```

--------------------------------

### Example of Import Rewriting

Source: https://github.com/davidvujic/python-polylith/blob/main/projects/hatch_polylith_bricks/README.md

Demonstrates how the build hook rewrites Python imports when a custom top namespace is configured. The original import is modified to include the custom namespace.

```python
from my_namespace.my_package import my_function

```

```python
from my_custom_namespace.my_namespace.my_package import my_function

```

--------------------------------

### Uninstall Poetry Plugin

Source: https://github.com/davidvujic/python-polylith/blob/main/development/README.md

Use this command to uninstall the Poetry Polylith plugin before installing a local version.

```shell
poetry self remove poetry-polylith-plugin
```

--------------------------------

### Python Import After Namespace Rewrite

Source: https://github.com/davidvujic/python-polylith/blob/main/projects/pdm_polylith_bricks/README.md

Example of a Python import statement after the build hook has rewritten it with a custom top namespace.

```python
from my_custom_namespace.my_namespace.my_package import my_function

```

--------------------------------

### Uninstall Local Test Version

Source: https://github.com/davidvujic/python-polylith/blob/main/development/README.md

After testing, use this command to uninstall the locally installed test version of the Poetry plugin.

```shell
~/Library/Application\ Support/pypoetry/venv/bin/pip uninstall poetry-polylith-plugin
```

--------------------------------

### Poetry Plugin Workspace Commands

Source: https://context7.com/davidvujic/python-polylith/llms.txt

Common workspace management commands available through the Poetry Polylith plugin, such as getting info, checking, diffing, syncing, managing dependencies, and listing libraries.

```bash
# Workspace commands
poetry poly info
poetry poly check --strict
poetry poly diff --since=v1.0.0
poetry poly sync --directory=projects/my_service
poetry poly deps --brick=user_service
poetry poly libs --strict
```

--------------------------------

### Initialize Project and Add Polylith CLI with uv

Source: https://github.com/davidvujic/python-polylith/blob/main/projects/polylith_cli/README.md

Initializes a new project repository using uv, adds the 'polylith-cli' as a development dependency, and synchronizes the environment to create virtual environment and lock files.

```shell
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
```

--------------------------------

### Initialize Git and PDM Project

Source: https://github.com/davidvujic/python-polylith/blob/main/projects/polylith_cli/README.md

Initializes a new project with Git and sets up the basic structure using PDM. The '-n' flag skips interactive prompts, and '--backend pdm-backend' specifies the build backend.

```shell
git init

pdm init -n --backend pdm-backend minimal
```

--------------------------------

### Initialize Git and Poetry

Source: https://github.com/davidvujic/python-polylith/blob/main/projects/poetry_polylith_plugin/README.md

Initializes a new Git repository and sets up a basic Poetry project configuration.

```shell
git init

poetry init
```

--------------------------------

### Initialize Project and Add Polylith CLI with Rye

Source: https://github.com/davidvujic/python-polylith/blob/main/projects/polylith_cli/README.md

Initializes a new project repository using Rye, adds the 'polylith-cli' as a development dependency, and synchronizes the environment to create virtual environment and lock files.

```shell
rye init my_repo  # name your repo

cd my_repo

rye add polylith-cli --dev

rye sync  # create a virtual environment and lock files
```

--------------------------------

### Initialize Git and Hatch Project

Source: https://github.com/davidvujic/python-polylith/blob/main/projects/polylith_cli/README.md

Initializes a new project with Git and sets up the basic structure using Hatch. Ensure Polylith CLI is added as a dev dependency in pyproject.toml.

```shell
git init

hatch new --init
```

--------------------------------

### Build Local Poetry Plugin Wheel

Source: https://github.com/davidvujic/python-polylith/blob/main/development/README.md

Builds a wheel file for the local Poetry plugin. Replace `<INSERT-VERSION-HERE>` with the actual version.

```shell
poetry build-project --directory projects/poetry_polylith_plugin
```

```shell
~/Library/Application\ Support/pypoetry/venv/bin/pip install projects/poetry_polylith_plugin/dist/poetry_polylith_plugin-<INSERT-VERSION-HERE>-py3-none-any.whl
```

--------------------------------

### Create Polylith Workspace

Source: https://context7.com/davidvujic/python-polylith/llms.txt

Initializes a new Polylith workspace with the necessary directory structure and configuration. Use the standalone CLI or Poetry plugin. A custom theme can be specified.

```bash
# Using the standalone CLI
poly create workspace --name=myorg
```

```bash
# Using Poetry plugin
poetry poly create workspace --name=myorg
```

```bash
# With a custom theme (default is "tdd", alternative is "loose")
poly create workspace --name=myorg --theme=loose
```

--------------------------------

### Create Polylith Project with uv

Source: https://github.com/davidvujic/python-polylith/blob/main/projects/polylith_cli/README.md

Use this command with uv to initialize a new project within your Polylith workspace. Projects are the top-level entities that consume bases and components.

```shell
uv run poly create project --name my_example_project
```

--------------------------------

### Build Commands with Hatch

Source: https://context7.com/davidvujic/python-polylith/llms.txt

Commands to build a wheel package for a Polylith project using Hatch, uv, or pip.

```bash
# Build wheel with Hatch
cd projects/my_service
hatch build
```

```bash
# Build with uv (uses hatchling)
uv build
```

```bash
# Build with pip
pip wheel . -w dist/
```

--------------------------------

### Create Polylith Components, Bases, and Projects

Source: https://github.com/davidvujic/python-polylith/blob/main/projects/poetry_polylith_plugin/README.md

Commands to create new Polylith elements: components, bases, and projects. These commands help in structuring the architecture according to Polylith principles.

```shell
poetry poly create component --name my_component

poetry poly create base --name my_example_endpoint

poetry poly create project --name my_example_project
```

--------------------------------

### Build Polylith Projects with Custom Top Namespaces

Source: https://github.com/davidvujic/python-polylith/blob/main/development/README.md

Commands to build project artifacts using Poetry, specifying custom top namespaces for different components like the CLI and build hooks.

```shell
poetry build-project --directory projects/poetry_polylith_plugin
```

```shell
poetry build-project --directory projects/polylith_cli --with-top-namespace polylith_cli
```

```shell
poetry build-project --directory projects/hatch_polylith_bricks --with-top-namespace hatch_polylith_bricks
```

```shell
poetry build-project --directory projects/pdm_polylith_bricks --with-top-namespace pdm_polylith_bricks
```

```shell
poetry build-project --directory projects/pdm_polylith_workspace --with-top-namespace pdm_polylith_workspace
```

--------------------------------

### Create Polylith Project with Rye

Source: https://github.com/davidvujic/python-polylith/blob/main/projects/polylith_cli/README.md

Use this command with Rye to initialize a new project within your Polylith workspace. Projects are the top-level entities that consume bases and components.

```shell
rye run poly create project --name my_example_project
```

--------------------------------

### List Libraries with Polylith CLI

Source: https://context7.com/davidvujic/python-polylith/llms.txt

Use the `poly libs` command to list libraries used in your Polylith bricks. Options include strict mode, specifying a directory, using aliases, a short format, and saving output to a file.

```bash
poly libs
```

```bash
poly libs --strict
```

```bash
poly libs --directory=projects/my_service
```

```bash
poly libs --alias=PIL:pillow
```

```bash
poly libs --short
```

```bash
poly libs --save
```

--------------------------------

### Sync Virtual Environment with Rye/uv

Source: https://github.com/davidvujic/python-polylith/blob/main/projects/polylith_cli/README.md

Updates the virtual environment by running the 'sync' command for either Rye or uv. This step ensures that all dependencies and configurations are up-to-date.

```shell
rye sync
```

```shell
uv sync
```

--------------------------------

### Create Polylith Project

Source: https://context7.com/davidvujic/python-polylith/llms.txt

Scaffolds a new deployable project artifact that combines bases and components. Each project has its own `pyproject.toml` for dependency management. Use the standalone CLI or Poetry plugin.

```bash
# Using the standalone CLI
poly create project --name=my_service --description="Main microservice"
```

```bash
# Using Poetry plugin
poetry poly create project --name=my_service --description="Main microservice"
```

--------------------------------

### Create Polylith Component

Source: https://context7.com/davidvujic/python-polylith/llms.txt

Creates a new reusable component with proper namespace structure, including source files and test scaffolding. Use the standalone CLI or Poetry plugin.

```bash
# Using the standalone CLI
poly create component --name=user_service --description="User management service"
```

```bash
# Using Poetry plugin
poetry poly create component --name=user_service --description="User management service"
```

--------------------------------

### CI/CD Integration with `poly test diff`

Source: https://context7.com/davidvujic/python-polylith/llms.txt

This bash script demonstrates how to integrate the `poly test diff --projects --short` command into a CI/CD pipeline to run tests only for affected projects.

```bash
#!/bin/bash
# Run tests only for affected projects
AFFECTED=$(poly test diff --projects --short)

if [ -n "$AFFECTED" ]; then
    for project in $AFFECTED;
    do
        echo "Testing $project..."
        cd projects/$project && pytest
    done
else
    echo "No projects affected by test changes"
fi
```

--------------------------------

### Configure Hatch Build for Rye/uv Users

Source: https://github.com/davidvujic/python-polylith/blob/main/projects/polylith_cli/README.md

Configures Hatch, the default build backend for Rye and uv, to be aware of the Polylith source code organization. This ensures correct builds for projects using Polylith.

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

```

--------------------------------

### Configure Hatch for Polylith

Source: https://github.com/davidvujic/python-polylith/blob/main/projects/polylith_cli/README.md

Adds Polylith CLI as a dev dependency and configures Hatch to recognize the Polylith directory structure for development builds.

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

```

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

```

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

```

--------------------------------

### Configure PDM Build System

Source: https://github.com/davidvujic/python-polylith/blob/main/projects/pdm_polylith_bricks/README.md

Add the pdm-polylith-bricks plugin to your PDM build system requirements in pyproject.toml.

```toml
[build-system]
requires = ["pdm-backend", "pdm-polylith-bricks"]
build-backend = "pdm.backend"

```

--------------------------------

### Sync Polylith Project Dependencies

Source: https://context7.com/davidvujic/python-polylith/llms.txt

The `sync` command updates project `pyproject.toml` files with missing brick dependencies by analyzing actual imports. It ensures projects correctly declare all used bricks. Options include specifying a directory, quiet mode, and verbose mode.

```bash
# Using the standalone CLI
poly sync

# Using Poetry plugin
poetry poly sync

# Sync a specific project
poly sync --directory=projects/my_service

# Quiet mode (no output)
poly sync --quiet

# Verbose mode (show import details)
poly sync --verbose
```

--------------------------------

### Create Polylith Base

Source: https://context7.com/davidvujic/python-polylith/llms.txt

Creates a new base, which serves as an entry point for applications like REST APIs or CLIs. Use the standalone CLI or Poetry plugin.

```bash
# Using the standalone CLI
poly create base --name=web_api --description="REST API for the application"
```

```bash
# Using Poetry plugin
poetry poly create base --name=web_api --description="REST API for the application"
```

--------------------------------

### Create Polylith Workspace

Source: https://github.com/davidvujic/python-polylith/blob/main/projects/poetry_polylith_plugin/README.md

Creates a new Polylith workspace with a specified name and theme. This command sets up the basic folder structure for a Polylith project.

```shell
poetry poly create workspace --name my_namespace --theme loose
```

--------------------------------

### Create Polylith Workspace with uv

Source: https://github.com/davidvujic/python-polylith/blob/main/projects/polylith_cli/README.md

Creates a new Polylith workspace using the 'poly' command within the uv environment. This command sets up the initial folder structure for a Polylith project.

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

--------------------------------

### Create Polylith Workspace with Rye

Source: https://github.com/davidvujic/python-polylith/blob/main/projects/polylith_cli/README.md

Creates a new Polylith workspace using the 'poly' command within the Rye environment. This command sets up the initial folder structure for a Polylith project.

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

--------------------------------

### Poetry Plugin Commands for Polylith Workspace

Source: https://context7.com/davidvujic/python-polylith/llms.txt

Commands to manage a Polylith workspace using the Poetry plugin, including creating workspaces, bricks, and projects.

```bash
# Create workspace
poetry poly create workspace --name=myorg
```

```bash
# Create bricks
poetry poly create component --name=user_service
poetry poly create base --name=web_api
```

```bash
# Create project
poetry poly create project --name=my_service
```

--------------------------------

### Create Polylith Base with uv

Source: https://github.com/davidvujic/python-polylith/blob/main/projects/polylith_cli/README.md

Use this command with uv to add a new base to your Polylith workspace. Bases are fundamental building blocks in Polylith.

```shell
uv run poly create base --name my_example_endpoint
```

--------------------------------

### Create Polylith Workspace with Hatch

Source: https://github.com/davidvujic/python-polylith/blob/main/projects/polylith_cli/README.md

Creates a new Polylith workspace using the 'poly' command within the Hatch environment. This command sets up the initial folder structure for a Polylith project.

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

--------------------------------

### Create Polylith Entities with PDM

Source: https://github.com/davidvujic/python-polylith/blob/main/projects/polylith_cli/README.md

Commands to create new components, bases, and projects within an existing Polylith workspace using PDM. These commands help scaffold new parts of your Polylith architecture.

```shell
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
```

--------------------------------

### Analyze Third-Party Libraries with Polylith Libs

Source: https://context7.com/davidvujic/python-polylith/llms.txt

The `libs` command shows third-party libraries used across the workspace by analyzing imports and comparing them with declared dependencies. It helps identify missing or undeclared libraries.

```bash
# Using the standalone CLI
poly libs
```

--------------------------------

### Create Polylith Workspace with PDM

Source: https://github.com/davidvujic/python-polylith/blob/main/projects/polylith_cli/README.md

Creates a new Polylith workspace using the 'poly' command within the PDM environment. This command sets up the initial folder structure for a Polylith project.

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

--------------------------------

### Create Polylith Entities with Hatch

Source: https://github.com/davidvujic/python-polylith/blob/main/projects/polylith_cli/README.md

Commands to create new components, bases, and projects within an existing Polylith workspace using Hatch. These commands help scaffold new parts of your Polylith architecture.

```shell
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
```

--------------------------------

### PDM Build Hook Configuration for Polylith

Source: https://context7.com/davidvujic/python-polylith/llms.txt

Configure PDM build hooks (`pdm-polylith-bricks` and `pdm-polylith-workspace`) in `pyproject.toml` for Polylith integration. This includes specifying brick paths and an optional custom top namespace.

```toml
# projects/my_service/pyproject.toml
[project]
name = "my_service"
version = "0.1.0"
requires-python = ">=3.9"

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

[tool.polylith.bricks]
"../../bases/web_api/src/myorg/web_api" = "myorg/web_api"
"../../components/user_service/src/myorg/user_service" = "myorg/user_service"

# Optional: Custom top namespace
[tool.polylith]
top_namespace = "mycompany"
```

--------------------------------

### Configure Hatch Build Hook for Polylith

Source: https://github.com/davidvujic/python-polylith/blob/main/projects/hatch_polylith_bricks/README.md

Add this section to your pyproject.toml to enable the Polylith build hook. It requires hatchling and the hatch-polylith-bricks plugin.

```toml
[build-system]
requires = ["hatchling", "hatch-polylith-bricks"]
build-backend = "hatchling.build"

[tool.hatch.build.hooks.polylith-bricks]
# NOTE: this section is needed to enable the hook in the build process, even if empty

```

--------------------------------

### Visualize Polylith Brick Dependencies

Source: https://context7.com/davidvujic/python-polylith/llms.txt

The `deps` command visualizes dependencies between bricks, helping to understand architecture and detect circular dependencies. It can show incoming/outgoing dependencies, interface details, and save output to a file.

```bash
# Using the standalone CLI
poly deps

# Using Poetry plugin
poetry poly deps

# For a specific project
poly deps --directory=projects/my_service

# For a specific brick
poly deps --brick=user_service

# Show interface details
poly deps --interface

# Save visualization to file
poly deps --save
```

--------------------------------

### Workspace-level PDM Configuration

Source: https://context7.com/davidvujic/python-polylith/llms.txt

Configure PDM at the workspace level to enable Polylith integration using the `pdm-polylith-workspace` plugin and define development dependencies.

```toml
# workspace pyproject.toml
[tool.pdm]
plugins = ["pdm-polylith-workspace"]

[tool.pdm.dev-dependencies]
dev = [
    "pytest>=7.0",
    "mypy>=1.0",
]
```

--------------------------------

### Configure Polylith Workspace Settings

Source: https://context7.com/davidvujic/python-polylith/llms.txt

Defines core Polylith workspace settings including namespace, Git tag patterns, and structure theme. Ensure 'namespace' is set to your organization's top-level identifier.

```toml
# workspace.toml
[tool.polylith]
# Required: The top-level namespace for all bricks
namespace = "myorg"

# Git tag pattern for diff comparisons (legacy)
git_tag_pattern = "stable-*"

[tool.polylith.structure]
# Theme: "tdd" (default) or "loose"
# tdd: bases/component_name/src/namespace/component_name/
# loose: bases/namespace/component_name/
theme = "tdd"

[tool.polylith.tag.patterns]
# Named tag patterns for diff command
stable = "stable-*"
release = "v[0-9]*"

[tool.polylith.tag]
# Git sorting options for tag selection
sorting = ["-committerdate"]

[tool.polylith.resources]
# Auto-generate README for new bricks
brick_docs_enabled = false

[tool.polylith.test]
# Auto-generate test files for new bricks
enabled = true

[tool.polylith.projects]
# Project aliases for display
[tool.polylith.projects.alias]
my_service = "API"
admin_service = "Admin"

# Project groups for filtering
[tool.polylith.projects.groups]
backend = ["my_service", "worker_service"]
frontend = ["admin_service"]

[tool.polylith.commands]
# Default output directory for saved reports
output = "development/poly"

[tool.polylith.commands.info]
output = "development/poly/info"

[tool.polylith.commands.deps]
output = "development/poly/deps"

```

--------------------------------

### Hatch Build Hook Configuration for Polylith

Source: https://context7.com/davidvujic/python-polylith/llms.txt

Configure `hatch-polylith-bricks` in `pyproject.toml` to automatically include Polylith bricks when building wheels and sdists. This includes specifying brick paths and optionally a custom top namespace.

```toml
# projects/my_service/pyproject.toml
[project]
name = "my_service"
version = "0.1.0"
requires-python = ">=3.9"

[build-system]
requires = ["hatchling", "hatch-polylith-bricks"]
build-backend = "hatchling.build"

[tool.hatch.build.targets.wheel]
packages = ["src/myorg"]

[tool.polylith.bricks]
"../../bases/web_api/src/myorg/web_api" = "myorg/web_api"
"../../components/user_service/src/myorg/user_service" = "myorg/user_service"
"../../components/auth_service/src/myorg/auth_service" = "myorg/auth_service"

# Optional: Custom top namespace for published packages
[tool.polylith]
top_namespace = "mycompany.myservice"

[tool.hatch.build.hooks.polylith-bricks]
# Hook configuration (optional)
work-dir = ".polylith_build"
```

--------------------------------

### Create Polylith Base with Rye

Source: https://github.com/davidvujic/python-polylith/blob/main/projects/polylith_cli/README.md

Use this command with Rye to add a new base to your Polylith workspace. Bases are fundamental building blocks in Polylith.

```shell
rye run poly create base --name my_example_endpoint
```

--------------------------------

### Poetry Plugin Test Commands

Source: https://context7.com/davidvujic/python-polylith/llms.txt

Use the `poly test diff` command via the Poetry plugin to identify affected projects for targeted testing.

```bash
# Test commands
poetry poly test diff --projects
```

--------------------------------

### Configure Custom Top Namespace for Building

Source: https://github.com/davidvujic/python-polylith/blob/main/projects/hatch_polylith_bricks/README.md

Set a custom top namespace in pyproject.toml to prevent import collisions when building libraries from the same monorepo. This will prepend the specified namespace to all imports.

```toml
[tool.polylith.build]
top-namespace = "my_custom_namespace"

```

--------------------------------

### Detect Changed Bricks with Polylith Diff

Source: https://context7.com/davidvujic/python-polylith/llms.txt

The `diff` command shows bricks that have changed since the last git tag, useful for incremental builds and targeted testing. You can specify a tag, use a short format, show only changed bricks, or include their dependents.

```bash
# Using the standalone CLI
poly diff

# Using Poetry plugin
poetry poly diff

# Since a specific tag
poly diff --since=v1.2.0

# Short format (only project names)
poly diff --short

# Show only changed bricks
poly diff --bricks

# Show changed bricks and their dependents
poly diff --bricks --deps
```

--------------------------------

### Define Polylith Bricks in pyproject.toml

Source: https://github.com/davidvujic/python-polylith/blob/main/projects/hatch_polylith_bricks/README.md

Specify the relative paths to your Polylith bases and components and their corresponding target import paths. This configuration is used by the build hook to include bricks in the build.

```toml
[tool.polylith.bricks]
"../../bases/my_namespace/my_base" = "my_namespace/my_base"
"../../components/my_namespace/my_component" = "my_namespace/my_component

```

--------------------------------

### Validate Polylith Workspace Dependencies

Source: https://context7.com/davidvujic/python-polylith/llms.txt

The `check` command validates your Polylith workspace, ensuring brick imports are declared in project dependencies and detecting missing or unused dependencies. Options include strict mode, verbose output, specifying a directory, quiet mode, and using library aliases.

```bash
# Using the standalone CLI
poly check

# Using Poetry plugin
poetry poly check

# Strict mode (check for unused bricks too)
poly check --strict

# Verbose output with detailed import analysis
poly check --verbose

# Check a specific project directory
poly check --directory=projects/my_service

# Quiet mode (only show errors)
poly check --quiet

# Use library aliases for import resolution
poly check --alias=PIL:pillow,cv2:opencv-python
```

--------------------------------

### Remove src Boilerplate with Rye/uv

Source: https://github.com/davidvujic/python-polylith/blob/main/projects/polylith_cli/README.md

Removes the default 'src' directory that is often created by Rye and uv during project initialization. This is a cleanup step to align with Polylith's directory structure.

```shell
rm -r src
```

--------------------------------

### Test Diff Command for Targeted Testing

Source: https://context7.com/davidvujic/python-polylith/llms.txt

The `poly test diff` command identifies affected projects and bricks by test changes. Use it to run targeted tests in CI/CD pipelines. Options include specifying a tag, showing only bricks, projects, or using a short format.

```bash
# Using the standalone CLI
poly test diff
```

```bash
# Using Poetry plugin
poetry poly test diff
```

```bash
# Since a specific tag
poly test diff --since=v1.2.0
```

```bash
# Show only affected bricks
poly test diff --bricks
```

```bash
# Show only affected projects
poly test diff --projects
```

```bash
# Short format
poly test diff --short
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.