{"id":6665,"library":"hatch-polylith-bricks","title":"Hatch Polylith Bricks","description":"Hatch Polylith Bricks is a Hatch build hook plugin that integrates Polylith architecture principles into Hatch-managed Python projects. It enables the use of Polylith's `poly` CLI commands for monorepo development, helping manage workspaces, components, and bases. The current version is 1.5.5, with frequent updates addressing new features and fixes.","status":"active","version":"1.5.5","language":"en","source_language":"en","source_url":"https://github.com/davidvujic/python-polylith","tags":["hatch","polylith","build-hook","monorepo","cli","architecture","developer-tool"],"install":[{"cmd":"pip install hatch-polylith-bricks","lang":"bash","label":"Install build hook"}],"dependencies":[{"reason":"Provides core Polylith functionality and `poly` CLI commands, used by the build hook.","package":"polylith"},{"reason":"Required to use `hatch-polylith-bricks` as a build hook within a Hatch project; project must be managed by Hatch.","package":"hatch"},{"reason":"Ensures compatibility with the underlying Typer CLI framework across various Python versions, especially Python 3.8.","package":"typing-extensions","optional":true}],"imports":[{"note":"Hatch Polylith Bricks is primarily used as a Hatch build hook via `pyproject.toml` configuration and provides the `poly` CLI. Direct Python imports into user application code are not a common usage pattern for typical users.","symbol":"PolylithBuildHook","correct":"from hatch_polylith_bricks.plugin import PolylithBuildHook"}],"quickstart":{"code":"# 1. Ensure you have Hatch installed: `pip install hatch`\n# 2. Initialize a Hatch project (if you don't have one):\n#    `hatch new my-polylith-project`\n#    `cd my-polylith-project`\n\nprint(\"--- Step 1: Configure pyproject.toml ---\")\nprint(\"Add the following to your project's pyproject.toml:\")\nprint(\"```toml\")\nprint(\"[tool.hatch.build.hooks.polylith]\")\nprint(\"# Optional: specify top-level namespace if different from 'project.name'\")\nprint(\"# namespace = \\\"my_polylith_namespace\\\"\")\nprint(\"```\")\nprint(\"\\n--- Step 2: Create a workspace.toml (optional but recommended) ---\")\nprint(\"Create a file named workspace.toml in your project root with content like:\")\nprint(\"```toml\")\nprint(\"[tool.polylith]\")\nprint(\"namespace = \\\"my_polylith_namespace\\\" # Replace with your actual namespace\")\nprint(\"bases = [\\\"src/bases\\\"]\")\nprint(\"components = [\\\"src/components\\\"]\")\nprint(\"projects = [\\\"projects/*\\\"]\")\nprint(\"```\")\nprint(\"\\n--- Step 3: Run a Polylith CLI command ---\")\nprint(\"Make sure you are in the project's root directory where pyproject.toml and workspace.toml reside.\")\n\nimport subprocess\n\ntry:\n    print(\"Attempting to run 'poly info'...\")\n    # In a real Hatch project, you'd typically run: hatch run poly info\n    # This example assumes 'poly' is accessible from the current environment/PATH\n    result = subprocess.run(['poly', 'info'], capture_output=True, text=True, check=True)\n    print(\"STDOUT:\\n\", result.stdout)\n    if result.stderr:\n        print(\"STDERR:\\n\", result.stderr)\n    print(\"\\nSuccessfully ran 'poly info'.\")\nexcept FileNotFoundError:\n    print(\"Error: 'poly' command not found.\\nEnsure 'hatch-polylith-bricks' is installed and 'poly' is in your PATH,\\nor run via 'hatch run poly info' if within a Hatch-managed project environment.\")\nexcept subprocess.CalledProcessError as e:\n    print(f\"Error running 'poly info': {e}\")\n    print(\"STDOUT:\\n\", e.stdout)\n    print(\"STDERR:\\n\", e.stderr)\n","lang":"python","description":"Configure `hatch-polylith-bricks` in your `pyproject.toml` as a Hatch build hook, set up your Polylith `workspace.toml`, and then use the `poly` command-line interface to interact with your Polylith project. The example guides through the setup and demonstrates running a basic `poly info` command."},"warnings":[{"fix":"Upgrade to `hatch-polylith-bricks>=1.5.0` or explicitly install `typing-extensions` (`pip install typing-extensions`).","message":"Older versions (before 1.5.0, stable-94) might fail at runtime for Python 3.8 environments due to a missing `typing-extensions` dependency for Typer, which was silently dropped by Typer. This could lead to `ModuleNotFoundError`.","severity":"gotcha","affected_versions":"<1.5.0"},{"fix":"Upgrade to `hatch-polylith-bricks>=1.5.2` for accurate dependency and import reporting.","message":"The `poly check` and `poly libs` commands in older versions (before 1.5.2, stable-99) might incorrectly report missing imports or dependencies when third-party libraries have similar names to Polylith top namespaces. This could lead to misleading warnings or errors.","severity":"gotcha","affected_versions":"<1.5.2"},{"fix":"Update automation scripts to check for the exit code (`0` for success, non-`0` for failure), or ensure unique brick names are provided when creating new bricks.","message":"Running `poly create component` or `poly create base` in versions 1.5.1 and newer (stable-98) will now exit with a non-zero fail code if a brick with the same name already exists. This changes previous behavior where it might have proceeded or warned without failing, potentially breaking automation scripts.","severity":"gotcha","affected_versions":">=1.5.1"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}