pyarchrules

⚠️ 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

pip install pyarchrules

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

This site is open source. Improve this page.