pyarchrules

PyArchRules Logo

⚠️ Pre-release (beta). APIs may change before the stable 1.0 release.

📚 Full Documentation — Getting Started · Configuration · CLI Reference · Use Cases

PyArchRules enforces architecture rules in Python projects:

🏗️ Folder structure validation per service
🔗 Internal dependency direction control
🛡️ Cross-service import isolation for monorepos
🐍 Python DSL for writing rules inside your test suite
⚙️ Zero extra config — everything in pyproject.toml
🚀 CI-ready — exit code 1 on any violation

Installation

Quick start

# 1. Add [tool.pyarchrules] to pyproject.toml
pyarchrules init-project

# 2. Register a service
pyarchrules add-service backend src/backend

# 3. Run the check
pyarchrules check

TOML configuration

[tool.pyarchrules]
root             = "."
validate_paths   = true
isolate_services = true

[tool.pyarchrules.services.backend]
path         = "src/backend"
tree         = ["api", "domain", "infra"]
tree_mode    = "strict"
dependencies = ["api -> domain", "domain -> infra", "* -> utils"]

Python DSL

# tests/test_architecture.py
from pyarchrules import PyArchRules

def test_architecture():
    rules = PyArchRules()
    rules.for_service("backend") \
        .must_contain_folders(["api", "domain", "infra"], allow_extra=False) \
        .no_wildcard_imports() \
        .no_circular_imports()
    rules.validate()

CLI commands

Command	Description
`init-project`	Initialise `[tool.pyarchrules]` in `pyproject.toml`
`add-service NAME PATH`	Register a service
`remove-service NAME`	Remove a service
`list-services`	Show all configured services
`check`	Validate architecture

Contributing

See CONTRIBUTING.md.

License

MIT