pytestarch 4.0.0__tar.gz → 5.0.0__tar.gz

pytestarch-5.0.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: PyTestArch
+Version: 5.0.0
+Summary: Test framework for software architecture based on imports between modules
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: architecture,test
+Author: zyskarch
+Author-email: zyskarch@gmail.com
+Maintainer: zyskarch
+Maintainer-email: zyskarch@gmail.com
+Requires-Python: >=3.11
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.11
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Software Development :: Testing :: Unit
+Provides-Extra: visualization
+Requires-Dist: matplotlib (>=3.11) ; extra == "visualization"
+Requires-Dist: networkx (>=3.6)
+Project-URL: Documentation, https://zyskarch.github.io/pytestarch/latest
+Project-URL: Repository, https://github.com/zyskarch/pytestarch
+Project-URL: issues, https://github.com/zyskarch/pytestarch/issues
+Description-Content-Type: text/markdown
+
+# Welcome to PyTestArch
+
+PyTestArch is an open source library that allows users to define architectural rules and test their code against them. It is 
+generally inspired by [ArchUnit](https://www.archunit.org/).
+
+## Installation Guide
+PyTestArch is available via [PyPI](https://pypi.org/project/pytestarch/) and can be installed e.g. via pip: `pip install pytestarch`. To also install the
+optional dependency matplotlib, which is required to draw the created dependency graphs, install `pytestarch[visualization]`
+
+## Usage Guide
+Three steps are required to test an architectural rule:
+
+1) Create an evaluable representation of the source code you want to test
+
+```
+from pytestarch import get_evaluable_architecture
+
+evaluable = get_evaluable_architecture("/home/dummy/project", "/home/dummy/project/src")
+```
+This will scan all python files under /home/dummy/project/src for imports and build an internal representation that can
+later be queried. The first parameter /home/dummy/project helps PyTestArch to differentiate between internal and external 
+dependencies. This evaluable can be used for multiple architectural rule checks; if you are using [pytest](https://docs.pytest.org/en/7.1.x/),
+you could use a fixture for this evaluable object.
+
+2) Define an architectural rule
+```
+from pytestarch import Rule
+
+rule = (
+    Rule() 
+    .modules_that() 
+    .are_named("project.src.moduleB") 
+    .should_not() 
+    .be_imported_by_modules_that() 
+    .are_sub_modules_of("project.src.moduleA") 
+)
+```
+
+This rule represents the architectural requirements that a module named "project.src.moduleB" should not be imported by any module
+that is a submodule of "project.src.moduleA", excluding "project.src.moduleA" itself.
+
+3) Evaluate your code against this rule
+
+```
+rule.assert_applies(evaluable)
+```
+That's it!
+
+## Real-World Example
+
+The snippet below is taken directly from pytestarch's own architecture tests
+([`tests/test_architecture.py`](https://github.com/zyskarch/pytestarch/blob/main/tests/test_architecture.py)).
+It guards the library's own internal module boundaries
+
+```python
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from pytestarch import EvaluableArchitecture, Rule, get_evaluable_architecture
+
+
+@pytest.fixture(scope="session")
+def pytestarch_architecture() -> EvaluableArchitecture:
+    cwd = Path.cwd()
+    while cwd.stem != "pytestarch":
+        cwd = cwd.parent
+    src_folder = str(cwd / "src/pytestarch")
+
+    return get_evaluable_architecture(
+        src_folder,
+        src_folder,
+        ("*__pycache__", "*__init__.py"),
+    )
+
+
+BASE_MODULE = "pytestarch"
+DIAGRAM = f"{BASE_MODULE}.diagram_extension"
+STRUCTURE = f"{BASE_MODULE}.eval_structure"
+GENERATION = f"{BASE_MODULE}.eval_structure_generation"
+LANGUAGE = f"{BASE_MODULE}.query_language"
+ASSESSMENT = f"{BASE_MODULE}.rule_assessment"
+UTILS = f"{BASE_MODULE}.utils"
+
+
+top_level_rules = [
+    pytest.param(
+        Rule()
+        .modules_that()
+        .are_named(DIAGRAM)
+        .should_only()
+        .import_modules_that()
+        .are_named([LANGUAGE, STRUCTURE]),
+        id="diagram_extension",
+    ),
+    pytest.param(
+        Rule().modules_that().are_named(STRUCTURE).should_not().import_anything(),
+        id="eval_structure",
+    ),
+    pytest.param(
+        Rule()
+        .modules_that()
+        .are_named(GENERATION)
+        .should_only()
+        .import_modules_that()
+        .are_named(STRUCTURE),
+        id="eval_structure_generation",
+    ),
+    pytest.param(
+        Rule()
+        .modules_that()
+        .are_named(LANGUAGE)
+        .should_only()
+        .import_modules_that()
+        .are_named([STRUCTURE, ASSESSMENT, UTILS]),
+        id="query_language",
+    ),
+    pytest.param(
+        Rule()
+        .modules_that()
+        .are_named(ASSESSMENT)
+        .should_only()
+        .import_modules_that()
+        .are_named(STRUCTURE),
+        id="rule_assessment",
+    ),
+]
+
+
+@pytest.mark.parametrize("rule", top_level_rules)
+def test_top_level_module_structure(
+    rule: Rule, pytestarch_architecture: EvaluableArchitecture
+) -> None:
+    rule.assert_applies(pytestarch_architecture)
+```
+
+## Further Resources
+
+- [Full documentation](https://zyskarch.github.io/pytestarch/latest)
+- More test examples on GitHub:
+  - [`tests/test_architecture.py`](https://github.com/zyskarch/pytestarch/blob/main/tests/test_architecture.py) — module boundary rules (shown above)
+  - [`tests/diagram_extension/`](https://github.com/zyskarch/pytestarch/tree/main/tests/diagram_extension) — generating rules from PlantUML diagrams
+  - [`tests/integration/`](https://github.com/zyskarch/pytestarch/tree/main/tests/integration) — extensive parametrized test cases
+

pytestarch-5.0.0/README.md

@@ -0,0 +1,145 @@
+# Welcome to PyTestArch
+
+PyTestArch is an open source library that allows users to define architectural rules and test their code against them. It is 
+generally inspired by [ArchUnit](https://www.archunit.org/).
+
+## Installation Guide
+PyTestArch is available via [PyPI](https://pypi.org/project/pytestarch/) and can be installed e.g. via pip: `pip install pytestarch`. To also install the
+optional dependency matplotlib, which is required to draw the created dependency graphs, install `pytestarch[visualization]`
+
+## Usage Guide
+Three steps are required to test an architectural rule:
+
+1) Create an evaluable representation of the source code you want to test
+
+```
+from pytestarch import get_evaluable_architecture
+
+evaluable = get_evaluable_architecture("/home/dummy/project", "/home/dummy/project/src")
+```
+This will scan all python files under /home/dummy/project/src for imports and build an internal representation that can
+later be queried. The first parameter /home/dummy/project helps PyTestArch to differentiate between internal and external 
+dependencies. This evaluable can be used for multiple architectural rule checks; if you are using [pytest](https://docs.pytest.org/en/7.1.x/),
+you could use a fixture for this evaluable object.
+
+2) Define an architectural rule
+```
+from pytestarch import Rule
+
+rule = (
+    Rule() 
+    .modules_that() 
+    .are_named("project.src.moduleB") 
+    .should_not() 
+    .be_imported_by_modules_that() 
+    .are_sub_modules_of("project.src.moduleA") 
+)
+```
+
+This rule represents the architectural requirements that a module named "project.src.moduleB" should not be imported by any module
+that is a submodule of "project.src.moduleA", excluding "project.src.moduleA" itself.
+
+3) Evaluate your code against this rule
+
+```
+rule.assert_applies(evaluable)
+```
+That's it!
+
+## Real-World Example
+
+The snippet below is taken directly from pytestarch's own architecture tests
+([`tests/test_architecture.py`](https://github.com/zyskarch/pytestarch/blob/main/tests/test_architecture.py)).
+It guards the library's own internal module boundaries
+
+```python
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from pytestarch import EvaluableArchitecture, Rule, get_evaluable_architecture
+
+
+@pytest.fixture(scope="session")
+def pytestarch_architecture() -> EvaluableArchitecture:
+    cwd = Path.cwd()
+    while cwd.stem != "pytestarch":
+        cwd = cwd.parent
+    src_folder = str(cwd / "src/pytestarch")
+
+    return get_evaluable_architecture(
+        src_folder,
+        src_folder,
+        ("*__pycache__", "*__init__.py"),
+    )
+
+
+BASE_MODULE = "pytestarch"
+DIAGRAM = f"{BASE_MODULE}.diagram_extension"
+STRUCTURE = f"{BASE_MODULE}.eval_structure"
+GENERATION = f"{BASE_MODULE}.eval_structure_generation"
+LANGUAGE = f"{BASE_MODULE}.query_language"
+ASSESSMENT = f"{BASE_MODULE}.rule_assessment"
+UTILS = f"{BASE_MODULE}.utils"
+
+
+top_level_rules = [
+    pytest.param(
+        Rule()
+        .modules_that()
+        .are_named(DIAGRAM)
+        .should_only()
+        .import_modules_that()
+        .are_named([LANGUAGE, STRUCTURE]),
+        id="diagram_extension",
+    ),
+    pytest.param(
+        Rule().modules_that().are_named(STRUCTURE).should_not().import_anything(),
+        id="eval_structure",
+    ),
+    pytest.param(
+        Rule()
+        .modules_that()
+        .are_named(GENERATION)
+        .should_only()
+        .import_modules_that()
+        .are_named(STRUCTURE),
+        id="eval_structure_generation",
+    ),
+    pytest.param(
+        Rule()
+        .modules_that()
+        .are_named(LANGUAGE)
+        .should_only()
+        .import_modules_that()
+        .are_named([STRUCTURE, ASSESSMENT, UTILS]),
+        id="query_language",
+    ),
+    pytest.param(
+        Rule()
+        .modules_that()
+        .are_named(ASSESSMENT)
+        .should_only()
+        .import_modules_that()
+        .are_named(STRUCTURE),
+        id="rule_assessment",
+    ),
+]
+
+
+@pytest.mark.parametrize("rule", top_level_rules)
+def test_top_level_module_structure(
+    rule: Rule, pytestarch_architecture: EvaluableArchitecture
+) -> None:
+    rule.assert_applies(pytestarch_architecture)
+```
+
+## Further Resources
+
+- [Full documentation](https://zyskarch.github.io/pytestarch/latest)
+- More test examples on GitHub:
+  - [`tests/test_architecture.py`](https://github.com/zyskarch/pytestarch/blob/main/tests/test_architecture.py) — module boundary rules (shown above)
+  - [`tests/diagram_extension/`](https://github.com/zyskarch/pytestarch/tree/main/tests/diagram_extension) — generating rules from PlantUML diagrams
+  - [`tests/integration/`](https://github.com/zyskarch/pytestarch/tree/main/tests/integration) — extensive parametrized test cases

{pytestarch-4.0.0 → pytestarch-5.0.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "PyTestArch"
-version = "4.0.0"
-requires-python = ">=3.9"
+version = "5.0.0"
+requires-python = ">=3.11"
 description = "Test framework for software architecture based on imports between modules"
 authors = [{ name = "zyskarch", email = "zyskarch@gmail.com" }]
 maintainers = [{ name = "zyskarch", email = "zyskarch@gmail.com" }]
@@ -10,11 +10,11 @@ license = "Apache-2.0"
 
 keywords = ["architecture", "test"]
 classifiers = [
+    "Programming Language :: Python :: 3.15",
+    "Programming Language :: Python :: 3.14",
     "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.11",
-    "Programming Language :: Python :: 3.10",
-    "Programming Language :: Python :: 3.9",
     "License :: OSI Approved :: Apache Software License",
     "Operating System :: OS Independent",
     "Intended Audience :: Developers",
@@ -22,10 +22,10 @@ classifiers = [
     "Topic :: Software Development :: Testing :: Unit",
 ]
 
-dependencies = ["networkx>=3.2"]
+dependencies = ["networkx>=3.6"]
 
 [project.optional-dependencies]
-visualization = ["matplotlib>=3.9"]
+visualization = ["matplotlib>=3.11"]
 
 [project.urls]
 issues = "https://github.com/zyskarch/pytestarch/issues"
@@ -33,19 +33,14 @@ documentation = "https://zyskarch.github.io/pytestarch/latest"
 repository = "https://github.com/zyskarch/pytestarch"
 
 [tool.poetry.group.dev.dependencies]
-mkdocs = "1.6.0"
-mkdocstrings-python = "1.10.3"
-mkdocs-material = "9.5.25"
-mkdocs-autorefs = "1.0.1"
-mkdocs-material-extensions = "1.3.1"
-mkdocstrings = "0.25.1"
-griffe = "0.45.2"
-nox = "2024.4.15"
-pre-commit = "3.7.1"
-pytest = "^8.2.1"
-coverage = "^7.5.2"
-mike = "2.1.1"
-ruff = "^0.7.0"
+zensical = "0.0.63"
+mkdocstrings-python = "2.0.8"
+mike = { git = "https://github.com/squidfunk/mike.git" }
+nox = "2026.8.17"
+pre-commit = "4.6.2"
+pytest = "^9.1.1"
+coverage = "^7.16.1"
+ruff = "^0.16.8"
 
 [build-system]
 requires = ["poetry-core>=2.0"]

{pytestarch-4.0.0 → pytestarch-5.0.0}/src/pytestarch/diagram_extension/diagram_parser.py

@@ -57,7 +57,7 @@ class PumlParser(DiagramParser):
             * component names must be enclosed in square brackets
             * exception: if a component as been given an alias via `[module name] as alias`, then the alias should not be
                 wrapped in square brackets
-            * dependencies must be with either -->, ->, <--, <-, -text->, or <-text-. The dependee is to be placed
+            * dependencies must be with either `-->`, `->`, `<--`, `<-`, `-text->`, or `<-text-`. The dependee is to be placed
                 on the side of the arrow head, the dependor on the opposite side
         Args:
             file_path: .puml file to parse

{pytestarch-4.0.0 → pytestarch-5.0.0}/src/pytestarch/diagram_extension/diagram_rule.py

@@ -56,7 +56,7 @@ class DiagramRule(FileRule, BaseModuleSpecifier, RuleApplier):
 
         Args:
              should_only_rule: if True, edges between components will be converted into 'should only import' rules.
-             If False, 'should import' rules will be generated instead.
+                 If False, 'should import' rules will be generated instead.
         """
         self._file_path: Path | None = None
         self._name_relative_to_root: str | None = None

{pytestarch-4.0.0 → pytestarch-5.0.0}/src/pytestarch/eval_structure/breadth_first_searches.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 from pytestarch.eval_structure.evaluable_architecture import Dependency, ModuleFilter
 from pytestarch.eval_structure.evaluable_structures import AbstractGraph, AbstractNode
-from pytestarch.eval_structure.utils import get_node, get_parent_nodes, to_modules
+from pytestarch.eval_structure.utils import get_node, get_parent_nodes, to_module
 
 
 def get_dependency_between_modules(
@@ -16,7 +16,7 @@ def get_dependency_between_modules(
     nodes_to_check = [dependent_node]
     checked_nodes = set()
 
-    dependencies = []
+    dependencies: list[Dependency] = []
 
     while nodes_to_check:
         node = nodes_to_check.pop()
@@ -37,8 +37,8 @@ def get_dependency_between_modules(
                 and node not in nodes_to_exclude
                 and child not in nodes_to_exclude
             ):
-                dependencies.append(tuple(to_modules([node, child])))
-    return dependencies  # type: ignore
+                dependencies.append((to_module(node), to_module(child)))
+    return dependencies
 
 
 def any_dependency_to_module_other_than(
@@ -51,7 +51,7 @@ def any_dependency_to_module_other_than(
             continue
         nodes_to_exclude.update(get_all_submodules_of(graph, dependent_upon))
 
-    nodes_fulfilling_criteria = []
+    nodes_fulfilling_criteria: list[Dependency] = []
 
     # nodes that count as not fulfilling the criterion are nodes that would technically fulfill the criterion,
     # but have to be excluded for consistency reasons. For example, if the dependent is called A and has two
@@ -102,11 +102,13 @@ def any_dependency_to_module_other_than(
                     child not in nodes_to_exclude
                     and child not in nodes_that_do_not_fulfill_criterion
                 ):
-                    nodes_fulfilling_criteria.append(tuple(to_modules([node, child])))
+                    nodes_fulfilling_criteria.append(
+                        (to_module(node), to_module(child))
+                    )
                 else:
                     nodes_to_check.append(child)
 
-    return nodes_fulfilling_criteria  # type: ignore
+    return nodes_fulfilling_criteria
 
 
 def any_other_dependency_to_module_than(
@@ -122,7 +124,7 @@ def any_other_dependency_to_module_than(
             continue
         nodes_to_exclude.update(get_all_submodules_of(graph, dependent))
 
-    nodes_fulfilling_criteria = []
+    nodes_fulfilling_criteria: list[Dependency] = []
 
     # nodes that count as not fulfilling the criterion are nodes that would technically fulfill the criterion,
     # but have to be excluded for consistency reasons. For example, if the dependent upon is called A and has two
@@ -171,12 +173,14 @@ def any_other_dependency_to_module_than(
                     parent not in nodes_to_exclude
                     and parent not in nodes_that_count_as_not_fulfilling_criterion
                 ):
-                    nodes_fulfilling_criteria.append(tuple(to_modules([parent, node])))
+                    nodes_fulfilling_criteria.append(
+                        (to_module(parent), to_module(node))
+                    )
 
                 if parent not in nodes_to_exclude:
                     nodes_to_check.append(parent)
 
-    return nodes_fulfilling_criteria  # type: ignore
+    return nodes_fulfilling_criteria
 
 
 def get_all_submodules_of(

{pytestarch-4.0.0 → pytestarch-5.0.0}/src/pytestarch/eval_structure/evaluable_architecture.py

@@ -236,8 +236,8 @@ class EvaluableArchitecture(Protocol):
         matches.
 
         Args:
-            dependent: Module(s)
-            dependent_upon: Module(s)
+            dependents: Module(s)
+            dependent_upons: Module(s)
 
         Returns:
             Importer and importee per pair of dependent and dependent_upon module if there are any
@@ -260,8 +260,8 @@ class EvaluableArchitecture(Protocol):
             Y's parent is such a module, as this parent module can and usually will also contain other modules than Y.
 
         Args:
-            dependent: Module
-            dependent_upon: Module
+            dependents: Module
+            dependent_upons: Module
 
         Returns:
             All modules other than dependent_upon on which dependent module as any dependency per dependent module
@@ -282,8 +282,8 @@ class EvaluableArchitecture(Protocol):
         If the dependent upon module is defined via a parent module, this parent module is not taken into account.
 
         Args:
-            dependent: Module
-            dependent_upon: Module
+            dependents: Module
+            dependent_upons: Module
 
         Returns:
             All modules other than dependent that have any dependency on the dependent upon module per dependent_upon module
@@ -296,7 +296,8 @@ class EvaluableArchitecture(Protocol):
         Args:
             **kwargs: Any formatting options available for networkx' drawing function, as this is currently the only
                 available backend.
-                Exception: If 'spacing' is set, this will be interpreted as the parameter 'k' of the spring layout (https://networkx.org/documentation/stable/reference/generated/networkx.drawing.layout.spring_layout.html#networkx.drawing.layout.spring_layout).
+                Exception: If 'spacing' is set, this will be interpreted as the parameter 'k' of the spring layout
+                ([networkx spring layout](https://networkx.org/documentation/stable/reference/generated/networkx.drawing.layout.spring_layout.html#networkx.drawing.layout.spring_layout)).
         """
         raise NotImplementedError()
 

pytestarch-5.0.0/src/pytestarch/eval_structure/exceptions.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+
+class ImpossibleMatch(Exception):
+    pass
+
+
+class LayerMismatch(Exception):
+    pass
+
+
+class ModuleUnknown(Exception):
+    """Raised when a queried module is not present in the dependency graph.
+
+    The exception message includes actionable guidance on common causes,
+    such as the module being an external library that was excluded from the
+    graph or the module name being misspelled.
+    """

{pytestarch-4.0.0 → pytestarch-5.0.0}/src/pytestarch/eval_structure/module_name_converter.py

@@ -27,8 +27,8 @@ class ModuleNameConverter:
         """Converts each regex pattern that serves to identify module names into actual modules that match this pattern.
 
         Args:
-            - modules: list of modules, some of which may need converting since their names are regex patterns
-            - arch: architecture that contains actual modules
+            modules: list of modules, some of which may need converting since their names are regex patterns
+            arch: architecture that contains actual modules
 
         Returns:
             - list of module filters, now without any regex patterns. Will be used for later dependency graph queries.
@@ -60,8 +60,7 @@ class ModuleNameConverter:
                     converted_module_filters.add(converted_module_filter)
                     conversion_mapping[module_to_match].append(converted_module)
 
-                    if module_to_match in never_matched:
-                        never_matched.remove(module_to_match)
+                    never_matched.discard(module_to_match)
 
                     submodules_of_match = get_all_submodules_of(
                         arch._graph,  # type: ignore
@@ -74,7 +73,7 @@ class ModuleNameConverter:
 
         if never_matched:
             raise ImpossibleMatch(
-                f'No modules found that match: {", ".join(never_matched)}'
+                f"No modules found that match: {', '.join(never_matched)}"
             )
 
         all_converted_modules = list(converted_module_filters) + other_modules  # type: ignore

{pytestarch-4.0.0 → pytestarch-5.0.0}/src/pytestarch/eval_structure/networkxgraph.py

@@ -10,6 +10,7 @@ import networkx as nx
 from networkx import draw_networkx, has_path, spring_layout
 
 from pytestarch.eval_structure.evaluable_structures import AbstractGraph, AbstractNode
+from pytestarch.eval_structure.exceptions import ModuleUnknown
 from pytestarch.eval_structure.types import Import, get_parent_modules
 
 EXPECTED_EDGE_AND_NODE_TYPES = "Only str and tuple of two str supported."
@@ -140,7 +141,7 @@ class NetworkxGraph(AbstractGraph):
             self._graph.add_edge(node_start, node_end, inherits=inherits)
 
     def __contains__(self, item) -> bool:
-        if not isinstance(item, (str, tuple)):
+        if not isinstance(item, str | tuple):
             raise TypeError(EXPECTED_EDGE_AND_NODE_TYPES)
 
         if isinstance(item, str):
@@ -179,7 +180,11 @@ class NetworkxGraph(AbstractGraph):
 
         Returns:
             all predecessor nodes
+
+        Raises:
+            ModuleUnknown: if node is not present in the dependency graph
         """
+        self._assert_node_exists(node)
         return sorted(self._graph.predecessors(node))
 
     def direct_successor_nodes(self, node: Node) -> list[Node]:
@@ -190,7 +195,11 @@ class NetworkxGraph(AbstractGraph):
 
         Returns:
             all successor nodes
+
+        Raises:
+            ModuleUnknown: if node is not present in the dependency graph
         """
+        self._assert_node_exists(node)
         return sorted(self._graph.successors(node))
 
     def parent_child_relationship(
@@ -224,8 +233,8 @@ class NetworkxGraph(AbstractGraph):
                 priority, e.g. with the same modules as above and
                 aliases == {'a': 'A', 'a.c': 'C'} the plot labels will be A, A.b, C,
                 C.d.
-            Remaining keyword args are passed to draw_networkx. Notably, "ax" can be
-            used to draw the graph onto an existing matploblib Axis object.
+            **kwargs: Remaining keyword args are passed to draw_networkx. Notably, "ax"
+                can be used to draw the graph onto an existing matploblib Axis object.
         """
         try:
             import matplotlib  # noqa: F401
@@ -295,6 +304,24 @@ class NetworkxGraph(AbstractGraph):
         except StopIteration:  # no alias for module or parent module
             return module_name
 
+    def _assert_node_exists(self, node: Node) -> None:
+        """Raises ModuleUnknown with a diagnostic message if node is absent from the graph.
+
+        Args:
+            node: the node to check for existence
+        """
+        if not self._graph.has_node(node):
+            raise ModuleUnknown(
+                f"'{node}' was not found in the dependency graph.\n"
+                "If it is an external library, ensure "
+                "'exclude_external_libraries=False' is passed to "
+                "'get_evaluable_architecture()'.\n"
+                "If this flag is already set, the module may not be "
+                "imported by any code in the scanned source path.\n"
+                "Verify the module name is correct as it would appear "
+                "in a Python import statement."
+            )
+
     def _flatten_graph_node(self, node: Node) -> Node:
         """Limits the depth of the graph by aggregating sub modules above a certain limit.
         Args:

{pytestarch-4.0.0 → pytestarch-5.0.0}/src/pytestarch/eval_structure/utils.py

@@ -10,8 +10,12 @@ from pytestarch.eval_structure.evaluable_architecture import (
 from pytestarch.eval_structure.evaluable_structures import AbstractNode
 
 
+def to_module(node: AbstractNode) -> Module:
+    return Module(identifier=node)
+
+
 def to_modules(nodes: list[AbstractNode]) -> list[Module]:
-    return list(map(lambda node: Module(identifier=node), nodes))
+    return list(map(to_module, nodes))
 
 
 def filter_to_module(filter: ModuleFilter) -> Module:

{pytestarch-4.0.0 → pytestarch-5.0.0}/src/pytestarch/eval_structure_generation/file_import/parser.py

@@ -51,8 +51,7 @@ class Parser:
         """Converts a given python file to an ast module and its name."""
         absolute_path = path.resolve()
         if self._file_should_be_parsed(absolute_path):
-            with open(absolute_path) as file:
-                code = file.read()
+            code = absolute_path.read_bytes()
 
             module_name = self._get_module_name(path)
             self._all_modules.append(module_name)

{pytestarch-4.0.0 → pytestarch-5.0.0}/src/pytestarch/pytestarch.py

@@ -22,8 +22,8 @@ DEFAULT_EXCLUSIONS = ("*__pycache__*",)
 
 
 def get_evaluable_architecture(
-    root_path: str,
-    module_path: str,
+    root_path: str | Path,
+    module_path: str | Path,
     exclusions: tuple[str, ...] = DEFAULT_EXCLUSIONS,
     exclude_external_libraries: bool = True,
     level_limit: int | None = None,
@@ -44,7 +44,7 @@ def get_evaluable_architecture(
             modules one level below the module path to be added as nodes. Note that this only applies to the final graph;
             all modules will be parsed, the graph will simply be flattened: if a submodule of X imports Y, this import is
             then assigned to X instead, if Y is above the level limit.
-        regex_exclusions: Proper regex version of 'exclusions'. Can only be specified if regex_exclusions is not specified.
+        regex_exclusions: Proper regex version of 'exclusions'. Can only be specified if exclusions is not specified.
         regex_external_exclusions: Proper regex version of 'external_exclusions' to exclude certain external dependencies from being integrated into the evaluable. Can only be specified if exclude_external_libraries is False and external_exclusions is not specified. If a parent module (e.g. 'logging') is excluded, so will be child modules (e.g. 'logging.handlers').
     """
     if regex_exclusions and exclusions:

{pytestarch-4.0.0 → pytestarch-5.0.0}/src/pytestarch/query_language/base_language.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 from abc import ABC, abstractmethod
 from pathlib import Path
-from typing import Generic, TypeVar, Union
+from typing import Generic, TypeVar
 
 from pytestarch.eval_structure.evaluable_architecture import EvaluableArchitecture
 from pytestarch.utils.decorators import deprecated
@@ -247,7 +247,7 @@ LayerSpecificationSuccessor = TypeVar(
     "LayerSpecificationSuccessor", LayerBehaviorSpecification, RuleApplier
 )
 
-InputTypes = TypeVar("InputTypes", str, Union[str, list[str]])
+InputTypes = TypeVar("InputTypes", str, str | list[str])
 
 
 class LayerSpecification(Generic[LayerSpecificationSuccessor, InputTypes], ABC):
@@ -258,7 +258,7 @@ class LayerSpecification(Generic[LayerSpecificationSuccessor, InputTypes], ABC):
         pass
 
 
-class LayerRuleObject(LayerSpecification[RuleApplier, Union[str, list[str]]], ABC):
+class LayerRuleObject(LayerSpecification[RuleApplier, str | list[str]], ABC):
     pass
 
 

{pytestarch-4.0.0 → pytestarch-5.0.0}/src/pytestarch/query_language/layered_architecture_rule.py

@@ -54,7 +54,7 @@ class LayeredArchitecture(BaseLayeredArchitecture, LayerName, LayerDefinition):
 
         if underspecified_layers:
             raise ImproperlyConfigured(
-                f'Specify the modules of layer(s) {", ".join(underspecified_layers)} first.'
+                f"Specify the modules of layer(s) {', '.join(underspecified_layers)} first."
             )
 
         if name in self._modules_by_layer_name:
@@ -94,7 +94,7 @@ class LayeredArchitecture(BaseLayeredArchitecture, LayerName, LayerDefinition):
 
         if duplicates:
             raise ImproperlyConfigured(
-                f'Module(s) {", ".join(duplicates)} already assigned to a layer.'
+                f"Module(s) {', '.join(duplicates)} already assigned to a layer."
             )
 
         self._modules_by_layer_name[layers_without_modules[0]] = (
@@ -124,7 +124,7 @@ class LayeredArchitecture(BaseLayeredArchitecture, LayerName, LayerDefinition):
             f"Layer {layer}: [{', '.join(map(lambda m: m.identifier, modules))}]"
             for layer, modules in self._modules_by_layer_name.items()
         ]
-        return f'Layered Architecture: {"; ".join(layers)}'
+        return f"Layered Architecture: {'; '.join(layers)}"
 
     def __getitem__(self, layer: str) -> Sequence[ModuleFilter]:
         return self._modules_by_layer_name[layer]
@@ -146,8 +146,8 @@ class LayerRule(
     LayerSpecification,
     LayerBase,
 ):
-    """Represents an architectural rule of the form
-    Layer X [verb, such as 'should'] [access type, such as 'be accessed by'] Layer Y
+    r"""Represents an architectural rule of the form
+    Layer X \[verb, such as 'should'\] \[access type, such as 'be accessed by'\] Layer Y
     The modules that each layer contains are to be specified via a LayeredArchitecture object.
     """
 

{pytestarch-4.0.0 → pytestarch-5.0.0}/src/pytestarch/query_language/rule.py

@@ -1,8 +1,7 @@
 from __future__ import annotations
 
-from collections.abc import Sequence
+from collections.abc import Callable, Sequence
 from dataclasses import dataclass, replace
-from typing import Callable
 
 from pytestarch.eval_structure.evaluable_architecture import (
     EvaluableArchitecture,
@@ -54,8 +53,8 @@ class Rule(
     RuleSubject,
     RuleApplier,
 ):
-    """Represents an architectural rule of the form
-    Module1 [verb, such as 'should'] [import type, such as 'import'] Module2
+    r"""Represents an architectural rule of the form
+    Module1 \[verb, such as 'should'\] \[import type, such as 'import'\] Module2
     """
 
     def __init__(
@@ -85,6 +84,18 @@ class Rule(
         return self
 
     def are_named(self, names: str | Sequence[str]) -> BehaviorSpecification:  # type: ignore
+        # Check for wildcard usage and suggest alternative
+        if isinstance(names, str):
+            if "*" in names:
+                raise ImproperlyConfigured(
+                    f'Wildcard "*" detected in module name "{names}". Use "have_name_matching" with a regex pattern instead.'
+                )
+        else:
+            for name in names:
+                if "*" in name:
+                    raise ImproperlyConfigured(
+                        f'Wildcard "*" detected in module name "{name}". Use "have_name_matching" with a regex pattern instead.'
+                    )
         self._set_modules(names, lambda name: ModuleNameFilter(name=name))
         return self
 
@@ -133,11 +144,7 @@ class Rule(
         for module, name_is_regex in modules:
             module_names.append(module)
             module_creation_fn.append(
-                lambda name: (
-                    ModuleNameFilter(name=name)
-                    if not name_is_regex
-                    else ModuleNameRegexFilter(name=name)
-                )
+                ModuleNameRegexFilter if name_is_regex else ModuleNameFilter
             )
 
         self._append_modules(module_names, module_creation_fn)
@@ -229,7 +236,7 @@ class Rule(
     def __str__(self) -> str:
         self._assert_required_configuration_present()
 
-        method_name = f'{"should" if self._configuration.should else "should only" if self._configuration.should_only else "should not"}'
+        method_name = f"{'should' if self._configuration.should else 'should only' if self._configuration.should_only else 'should not'}"
 
         subject_prefix = (
             "Sub modules of "
@@ -239,7 +246,7 @@ class Rule(
         if self._configuration.rule_object_anything:
             object_message = "anything "
         else:
-            object_message = f'modules that are {"sub modules of" if self._configuration.modules_to_check_against[0].identifier_is_parent_module else "named"} '  # type: ignore
+            object_message = f"modules that are {'sub modules of' if self._configuration.modules_to_check_against[0].identifier_is_parent_module else 'named'} "  # type: ignore
 
         combined_rule_subjects = self._combine_names(
             self._configuration.modules_to_check  # type: ignore
@@ -250,8 +257,8 @@ class Rule(
         return (
             f'{subject_prefix}"{combined_rule_subjects}" '
             f"{method_name} "
-            f'{"import" if self._configuration.import_ else "be imported by"} '
-            f'{"modules except " if self._configuration.except_present else ""}'
+            f"{'import' if self._configuration.import_ else 'be imported by'} "
+            f"{'modules except ' if self._configuration.except_present else ''}"
             f"{object_message}"
             f'"{combined_rule_objects}".'
         )
@@ -288,9 +295,7 @@ class Rule(
                 object_message,
             ]
 
-            error_message = (
-                f"Specify {', '.join(filter(lambda m: len(m) > 0, messages))}."
-            )
+            error_message = f"Specify {', '.join(filter(None, messages))}."
 
             raise ImproperlyConfigured(error_message)
 

{pytestarch-4.0.0 → pytestarch-5.0.0}/src/pytestarch/rule_assessment/error_message/message_generator.py

@@ -219,14 +219,6 @@ class RuleViolationMessageGenerator(RuleViolationMessageBaseGenerator):
 
         return rule_objects_for_rule_subject, violating_rule_subjects
 
-    def _convert_to_names(
-        self, violating_dependencies: list[Dependency]
-    ) -> list[tuple[str, str]]:
-        return [
-            (dependency[0].identifier, dependency[1].identifier)
-            for dependency in violating_dependencies
-        ]
-
     def _create_should_only_import_violated_messages(
         self, rule_violations: RuleViolations
     ) -> list[RuleViolatedMessage]:

{pytestarch-4.0.0 → pytestarch-5.0.0}/src/pytestarch/rule_assessment/rule_check/rule_matcher.py

@@ -256,6 +256,6 @@ class LayerRuleMatcher(RuleMatcher):
                 )
 
             else:
-                result = result + module_name_conversion_mapping[module.identifier]
+                result.extend(module_name_conversion_mapping.get(module.identifier, []))
 
         return result

{pytestarch-4.0.0 → pytestarch-5.0.0}/src/pytestarch/rule_assessment/rule_check/rule_violation_detector.py

@@ -241,10 +241,16 @@ class RuleViolationDetector(RuleViolationBaseDetector):
     this class decides whether any of the requirements have been violated and how.
 
     ExplicitlyRequestedDependenciesByBaseModules follow this structure:
+
+    ```
     {(requested dependency, e.g. from A to B): [list of dependencies found that qualifiy as the requested dependency, e.g. A.a1 imports B, A.a2 imports B]}
+    ```
 
     NotExplicitlyRequestedDependenciesByBaseModule on the other hand are structured like this:
-    {Module for which not explicitly requested dependencies (either from or to this module) were found: [list of such dependencies]}.
+
+    ```
+    {Module for which not explicitly requested dependencies (either from or to this module) were found: [list of such dependencies]}
+    ```
 
     The output is a rule violation object which for each type of rule contains a list of (rule subject, rule object) modules which violate the rule. These are ordered according
     to the order the user used when specifying the rule, i.e. the rule subject is the original rule subject no matter if the rule is an import

pytestarch-4.0.0/PKG-INFO

@@ -1,77 +0,0 @@
-Metadata-Version: 2.3
-Name: PyTestArch
-Version: 4.0.0
-Summary: Test framework for software architecture based on imports between modules
-License: Apache-2.0
-Keywords: architecture,test
-Author: zyskarch
-Author-email: zyskarch@gmail.com
-Maintainer: zyskarch
-Maintainer-email: zyskarch@gmail.com
-Requires-Python: >=3.9
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.9
-Classifier: License :: OSI Approved :: Apache Software License
-Classifier: Operating System :: OS Independent
-Classifier: Intended Audience :: Developers
-Classifier: Topic :: Software Development :: Testing
-Classifier: Topic :: Software Development :: Testing :: Unit
-Provides-Extra: visualization
-Requires-Dist: matplotlib (>=3.9) ; extra == "visualization"
-Requires-Dist: networkx (>=3.2)
-Project-URL: Documentation, https://zyskarch.github.io/pytestarch/latest
-Project-URL: Repository, https://github.com/zyskarch/pytestarch
-Project-URL: issues, https://github.com/zyskarch/pytestarch/issues
-Description-Content-Type: text/markdown
-
-# Welcome to PyTestArch
-
-PyTestArch is an open source library that allows users to define architectural rules and test their code against them. It is 
-generally inspired by [ArchUnit](https://www.archunit.org/).
-
-## Installation Guide
-PyTestArch is available via [PyPI](https://pypi.org/project/pytestarch/) and can be installed e.g. via pip: `pip install pytestarch`. To also install the
-optional dependency matplotlib, which is required to draw the created dependency graphs, install `pytestarch[visualization]`
-
-## Usage Guide
-Three steps are required to test an architectural rule:
-
-1) Create an evaluable representation of the source code you want to test
-
-```
-from pytestarch import get_evaluable_architecture
-
-evaluable = get_evaluable_architecture("/home/dummy/project", "/home/dummy/project/src")
-```
-This will scan all python files under /home/dummy/project/src for imports and build an internal representation that can
-later be queried. The first parameter /home/dummy/project helps PyTestArch to differentiate between internal and external 
-dependencies. This evaluable can be used for multiple architectural rule checks; if you are using [pytest](https://docs.pytest.org/en/7.1.x/),
-you could use a fixture for this evaluable object.
-
-2) Define an architectural rule
-```
-from pytestarch import Rule
-
-rule = (
-    Rule() 
-    .modules_that() 
-    .are_named("project.src.moduleB") 
-    .should_not() 
-    .be_imported_by_modules_that() 
-    .are_sub_modules_of("project.src.moduleA") 
-)
-```
-
-This rule represents the architectural requirements that a module named "project.src.moduleB" should not be imported by any module
-that is a submodule of "project.src.moduleA", excluding "project.src.moduleA" itself.
-
-3) Evaluate your code against this rule
-
-```
-rule.assert_applies(evaluable)
-```
-That's it!
-

pytestarch-4.0.0/README.md

@@ -1,47 +0,0 @@
-# Welcome to PyTestArch
-
-PyTestArch is an open source library that allows users to define architectural rules and test their code against them. It is 
-generally inspired by [ArchUnit](https://www.archunit.org/).
-
-## Installation Guide
-PyTestArch is available via [PyPI](https://pypi.org/project/pytestarch/) and can be installed e.g. via pip: `pip install pytestarch`. To also install the
-optional dependency matplotlib, which is required to draw the created dependency graphs, install `pytestarch[visualization]`
-
-## Usage Guide
-Three steps are required to test an architectural rule:
-
-1) Create an evaluable representation of the source code you want to test
-
-```
-from pytestarch import get_evaluable_architecture
-
-evaluable = get_evaluable_architecture("/home/dummy/project", "/home/dummy/project/src")
-```
-This will scan all python files under /home/dummy/project/src for imports and build an internal representation that can
-later be queried. The first parameter /home/dummy/project helps PyTestArch to differentiate between internal and external 
-dependencies. This evaluable can be used for multiple architectural rule checks; if you are using [pytest](https://docs.pytest.org/en/7.1.x/),
-you could use a fixture for this evaluable object.
-
-2) Define an architectural rule
-```
-from pytestarch import Rule
-
-rule = (
-    Rule() 
-    .modules_that() 
-    .are_named("project.src.moduleB") 
-    .should_not() 
-    .be_imported_by_modules_that() 
-    .are_sub_modules_of("project.src.moduleA") 
-)
-```
-
-This rule represents the architectural requirements that a module named "project.src.moduleB" should not be imported by any module
-that is a submodule of "project.src.moduleA", excluding "project.src.moduleA" itself.
-
-3) Evaluate your code against this rule
-
-```
-rule.assert_applies(evaluable)
-```
-That's it!

pytestarch-4.0.0/src/pytestarch/eval_structure/exceptions.py

@@ -1,9 +0,0 @@
-from __future__ import annotations
-
-
-class ImpossibleMatch(Exception):
-    pass
-
-
-class LayerMismatch(Exception):
-    pass