archunitpython 1.4.0__tar.gz → 1.6.0__tar.gz

{archunitpython-1.4.0 → archunitpython-1.6.0}/BACKLOG.md

@@ -13,14 +13,14 @@ This backlog collects product and maintenance ideas from project research.
 
 - [x] Add an `.archignore` or similar file, modeled after `.gitignore`, for files that should never be analyzed.
 - [x] Add a `.because(...)` API so rules can carry user-facing rationale into failure messages and generated architecture documentation.
-- Add configuration-file support for common rules, while keeping the fluent Python API as the primary interface.
+- [x] Add configuration-file support for common rules, while keeping the fluent Python API as the primary interface.
 - Add support for monorepo and multi-package Python projects.
 
 ## P1 - Python Import Semantics
 
 - Add support for namespace packages that do not contain `__init__.py`.
-- Detect dynamic imports such as `importlib.import_module()` and `__import__()`.
-- Detect conditional imports such as `try/except ImportError`.
+- [x] Detect dynamic imports such as `importlib.import_module()` and `__import__()`.
+- [x] Detect conditional imports such as `try/except ImportError`.
 - Add better `TYPE_CHECKING` import handling, including options to ignore, include, or report type-only imports separately.
 - Improve external dependency rules so users can express allowed and forbidden third-party packages at module or slice level.
 - Consider a public-interface rule inspired by Tach, where modules may only import through declared package APIs.
@@ -31,11 +31,11 @@ This backlog collects product and maintenance ideas from project research.
 - Auto-generate architecture documentation based on tests and rule rationales.
 - Make logged paths clickable in IDEs and common terminal integrations.
 - Add PlantUML or Mermaid export for discovered architecture graphs.
-- Improve metric export examples and document how metric thresholds should be selected.
+- [x] Improve metric export examples and document how metric thresholds should be selected.
 
 ## P2 - Rule Surface
 
-- Add first-class layered architecture helpers so common clean/hexagonal/layered rules require less boilerplate.
+- [x] Add first-class layered architecture helpers so common clean/hexagonal/layered rules require less boilerplate.
 - Add slice isolation helpers for bounded contexts and modular monoliths.
 - Add richer custom rule hooks for dependency edges, files, classes, and metrics.
 - Add transitive dependency checks, especially for "domain must not transitively reach infrastructure" style rules.
@@ -56,7 +56,7 @@ This backlog collects product and maintenance ideas from project research.
 
 ## P3 - Packaging And Docs
 
-- Publish to PyPI as part of the release pipeline if this is not already automated.
+- [x] Publish to PyPI as part of the release pipeline if this is not already automated.
 - Add a Sphinx or MkDocs documentation site.
 - Add a complete example repository or examples folder covering pytest, unittest, PlantUML, metrics, and CI.
 - Add contribution guidance for new rule types and metric implementations.

{archunitpython-1.4.0 → archunitpython-1.6.0}/CHANGELOG.md

