PyArchRules

Architecture linter for Python.

Define your project's folder structure and import rules in pyproject.toml (or in Python) and enforce them in CI or from your test suite.

Key features

•   Folder structure validation.
•   Directional dependency rules between modules.
•   Isolation between services and layers.
•   Circular import detection.

Quick start

1. Install

pip install pyarchrules

2. Define your rules

Option A — pyproject.toml (recommended)

# pyproject.toml
[tool.pyarchrules.services.backend]
path = "src/backend"

# Required folder structure
tree      = ["api", "domain", "infra"]
tree_mode = "strict"                       # exists / strict / exact

# Allowed import directions
dependencies = [
    "api -> domain",
    "domain -> infra",
]

# Prevent circular imports
no_circular_imports = true

Run it:

pyarchrules check

Option B — Python DSL (great for tests)

# tests/test_architecture.py
from pyarchrules import PyArchRules


def test_backend_architecture():
    rules = PyArchRules()
    (
        rules.for_service("backend")
             .tree_structure(["api", "domain", "infra"], mode="strict")
             .dependencies(["api -> domain", "domain -> infra"])
             .no_circular_imports()
    )
    rules.validate()

Run it:

pytest tests/test_architecture.py

Next steps

• Configuration — full [tool.pyarchrules] reference.
• Python DSL — every rule available as a fluent method.
• Use Cases — monorepo and Clean Architecture patterns.