python-dependency-linter 0.1.0__py3-none-any.whl

python_dependency_linter/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

python_dependency_linter/checker.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from python_dependency_linter.config import AllowDeny, Rule
+from python_dependency_linter.matcher import matches_pattern
+from python_dependency_linter.parser import ImportInfo
+from python_dependency_linter.resolver import ImportCategory
+
+
+@dataclass
+class Violation:
+    rule_name: str
+    source_module: str
+    imported_module: str
+    category: ImportCategory
+    lineno: int
+
+
+def _get_category_list(
+    allow_deny: AllowDeny | None, category: ImportCategory
+) -> list[str] | None:
+    if allow_deny is None:
+        return None
+    match category:
+        case ImportCategory.STANDARD_LIBRARY:
+            return allow_deny.standard_library
+        case ImportCategory.THIRD_PARTY:
+            return allow_deny.third_party
+        case ImportCategory.LOCAL:
+            return allow_deny.local
+
+
+def _matches_pattern_or_submodule(pattern: str, module: str) -> bool:
+    """Return True if module matches pattern exactly or is a submodule of it."""
+    if matches_pattern(pattern, module):
+        return True
+    # Check if module starts with a prefix that matches the pattern.
+    # e.g. "contexts.*.domain" should match "contexts.boards.domain.models"
+    module_parts = module.split(".")
+    pattern_parts = pattern.split(".")
+    if len(module_parts) > len(pattern_parts):
+        prefix = ".".join(module_parts[: len(pattern_parts)])
+        if matches_pattern(pattern, prefix):
+            return True
+    # Literal prefix match (no wildcards in pattern)
+    if "*" not in pattern and module.startswith(pattern + "."):
+        return True
+    return False
+
+
+def _is_in_list(module: str, patterns: list[str]) -> bool:
+    if "*" in patterns:
+        return True
+    return any(_matches_pattern_or_submodule(p, module) for p in patterns)
+
+
+def check_import(
+    import_info: ImportInfo,
+    category: ImportCategory,
+    merged_rule: Rule | None,
+    source_module: str,
+) -> Violation | None:
+    if merged_rule is None:
+        return None
+
+    module = import_info.module
+
+    # Check deny first (deny takes priority over allow)
+    deny_list = _get_category_list(merged_rule.deny, category)
+    if deny_list is not None and _is_in_list(module, deny_list):
+        return Violation(
+            rule_name=merged_rule.name,
+            source_module=source_module,
+            imported_module=module,
+            category=category,
+            lineno=import_info.lineno,
+        )
+
+    # Check allow
+    allow_list = _get_category_list(merged_rule.allow, category)
+    if allow_list is None:
+        # No allow list for this category = allow all
+        return None
+    if _is_in_list(module, allow_list):
+        return None
+
+    return Violation(
+        rule_name=merged_rule.name,
+        source_module=source_module,
+        imported_module=module,
+        category=category,
+        lineno=import_info.lineno,
+    )

python_dependency_linter/cli.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from python_dependency_linter.checker import check_import
+from python_dependency_linter.config import load_config
+from python_dependency_linter.matcher import find_matching_rules, merge_rules
+from python_dependency_linter.parser import parse_imports
+from python_dependency_linter.reporter import format_violations
+from python_dependency_linter.resolver import resolve_import
+
+
+def _file_to_module(file_path: Path, project_root: Path) -> str:
+    relative = file_path.relative_to(project_root)
+    parts = relative.with_suffix("").parts
+    if parts[-1] == "__init__":
+        parts = parts[:-1]
+    return ".".join(parts)
+
+
+def _package_module(file_path: Path, project_root: Path) -> str:
+    """Return the package (directory) module path for a file.
+
+    For ``contexts/boards/domain/models.py`` this returns
+    ``contexts.boards.domain``, which is the module name to use when
+    matching against rule patterns like ``contexts.*.domain``.
+    """
+    relative = file_path.relative_to(project_root)
+    parts = relative.with_suffix("").parts
+    if parts[-1] != "__init__":
+        parts = parts[:-1]
+    else:
+        parts = parts[:-1]
+    return ".".join(parts)
+
+
+def _find_python_files(project_root: Path) -> list[Path]:
+    return sorted(project_root.rglob("*.py"))
+
+
+@click.group()
+def main():
+    pass
+
+
+@main.command()
+@click.option(
+    "--config",
+    "config_path",
+    default=".python-dependency-linter.yaml",
+    help="Path to config file.",
+)
+@click.option("--project-root", default=".", help="Project root directory.")
+def check(config_path: str, project_root: str):
+    root = Path(project_root).resolve()
+    config_file = Path(config_path)
+
+    try:
+        config = load_config(config_file)
+    except FileNotFoundError as e:
+        click.echo(f"Error: {e}", err=True)
+        raise SystemExit(1)
+
+    all_violations = []
+    python_files = _find_python_files(root)
+
+    for file_path in python_files:
+        module = _file_to_module(file_path, root)
+        package = _package_module(file_path, root)
+        matching_rules = find_matching_rules(package, config.rules)
+        if not matching_rules:
+            continue
+
+        merged_rule = merge_rules(matching_rules)
+        imports = parse_imports(file_path)
+
+        file_violations = []
+        for imp in imports:
+            category = resolve_import(imp.module, root)
+            violation = check_import(imp, category, merged_rule, module)
+            if violation is not None:
+                file_violations.append(violation)
+
+        if file_violations:
+            rel_path = str(file_path.relative_to(root))
+            output = format_violations(rel_path, file_violations)
+            click.echo(output)
+            all_violations.extend(file_violations)
+
+    if all_violations:
+        click.echo(f"Found {len(all_violations)} violation(s).")
+        raise SystemExit(1)
+    else:
+        click.echo("No violations found.")