@@ -1,3 +1,23 @@
+# [1.6.0](https://github.com/LukasNiessen/ArchUnitPython/compare/v1.5.0...v1.6.0) (2026-09-12)
+
+
+### Bug Fixes
+
+* preserve package targets for relative imports ([09c9d19](https://github.com/LukasNiessen/ArchUnitPython/commit/09c9d199dec095aaa60be227bfd7b5c2b7ffb107))
+* preserve relative conditional import targets ([0ae22bb](https://github.com/LukasNiessen/ArchUnitPython/commit/0ae22bbed008c39f39b80ac6428fa1207115a394))
+
+
+### Features
+
+* classify conditional imports ([5f0f600](https://github.com/LukasNiessen/ArchUnitPython/commit/5f0f600e02d82249e0735738b43cc75317eff790))
+
+# [1.5.0](https://github.com/LukasNiessen/ArchUnitPython/compare/v1.4.0...v1.5.0) (2026-07-18)
+
+
+### Features
+
+* load common rules from config ([c7c968a](https://github.com/LukasNiessen/ArchUnitPython/commit/c7c968af20e929f7e7a2372275eaa7e26cb38e5f))
+
 # [1.4.0](https://github.com/LukasNiessen/ArchUnitPython/compare/v1.3.0...v1.4.0) (2026-07-18)
 
 

{archunitpython-1.4.0 → archunitpython-1.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: archunitpython
-Version: 1.4.0
+Version: 1.6.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,7 +41,6 @@ Description-Content-Type: text/markdown
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Build & tests](https://img.shields.io/github/actions/workflow/status/LukasNiessen/ArchUnitPython/integrate.yaml?branch=main&label=build%20%26%20tests)](https://github.com/LukasNiessen/ArchUnitPython/actions/workflows/integrate.yaml) [![GitHub stars](https://img.shields.io/github/stars/LukasNiessen/ArchUnitPython.svg)](https://github.com/LukasNiessen/ArchUnitPython)<br>
 [![PyPI downloads](https://static.pepy.tech/badge/archunitpython/month)](https://pepy.tech/project/archunitpython) [![PyPI total downloads](https://img.shields.io/pepy/dt/archunitpython?label=total%20downloads&color=007ec6)](https://pepy.tech/project/archunitpython)
-<!-- [![PyPI version](https://img.shields.io/pypi/v/archunitpython.svg)](https://pypi.org/project/archunitpython/) -->
 
 </div>
 
@@ -51,7 +50,7 @@ The #1 ArchUnit-style architecture testing library for Python, measured by GitHu
 
 _Inspired by the amazing ArchUnit library but we are not affiliated with ArchUnit._
 
-[Setup](#-setup) • [Use Cases](#-use-cases) • [Features](#-features) • [Why ArchUnitPython?](#-library-comparison) • [Sponsor](https://github.com/sponsors/LukasNiessen) • [Contributing](CONTRIBUTING.md)
+[Setup](#-setup) • [Use Cases](#-use-cases) • [Features](#-features) • [Why ArchUnitPython?](#-library-comparison) • [Sponsor](https://github.com/sponsors/LukasNiessen) • [Contributing](CONTRIBUTING.md) • [Documentation](https://lukasniessen.github.io/ArchUnitPython/)
 
 ## ⚡ 5 min Quickstart
 
@@ -206,6 +205,42 @@ migrations/*.py
 
 Patterns support comments, blank lines, glob syntax, root-relative paths, path
 patterns, and directory patterns with a trailing `/`.
+
+### Loading Common Rules From Config
+
+For straightforward shared rules, you can load a JSON config file and still run
+the resulting rules in your normal test suite:
+
+```json
+{
+  "project_path": "src",
+  "rules": [
+    {
+      "name": "controllers must not use services directly",
+      "type": "forbidden_dependency",
+      "source": "**/controllers/**",
+      "target": "**/services/**"
+    },
+    {
+      "name": "source files have no cycles",
+      "type": "no_cycles"
+    }
+  ]
+}
+```
+
+```python
+from archunitpython import assert_passes, rules_from_config
+
+def test_configured_architecture_rules():
+    for rule in rules_from_config("archunitpython.json"):
+        assert_passes(rule)
+```
+
+Supported rule types are `no_cycles`, `forbidden_dependency`, and
+`forbidden_external_dependency`. The fluent Python API remains the primary and
+most flexible interface.
+
 ### Explaining Rules With `.because(...)`
 
 Attach a rationale to a rule so failing assertions explain why the rule exists:
@@ -342,6 +377,17 @@ ArchUnitPython detects string-based dynamic imports such as `importlib.import_mo
 from my_app.adapters.sql import Repository  # archunit: ignore
 ```
 
+### Conditional Imports
+
+Imports inside `try` blocks that handle `ImportError` or
+`ModuleNotFoundError` are marked as conditional dependencies. This helps graph
+reports distinguish optional imports and fallback implementations from regular
+runtime imports. Conditional dependencies remain part of architecture checks;
+relative and dynamic imports also retain their original import kind in graph
+reports. An edge may therefore have multiple kinds: CSV reports use
+pipe-delimited values such as `relative|conditional`, while HTML reports list
+both values separately.
+
 ### Naming Conventions
 
 ```python
@@ -357,6 +403,10 @@ def test_naming_patterns():
 
 ### Code Metrics
 
+Metric rules evaluate every matching file or class independently. Use filters such as
+`in_folder()`, `with_name()`, and `for_classes_matching()` when different parts of the
+project need different limits.
+
 ```python
 def test_no_large_files():
     rule = metrics("src/").count().lines_of_code().should_be_below(1000)
@@ -367,7 +417,7 @@ def test_high_class_cohesion():
     assert_passes(rule)
 
 def test_method_count():
-    rule = metrics("src/").count().method_count().should_be_below(20)
+    rule = metrics("src/").count().method_count().should_be_below_or_equal(20)
     assert_passes(rule)
 
 def test_field_count_for_data_classes():
@@ -381,6 +431,45 @@ def test_field_count_for_data_classes():
     assert_passes(rule)
 ```
 
+#### Comparison Semantics
+
+Metric comparisons are exact. In particular, `should_be_below(20)` means `< 20`, so
+a value of exactly `20` is a violation. Use the inclusive form when the limit itself
+should be accepted.
+
+| Method | Passing values |
+| --- | --- |
+| `should_be_below(n)` | `< n` |
+| `should_be_below_or_equal(n)` | `<= n` |
+| `should_be_above(n)` | `> n` |
+| `should_be_above_or_equal(n)` | `>= n` |
+| `should_be(n)` | exactly `n` |
+
+Not every metric builder exposes every comparison. The available methods are shown
+by the fluent API after selecting a metric.
+
+#### Choosing Thresholds
+
+There is no universal correct limit for every codebase. Treat thresholds as
+architecture decisions that should reflect the role and maturity of the code:
+
+1. Measure the current project before enabling a new rule.
+2. Start at the current maximum, or slightly above it, to prevent further regression.
+3. Use narrower filters when generated code, data classes, or adapters need different limits.
+4. Lower the threshold gradually as existing violations are removed.
+5. Record the reason with `.because(...)` so future maintainers understand the limit.
+
+| Metric | Interpretation | Useful starting point |
+| --- | --- | --- |
+| Lines of code | File size and review burden | Current maximum for hand-written files |
+| Method or field count | Class responsibility and size | Current maximum, split by class role |
+| LCOM | Lack of class cohesion; lower is generally better | Baseline one LCOM variant and keep it consistent |
+| Instability | Dependence on outgoing versus incoming dependencies | Compare files with similar architectural roles |
+| Distance from main sequence | Balance between abstractness and instability; closer to zero is better | Observe the current distribution before tightening |
+
+Thresholds are guardrails, not quality scores. A metric violation is a prompt to inspect
+the design; it does not automatically mean the code is incorrect.
+
 ### Distance Metrics
 
 ```python
@@ -476,13 +565,13 @@ from archunitpython import project_graph
 def test_export_dependency_graph_reports():
     graph = project_graph("src/requests").titled("Application Architecture")
 
-    graph.collapse_to_folder_depth(2).export_as_mermaid("reports/dependencies.md")
+    graph.collapse_to_folder_depth(2).export_as_mermaid("reports/dependencies.mmd")
 
 if __name__ == "__main__":
     test_export_dependency_graph_reports()
 ```
-**Exported mermaid diagram**
-``` mermaid
+**Exported Mermaid diagram**
+```mermaid
 flowchart LR
   n0["__init__.py"]
   n1["__version__.py"]
@@ -600,20 +689,36 @@ When you create reports through `project_graph("src/")`, internal file paths are
 
 ### Reports
 
-Generate HTML reports for your metrics. _Note that this feature is in beta._
+Generate an HTML report from metric values collected by your tests or build tooling.
+`MetricsExporter` formats the supplied dictionary; it does not execute metric rules or
+calculate the values itself. _This feature is in beta._
 
 ```python
 from archunitpython.metrics.fluentapi.export_utils import MetricsExporter, ExportOptions
 
-MetricsExporter.export_as_html(
-    {"MethodCount": 5, "FieldCount": 3, "LinesOfCode": 150},
+metric_summary = {
+    "Maximum method count": "18 (limit: <= 20)",
+    "Maximum field count": "9 (limit: <= 10)",
+    "Maximum lines of code": "420 (limit: < 500)",
+    "Highest LCOM96b": "0.24 (limit: < 0.30)",
+}
+
+html = MetricsExporter.export_as_html(
+    metric_summary,
     ExportOptions(
         output_path="reports/metrics.html",
         title="Architecture Metrics Dashboard",
+        include_timestamp=False,
     ),
 )
+
+assert "Maximum method count" in html
 ```
 
+Keep labels and units stable if these reports are stored as CI artifacts and compared
+between builds. Continue using executable metric rules with `assert_passes()` as the
+enforcement mechanism.
+
 ## 🔎 Pattern Matching System
 
 We offer three targeting options for pattern matching across all modules:
@@ -948,7 +1053,7 @@ If ArchUnitPython helps your project, please consider:
 
 ### Star History
 
-[![Star History Chart](https://api.star-history.com/svg?repos=LukasNiessen/ArchUnitPython&type=Date)](https://www.star-history.com/#LukasNiessen/ArchUnitPython&Date)
+[![Star History Chart](https://star-history.dera.page/svg?repos=LukasNiessen/ArchUnitPython&type=Date)](https://star-history.dera.page/#LukasNiessen/ArchUnitPython&Date)
 
 ## 📄 License
 

{archunitpython-1.4.0 → archunitpython-1.6.0}/README.md

@@ -8,7 +8,6 @@
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Build & tests](https://img.shields.io/github/actions/workflow/status/LukasNiessen/ArchUnitPython/integrate.yaml?branch=main&label=build%20%26%20tests)](https://github.com/LukasNiessen/ArchUnitPython/actions/workflows/integrate.yaml) [![GitHub stars](https://img.shields.io/github/stars/LukasNiessen/ArchUnitPython.svg)](https://github.com/LukasNiessen/ArchUnitPython)<br>
 [![PyPI downloads](https://static.pepy.tech/badge/archunitpython/month)](https://pepy.tech/project/archunitpython) [![PyPI total downloads](https://img.shields.io/pepy/dt/archunitpython?label=total%20downloads&color=007ec6)](https://pepy.tech/project/archunitpython)
-<!-- [![PyPI version](https://img.shields.io/pypi/v/archunitpython.svg)](https://pypi.org/project/archunitpython/) -->
 
 </div>
 
@@ -18,7 +17,7 @@ The #1 ArchUnit-style architecture testing library for Python, measured by GitHu
 
 _Inspired by the amazing ArchUnit library but we are not affiliated with ArchUnit._
 
-[Setup](#-setup) • [Use Cases](#-use-cases) • [Features](#-features) • [Why ArchUnitPython?](#-library-comparison) • [Sponsor](https://github.com/sponsors/LukasNiessen) • [Contributing](CONTRIBUTING.md)
+[Setup](#-setup) • [Use Cases](#-use-cases) • [Features](#-features) • [Why ArchUnitPython?](#-library-comparison) • [Sponsor](https://github.com/sponsors/LukasNiessen) • [Contributing](CONTRIBUTING.md) • [Documentation](https://lukasniessen.github.io/ArchUnitPython/)
 
 ## ⚡ 5 min Quickstart
 
@@ -173,6 +172,42 @@ migrations/*.py
 
 Patterns support comments, blank lines, glob syntax, root-relative paths, path
 patterns, and directory patterns with a trailing `/`.
+
+### Loading Common Rules From Config
+
+For straightforward shared rules, you can load a JSON config file and still run
+the resulting rules in your normal test suite:
+
+```json
+{
+  "project_path": "src",
+  "rules": [
+    {
+      "name": "controllers must not use services directly",
+      "type": "forbidden_dependency",
+      "source": "**/controllers/**",
+      "target": "**/services/**"
+    },
+    {
+      "name": "source files have no cycles",
+      "type": "no_cycles"
+    }
+  ]
+}
+```
+
+```python
+from archunitpython import assert_passes, rules_from_config
+
+def test_configured_architecture_rules():
+    for rule in rules_from_config("archunitpython.json"):
+        assert_passes(rule)
+```
+
+Supported rule types are `no_cycles`, `forbidden_dependency`, and
+`forbidden_external_dependency`. The fluent Python API remains the primary and
+most flexible interface.
+
 ### Explaining Rules With `.because(...)`
 
 Attach a rationale to a rule so failing assertions explain why the rule exists:
@@ -309,6 +344,17 @@ ArchUnitPython detects string-based dynamic imports such as `importlib.import_mo
 from my_app.adapters.sql import Repository  # archunit: ignore
 ```
 
+### Conditional Imports
+
+Imports inside `try` blocks that handle `ImportError` or
+`ModuleNotFoundError` are marked as conditional dependencies. This helps graph
+reports distinguish optional imports and fallback implementations from regular
+runtime imports. Conditional dependencies remain part of architecture checks;
+relative and dynamic imports also retain their original import kind in graph
+reports. An edge may therefore have multiple kinds: CSV reports use
+pipe-delimited values such as `relative|conditional`, while HTML reports list
+both values separately.
+
 ### Naming Conventions
 
 ```python
@@ -324,6 +370,10 @@ def test_naming_patterns():
 
 ### Code Metrics
 
+Metric rules evaluate every matching file or class independently. Use filters such as
+`in_folder()`, `with_name()`, and `for_classes_matching()` when different parts of the
+project need different limits.
+
 ```python
 def test_no_large_files():
     rule = metrics("src/").count().lines_of_code().should_be_below(1000)
@@ -334,7 +384,7 @@ def test_high_class_cohesion():
     assert_passes(rule)
 
 def test_method_count():
-    rule = metrics("src/").count().method_count().should_be_below(20)
+    rule = metrics("src/").count().method_count().should_be_below_or_equal(20)
     assert_passes(rule)
 
 def test_field_count_for_data_classes():
@@ -348,6 +398,45 @@ def test_field_count_for_data_classes():
     assert_passes(rule)
 ```
 
+#### Comparison Semantics
+
+Metric comparisons are exact. In particular, `should_be_below(20)` means `< 20`, so
+a value of exactly `20` is a violation. Use the inclusive form when the limit itself
+should be accepted.
+
+| Method | Passing values |
+| --- | --- |
+| `should_be_below(n)` | `< n` |
+| `should_be_below_or_equal(n)` | `<= n` |
+| `should_be_above(n)` | `> n` |
+| `should_be_above_or_equal(n)` | `>= n` |
+| `should_be(n)` | exactly `n` |
+
+Not every metric builder exposes every comparison. The available methods are shown
+by the fluent API after selecting a metric.
+
+#### Choosing Thresholds
+
+There is no universal correct limit for every codebase. Treat thresholds as
+architecture decisions that should reflect the role and maturity of the code:
+
+1. Measure the current project before enabling a new rule.
+2. Start at the current maximum, or slightly above it, to prevent further regression.
+3. Use narrower filters when generated code, data classes, or adapters need different limits.
+4. Lower the threshold gradually as existing violations are removed.
+5. Record the reason with `.because(...)` so future maintainers understand the limit.
+
+| Metric | Interpretation | Useful starting point |
+| --- | --- | --- |
+| Lines of code | File size and review burden | Current maximum for hand-written files |
+| Method or field count | Class responsibility and size | Current maximum, split by class role |
+| LCOM | Lack of class cohesion; lower is generally better | Baseline one LCOM variant and keep it consistent |
+| Instability | Dependence on outgoing versus incoming dependencies | Compare files with similar architectural roles |
+| Distance from main sequence | Balance between abstractness and instability; closer to zero is better | Observe the current distribution before tightening |
+
+Thresholds are guardrails, not quality scores. A metric violation is a prompt to inspect
+the design; it does not automatically mean the code is incorrect.
+
 ### Distance Metrics
 
 ```python
@@ -443,13 +532,13 @@ from archunitpython import project_graph
 def test_export_dependency_graph_reports():
     graph = project_graph("src/requests").titled("Application Architecture")
 
-    graph.collapse_to_folder_depth(2).export_as_mermaid("reports/dependencies.md")
+    graph.collapse_to_folder_depth(2).export_as_mermaid("reports/dependencies.mmd")
 
 if __name__ == "__main__":
     test_export_dependency_graph_reports()
 ```
-**Exported mermaid diagram**
-``` mermaid
+**Exported Mermaid diagram**
+```mermaid
 flowchart LR
   n0["__init__.py"]
   n1["__version__.py"]
@@ -567,20 +656,36 @@ When you create reports through `project_graph("src/")`, internal file paths are
 
 ### Reports
 
-Generate HTML reports for your metrics. _Note that this feature is in beta._
+Generate an HTML report from metric values collected by your tests or build tooling.
+`MetricsExporter` formats the supplied dictionary; it does not execute metric rules or
+calculate the values itself. _This feature is in beta._
 
 ```python
 from archunitpython.metrics.fluentapi.export_utils import MetricsExporter, ExportOptions
 
-MetricsExporter.export_as_html(
-    {"MethodCount": 5, "FieldCount": 3, "LinesOfCode": 150},
+metric_summary = {
+    "Maximum method count": "18 (limit: <= 20)",
+    "Maximum field count": "9 (limit: <= 10)",
+    "Maximum lines of code": "420 (limit: < 500)",
+    "Highest LCOM96b": "0.24 (limit: < 0.30)",
+}
+
+html = MetricsExporter.export_as_html(
+    metric_summary,
     ExportOptions(
         output_path="reports/metrics.html",
         title="Architecture Metrics Dashboard",
+        include_timestamp=False,
     ),
 )
+
+assert "Maximum method count" in html
 ```
 
+Keep labels and units stable if these reports are stored as CI artifacts and compared
+between builds. Continue using executable metric rules with `assert_passes()` as the
+enforcement mechanism.
+
 ## 🔎 Pattern Matching System
 
 We offer three targeting options for pattern matching across all modules:
@@ -915,7 +1020,7 @@ If ArchUnitPython helps your project, please consider:
 
 ### Star History
 
-[![Star History Chart](https://api.star-history.com/svg?repos=LukasNiessen/ArchUnitPython&type=Date)](https://www.star-history.com/#LukasNiessen/ArchUnitPython&Date)
+[![Star History Chart](https://star-history.dera.page/svg?repos=LukasNiessen/ArchUnitPython&type=Date)](https://star-history.dera.page/#LukasNiessen/ArchUnitPython&Date)
 
 ## 📄 License
 

{archunitpython-1.4.0 → archunitpython-1.6.0}/pyproject.toml

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

{archunitpython-1.4.0 → archunitpython-1.6.0}/src/archunitpython/__init__.py

@@ -1,6 +1,6 @@
 """ArchUnitPython - Architecture testing library for Python projects."""
 
-__version__ = "1.4.0"
+__version__ = "1.6.0"
 
 # Files API
 # Common
@@ -12,6 +12,7 @@ from archunitpython.common import (
     Violation,
 )
 from archunitpython.common.extraction import clear_graph_cache, extract_graph
+from archunitpython.config import ConfiguredRule, rules_from_config
 from archunitpython.files import files, project_files
 from archunitpython.graph import dependency_graph, project_graph
 from archunitpython.layers import layers, project_layers
@@ -35,6 +36,9 @@ __all__ = [
     # Layers
     "project_layers",
     "layers",
+    # Config
+    "rules_from_config",
+    "ConfiguredRule",
     # Slices
     "project_slices",
     # Metrics