archunitpython 1.1.2__tar.gz → 1.2.0__tar.gz

archunitpython-1.2.0/.github/FUNDING.yml

@@ -0,0 +1 @@
+github: [LukasNiessen]

{archunitpython-1.1.2 → archunitpython-1.2.0}/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [1.2.0](https://github.com/LukasNiessen/ArchUnitPython/compare/v1.1.2...v1.2.0) (2026-06-27)
+
+
+### Features
+
+* add graph reporting and sponsorship links ([6d5eabc](https://github.com/LukasNiessen/ArchUnitPython/commit/6d5eabc1c1395c5bb4cf18e222ac472d33c02eb4))
+
 ## [1.1.2](https://github.com/LukasNiessen/ArchUnitPython/compare/v1.1.1...v1.1.2) (2026-06-23)
 
 

{archunitpython-1.1.2 → archunitpython-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: archunitpython
-Version: 1.1.2
+Version: 1.2.0
 Summary: Architecture testing library for Python projects. Enforce dependency rules, detect cycles, validate metrics.
 Project-URL: Homepage, https://github.com/LukasNiessen/ArchUnitPython
 Project-URL: Repository, https://github.com/LukasNiessen/ArchUnitPython.git
@@ -41,16 +41,19 @@ Description-Content-Type: text/markdown
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![PyPI version](https://img.shields.io/pypi/v/archunitpython.svg)](https://pypi.org/project/archunitpython/)
-[![Python versions](https://img.shields.io/pypi/pyversions/archunitpython.svg)](https://pypi.org/project/archunitpython/)
+[![Downloads](https://static.pepy.tech/badge/archunitpython)](https://pepy.tech/project/archunitpython)
+[![Monthly downloads](https://static.pepy.tech/badge/archunitpython/month)](https://pepy.tech/project/archunitpython)
 [![GitHub stars](https://img.shields.io/github/stars/LukasNiessen/ArchUnitPython.svg)](https://github.com/LukasNiessen/ArchUnitPython)
 
 </div>
 
 Enforce architecture rules in Python projects. Check for dependency directions, detect circular dependencies, enforce coding standards and much more. Integrates with pytest and any other testing framework. Very simple setup and pipeline integration. Zero runtime dependencies.
 
+The #1 ArchUnit-style architecture testing library for Python, measured by GitHub stars.
+
 _Inspired by the amazing ArchUnit library but we are not affiliated with ArchUnit._
 
-[Setup](#-setup) • [Use Cases](#-use-cases) • [Features](#-features) • [Contributing](CONTRIBUTING.md)
+[Setup](#-setup) • [Use Cases](#-use-cases) • [Features](#-features) • [Why ArchUnitPython?](#-library-comparison) • [Contributing](CONTRIBUTING.md)
 
 ## ⚡ 5 min Quickstart
 
@@ -121,6 +124,22 @@ These tests run automatically in your testing setup, for example in your CI pipe
   run: pytest tests/test_architecture.py -v
 ```
 
+You can also export dependency graph reports as CI artifacts:
+
+```python
+from archunitpython import project_graph
+
+def test_generate_dependency_graph_reports():
+    graph = project_graph("src/").titled("Application Architecture")
+
+    graph.collapse_to_folder_depth(2).export_as_html(
+        "reports/dependency-graph.html"
+    )
+    graph.export_as_mermaid("reports/dependency-graph.mmd")
+
+    assert graph.snapshot().summary.node_count >= 0
+```
+
 ## 🚐 Setup
 
 Installation:
@@ -165,6 +184,7 @@ from archunitpython import CheckOptions
 options = CheckOptions(
     allow_empty_tests=True,  # Don't fail when no files match
     clear_cache=True,        # Clear the graph cache
+    ignore_type_checking_imports=True,  # Ignore imports inside if TYPE_CHECKING
 )
 
 violations = rule.check(options)
@@ -228,6 +248,65 @@ def test_business_not_depend_on_presentation():
     assert_passes(rule)
 ```
 
+### Named Layer Rules
+
+```python
+from archunitpython import project_layers
+
+def test_clean_architecture_layers():
+    rule = (
+        project_layers("src/")
+        .layer("presentation").defined_by_folder("**/presentation/**")
+        .layer("business").defined_by_folder("**/business/**")
+        .layer("database").defined_by_folder("**/database/**")
+        .where_layer("presentation")
+        .may_only_depend_on_layers("business")
+        .where_layer("business")
+        .may_only_depend_on_layers()
+        .where_layer("database")
+        .may_only_depend_on_layers()
+    )
+    assert_passes(rule)
+```
+
+### External Dependencies
+
+```python
+def test_domain_does_not_import_requests():
+    rule = (
+        project_files("src/")
+        .in_folder("**/domain/**")
+        .should_not()
+        .depend_on_external_modules()
+        .matching("requests")
+    )
+    assert_passes(rule)
+```
+
+### TYPE_CHECKING-aware Analysis
+
+```python
+from archunitpython import CheckOptions
+
+def test_type_only_dependencies_do_not_count_as_runtime_coupling():
+    rule = (
+        project_files("src/")
+        .in_folder("**/api/**")
+        .should_not()
+        .depend_on_files()
+        .in_folder("**/infrastructure/**")
+    )
+    assert_passes(rule, CheckOptions(ignore_type_checking_imports=True))
+```
+
+### Dynamic Imports and Ignore Directives
+
+ArchUnitPython detects string-based dynamic imports such as `importlib.import_module("my_app.adapters.sql")` and `__import__("my_app.adapters.sql")`. For known migration shims, you can suppress one import edge locally:
+
+```python
+from my_app.adapters.sql import Repository  # archunit: ignore
+```
+
 ### Naming Conventions
 
 ```python
@@ -350,6 +429,48 @@ def test_no_forbidden_dependency():
     assert_passes(rule)
 ```
 
+### Dependency Graph Reports
+
+Generate dependency graph reports in multiple formats and narrow them to the part of the codebase you want to inspect.
+
+```python
+from archunitpython import project_graph
+
+def test_export_dependency_graph_reports():
+    graph = project_graph("src/").titled("Application Architecture")
+
+    graph.collapse_to_folder_depth(2).export_as_mermaid(
+        "reports/dependencies.mmd"
+    )
+
+    graph.focus_on("**/domain/**", 1).export_as_html(
+        "reports/domain-dependencies.html"
+    )
+
+    assert graph.snapshot().summary.node_count >= 0
+```
+
+Supported formats:
+
+- DOT (`export_as_dot`, `to_dot`)
+- Mermaid (`export_as_mermaid`, `to_mermaid`)
+- D2 (`export_as_d2`, `to_d2`)
+- CSV (`export_as_csv`, `to_csv`)
+- JSON (`export_as_json`, `to_json`)
+- HTML (`export_as_html`, `to_html`)
+
+Graph exploration options:
+
+- `focus_on(pattern, depth)` keeps matching files and their neighbors.
+- `reachable_from(pattern)` keeps matching files and their transitive dependencies.
+- `dependents_of(pattern)` keeps files that transitively depend on the matching files.
+- `collapse_to_folder_depth(depth)` aggregates files to folder-level graph nodes.
+- `collapse_by_pattern(pattern, replacement)` maps files to custom graph nodes.
+- `include_external_dependencies()` includes imports to external modules such as `requests` or `sqlalchemy`.
+- `include_self_dependencies()` keeps self edges that are normally hidden in reports.
+
+When you create reports through `project_graph("src/")`, internal file paths are displayed relative to that project root so the output stays readable.
+
 ### Reports
 
 Generate HTML reports for your metrics. _Note that this feature is in beta._
@@ -529,6 +650,40 @@ def test_from_file():
     assert_passes(rule)
 ```
 
+## 📊 Library Comparison
+
+Here's how ArchUnitPython compares to other Python architecture-enforcement libraries.
+
+ArchUnitPython is optimized for **architecture rules as tests**: rules live next to your normal unit tests, run in pytest/unittest/CI, and fail with test-style violation messages. Broader CLI-first tools such as [Tach](https://github.com/tach-org/tach) and [Import Linter](https://github.com/seddonym/import-linter) are excellent adjacent tools, but they solve the problem through separate configuration and commands rather than a test-native ArchUnit-style API.
+
+| Feature | **ArchUnitPython** | **Tach** | **Import Linter** | **PyTestArch** |
+| ------- | ------------------ | -------- | ----------------- | -------------- |
+| **Primary workflow** | ✅ Architecture rules as unit tests | ⚠️ CLI + `tach.toml` | ⚠️ CLI + contracts config | ⚠️ pytest-oriented evaluable architecture |
+| **ArchUnit-style fluent API** | ✅ Yes | ❌ No | ❌ No | ⚠️ Partial |
+| **Testing framework integration** | ✅ pytest, unittest, any runner | ⚠️ CI/pre-commit CLI | ⚠️ CI/pre-commit CLI | ⚠️ pytest-focused |
+| **Zero runtime dependencies** | ✅ Standard library only | ⚠️ No app runtime impact, Rust-backed tool | ❌ Tool dependencies | ❌ Tool dependencies |
+| **Circular dependency detection** | ✅ First-class | ✅ First-class | ⚠️ Contract/graph based | ⚠️ Import-rule based |
+| **File/folder dependency rules** | ✅ Glob + regex | ✅ Module config | ✅ Import contracts | ✅ Module rules |
+| **Named layer rules** | ✅ `project_layers()` | ✅ Supported | ✅ Supported | ✅ Supported |
+| **External dependency rules** | ✅ `depend_on_external_modules()` | ⚠️ Internal module focus | ⚠️ Import contract focus | ⚠️ Internal import focus |
+| **TYPE_CHECKING-aware analysis** | ✅ Configurable | ⚠️ Not the core API | ⚠️ Not the core API | ⚠️ Not the core API |
+| **Dynamic import detection** | ✅ `importlib` + `__import__` string calls | ⚠️ Not the core workflow | ⚠️ Not the core workflow | ⚠️ Import analysis focused |
+| **Inline ignore directives** | ✅ `# archunit: ignore` | ✅ Supported | ⚠️ Config-based ignores | ⚠️ Rule/exclusion based |
+| **Naming convention checks** | ✅ Files and paths | ❌ No | ❌ No | ⚠️ Module-name oriented |
+| **Code metrics** | ✅ Counts, LCOM, distance metrics | ❌ No | ❌ No | ❌ No |
+| **Custom rules and metrics** | ✅ Full support | ❌ No | ⚠️ Custom contracts | ⚠️ Limited custom rule composition |
+| **PlantUML diagram validation** | ✅ Supported | ❌ No | ❌ No | ❌ No |
+| **Empty test protection** | ✅ Fails by default | ⚠️ Config validation | ⚠️ Contract validation | ⚠️ Not the main focus |
+| **Graph/reporting** | ✅ DOT, Mermaid, D2, CSV, JSON, HTML graph reports + metrics HTML | ✅ DOT, JSON, web graph | ✅ Browser UI | ⚠️ Optional graph visualization |
+| **Best fit** | Architecture tests, CI fitness functions, metrics, diagrams | Modular monolith dependency governance | Config-driven import contracts | pytest import-boundary checks |
+
+The most important differences:
+
+- **Test-native by design**: ArchUnitPython rules are just Python tests, so architecture decisions are reviewed, run, and debugged in the same workflow as the rest of your test suite.
+- **Broader rule surface**: dependency direction, cycles, layer policies, external modules, type-only imports, dynamic imports, naming, metrics, custom rules, and PlantUML validation live in one API.
+- **False-positive protection**: empty checks fail by default, which helps catch typos in file and folder patterns before they silently make your architecture tests meaningless.
+- **Quality beyond imports**: ArchUnitPython can enforce code metrics such as LCOM cohesion, field/method counts, abstractness, instability, and distance from the main sequence.
+
 ## 📢 Informative Error Messages
 
 When tests fail, you get helpful output with file paths and violation details:
@@ -590,6 +745,7 @@ The features of ArchUnitPython can very well be used as architectural fitness fu
 | **Files**   | File and folder based rules    | Stable       |
 | **Metrics** | Code quality metrics           | Stable       |
 | **Slices**  | Architecture slicing           | Stable       |
+| **Graph**   | Dependency graph reports       | Experimental |
 | **Testing** | Test framework integration     | Stable       |
 | **Common**  | Shared utilities               | Stable       |
 | **Reports** | Generate HTML reports          | Experimental |
@@ -659,6 +815,7 @@ Found a bug? Want to discuss features?
 If ArchUnitPython helps your project, please consider:
 
 - Starring the repository 💚
+- Sponsoring development via [GitHub Sponsors](https://github.com/sponsors/LukasNiessen)
 - Suggesting new features 💭
 - Contributing code or documentation ⌨️
 

{archunitpython-1.1.2 → archunitpython-1.2.0}/README.md

@@ -8,16 +8,19 @@
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![PyPI version](https://img.shields.io/pypi/v/archunitpython.svg)](https://pypi.org/project/archunitpython/)
-[![Python versions](https://img.shields.io/pypi/pyversions/archunitpython.svg)](https://pypi.org/project/archunitpython/)
+[![Downloads](https://static.pepy.tech/badge/archunitpython)](https://pepy.tech/project/archunitpython)
+[![Monthly downloads](https://static.pepy.tech/badge/archunitpython/month)](https://pepy.tech/project/archunitpython)
 [![GitHub stars](https://img.shields.io/github/stars/LukasNiessen/ArchUnitPython.svg)](https://github.com/LukasNiessen/ArchUnitPython)
 
 </div>
 
 Enforce architecture rules in Python projects. Check for dependency directions, detect circular dependencies, enforce coding standards and much more. Integrates with pytest and any other testing framework. Very simple setup and pipeline integration. Zero runtime dependencies.
 
+The #1 ArchUnit-style architecture testing library for Python, measured by GitHub stars.
+
 _Inspired by the amazing ArchUnit library but we are not affiliated with ArchUnit._
 
-[Setup](#-setup) • [Use Cases](#-use-cases) • [Features](#-features) • [Contributing](CONTRIBUTING.md)
+[Setup](#-setup) • [Use Cases](#-use-cases) • [Features](#-features) • [Why ArchUnitPython?](#-library-comparison) • [Contributing](CONTRIBUTING.md)
 
 ## ⚡ 5 min Quickstart
 
@@ -88,6 +91,22 @@ These tests run automatically in your testing setup, for example in your CI pipe
   run: pytest tests/test_architecture.py -v
 ```
 
+You can also export dependency graph reports as CI artifacts:
+
+```python
+from archunitpython import project_graph
+
+def test_generate_dependency_graph_reports():
+    graph = project_graph("src/").titled("Application Architecture")
+
+    graph.collapse_to_folder_depth(2).export_as_html(
+        "reports/dependency-graph.html"
+    )
+    graph.export_as_mermaid("reports/dependency-graph.mmd")
+
+    assert graph.snapshot().summary.node_count >= 0
+```
+
 ## 🚐 Setup
 
 Installation:
@@ -132,6 +151,7 @@ from archunitpython import CheckOptions
 options = CheckOptions(
     allow_empty_tests=True,  # Don't fail when no files match
     clear_cache=True,        # Clear the graph cache
+    ignore_type_checking_imports=True,  # Ignore imports inside if TYPE_CHECKING
 )
 
 violations = rule.check(options)
@@ -195,6 +215,65 @@ def test_business_not_depend_on_presentation():
     assert_passes(rule)
 ```
 
+### Named Layer Rules
+
+```python
+from archunitpython import project_layers
+
+def test_clean_architecture_layers():
+    rule = (
+        project_layers("src/")
+        .layer("presentation").defined_by_folder("**/presentation/**")
+        .layer("business").defined_by_folder("**/business/**")
+        .layer("database").defined_by_folder("**/database/**")
+        .where_layer("presentation")
+        .may_only_depend_on_layers("business")
+        .where_layer("business")
+        .may_only_depend_on_layers()
+        .where_layer("database")
+        .may_only_depend_on_layers()
+    )
+    assert_passes(rule)
+```
+
+### External Dependencies
+
+```python
+def test_domain_does_not_import_requests():
+    rule = (
+        project_files("src/")
+        .in_folder("**/domain/**")
+        .should_not()
+        .depend_on_external_modules()
+        .matching("requests")
+    )
+    assert_passes(rule)
+```
+
+### TYPE_CHECKING-aware Analysis
+
+```python
+from archunitpython import CheckOptions
+
+def test_type_only_dependencies_do_not_count_as_runtime_coupling():
+    rule = (
+        project_files("src/")
+        .in_folder("**/api/**")
+        .should_not()
+        .depend_on_files()
+        .in_folder("**/infrastructure/**")
+    )
+    assert_passes(rule, CheckOptions(ignore_type_checking_imports=True))
+```
+
+### Dynamic Imports and Ignore Directives
+
+ArchUnitPython detects string-based dynamic imports such as `importlib.import_module("my_app.adapters.sql")` and `__import__("my_app.adapters.sql")`. For known migration shims, you can suppress one import edge locally:
+
+```python
+from my_app.adapters.sql import Repository  # archunit: ignore
+```
+
 ### Naming Conventions
 
 ```python
@@ -317,6 +396,48 @@ def test_no_forbidden_dependency():
     assert_passes(rule)
 ```
 
+### Dependency Graph Reports
+
+Generate dependency graph reports in multiple formats and narrow them to the part of the codebase you want to inspect.
+
+```python
+from archunitpython import project_graph
+
+def test_export_dependency_graph_reports():
+    graph = project_graph("src/").titled("Application Architecture")
+
+    graph.collapse_to_folder_depth(2).export_as_mermaid(
+        "reports/dependencies.mmd"
+    )
+
+    graph.focus_on("**/domain/**", 1).export_as_html(
+        "reports/domain-dependencies.html"
+    )
+
+    assert graph.snapshot().summary.node_count >= 0
+```
+
+Supported formats:
+
+- DOT (`export_as_dot`, `to_dot`)
+- Mermaid (`export_as_mermaid`, `to_mermaid`)
+- D2 (`export_as_d2`, `to_d2`)
+- CSV (`export_as_csv`, `to_csv`)
+- JSON (`export_as_json`, `to_json`)
+- HTML (`export_as_html`, `to_html`)
+
+Graph exploration options:
+
+- `focus_on(pattern, depth)` keeps matching files and their neighbors.
+- `reachable_from(pattern)` keeps matching files and their transitive dependencies.
+- `dependents_of(pattern)` keeps files that transitively depend on the matching files.
+- `collapse_to_folder_depth(depth)` aggregates files to folder-level graph nodes.
+- `collapse_by_pattern(pattern, replacement)` maps files to custom graph nodes.
+- `include_external_dependencies()` includes imports to external modules such as `requests` or `sqlalchemy`.
+- `include_self_dependencies()` keeps self edges that are normally hidden in reports.
+
+When you create reports through `project_graph("src/")`, internal file paths are displayed relative to that project root so the output stays readable.
+
 ### Reports
 
 Generate HTML reports for your metrics. _Note that this feature is in beta._
@@ -496,6 +617,40 @@ def test_from_file():
     assert_passes(rule)
 ```
 
+## 📊 Library Comparison
+
+Here's how ArchUnitPython compares to other Python architecture-enforcement libraries.
+
+ArchUnitPython is optimized for **architecture rules as tests**: rules live next to your normal unit tests, run in pytest/unittest/CI, and fail with test-style violation messages. Broader CLI-first tools such as [Tach](https://github.com/tach-org/tach) and [Import Linter](https://github.com/seddonym/import-linter) are excellent adjacent tools, but they solve the problem through separate configuration and commands rather than a test-native ArchUnit-style API.
+
+| Feature | **ArchUnitPython** | **Tach** | **Import Linter** | **PyTestArch** |
+| ------- | ------------------ | -------- | ----------------- | -------------- |
+| **Primary workflow** | ✅ Architecture rules as unit tests | ⚠️ CLI + `tach.toml` | ⚠️ CLI + contracts config | ⚠️ pytest-oriented evaluable architecture |
+| **ArchUnit-style fluent API** | ✅ Yes | ❌ No | ❌ No | ⚠️ Partial |
+| **Testing framework integration** | ✅ pytest, unittest, any runner | ⚠️ CI/pre-commit CLI | ⚠️ CI/pre-commit CLI | ⚠️ pytest-focused |
+| **Zero runtime dependencies** | ✅ Standard library only | ⚠️ No app runtime impact, Rust-backed tool | ❌ Tool dependencies | ❌ Tool dependencies |
+| **Circular dependency detection** | ✅ First-class | ✅ First-class | ⚠️ Contract/graph based | ⚠️ Import-rule based |
+| **File/folder dependency rules** | ✅ Glob + regex | ✅ Module config | ✅ Import contracts | ✅ Module rules |
+| **Named layer rules** | ✅ `project_layers()` | ✅ Supported | ✅ Supported | ✅ Supported |
+| **External dependency rules** | ✅ `depend_on_external_modules()` | ⚠️ Internal module focus | ⚠️ Import contract focus | ⚠️ Internal import focus |
+| **TYPE_CHECKING-aware analysis** | ✅ Configurable | ⚠️ Not the core API | ⚠️ Not the core API | ⚠️ Not the core API |
+| **Dynamic import detection** | ✅ `importlib` + `__import__` string calls | ⚠️ Not the core workflow | ⚠️ Not the core workflow | ⚠️ Import analysis focused |
+| **Inline ignore directives** | ✅ `# archunit: ignore` | ✅ Supported | ⚠️ Config-based ignores | ⚠️ Rule/exclusion based |
+| **Naming convention checks** | ✅ Files and paths | ❌ No | ❌ No | ⚠️ Module-name oriented |
+| **Code metrics** | ✅ Counts, LCOM, distance metrics | ❌ No | ❌ No | ❌ No |
+| **Custom rules and metrics** | ✅ Full support | ❌ No | ⚠️ Custom contracts | ⚠️ Limited custom rule composition |
+| **PlantUML diagram validation** | ✅ Supported | ❌ No | ❌ No | ❌ No |
+| **Empty test protection** | ✅ Fails by default | ⚠️ Config validation | ⚠️ Contract validation | ⚠️ Not the main focus |
+| **Graph/reporting** | ✅ DOT, Mermaid, D2, CSV, JSON, HTML graph reports + metrics HTML | ✅ DOT, JSON, web graph | ✅ Browser UI | ⚠️ Optional graph visualization |
+| **Best fit** | Architecture tests, CI fitness functions, metrics, diagrams | Modular monolith dependency governance | Config-driven import contracts | pytest import-boundary checks |
+
+The most important differences:
+
+- **Test-native by design**: ArchUnitPython rules are just Python tests, so architecture decisions are reviewed, run, and debugged in the same workflow as the rest of your test suite.
+- **Broader rule surface**: dependency direction, cycles, layer policies, external modules, type-only imports, dynamic imports, naming, metrics, custom rules, and PlantUML validation live in one API.
+- **False-positive protection**: empty checks fail by default, which helps catch typos in file and folder patterns before they silently make your architecture tests meaningless.
+- **Quality beyond imports**: ArchUnitPython can enforce code metrics such as LCOM cohesion, field/method counts, abstractness, instability, and distance from the main sequence.
+
 ## 📢 Informative Error Messages
 
 When tests fail, you get helpful output with file paths and violation details:
@@ -557,6 +712,7 @@ The features of ArchUnitPython can very well be used as architectural fitness fu
 | **Files**   | File and folder based rules    | Stable       |
 | **Metrics** | Code quality metrics           | Stable       |
 | **Slices**  | Architecture slicing           | Stable       |
+| **Graph**   | Dependency graph reports       | Experimental |
 | **Testing** | Test framework integration     | Stable       |
 | **Common**  | Shared utilities               | Stable       |
 | **Reports** | Generate HTML reports          | Experimental |
@@ -626,6 +782,7 @@ Found a bug? Want to discuss features?
 If ArchUnitPython helps your project, please consider:
 
 - Starring the repository 💚
+- Sponsoring development via [GitHub Sponsors](https://github.com/sponsors/LukasNiessen)
 - Suggesting new features 💭
 - Contributing code or documentation ⌨️
 

{archunitpython-1.1.2 → archunitpython-1.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "archunitpython"
-version = "1.1.2"
+version = "1.2.0"
 description = "Architecture testing library for Python projects. Enforce dependency rules, detect cycles, validate metrics."
 readme = "README.md"
 license = "MIT"

{archunitpython-1.1.2 → archunitpython-1.2.0}/src/archunitpython/__init__.py

@@ -1,6 +1,6 @@
 """ArchUnitPython - Architecture testing library for Python projects."""
 
-__version__ = "1.1.2"
+__version__ = "1.2.0"
 
 # Files API
 # Common
@@ -13,6 +13,8 @@ from archunitpython.common import (
 )
 from archunitpython.common.extraction import clear_graph_cache, extract_graph
 from archunitpython.files import files, project_files
+from archunitpython.graph import dependency_graph, project_graph
+from archunitpython.layers import layers, project_layers
 
 # Metrics API
 from archunitpython.metrics import metrics
@@ -27,6 +29,12 @@ __all__ = [
     # Files
     "project_files",
     "files",
+    # Graph
+    "project_graph",
+    "dependency_graph",
+    # Layers
+    "project_layers",
+    "layers",
     # Slices
     "project_slices",
     # Metrics

{archunitpython-1.1.2 → archunitpython-1.2.0}/src/archunitpython/common/extraction/extract_graph.py

@@ -4,6 +4,8 @@ from __future__ import annotations
 
 import ast
 import os
+import re
+from dataclasses import dataclass
 
 from archunitpython.common.extraction.graph import Edge, Graph, ImportKind
 from archunitpython.common.fluentapi.checkable import CheckOptions
@@ -27,6 +29,34 @@ _DEFAULT_EXCLUDE = [
     "*.egg-info",
 ]
 
+_IGNORE_DIRECTIVE_REGEX = re.compile(
+    r"#\s*archunit(?::|-)\s*ignore"
+    r"(?:\([^)]*\))?"
+    r"(?P<modules>(?:\s+[\w.]+)*)\s*$"
+)
+
+
+@dataclass(frozen=True)
+class _LocatedImport:
+    module_name: str
+    import_kind: ImportKind
+    line_number: int
+
+
+@dataclass(frozen=True)
+class _IgnoreDirective:
+    line_number: int
+    modules: tuple[str, ...] = ()
+
+    def matches(self, import_: _LocatedImport) -> bool:
+        if not self.modules:
+            return True
+        return any(
+            import_.module_name == module
+            or import_.module_name.startswith(f"{module}.")
+            for module in self.modules
+        )
+
 
 def clear_graph_cache(options: CheckOptions | None = None) -> None:
     """Clear the cached dependency graphs."""
@@ -119,8 +149,10 @@ def _extract_graph_uncached(
         )
 
         # Extract and resolve imports
-        imports = _extract_imports(file_path)
-        for module_name, import_kind in imports:
+        imports = _extract_located_imports(file_path)
+        for located_import in imports:
+            module_name = located_import.module_name
+            import_kind = located_import.import_kind
             if (
                 ignore_type_checking_imports
                 and import_kind == ImportKind.TYPE_IMPORT
@@ -187,6 +219,14 @@ def _extract_imports(file_path: str) -> list[tuple[str, ImportKind]]:
 
     Returns list of (module_name, import_kind) tuples.
     """
+    return [
+        (import_.module_name, import_.import_kind)
+        for import_ in _extract_located_imports(file_path)
+    ]
+
+
+def _extract_located_imports(file_path: str) -> list[_LocatedImport]:
+    """Parse a Python file and extract imports with line numbers."""
     try:
         with open(file_path, "r", encoding="utf-8", errors="replace") as f:
             source = f.read()
@@ -198,7 +238,8 @@ def _extract_imports(file_path: str) -> list[tuple[str, ImportKind]]:
     except SyntaxError:
         return []
 
-    imports: list[tuple[str, ImportKind]] = []
+    imports: list[_LocatedImport] = []
+    ignore_directives = _find_ignore_directives(source)
     type_checking_ranges = _find_type_checking_ranges(tree)
 
     for node in ast.walk(tree):
@@ -206,7 +247,7 @@ def _extract_imports(file_path: str) -> list[tuple[str, ImportKind]]:
             is_type = _in_type_checking(node, type_checking_ranges)
             kind = ImportKind.TYPE_IMPORT if is_type else ImportKind.IMPORT
             for alias in node.names:
-                imports.append((alias.name, kind))
+                imports.append(_LocatedImport(alias.name, kind, node.lineno))
 
         elif isinstance(node, ast.ImportFrom):
             is_type = _in_type_checking(node, type_checking_ranges)
@@ -215,13 +256,79 @@ def _extract_imports(file_path: str) -> list[tuple[str, ImportKind]]:
                 kind = ImportKind.TYPE_IMPORT if is_type else ImportKind.RELATIVE_IMPORT
                 module = node.module or ""
                 dots = "." * node.level
-                imports.append((f"{dots}{module}", kind))
+                imports.append(_LocatedImport(f"{dots}{module}", kind, node.lineno))
             else:
                 kind = ImportKind.TYPE_IMPORT if is_type else ImportKind.FROM_IMPORT
                 if node.module:
-                    imports.append((node.module, kind))
+                    imports.append(_LocatedImport(node.module, kind, node.lineno))
+
+        elif isinstance(node, ast.Call):
+            is_type = _in_type_checking(node, type_checking_ranges)
+            kind = ImportKind.TYPE_IMPORT if is_type else ImportKind.DYNAMIC_IMPORT
+            for module_name in _extract_dynamic_import_names(node):
+                imports.append(_LocatedImport(module_name, kind, node.lineno))
+
+    return [
+        import_
+        for import_ in imports
+        if not _is_ignored_import(import_, ignore_directives)
+    ]
+
+
+def _find_ignore_directives(source: str) -> dict[int, _IgnoreDirective]:
+    """Find architecture-ignore directives.
+
+    Supports inline directives on an import line and standalone directives that
+    apply to the following line, for example:
+
+    - from x import y  # archunit: ignore
+    - # archunit: ignore
+      from x import y
+    """
+    directives: dict[int, _IgnoreDirective] = {}
+    for index, line in enumerate(source.splitlines(), start=1):
+        match = _IGNORE_DIRECTIVE_REGEX.search(line)
+        if match is None:
+            continue
+
+        modules = tuple(match.group("modules").split())
+        target_line = index + 1 if line.strip().startswith("#") else index
+        directives[target_line] = _IgnoreDirective(target_line, modules)
+    return directives
+
+
+def _is_ignored_import(
+    import_: _LocatedImport,
+    directives: dict[int, _IgnoreDirective],
+) -> bool:
+    directive = directives.get(import_.line_number)
+    return directive is not None and directive.matches(import_)
+
+
+def _extract_dynamic_import_names(node: ast.Call) -> list[str]:
+    """Extract literal module names from common dynamic import calls."""
+    if not node.args:
+        return []
+
+    first_arg = node.args[0]
+    if not isinstance(first_arg, ast.Constant) or not isinstance(first_arg.value, str):
+        return []
 
-    return imports
+    if isinstance(node.func, ast.Name) and node.func.id in {
+        "__import__",
+        "import_module",
+    }:
+        return [first_arg.value]
+
+    if (
+        isinstance(node.func, ast.Attribute)
+        and node.func.attr == "import_module"
+        and isinstance(node.func.value, ast.Name)
+        and node.func.value.id == "importlib"
+    ):
+        return [first_arg.value]
+
+    return []
 
 
 def _find_type_checking_ranges(tree: ast.Module) -> list[tuple[int, int]]: