Deply: keep your python architecture clean

Large Python projects often evolve into complex codebases that are tough to maintain. Keeping track of imports, layers, and who depends on whom can quickly turn into a mess. Deply is here to help. It analyzes your code structure and enforces architectural rules, ensuring your Python project remains clean, modular, and easy to maintain—even as it grows.

Why Architectural Enforcement Matters

Python's flexibility makes it easy to introduce spaghetti code if we're not careful. Adding new modules, decorators, or even changing how classes inherit can introduce subtle dependency issues across large teams. Clear boundaries—enforced by automated checks—help keep code quality high. This approach boosts readability and team productivity.

What Is Deply?

Deply is a standalone tool that:

1. Lets you define project layers (like views, models, services) in a YAML configuration.
2. Collects code elements into these layers through rules (e.g., class_inherits, decorator_usage, file_regex).
3. Enforces architectural policies to prevent undesired coupling or naming mishaps.

Why Not Use Another Tool?

• pydeps: Focuses on visualizing imports.
• import-linter: Checks import constraints.
• pytestarch or pytest-archon: Relies on writing code-based tests for architecture.
• Tach (Rust-based): Language-agnostic approach, may not align perfectly with Python specifics.

Deply's advantage is that it goes beyond imports, looking at decorators, class inheritance, file patterns, and more. Its YAML-based configuration makes it simpler to incorporate into CI pipelines without writing new test files.

New in 0.5.2

1. Upgraded Collectors: More flexible ways to define classes and functions, including advanced regex patterns.
2. Performance Boost: Deply now runs up to 10x faster than before. Integrating it with CI won't slow your builds.
3. Expanded Rules: Additional checks for inheritance, decorator usage, and naming conventions let you design granular policies.

Installation

pip install deply

You'll get the latest version, currently 0.5.2.

Deply Configuration (deply.yaml)

Create a deply.yaml file in your project root. At a minimum, define the paths you want to analyze, any files to exclude, your layers, and rules. Below is a sample snippet for a Django-like project.

deply:
  paths:
    - /path/to/your/project

  exclude_files:
    - ".*\\.venv/.*"

  layers:
    - name: models
      collectors:
        - type: bool
          any_of:
            - type: class_inherits
              base_class: "django.db.models.Model"
            - type: class_inherits
              base_class: "django.contrib.auth.models.AbstractUser"

    - name: views
      collectors:
        - type: file_regex
          regex: ".*/views_api.py"

  ruleset:
    views:
      disallow_layer_dependencies:
        - models
      enforce_function_decorator_usage:
        - type: bool
          any_of:
            - type: bool
              must:
                - type: function_decorator_name_regex
                  decorator_name_regex: "^HasPerm$"
                - type: function_decorator_name_regex
                  decorator_name_regex: "^extend_schema$"
            - type: function_decorator_name_regex
              decorator_name_regex: "^staticmethod$"

How it works:

1. models layer collects classes inheriting from Django's Model or AbstractUser.
2. views layer collects code from files ending with views_api.py.
3. Rules:
4. disallow_layer_dependencies: the views layer can't directly depend on models.
5. enforce_function_decorator_usage: all functions in views need either (HasPerm and extend_schema) or staticmethod.

Running Deply

Once your config is ready, run:

deply analyze

• --config=another_config.yaml lets you specify a different file.
• --report-format=text|json|github-actions controls how violations are displayed.

Additional Examples

Class Naming:

service:
  enforce_class_naming:
    - type: class_name_regex
      class_name_regex: ".*Service$"

All classes in the service layer must end with Service.

Function Naming:

tasks:
  enforce_function_naming:
    - type: function_name_regex
      function_name_regex: "^task_.*"

All functions in tasks must start with task_.

Pro Tip: Combine multiple conditions with bool to form advanced logic (must, any_of, must_not), ensuring you can craft highly specific rules.

CI Integration

Add a step to your CI pipeline:

deply analyze

Your pipeline can fail if any architectural violations are found.

Wrap-Up

Deply is designed to help you catch architectural violations before they become time-consuming refactors. By automating these checks, you can maintain a crisp, layered design, even on large teams.

• GitHub: https://github.com/Vashkatsi/deply
• PyPI: https://pypi.org/project/deply/

Feel free to test it out and adjust the configuration for your own needs. If you have questions or ideas, check out the repo for details on filing issues or contributing. Happy coding!