Enforcing Modular Boundaries with Import Linter in Python

Modularity Decay in Growing Python Codebases

In dynamic, interpreted languages like Python, the runtime executes imports at startup. Python has no language-enforced visibility layers.11 such as Java’s package-private visibility, C++‘s namespace restrictions, or C#‘s internal keyword If a module resides on the Python path, any other module can import it.

Compiled languages offer package-private visibility or namespace restrictions that block unauthorized access at compile time. Python provides no equivalent mechanism, relying entirely on developer discipline and convention.

This lack of compiler enforcement means that modular boundaries exist only as conceptual agreements between developers. A single import statement in the wrong module can silently break architectural contracts, and no built-in tooling raises an alarm. The problem compounds as teams grow: new contributors unfamiliar with the intended layer separation introduce shortcut imports under time pressure.

As codebases grow, several modularity decay patterns emerge. You must identify and eliminate them to maintain a clean codebase architecture.

Developers often introduce shortcut imports when sibling layers bypass defined ports and import concrete adapters directly. The shortcut circumvents the port-adapter contract, making it difficult to swap implementations (e.g., swapping a database client) and causing compile-time or testing-time dependencies to leak across boundaries. In practice, shortcut coupling results in test suites requiring fully configured database connections just to verify simple application behavior.

Circular dependencies emerge when modules across different layers import each other, creating execution cycles during package initialization. Because Python executes import statements dynamically at runtime, these cycles cause ImportError crashes at application startup. Operationally, circular imports force developers to use localized or late imports, obscure the dependency graph, and prevent unit tests from isolating specific components.

Accidental coupling happens when the core domain layer imports external libraries22 like psycopg2, redis, or boto3 or low-level implementation details, often because an adapter has leaked into a domain model. When the domain layer directly couples to third-party dependencies, any upgrade or modification to those libraries forces changes inside the core business logic. This tight coupling defeats the purpose of clean architecture, which dictates that business logic must remain stable and unaffected by infrastructure changes.

# Example of boundary leakage in shop/domain/models.py
from shop.adapters.db_adapter import PostgresOrderRepository  # Leaked

A static analysis tool that treats architectural modular boundaries as first-class constraints solves this problem. The linter fails the build immediately if the source code violates a contract.

Enforcing Modular Boundaries with Import Linter

To prevent modularity decay, you must establish strict rules for dependency direction and package layout. Once you design these boundaries, you can automate their enforcement using Import Linter contracts.

Before configuring automated checks, establish the allowed direction of dependencies. As discussed in the previous article on Hexagonal Architecture,33 Ports and Adapters the core domain and application layers reside at the center. Outward adapters depend on inward ports.

                     Allowed Direction
                     ─────────────────
                          INWARD ↓

  ┌─────────────────────────────────────────────┐
  │             Adapters Layer                  │
  │           (shop.adapters)                   │
  │                                             │
  │   ┌─────────────────────────────────────┐   │
  │   │        Application Layer            │   │
  │   │      (shop.application)             │   │
  │   │                                     │   │
  │   │   ┌─────────────────────────────┐   │   │
  │   │   │        Ports Layer          │   │   │
  │   │   │      (shop.ports)           │   │   │
  │   │   │                             │   │   │
  │   │   │   ┌─────────────────────┐   │   │   │
  │   │   │   │    Domain Layer     │   │   │   │
  │   │   │   │   (shop.domain)     │   │   │   │
  │   │   │   │  Zero outbound      │   │   │   │
  │   │   │   │  dependencies       │   │   │   │
  │   │   │   └─────────────────────┘   │   │   │
  │   │   │                             │   │   │
  │   │   └─────────────────────────────┘   │   │
  │   │                                     │   │
  │   └─────────────────────────────────────┘   │
  │                                             │
  └─────────────────────────────────────────────┘

  Rule: imports flow INWARD only (↓).
        Outward imports (↑) are FORBIDDEN.

  tests/ lives outside shop/ (can import any layer).

# shop/application/use_cases.py: BEFORE (leaky)
from shop.adapters.db_adapter import (
    PostgresOrderRepository,
)

class OrderProcessor:
    def __init__(self) -> None:
        self._repo = PostgresOrderRepository(
            "postgresql://localhost/shop"
        )

$ lint-imports
=============
Import Linter
=============

----- Forbidden import -----

shop.application.use_cases
  -> shop.adapters.db_adapter

Contracts: 1 broken

# shop/application/use_cases.py: AFTER (clean)
from shop.ports.repositories import (
    OrderRepositoryPort,
)

class OrderProcessor:
    def __init__(
        self, repo: OrderRepositoryPort
    ) -> None:
        self._repo = repo

pip install import-linter

[tool.importlinter]
root_package = "shop"
exclude_type_checking_imports = true

[[tool.importlinter.contracts]]
name = "Domain layer isolation"
type = "forbidden"
source_modules = [
    "shop.domain",
]
forbidden_modules = [
    "shop.ports",
    "shop.application",
    "shop.adapters",
]

[[tool.importlinter.contracts]]
name = "Ports depend only on domain"
type = "forbidden"
source_modules = [
    "shop.ports",
]
forbidden_modules = [
    "shop.application",
    "shop.adapters",
]

