From 85e41c3a823b94e08429f81c99effef8927bd231 Mon Sep 17 00:00:00 2001 From: TristanKruse Date: Sun, 19 Jul 2026 00:15:10 +0200 Subject: [PATCH] docs: tidy examples and completed backlog items --- BACKLOG.md | 8 ++++---- README.md | 6 +++--- src/archunitpython/files/assertion/custom_file_logic.py | 6 +++--- src/archunitpython/files/assertion/depend_on_files.py | 6 +++--- src/archunitpython/files/assertion/matching_files.py | 6 +++--- src/archunitpython/slices/assertion/admissible_edges.py | 2 +- 6 files changed, 17 insertions(+), 17 deletions(-) diff --git a/BACKLOG.md b/BACKLOG.md index 4fefa5e..2590ae9 100644 --- a/BACKLOG.md +++ b/BACKLOG.md @@ -19,7 +19,7 @@ This backlog collects product and maintenance ideas from project research. ## 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__()`. +- [x] Detect dynamic imports such as `importlib.import_module()` and `__import__()`. - 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. @@ -30,12 +30,12 @@ This backlog collects product and maintenance ideas from project research. - Add comprehensive HTML reports with dependency graphs, metric charts, and zone visualization. - 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. +- [x] Add PlantUML or Mermaid export for discovered architecture graphs. - 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. diff --git a/README.md b/README.md index 6b8510a..121205f 100644 --- a/README.md +++ b/README.md @@ -479,13 +479,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"] diff --git a/src/archunitpython/files/assertion/custom_file_logic.py b/src/archunitpython/files/assertion/custom_file_logic.py index 573a872..add8a0d 100644 --- a/src/archunitpython/files/assertion/custom_file_logic.py +++ b/src/archunitpython/files/assertion/custom_file_logic.py @@ -72,8 +72,8 @@ def gather_custom_file_violations( nodes: All projected nodes. condition: Custom function that returns True if the file passes. message: Message to include in violation. - is_negated: If False (should adhere), violation when condition returns False. - If True (shouldNot adhere), violation when condition returns True. + is_negated: If False (positive assertion), violation when condition returns False. + If True (negated assertion), violation when condition returns True. pre_filters: Filters to apply before checking the condition. Returns: @@ -90,7 +90,7 @@ def gather_custom_file_violations( result = condition(file_info) if is_negated: - # shouldNot: violation if condition IS True + # Negated assertion: violation if condition IS True if result: violations.append(CustomFileViolation(message=message, file_info=file_info)) else: diff --git a/src/archunitpython/files/assertion/depend_on_files.py b/src/archunitpython/files/assertion/depend_on_files.py index 99d2946..69abd90 100644 --- a/src/archunitpython/files/assertion/depend_on_files.py +++ b/src/archunitpython/files/assertion/depend_on_files.py @@ -30,9 +30,9 @@ def gather_depend_on_file_violations( edges: Projected dependency edges. subject_filters: Patterns for the source files (subject of the rule). object_filters: Patterns for the target files (dependency targets). - is_negated: If False (should), files matching subject MUST depend on + is_negated: If False (`should()`), files matching subject MUST depend on files matching object. - If True (shouldNot), files matching subject must NOT + If True (`should_not()`), files matching subject must NOT depend on files matching object. Returns: @@ -48,7 +48,7 @@ def gather_depend_on_file_violations( target_matches = all(matches_pattern(edge.target_label, f) for f in object_filters) if is_negated: - # shouldNot: violation if dependency EXISTS + # should_not(): violation if dependency EXISTS if target_matches: violations.append(ViolatingFileDependency(dependency=edge, is_negated=True)) else: diff --git a/src/archunitpython/files/assertion/matching_files.py b/src/archunitpython/files/assertion/matching_files.py index 8d10ace..8bd8c96 100644 --- a/src/archunitpython/files/assertion/matching_files.py +++ b/src/archunitpython/files/assertion/matching_files.py @@ -29,8 +29,8 @@ def gather_regex_matching_violations( Args: nodes: Files to check. check_filters: Patterns to match against. - is_negated: If False (should), files MUST match all patterns. - If True (shouldNot), files must NOT match any pattern. + is_negated: If False (`should()`), files MUST match all patterns. + If True (`should_not()`), files must NOT match any pattern. Returns: List of violations. @@ -41,7 +41,7 @@ def gather_regex_matching_violations( for filter_ in check_filters: matched = matches_pattern(node.label, filter_) if is_negated: - # shouldNot: violation if file DOES match + # should_not(): violation if file DOES match if matched: violations.append( ViolatingNode( diff --git a/src/archunitpython/slices/assertion/admissible_edges.py b/src/archunitpython/slices/assertion/admissible_edges.py index 359f9cb..87ca9b7 100644 --- a/src/archunitpython/slices/assertion/admissible_edges.py +++ b/src/archunitpython/slices/assertion/admissible_edges.py @@ -30,7 +30,7 @@ def gather_violations( edges: list[ProjectedEdge], rules: list[Rule], ) -> list[Violation]: - """Check for forbidden dependencies (used with shouldNot). + """Check for forbidden dependencies (used with `should_not()`). Args: edges: Projected dependency edges between slices.