python-dependency-linter 0.1.0

A dependency linter for Python projects

python-dependency-linter

A dependency linter for Python projects. Define rules for which modules can depend on what, and catch violations.

Installation

pip install python-dependency-linter

Or with uv:

uv add python-dependency-linter

Quick Start

Create .python-dependency-linter.yaml in your project root:

rules:
  - name: domain-isolation
    modules: contexts.*.domain
    allow:
      standard_library: [dataclasses, typing]
      third_party: [pydantic]
      local: [contexts.*.domain]

  - name: application-dependency
    modules: contexts.*.application
    allow:
      standard_library: ["*"]
      third_party: [pydantic]
      local:
        - contexts.*.application
        - contexts.*.domain

Run:

pdl check

Output:

contexts/boards/domain/models.py:6
    [domain-isolation] contexts.boards.domain.models → contexts.boards.application.service (local)

contexts/boards/domain/models.py:9
    [domain-isolation] contexts.boards.domain.models → sqlalchemy (third_party)

Found 2 violation(s).

Configuration

Rule Structure

Each rule has:

• name — Rule identifier, shown in violation output
• modules — Module pattern to apply the rule to (supports * wildcard)
• allow — Whitelist: only listed dependencies are allowed
• deny — Blacklist: listed dependencies are denied

rules:
  - name: rule-name
    modules: my_package.*.domain
    allow:
      standard_library: [dataclasses]
      third_party: [pydantic]
      local: [my_package.*.domain]
    deny:
      third_party: [boto3]

Import Categories

Dependencies are classified into three categories (per PEP 8):

• standard_library — Python built-in modules (os, sys, typing, ...)
• third_party — Installed packages (pydantic, sqlalchemy, ...)
• local — Modules in your project

Behavior

• No rule — Everything is allowed
• allow only — Whitelist mode. Only listed dependencies are allowed
• deny only — Blacklist mode. Listed dependencies are denied, rest allowed
• allow + deny — Allow first, then deny removes exceptions
• If allow exists but a category is omitted, that category allows all

Use "*" to allow all within a category:

allow:
  standard_library: ["*"]  # allow all standard library imports

Wildcard

* matches a single level in dotted module paths:

modules: contexts.*.domain  # matches contexts.boards.domain, contexts.auth.domain, ...

Rule Merging

When multiple rules match a module, they are merged. Specific rules override wildcard rules per field:

rules:
  - name: base
    modules: contexts.*.domain
    allow:
      third_party: [pydantic]

  - name: boards-extra
    modules: contexts.boards.domain
    allow:
      third_party: [attrs]  # merged: [pydantic, attrs]

pyproject.toml

You can also configure in pyproject.toml:

[[tool.python-dependency-linter.rules]]
name = "domain-isolation"
modules = "contexts.*.domain"

[tool.python-dependency-linter.rules.allow]
standard_library = ["dataclasses", "typing"]
third_party = ["pydantic"]
local = ["contexts.*.domain"]

CLI

# Check with default config (.python-dependency-linter.yaml)
pdl check

# Specify config file
pdl check --config path/to/config.yaml

# Specify project root
pdl check --project-root path/to/project

Exit codes:

• 0 — No violations
• 1 — Violations found

Pre-commit

Add to .pre-commit-config.yaml:

- repo: https://github.com/heumsi/python-dependency-linter
  rev: v0.1.0
  hooks:
    - id: python-dependency-linter

License

MIT