python_dependency_linter/config.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import yaml
+
+
+@dataclass
+class AllowDeny:
+    standard_library: list[str] | None = None
+    third_party: list[str] | None = None
+    local: list[str] | None = None
+
+
+@dataclass
+class Rule:
+    name: str
+    modules: str
+    allow: AllowDeny | None = None
+    deny: AllowDeny | None = None
+
+
+@dataclass
+class Config:
+    rules: list[Rule]
+
+
+def _parse_allow_deny(data: dict | None) -> AllowDeny | None:
+    if data is None:
+        return None
+    return AllowDeny(
+        standard_library=data.get("standard_library"),
+        third_party=data.get("third_party"),
+        local=data.get("local"),
+    )
+
+
+def _parse_rules(rules_data: list[dict]) -> list[Rule]:
+    rules = []
+    for r in rules_data:
+        rules.append(
+            Rule(
+                name=r["name"],
+                modules=r["modules"],
+                allow=_parse_allow_deny(r.get("allow")),
+                deny=_parse_allow_deny(r.get("deny")),
+            )
+        )
+    return rules
+
+
+def _load_yaml(path: Path) -> Config:
+    with open(path) as f:
+        data = yaml.safe_load(f)
+    return Config(rules=_parse_rules(data["rules"]))
+
+
+def _load_pyproject_toml(path: Path) -> Config:
+    try:
+        import tomllib
+    except ImportError:
+        import tomli as tomllib  # type: ignore[no-redef]
+
+    with open(path, "rb") as f:
+        data = tomllib.load(f)
+    tool_config = data["tool"]["python-dependency-linter"]
+    return Config(rules=_parse_rules(tool_config["rules"]))
+
+
+def load_config(path: Path) -> Config:
+    if not path.exists():
+        raise FileNotFoundError(f"Config file not found: {path}")
+    if path.suffix == ".toml":
+        return _load_pyproject_toml(path)
+    return _load_yaml(path)

python_dependency_linter/matcher.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from python_dependency_linter.config import AllowDeny, Rule
+
+
+def matches_pattern(pattern: str, module: str) -> bool:
+    pattern_parts = pattern.split(".")
+    module_parts = module.split(".")
+
+    if len(pattern_parts) != len(module_parts):
+        return False
+
+    for p, m in zip(pattern_parts, module_parts):
+        if p == "*":
+            continue
+        if p != m:
+            return False
+
+    return True
+
+
+def find_matching_rules(module: str, rules: list[Rule]) -> list[Rule]:
+    return [r for r in rules if matches_pattern(r.modules, module)]
+
+
+def _merge_allow_deny(
+    base: AllowDeny | None, override: AllowDeny | None
+) -> AllowDeny | None:
+    if base is None and override is None:
+        return None
+    if base is None:
+        return override
+    if override is None:
+        return base
+
+    def _merge_lists(a: list[str] | None, b: list[str] | None) -> list[str] | None:
+        if a is None and b is None:
+            return None
+        if a is None:
+            return b
+        if b is None:
+            return a
+        return list(set(a + b))
+
+    return AllowDeny(
+        standard_library=_merge_lists(base.standard_library, override.standard_library),
+        third_party=_merge_lists(base.third_party, override.third_party),
+        local=_merge_lists(base.local, override.local),
+    )
+
+
+def merge_rules(rules: list[Rule]) -> Rule:
+    merged = rules[0]
+    for rule in rules[1:]:
+        merged = Rule(
+            name=merged.name,
+            modules=merged.modules,
+            allow=_merge_allow_deny(merged.allow, rule.allow),
+            deny=_merge_allow_deny(merged.deny, rule.deny),
+        )
+    return merged

