pytestarch 3.0.0__tar.gz → 3.1.0__tar.gz

{pytestarch-3.0.0 → pytestarch-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pytestarch
-Version: 3.0.0
+Version: 3.1.0
 Summary: Test framework for software architecture based on imports between modules
 Home-page: https://github.com/zyskarch/pytestarch
 License: Apache-2.0

{pytestarch-3.0.0 → pytestarch-3.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "PyTestArch"
-version = "3.0.0"
+version = "3.1.0"
 description = "Test framework for software architecture based on imports between modules"
 authors = ["zyskarch <zyskarch@gmail.com>"]
 maintainers = ["zyskarch <zyskarch@gmail.com>"]

{pytestarch-3.0.0 → pytestarch-3.1.0}/setup.py

@@ -28,7 +28,7 @@ extras_require = \
 
 setup_kwargs = {
     'name': 'pytestarch',
-    'version': '3.0.0',
+    'version': '3.1.0',
     'description': 'Test framework for software architecture based on imports between modules',
     'long_description': '# Welcome to PyTestArch\n\nPyTestArch is an open source library that allows users to define architectural rules and test their code against them. It is \ngenerally inspired by [ArchUnit](https://www.archunit.org/).\n\n## Installation Guide\nPyTestArch is available via [PyPI](https://pypi.org/project/pytestarch/) and can be installed e.g. via pip: `pip install pytestarch`. To also install the\noptional dependency matplotlib, which is required to draw the created dependency graphs, install `pytestarch[visualization]`\n\n## Usage Guide\nThree steps are required to test an architectural rule:\n\n1) Create an evaluable representation of the source code you want to test\n\n```\nfrom pytestarch import get_evaluable_architecture\n\nevaluable = get_evaluable_architecture("/home/dummy/project", "/home/dummy/project/src")\n```\nThis will scan all python files under /home/dummy/project/src for imports and build an internal representation that can\nlater be queried. The first parameter /home/dummy/project helps PyTestArch to differentiate between internal and external \ndependencies. This evaluable can be used for multiple architectural rule checks; if you are using [pytest](https://docs.pytest.org/en/7.1.x/),\nyou could use a fixture for this evaluable object.\n\n2) Define an architectural rule\n```\nfrom pytestarch import Rule\n\nrule = (\n    Rule() \n    .modules_that() \n    .are_named("project.src.moduleB") \n    .should_not() \n    .be_imported_by_modules_that() \n    .are_sub_modules_of("project.src.moduleA") \n)\n```\n\nThis rule represents the architectural requirements that a module named "project.src.moduleB" should not be imported by any module\nthat is a submodule of "project.src.moduleA", excluding "project.src.moduleA" itself.\n\n3) Evaluate your code against this rule\n\n```\nrule.assert_applies(evaluable)\n```\nThat\'s it!\n',
     'author': 'zyskarch',

{pytestarch-3.0.0 → pytestarch-3.1.0}/src/pytestarch/diagram_extension/diagram_parser.py

@@ -25,18 +25,18 @@ class Module:
 PUML_START_MARKER = "@startuml"
 PUML_END_MARKER = "@enduml"
 ANYTHING = ".*"
-ANY_ARROW_TEXT = "(-?|\w+-)"  # noqa: W605
+ANY_ARROW_TEXT = r"(-?|\w+-)"
 NON_EMPTY_STRING = ".+"
 COMPONENT_MARKER = "component"
-NON_EMPTY_WHITESPACE = "\s+"  # noqa: W605
-NON_EMPTY_CHAR_OR_DIGIT = "(\w|\d)+"  # noqa: W605
-NON_EMPTY_CHAR_OR_DIGIT_OR_WHITESPACE = "(\w|\d|\s)+"  # noqa: W605
+NON_EMPTY_WHITESPACE = r"\s+"
+NON_EMPTY_CHAR_OR_DIGIT = r"(\w|\d)+"
+NON_EMPTY_CHAR_OR_DIGIT_OR_WHITESPACE = r"(\w|\d|\s)+"
 START_LINE = "^"
 END_LINE = "$"
-BRACKET_OPEN = "\["  # noqa: W605
-BRACKET_CLOSE = "\]"  # noqa: W605
-OPTIONAL_BRACKET_OPEN = "(\[)?"  # noqa: W605
-OPTIONAL_BRACKET_CLOSE = "(\])?"  # noqa: W605
+BRACKET_OPEN = r"\["
+BRACKET_CLOSE = r"\]"
+OPTIONAL_BRACKET_OPEN = r"(\[)?"
+OPTIONAL_BRACKET_CLOSE = r"(\])?"
 ALIAS_MARKER = "as"
 ARROW_BODY = "-"
 ARROW_HEAD_LEFT = "<"

{pytestarch-3.0.0 → pytestarch-3.1.0}/src/pytestarch/eval_structure_generation/file_import/config.py

@@ -10,6 +10,7 @@ class Config:
     Attributes:
         excluded_directories: Directory paths not to include in parsing specified via regex. Can be used to exclude
         e.g. test directories.
+        excluded_external_dependencies: All external dependencies matching these patterns shall be excluded.
     """
 
     excluded_directories: tuple[str, ...]

pytestarch-3.1.0/src/pytestarch/eval_structure_generation/file_import/file_filter.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import re
+from functools import singledispatchmethod
+from pathlib import Path
+
+from pytestarch.eval_structure_generation.file_import.config import Config
+
+ALL_MARKER = "*"
+
+
+class FileFilter:
+    """Uses a regex pattern to determine whether a file or directory should be excluded."""
+
+    def __init__(self, config: Config) -> None:
+        self._excluded_directories = [
+            re.compile(directory_pattern)
+            for directory_pattern in config.excluded_directories
+        ]
+
+    @singledispatchmethod
+    def is_excluded(self, obj: str | Path) -> bool:
+        """Returns True if the object matches one of the pre-configured exclusion patterns."""
+        raise NotImplementedError
+
+    @is_excluded.register(Path)
+    def _(self, obj: Path) -> bool:
+        path_as_str = str(obj)
+
+        return self.is_excluded(path_as_str)
+
+    @is_excluded.register(str)
+    def _(self, obj: str) -> bool:
+        return any(
+            re.match(pattern, obj) is not None for pattern in self._excluded_directories
+        )
+
+    def has_filter(self) -> bool:
+        return len(self._excluded_directories) > 0

pytestarch-3.1.0/src/pytestarch/eval_structure_generation/file_import/import_filter.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from pytestarch.eval_structure.types import Import
+from pytestarch.eval_structure_generation.file_import.config import Config
+from pytestarch.eval_structure_generation.file_import.file_filter import FileFilter
+
+
+class ExternalImportFilter:
+    """Filters out imports of (some) external modules from the list of all imports.
+    External modules are all modules that are not submodules of the configured module to search for imports.
+
+    Two possibilities: either all external modules are filtered out, or only those matching given regex patterns.
+    """
+
+    def __init__(
+        self,
+        exclude_external_libraries: bool,
+        root_module_name: str,
+        external_exclusions: tuple[str, ...],
+    ) -> None:
+        """
+        Args:
+            exclude_external_libraries: If True, external modules will be filtered out, otherwise this class implements a no-op.
+            root_module_name: name of the module that determines which modules are considered external. If a module
+                is a submodule of this module, it is considered internal.
+            external_exclusions: regex pattern: all external modules that match it shall be filtered out.
+        """
+        self._exclude_external_libraries = exclude_external_libraries
+        self._root_module_name = root_module_name
+        self._external_exclusion_filter = FileFilter(Config(external_exclusions))
+
+    def filter(self, imports: Sequence[Import]) -> Sequence[Import]:
+        """According to the configuration, imports will be filtered.
+
+        Args:
+            imports: list of imports to be filtered
+        Returns:
+            filtered list of imports
+        """
+        if (
+            not self._exclude_external_libraries
+            and not self._external_exclusion_filter.has_filter()
+        ):
+            return imports
+
+        # is this is set, then _exclude_external_libraries is False, as asserted by previously executed code
+        if self._external_exclusion_filter.has_filter():
+            return [
+                i for i in imports if self._is_internal_or_retained_external_import(i)
+            ]
+
+        return [i for i in imports if self._is_internal_import(i)]
+
+    def _is_internal_import(self, i: Import) -> bool:
+        importee = i.importee()
+
+        return importee.startswith(self._root_module_name)
+
+    def _is_internal_or_retained_external_import(self, i: Import) -> bool:
+        if self._is_internal_import(i):
+            return True
+
+        importee = i.importee()
+
+        excluded = self._external_exclusion_filter.is_excluded(importee)
+        any_parent_excluded = any(
+            self._external_exclusion_filter.is_excluded(parent)
+            for parent in i.importee_parent_modules()
+        )
+        return not (excluded or any_parent_excluded)

{pytestarch-3.0.0 → pytestarch-3.1.0}/src/pytestarch/eval_structure_generation/graph_generation/graph_generator.py

@@ -10,7 +10,9 @@ from pytestarch.eval_structure.types import Import
 from pytestarch.eval_structure_generation.file_import.config import Config
 from pytestarch.eval_structure_generation.file_import.converter import ImportConverter
 from pytestarch.eval_structure_generation.file_import.file_filter import FileFilter
-from pytestarch.eval_structure_generation.file_import.import_filter import ImportFilter
+from pytestarch.eval_structure_generation.file_import.import_filter import (
+    ExternalImportFilter,
+)
 from pytestarch.eval_structure_generation.file_import.import_types import NamedModule
 from pytestarch.eval_structure_generation.file_import.importee_module_calculator import (
     ImporteeModuleCalculator,
@@ -36,6 +38,7 @@ def generate_graph(
     exclusions: tuple[str, ...],
     exclude_external_libraries: bool,
     level_limit: int | None,
+    external_exclusions: tuple[str, ...] | None,
 ) -> EvaluableArchitectureGraph:
     level_limit = _add_extra_levels_to_limit_if_root_and_module_path_differ(
         level_limit,
@@ -56,12 +59,15 @@ def generate_graph(
         _get_all_internal_modules(all_modules, internal_module_prefix),
     )
 
+    if external_exclusions is None:
+        external_exclusions = ()
+
     imports = _remove_excluded_imports(
-        exclude_external_libraries, imports, internal_module_prefix
+        exclude_external_libraries, imports, internal_module_prefix, external_exclusions
     )
 
     all_modules = _append_external_modules_to_module_list(
-        all_modules, exclude_external_libraries, imports, root_path
+        all_modules, exclude_external_libraries, imports, root_path, external_exclusions
     )
     return EvaluableArchitectureGraph(NetworkxGraph(all_modules, imports, level_limit))
 
@@ -71,24 +77,36 @@ def _append_external_modules_to_module_list(
     exclude_external_libraries: bool,
     imports: Sequence[Import],
     root_path: Path,
+    external_exclusions: tuple[str, ...],
 ) -> list[Node]:
     """External modules are not detected as modules when importing the source folder - but they will of course show up
     in the imports. To ensure that all edges in the graph have nodes attached, the external modules need to be added to
     the list of modules/nodes."""
-    if not exclude_external_libraries:
-        all_modules = ImporteeModuleCalculator(root_path).calculate_importee_modules(
-            imports,
-            all_modules,
-        )
-    return all_modules
+    if exclude_external_libraries:
+        return all_modules
+
+    all_modules = ImporteeModuleCalculator(root_path).calculate_importee_modules(
+        imports,
+        all_modules,
+    )
+
+    file_filter = FileFilter(Config(external_exclusions))
+
+    if not file_filter.has_filter():
+        return all_modules
+
+    return [module for module in all_modules if not file_filter.is_excluded(module)]
 
 
 def _remove_excluded_imports(
     exclude_external_libraries: bool,
     imports: Sequence[Import],
     internal_module_prefix: str,
+    external_exclusions: tuple[str, ...],
 ) -> Sequence[Import]:
-    import_filter = ImportFilter(exclude_external_libraries, internal_module_prefix)
+    import_filter = ExternalImportFilter(
+        exclude_external_libraries, internal_module_prefix, external_exclusions
+    )
     return import_filter.filter(imports)
 
 
@@ -139,7 +157,9 @@ def _get_imports_from_ast(
 
 
 def _get_all_ast_modules(
-    module_path: Path, root_path: Path, exclusions: tuple[str, ...]
+    module_path: Path,
+    root_path: Path,
+    exclusions: tuple[str, ...],
 ) -> tuple[list[str], list[NamedModule]]:
     config = Config(exclusions)
     file_filter = FileFilter(config)

{pytestarch-3.0.0 → pytestarch-3.1.0}/src/pytestarch/pytestarch.py

@@ -28,32 +28,52 @@ def get_evaluable_architecture(
     exclude_external_libraries: bool = True,
     level_limit: int | None = None,
     regex_exclusions: tuple[str, ...] | None = None,
+    external_exclusions: tuple[str, ...] | None = None,
+    regex_external_exclusions: tuple[str, ...] | None = None,
 ) -> EvaluableArchitecture:
     """Constructs an evaluable object based on the given module.
 
     Args:
         root_path: root directory of the source code. Should not be set to a submodule of the top level module.
         module_path: path of module to generate the evaluable for. Must be a submodule of the root_path module.
-        exclusions: pseudo-regex to exclude files and directories from being integrated into the evaluable, e.g. *Test.py
+        exclusions: pseudo-regex to exclude files and directories from being integrated into the evaluable, e.g. *Test.py. Can only be specified if regex_exclusions is not specified.
+        external_exclusions: pseudo-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 regex_external_exclusions is not specified. Note that child dependencies are not automatically excluded, e.g. if exclusion regex is 'logging', then 'logging.handler' will not be excluded. For exclude this as well, use 'logging.*'.
         exclude_external_libraries: if True, external dependencies (defined as all dependencies to module outside the
-            module_path, including Python built-in modules) will not be taken into account for the dependency analysis.
-            Can only be specified if regex_exclusions is not specified.
+            module_path, including Python built-in modules) will not be taken into account for the dependency analysis. If a parent module (e.g. 'logging') is excluded, so will be child modules (e.g. 'logging.handlers').
         level_limit: if not None, specifies the depth of the graph. For example, a limit of 1 will result in only the
             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_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:
         raise ImproperlyConfigured(
             "Partial match exclusions and regex exclusions cannot both be specified."
         )
 
+    if regex_external_exclusions and external_exclusions:
+        raise ImproperlyConfigured(
+            "Partial match external_exclusions and regex external_exclusions cannot both be specified."
+        )
+
+    if exclude_external_libraries and (
+        external_exclusions or regex_external_exclusions
+    ):
+        raise ImproperlyConfigured(
+            "If external libraries are excluded, no exclusion patterns can be defined for them."
+        )
+
     if exclusions:
         regex_exclusions = tuple(
             convert_partial_match_to_regex(pattern) for pattern in exclusions
         )
 
+    if external_exclusions:
+        regex_external_exclusions = tuple(
+            convert_partial_match_to_regex(pattern) for pattern in external_exclusions
+        )
+
     root_as_path = Path(root_path)
     module_as_path = Path(module_path)
 
@@ -68,6 +88,7 @@ def get_evaluable_architecture(
         regex_exclusions,  # type: ignore
         exclude_external_libraries,
         level_limit,
+        regex_external_exclusions,
     )
 
 
@@ -78,6 +99,8 @@ def get_evaluable_architecture_for_module_objects(
     exclude_external_libraries: bool = True,
     level_limit: int | None = None,
     regex_exclusions: tuple[str, ...] | None = None,
+    external_exclusions: tuple[str, ...] | None = None,
+    regex_external_exclusions: tuple[str, ...] | None = None,
 ) -> EvaluableArchitecture:
     """Same functionality as get_evaluable_architecture, but root module and module to evaluate are passed in as module objects
     instead of the absolute paths to them.
@@ -92,4 +115,6 @@ def get_evaluable_architecture_for_module_objects(
         exclude_external_libraries,
         level_limit,
         regex_exclusions,
+        external_exclusions,
+        regex_external_exclusions,
     )

{pytestarch-3.0.0 → pytestarch-3.1.0}/src/pytestarch/utils/partial_match_to_regex_converter.py

@@ -16,7 +16,7 @@ def convert_partial_match_to_regex(match: str) -> str:
     Returns:
         Regex version of the partial match string. This means that the partial match characters * have been replaced
         by their regex equivalent .* and the rest of the string has been escaped to not contain any characters that
-        have a special meaning in a regex. In addition, $ will be added at the end if no * was present their before.
+        have a special meaning in a regex. In addition, $ will be added at the end if no * was present there before.
         This is done because partial matches are used as full string matches, unless * is present at the end.
     """
     all_at_start = match.startswith(PARTIAL_MATCH_ALL_MARKER)

pytestarch-3.0.0/src/pytestarch/eval_structure_generation/file_import/file_filter.py

@@ -1,34 +0,0 @@
-from __future__ import annotations
-
-import re
-from pathlib import Path
-
-from pytestarch.eval_structure_generation.file_import.config import Config
-
-ALL_MARKER = "*"
-
-
-class FileFilter:
-    """Uses a pseudo-regex pattern to determine whether a file or directory should be excluded.
-
-    Allowed patterns are:
-    - *A*: file or dir will be excluded, if 'A' is part of their name
-    - *A: file or dir will be excluded, if their name ends with 'A'
-    - A*: file or dir will be excluded, if their name starts with 'A'
-    - A: file or dir will be excluded, if their name is 'A'
-    """
-
-    def __init__(self, config: Config) -> None:
-        self._excluded_directories = [
-            re.compile(directory_pattern)
-            for directory_pattern in config.excluded_directories
-        ]
-
-    def is_excluded(self, path: Path) -> bool:
-        """Returns True if the path matches one of the pre-configured exclusion patterns."""
-        path_as_str = str(path)
-
-        return any(
-            re.match(pattern, path_as_str) is not None
-            for pattern in self._excluded_directories
-        )

pytestarch-3.0.0/src/pytestarch/eval_structure_generation/file_import/import_filter.py

@@ -1,39 +0,0 @@
-from __future__ import annotations
-
-from collections.abc import Sequence
-
-from pytestarch.eval_structure.types import Import
-
-
-class ImportFilter:
-    """Filters out imports of external modules from the list of all imports.
-    External modules are all modules that are not submodules of the configured module to search for imports.
-    """
-
-    def __init__(self, exclude_external_libraries: bool, root_module_name: str) -> None:
-        """
-        Args:
-            exclude_external_libraries: If True, external modules will be filtered out, otherwise this class implements a no-op.
-            root_module_name: name of the module that determines which modules are considered external. If a module
-                is a submodule of this module, it is considered internal.
-        """
-        self._exclude_external_libraries = exclude_external_libraries
-        self._root_module_name = root_module_name
-
-    def filter(self, imports: Sequence[Import]) -> Sequence[Import]:
-        """According to the configuration, imports will be filtered.
-
-        Args:
-            imports: list of imports to be filtered
-        Returns:
-            filtered list of imports
-        """
-        if not self._exclude_external_libraries:
-            return imports
-
-        return [i for i in imports if self._is_internal_import(i)]
-
-    def _is_internal_import(self, i: Import) -> bool:
-        importee = i.importee()
-
-        return importee.startswith(self._root_module_name)