Deply

Deply is a static code analysis tool for Python that helps you communicate, visualize and enforce architectural decisions in your projects. You can freely define your architectural layers over classes and which rules should apply to them.

For example, you can use Deply to ensure that modules/packages in your project are truly independent of each other to make them easier to reuse.

Deply can be used in a CI pipeline to make sure a pull request does not violate any of the architectural rules you defined. With the optional Mermaid formatter you can visualize your layers, rules and violations.

pip install deply

deply analyze
which is equivalent to
deply analyze --config=deply.yaml

deply:
  paths:
    - /path/to/your/project
exclude_files:
    - ".\\.venv/."
layers:
    - name: models
      collectors:
        - type: class_inherits
          base_class: "django.db.models.Model"
- name: views
      collectors:
        - type: file_regex
          regex: ".*/views_api.py"
- name: services
      collectors:
        - type: class_name_regex
          class_name_regex: ".*Service$"
ruleset:
    views:
      disallow_layer_dependencies:
        - models
services:
      disallow_external_imports:
        - django
        - requests

# Basic usage
deply analyze
With a specific config file
deply analyze --config=custom_config.yaml
Validate configuration only
deply validate --config=custom_config.yaml
Generate a Mermaid diagram
deply analyze --mermaid
Get help
deply --help

Every completed analysis report includes completeness metrics for discovered, excluded, parsed, mapped, and unmapped files; mapped and overlapping elements; and detected dependencies. Incomplete analysis prints the available metrics to standard error before exiting. With --report-format=json, invalid configuration and incomplete analysis also produce a structured error report. JSON schema v1 includes analysis status, configured rule IDs, source/target identities, layer pairs, and stable violation fingerprints for agent integrations. See the JSON contract for fields and identity guarantees. Distinct dependencies and configured rules at the same location are now preserved in every report, so totals may increase compared with previously collapsed findings.

Violation Baseline

Accept reviewed architecture debt once and fail only on new relationships:

deply analyze --write-baseline=deply-baseline.json
deply analyze --baseline=deply-baseline.json --report-format=json

Creation requires complete analysis and never overwrites a file. Comparison adds new, existing, and resolved categories to JSON and fails on new violations or errors. Other formats show only new findings. Fingerprints identify relationships, so additional call sites for accepted relationships are also accepted. See baseline semantics and safe refresh. Baseline support is available starting with Deply v1.2.2.

Agent Skill

Deply v1.2.2 includes a portable Agent Skill at skills/deply-config/ for Codex, Claude Code, and other Agent Skills-compatible assistants. It helps an assistant inspect a Python project, generate deply.yaml using light, medium, or strict guidance, validate it with deply validate, run analysis, and add Makefile/CI/docs integration. These profiles belong to the Agent Skill; they are not built-in Deply CLI presets.

Use it with:

Use $deply-config to create and validate a Deply architecture config for this Python project.

See Agent Skill for installation instructions.

Features

• Layer-Based Analysis: Define project layers and restrict their dependencies to enforce modularity.
• Dynamic Layer Configuration: Easily configure collectors for each layer using file patterns, class inheritance, and logical conditions.
• Cross-Layer Dependency Rules: Resolve internal dependencies through modules, absolute and relative imports, aliases, and lexical bindings before checking layer boundaries.
• External Import Restrictions: Prevent selected layers from importing framework, persistence, or SDK package roots through absolute imports. Relative imports are ignored.
• Extensible and Configurable: Customize layers with built-in or custom collectors and supported rules.
• Mermaid Diagrams: Visualize your architecture and dependencies with Mermaid diagrams.
• Error Suppression: Suppress specific rule violations with inline comments.
• Config Validation: Validate deply.yaml explicitly or automatically before analysis.
• SARIF Reports: Export findings for GitHub Code Scanning with deply analyze --report-format=sarif --output=deply.sarif. See the CLI guide for upload instructions and limitations.
• Architecture Recipes: Copy and adapt documented configurations for 21 architecture and application patterns; they are not built-in presets.

Error Suppression

Deply provides options to suppress rule violations using comments in your code:

# Line-level suppression
user.get()  # deply:ignore:DISALLOW_LAYER_DEPENDENCIES
import requests  # deply:ignore:DISALLOWED_EXTERNAL_IMPORT
File-level suppression (at the top of the file)
deply:ignore-file:ENFORCE_INHERITANCE

How to Contribute

Running Tests

Use the following commands for local quality checks:

make check
make test
make mutation
make lint
make typing
make security
make pre-commit

Or run unittest directly:

python -m unittest discover tests

Roadmap

See the verified technical roadmap for current priorities, evidence, and implementation conditions.

Further Documentation

• Core Concepts - Explains layers, rules and violations in more details.
• Configuration - Reference for all available settings in a depfile
• Collectors - Reference for which collectors are available in Deply to define your layers.
• Rules - Lists the different rule types supported by Deply
• Mermaid Diagrams - Overview of the diagram generation capabilities
• Command Line Interface - Advice for using the CLI
• Agent Skill - Install and use the Deply Config Agent Skill
• Architecture Styles - Compare 21 architecture and application pattern recipes
• FastAPI - Configure layered FastAPI boundaries
• Full Stack FastAPI Template - Verified baseline for FastAPI's official template
• Django - Configure Django model, view, and domain boundaries
• Flask - Configure Flask route, blueprint, and persistence boundaries

Author

Archil Abuladze

License

See the LICENSE file for details.