[[tool.importlinter.contracts]]
name = "Hexagonal layer hierarchy"
type = "layers"
containers = ["shop"]
layers = [
    "adapters",
    "application",
    "ports",
    "domain",
]

[[tool.importlinter.contracts]]
name = "Adapter sibling independence"
type = "independence"
modules = [
    "shop.adapters.db_adapter",
    "shop.adapters.stripe_adapter",
]

lint-imports

Managing Test Suites and Type Hint Cycles

Integrating architectural contracts into real-world codebases introduces practical challenges. You must handle unit testing exceptions and cyclic type annotations without eroding boundaries.

[[tool.importlinter.contracts]]
name = "Domain layer isolation"
type = "forbidden"
source_modules = ["shop.domain"]
forbidden_modules = ["shop.adapters"]
ignore_imports = [
    "shop.domain.tests.test_models -> shop.adapters.db_adapter",
]

from typing import TYPE_CHECKING, Protocol

if TYPE_CHECKING:
    from shop.domain.models import Order


class OrderProcessorPort(Protocol):
    async def process(
        self, order: Order
    ) -> bool: ...

Benchmarking Import Linter on Real Codebases

I benchmarked lint-imports against three open source projects that already use it in production, with their real contract configurations in place, to see how this tool performs in different situations.

A clean venv keeps the import graph from picking up unrelated site-packages:

python3 -m venv .bench-venv
source .bench-venv/bin/activate
pip install import-linter

For a project that already declares import-linter in pyproject.toml, install it in editable mode so the linter picks up the real root_package and contracts:

git clone --depth=1 https://github.com/janbjorge/pgqueuer.git
cd pgqueuer
pip install -e .[dev]

I used hyperfine to time the linter because it’s written in rust it runs warmups and reports standard deviation:

hyperfine --warmup 1 --runs 5 'lint-imports'

Here are the benchmarks on an Apple M1 Pro with import-linter 2.13 and Python 3.14:

The PostHog figure is the most representative for “large codebase” expectations. Even with 6k files and 10k import edges, the linter finishes in under half a second, and the entire graph fits in 65 MB of RAM.

Key Practices for Enforcing Modular Python Boundaries

• Import Linter automates boundary enforcement by treating architectural rules as builds errors.
• Keeping test suites external to the source package simplifies contracts and eliminates the need for ignore_imports whitelists.
• Tracking the ignore_imports count over time surfaces architectural debt before boundaries erode.
• Resolving type hint cycles with TYPE_CHECKING guards keeps the linter happy without introducing runtime overhead.

Detecting Dynamic Import Bypasses with AST Scanning

Import Linter handles static import analysis comprehensively, but it can’t detect importlib.import_module calls or inline imports hidden inside function bodies. In most well-maintained codebases, static contracts are sufficient. However, in legacy projects with accumulated technical debt, or in repositories with many contributors where coding conventions vary widely, developers may inadvertently (or deliberately) bypass static linters using dynamic imports.

For these scenarios, a custom Abstract Syntax Tree (AST) checker serves as a last line of defense. The following script scans all Python files in the domain and application layers, reporting any inline imports or import_module calls it finds:

import ast
import sys
from pathlib import Path

class ImportScanner(ast.NodeVisitor):
    def __init__(self, path: Path) -> None:
        self.path = path
        self._in_function = False
        self.violations: list[str] = []

    def visit_FunctionDef(
        self,
        node: ast.FunctionDef | ast.AsyncFunctionDef,
    ) -> None:
        self._in_function = True
        self.generic_visit(node)
        self._in_function = False

    visit_AsyncFunctionDef = visit_FunctionDef

    def visit_Import(
        self, node: ast.Import | ast.ImportFrom
    ) -> None:
        if self._in_function:
            self.violations.append(
                f"{self.path}:{node.lineno}"
                " - Inline import forbidden"
            )
            return
        self.generic_visit(node)

    visit_ImportFrom = visit_Import

The scanner walks each file’s AST, tracking whether the current node is inside a function body. When visit_Import fires while _in_function is True, the script records an inline-import violation on the visitor’s violations list and returns without descending further into that subtree. Letting the visitor accumulate findings produces a complete report in a single pass.

A second visitor method catches importlib.import_module calls:

    def visit_Call(self, node: ast.Call) -> None:
        if (
            isinstance(node.func, ast.Attribute)
            and node.func.attr == "import_module"
        ):
            self.violations.append(
                f"{self.path}:{node.lineno}"
                " - import_module forbidden"
            )
            return
        self.generic_visit(node)

To run the scanner, add a driver script that iterates over the source tree:

if __name__ == "__main__":
    total = 0
    for p in Path("./src").rglob("*.py"):
        scanner = ImportScanner(p)
        scanner.visit(ast.parse(p.read_text()))
        for v in scanner.violations:
            print(v, file=sys.stderr)
        total += len(scanner.violations)
    if total:
        print(
            f"{total} dynamic import(s) detected.",
            file=sys.stderr,
        )
        sys.exit(1)
    print("No dynamic imports detected.")

This AST scanning script can be useful in codebases where dynamic import bypasses have been observed in code reviews or where the contributor base is large enough that convention alone is insufficient.

Running the scanner against the three benchmarked projects returned several dynamic imports in all of them!

References and Additional Resources

• Read the Import Linter Documentation for detailed contract specifications.
• Read the Python ast module documentation to understand abstract syntax trees.