python_dependency_linter/parser.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class ImportInfo:
+    module: str
+    lineno: int
+
+
+def parse_imports(file_path: Path) -> list[ImportInfo]:
+    source = file_path.read_text()
+    tree = ast.parse(source, filename=str(file_path))
+
+    imports = []
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                imports.append(ImportInfo(module=alias.name, lineno=node.lineno))
+        elif isinstance(node, ast.ImportFrom):
+            if node.module is not None:
+                imports.append(ImportInfo(module=node.module, lineno=node.lineno))
+
+    return imports

python_dependency_linter/reporter.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from python_dependency_linter.checker import Violation
+
+
+def format_violations(file_path: str, violations: list[Violation]) -> str:
+    if not violations:
+        return ""
+
+    lines = []
+    for v in violations:
+        lines.append(f"{file_path}:{v.lineno}")
+        arrow = f"{v.source_module} \u2192 {v.imported_module}"
+        lines.append(f"    [{v.rule_name}] {arrow} ({v.category.value})")
+        lines.append("")
+
+    return "\n".join(lines)

python_dependency_linter/resolver.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import sys
+from enum import Enum
+from pathlib import Path
+
+
+class ImportCategory(Enum):
+    STANDARD_LIBRARY = "standard_library"
+    THIRD_PARTY = "third_party"
+    LOCAL = "local"
+
+
+def resolve_import(module: str, project_root: Path) -> ImportCategory:
+    top_level = module.split(".")[0]
+
+    if top_level in sys.stdlib_module_names:
+        return ImportCategory.STANDARD_LIBRARY
+
+    # Check if it exists as a local module/package
+    if (project_root / top_level).is_dir() or (
+        project_root / f"{top_level}.py"
+    ).is_file():
+        return ImportCategory.LOCAL
+
+    return ImportCategory.THIRD_PARTY

python_dependency_linter-0.1.0.dist-info/METADATA

@@ -0,0 +1,200 @@
+Metadata-Version: 2.4
+Name: python-dependency-linter
+Version: 0.1.0
+Summary: A dependency linter for Python projects
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: pre-commit>=3.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# python-dependency-linter
+
+A dependency linter for Python projects. Define rules for which modules can depend on what, and catch violations.
+
+## Installation
+
+```bash
+pip install python-dependency-linter
+```
+
+Or with uv:
+
+```bash
+uv add python-dependency-linter
+```
+
+## Quick Start
+
+Create `.python-dependency-linter.yaml` in your project root:
+
+```yaml
+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:
+
+```bash
+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
+
+```yaml
+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:
+
+```yaml
+allow:
+  standard_library: ["*"]  # allow all standard library imports
+```
+
+### Wildcard
+
+`*` matches a single level in dotted module paths:
+
+```yaml
+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:
+
+```yaml
+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`:
+
+```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
+
+```bash
+# 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`:
+
+```yaml
+- repo: https://github.com/heumsi/python-dependency-linter
+  rev: v0.1.0
+  hooks:
+    - id: python-dependency-linter
+```
+
+## License
+
+MIT

python_dependency_linter-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+python_dependency_linter/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+python_dependency_linter/checker.py,sha256=haKQTsuhWJ7UQ72vB48WQD-xgwWwan5JUtoyrd0v2zk,2905
+python_dependency_linter/cli.py,sha256=N36yqK-rIRM2U6Wpe1yJuPvH5vrxZLmdKpeN1vVAU7E,2994
+python_dependency_linter/config.py,sha256=OModCwXwyC_fekgommY0IqjjfdEw7R6y-tRTMl6Bn1g,1794
+python_dependency_linter/matcher.py,sha256=i__SuJ-KXoTb-tEtGW4F2d7Vmz2MSxls4eGBqolqQ0A,1696
+python_dependency_linter/parser.py,sha256=5rHlogeT_BmuMfVjvCSDEl-z4peIYKEbc0ArEA1CIxA,729
+python_dependency_linter/reporter.py,sha256=5sB1GVa601QW6xo5tc8_SdrRFfaAXvZ8ErbX708ej_A,490
+python_dependency_linter/resolver.py,sha256=Upw8jgfhbk0A6PR36HcLfw3Q0Ao_qB2cYr4utwBht1g,654
+python_dependency_linter-0.1.0.dist-info/METADATA,sha256=CPvtMPJlXHXJNKcu-1MvM4OvT0e1SbabO7_ZjVzXgYw,4630
+python_dependency_linter-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+python_dependency_linter-0.1.0.dist-info/entry_points.txt,sha256=hBvZb-KbMnX7kylKQCUtJSYdunKRht18t5PH1GnRQKU,58
+python_dependency_linter-0.1.0.dist-info/licenses/LICENSE,sha256=6jnaAo6a4d5VHjYOiCeh2k2tlMKfCXI4itz82GNbuMs,1063
+python_dependency_linter-0.1.0.dist-info/RECORD,,

python_dependency_linter-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

python_dependency_linter-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pdl = python_dependency_linter.cli:main

python_dependency_linter-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 heumsi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.