What is archetype-py?

mossabarektout/archetype-py — explained in plain English

Analysis updated 2026-05-18

★ 3PythonAudience · developerComplexity · 3/5LicenseSetup · easy

Mindmap

mindmap
  root((repo))
    What it does
      Enforce architecture rules
      Detect import cycles
      Fail CI on violations
    Tech stack
      Python
      pytest integration
      CLI tool
    Use cases
      Prevent layer leaks
      Enforce clean architecture
      Adopt rules gradually
    Audience
      Developers
      Backend teams
    Setup
      pip install archetype-py
      archetype init
      archetype check
    Limits
      Python 3.11 plus only
      Rules must be written manually

mindmap root((repo)) What it does Enforce architecture rules Detect import cycles Fail CI on violations Tech stack Python pytest integration CLI tool Use cases Prevent layer leaks Enforce clean architecture Adopt rules gradually Audience Developers Backend teams Setup pip install archetype-py archetype init archetype check Limits Python 3.11 plus only Rules must be written manually

What do people build with it?

USE CASE 1

Codify rules like 'API must not import database internals' and enforce them in CI.

USE CASE 2

Detect and block circular import dependencies before they merge.

USE CASE 3

Gradually adopt architecture rules on an existing codebase using date-scoped rules.

USE CASE 4

Run architecture checks alongside pytest unit tests.

What is it built with?

Pythonpytest

How does it compare?

	mossabarektout/archetype-py	0marildo/imago	agentlexi/agent-lexi
Stars	3	3	3
Language	Python	Python	Python
Setup difficulty	easy	easy	moderate
Complexity	3/5	2/5	4/5
Audience	developer	general	vibe coder

Figures from each repo's GitHub metadata at analysis time.

How do you get it running?

Difficulty · easy Time to first run · 30min

Requires Python 3.11 or newer, install via pip.

Use freely for any purpose, including commercial use, as long as you keep the copyright notice.

So what is it?

archetype-py is a Python library that lets software teams write their architectural rules as code and automatically check that those rules are never broken as the codebase grows. Architecture here means the structural decisions about how different parts of a program are allowed to talk to each other, for example, the API layer must not directly call the database layer, or no two modules may depend on each other in a circle. Without a tool like this, these rules live only in documentation or team memory and silently erode over time. With archetype-py, you create a file called architecture.py in your project and write Python functions decorated with rule to describe what is and is not allowed. The command line tool then inspects your codebase's actual import relationships and flags violations with a clear message showing exactly which file broke which rule. Rules can be set to fail the build or only warn, and some can be scoped to files changed after a specific date, helping teams adopt the tool gradually on existing codebases. The checks integrate with pytest, a popular Python testing framework, so architecture tests run alongside unit tests, and a single line in a CI pipeline is enough to enforce rules on every pull request. A skip decorator lets teams temporarily defer a rule, and a group system lets you run subsets of rules independently. It is aimed at Python projects following patterns like Clean Architecture, Hexagonal Architecture, or Domain driven design, especially growing teams where tribal knowledge about module boundaries is no longer reliable. The tool is installed with pip, requires Python 3.11 or newer, and is released under the MIT license. The full README is longer than what was shown.

Copy-paste prompts

Prompt 1

Help me write an architecture.py file that enforces layered boundaries in my Python project.

Prompt 2

Show me how to add archetype-py's check command to my CI pipeline.

Prompt 3

Explain how the @since decorator lets me adopt rules gradually on legacy code.

Prompt 4

Walk me through detecting import cycles with archetype-py's no_cycles rule.

Frequently asked questions