archunitpython 1.6.1__tar.gz → 1.8.0__tar.gz

{archunitpython-1.6.1 → archunitpython-1.8.0}/BACKLOG.md

@@ -18,7 +18,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`.
+- [x] Add support for namespace packages that do not contain `__init__.py`.
 - [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.

{archunitpython-1.6.1 → archunitpython-1.8.0}/CHANGELOG.md

@@ -1,3 +1,22 @@
+# [1.8.0](https://github.com/LukasNiessen/ArchUnitPython/compare/v1.7.0...v1.8.0) (2026-09-30)
+
+
+### Features
+
+* add detailed per-check inspection and styled reports ([#65](https://github.com/LukasNiessen/ArchUnitPython/issues/65)) ([ab0f9ef](https://github.com/LukasNiessen/ArchUnitPython/commit/ab0f9efb71c90712366490121e82c09b112a5d06))
+
+# [1.7.0](https://github.com/LukasNiessen/ArchUnitPython/compare/v1.6.1...v1.7.0) (2026-09-13)
+
+
+### Bug Fixes
+
+* preserve mixed namespace import targets ([489624b](https://github.com/LukasNiessen/ArchUnitPython/commit/489624b4de5465847f6e83106cbe0a398a7c1e8e))
+
+
+### Features
+
+* resolve namespace package submodule imports ([86c53e6](https://github.com/LukasNiessen/ArchUnitPython/commit/86c53e619ad25dfcdfb109de4593967d3d5603a6))
+
 ## [1.6.1](https://github.com/LukasNiessen/ArchUnitPython/compare/v1.6.0...v1.6.1) (2026-09-13)
 
 

{archunitpython-1.6.1 → archunitpython-1.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: archunitpython
-Version: 1.6.1
+Version: 1.8.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
@@ -377,6 +377,12 @@ ArchUnitPython detects string-based dynamic imports such as `importlib.import_mo
 from my_app.adapters.sql import Repository  # archunit: ignore
 ```
 
+### Namespace Packages
+
+ArchUnitPython resolves imports from namespace packages that do not contain
+`__init__.py` files. For example, `from my_app.domain import model` is resolved
+to `my_app/domain/model.py` when `my_app/domain/` is a namespace package.
+
 ### Conditional Imports
 
 Imports inside `try` blocks that handle `ImportError` or
@@ -920,6 +926,10 @@ The most important differences:
 
 When tests fail, you get helpful output with file paths and violation details:
 
+Interactive terminals also highlight the failure summary, numbered headings,
+paths, metric values, and rule rationale. Output stays plain when redirected,
+when `CI=true`, or when `NO_COLOR` is set (even to an empty value).
+
 ```
 Found 2 architecture violation(s):
 
@@ -932,25 +942,91 @@ Found 2 architecture violation(s):
 
 ## 📝 Debug Logging & Configuration
 
-We support logging to help you understand what files are being analyzed and troubleshoot test failures. Logging is disabled by default to keep test output clean.
+Logging is disabled by default. Enable it per check to inspect file discovery,
+graph extraction and cache use, selector decisions, edge projections, class
+analysis, metric values, and the resulting violations. File, layer, slice,
+count/LCOM/distance, and custom metric checks use the same logging options.
+
+| Level | What you see |
+| --- | --- |
+| `error` | Analysis exceptions (the original exception is still raised). |
+| `warn` | Failed check summaries and every violation, plus errors. |
+| `info` | Check start, completion, duration, and violations, plus errors. |
+| `debug` | All of the above, plus rule configuration, discovered files, dependencies, cache decisions, selector matches, projected/omitted edges, classes, and measured values. |
 
 ### Enabling Debug Logging
 
 ```python
-from archunitpython import CheckOptions
-from archunitpython.common.logging.types import LoggingOptions
+from archunitpython import CheckOptions, LoggingOptions, project_files
+
+rule = project_files("src/").should().have_no_cycles()
 
 options = CheckOptions(
     logging=LoggingOptions(
         enabled=True,
         level="debug",       # "error" | "warn" | "info" | "debug"
-        log_file=True,       # Creates logs/archunit-YYYY-MM-DD_HH-MM-SS.log
+        log_file=True,       # Creates a unique timestamped file in logs/
     ),
 )
 
 violations = rule.check(options)
 ```
 
+For example, a debug trace includes entries like these (paths and timings depend
+on your project):
+
+```text
+[INFO] Starting check: CycleFreeFileCondition
+[DEBUG] Graph cache miss
+[DEBUG] Discovered file: /project/src/api.py
+[DEBUG] Processing file: /project/src/api.py
+[DEBUG] Dependency: /project/src/api.py -> /project/src/storage.py; external=False; kinds=[]
+[DEBUG] Projection: /project/src/api.py -> /project/src/storage.py becomes /project/src/api.py -> /project/src/storage.py
+[INFO] Finished check: CycleFreeFileCondition - 0 violation(s) (0.002s)
+```
+
+Console diagnostics use the standard `archunitpython` logger when handlers are
+configured, respecting their levels and formatting; otherwise they go to stderr.
+For pytest live logs, use `pytest --log-cli-level=DEBUG`. You can also configure
+Python's standard `logging` module in your application.
+
+### Save detailed inspection without console noise
+
+```python
+options = CheckOptions(logging=LoggingOptions(
+    enabled=True,
+    level="debug",
+    console=False,
+    log_file=True,
+    log_path="logs/architecture.log",
+    append_to_log_file=True,
+))
+violations = rule.check(options)
+```
+
+File logs are UTF-8, timestamped, and contain no added ANSI colors. Automatic
+paths are unique per check; an explicit `log_path` replaces that path.
+`append_to_log_file=False` overwrites an explicit file at the start of each check.
+Each check closes its own output file and isolates its diagnostics from nested
+and concurrent checks. Use separate paths when concurrent checks write to files.
+Diagnostic output is best effort: an unavailable file or failing logging handler
+does not change rule results or hide analysis exceptions. Debug inspection does
+not re-run custom predicates or metric calculations.
+
+### Format results independently of logging
+
+```python
+from archunitpython import assert_passes, format_violations
+
+print(format_violations(violations))               # Detect terminal colors
+text = format_violations(violations, color=False)  # Stable plain text for artifacts
+assert_passes(rule, options, color=False)         # Plain assertion failure
+```
+
+Pass `color=True` to explicitly request ANSI styling; `NO_COLOR` always wins.
+The numbered report, rationale, and details remain available at every log level,
+including when logging is disabled. Existing plain-text report wording is retained.
+
 ### CI Pipeline Integration
 
 ```yaml

{archunitpython-1.6.1 → archunitpython-1.8.0}/README.md

@@ -344,6 +344,12 @@ ArchUnitPython detects string-based dynamic imports such as `importlib.import_mo
 from my_app.adapters.sql import Repository  # archunit: ignore
 ```
 
+### Namespace Packages
+
+ArchUnitPython resolves imports from namespace packages that do not contain
+`__init__.py` files. For example, `from my_app.domain import model` is resolved
+to `my_app/domain/model.py` when `my_app/domain/` is a namespace package.
+
 ### Conditional Imports
 
 Imports inside `try` blocks that handle `ImportError` or
@@ -887,6 +893,10 @@ The most important differences:
 
 When tests fail, you get helpful output with file paths and violation details:
 
+Interactive terminals also highlight the failure summary, numbered headings,
+paths, metric values, and rule rationale. Output stays plain when redirected,
+when `CI=true`, or when `NO_COLOR` is set (even to an empty value).
+
 ```
 Found 2 architecture violation(s):
 
@@ -899,25 +909,91 @@ Found 2 architecture violation(s):
 
 ## 📝 Debug Logging & Configuration
 
-We support logging to help you understand what files are being analyzed and troubleshoot test failures. Logging is disabled by default to keep test output clean.
+Logging is disabled by default. Enable it per check to inspect file discovery,
+graph extraction and cache use, selector decisions, edge projections, class
+analysis, metric values, and the resulting violations. File, layer, slice,
+count/LCOM/distance, and custom metric checks use the same logging options.
+
+| Level | What you see |
+| --- | --- |
+| `error` | Analysis exceptions (the original exception is still raised). |
+| `warn` | Failed check summaries and every violation, plus errors. |
+| `info` | Check start, completion, duration, and violations, plus errors. |
+| `debug` | All of the above, plus rule configuration, discovered files, dependencies, cache decisions, selector matches, projected/omitted edges, classes, and measured values. |
 
 ### Enabling Debug Logging
 
 ```python
-from archunitpython import CheckOptions
-from archunitpython.common.logging.types import LoggingOptions
+from archunitpython import CheckOptions, LoggingOptions, project_files
+
+rule = project_files("src/").should().have_no_cycles()
 
 options = CheckOptions(
     logging=LoggingOptions(
         enabled=True,
         level="debug",       # "error" | "warn" | "info" | "debug"
-        log_file=True,       # Creates logs/archunit-YYYY-MM-DD_HH-MM-SS.log
+        log_file=True,       # Creates a unique timestamped file in logs/
     ),
 )
 
 violations = rule.check(options)
 ```
 
+For example, a debug trace includes entries like these (paths and timings depend
+on your project):
+
+```text
+[INFO] Starting check: CycleFreeFileCondition
+[DEBUG] Graph cache miss
+[DEBUG] Discovered file: /project/src/api.py
+[DEBUG] Processing file: /project/src/api.py
+[DEBUG] Dependency: /project/src/api.py -> /project/src/storage.py; external=False; kinds=[]
+[DEBUG] Projection: /project/src/api.py -> /project/src/storage.py becomes /project/src/api.py -> /project/src/storage.py
+[INFO] Finished check: CycleFreeFileCondition - 0 violation(s) (0.002s)
+```
+
+Console diagnostics use the standard `archunitpython` logger when handlers are
+configured, respecting their levels and formatting; otherwise they go to stderr.
+For pytest live logs, use `pytest --log-cli-level=DEBUG`. You can also configure
+Python's standard `logging` module in your application.
+
+### Save detailed inspection without console noise
+
+```python
+options = CheckOptions(logging=LoggingOptions(
+    enabled=True,
+    level="debug",
+    console=False,
+    log_file=True,
+    log_path="logs/architecture.log",
+    append_to_log_file=True,
+))
+violations = rule.check(options)
+```
+
+File logs are UTF-8, timestamped, and contain no added ANSI colors. Automatic
+paths are unique per check; an explicit `log_path` replaces that path.
+`append_to_log_file=False` overwrites an explicit file at the start of each check.
+Each check closes its own output file and isolates its diagnostics from nested
+and concurrent checks. Use separate paths when concurrent checks write to files.
+Diagnostic output is best effort: an unavailable file or failing logging handler
+does not change rule results or hide analysis exceptions. Debug inspection does
+not re-run custom predicates or metric calculations.
+
+### Format results independently of logging
+
+```python
+from archunitpython import assert_passes, format_violations
+
+print(format_violations(violations))               # Detect terminal colors
+text = format_violations(violations, color=False)  # Stable plain text for artifacts
+assert_passes(rule, options, color=False)         # Plain assertion failure
+```
+
+Pass `color=True` to explicitly request ANSI styling; `NO_COLOR` always wins.
+The numbered report, rationale, and details remain available at every log level,
+including when logging is disabled. Existing plain-text report wording is retained.
+
 ### CI Pipeline Integration
 
 ```yaml

{archunitpython-1.6.1 → archunitpython-1.8.0}/pyproject.toml

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

{archunitpython-1.6.1 → archunitpython-1.8.0}/src/archunitpython/__init__.py

@@ -1,12 +1,13 @@
 """ArchUnitPython - Architecture testing library for Python projects."""
 
-__version__ = "1.6.1"
+__version__ = "1.8.0"
 
 # Files API
 # Common
 from archunitpython.common import (
     CheckOptions,
     EmptyTestViolation,
+    LoggingOptions,
     TechnicalError,
     UserError,
     Violation,
@@ -50,6 +51,7 @@ __all__ = [
     "Violation",
     "EmptyTestViolation",
     "CheckOptions",
+    "LoggingOptions",
     "TechnicalError",
     "UserError",
     "extract_graph",

{archunitpython-1.6.1 → archunitpython-1.8.0}/src/archunitpython/common/extraction/extract_graph.py

@@ -9,6 +9,7 @@ from dataclasses import dataclass
 
 from archunitpython.common.extraction.graph import Edge, Graph, ImportKind
 from archunitpython.common.fluentapi.checkable import CheckOptions
+from archunitpython.common.logging.inspection import debug, debug_enabled
 
 GraphCacheKey = tuple[str, tuple[str, ...], bool]
 
@@ -45,6 +46,7 @@ class _LocatedImport:
     line_number: int
     resolution_kind: ImportKind | None = None
     fallback_module_name: str | None = None
+    aliases: tuple[str, ...] = ()
 
 
 @dataclass(frozen=True)
@@ -56,8 +58,7 @@ class _IgnoreDirective:
         if not self.modules:
             return True
         return any(
-            import_.module_name == module
-            or import_.module_name.startswith(f"{module}.")
+            import_.module_name == module or import_.module_name.startswith(f"{module}.")
             for module in self.modules
         )
 
@@ -96,21 +97,46 @@ def extract_graph(
     ignore_type_checking_imports = bool(options and options.ignore_type_checking_imports)
     cache_key = _build_cache_key(project_path, excludes, ignore_type_checking_imports)
 
+    debug(
+        "Extraction root: %s; excludes: %s; ignore type-only imports: %s",
+        project_path,
+        excludes,
+        ignore_type_checking_imports,
+    )
     if options and options.clear_cache:
+        debug("Clearing graph cache for %s", project_path)
         _graph_cache.pop(cache_key, None)
 
     if cache_key in _graph_cache:
+        debug("Graph cache hit: %d edges", len(_graph_cache[cache_key]))
+        _inspect_graph(_graph_cache[cache_key])
         return _graph_cache[cache_key]
+    debug("Graph cache miss")
 
     result = _extract_graph_uncached(
         project_path,
         excludes,
         ignore_type_checking_imports=ignore_type_checking_imports,
     )
+    _inspect_graph(result)
     _graph_cache[cache_key] = result
     return result
 
 
+def _inspect_graph(graph: Graph) -> None:
+    if not debug_enabled():
+        return
+    debug("Extracted graph: %d edges (including self-edges)", len(graph))
+    for edge in graph:
+        debug(
+            "Dependency: %s -> %s; external=%s; kinds=%s",
+            edge.source,
+            edge.target,
+            edge.external,
+            edge.import_kinds,
+        )
+
+
 def _build_cache_key(
     project_path: str,
     exclude_patterns: list[str],
@@ -166,6 +192,7 @@ def _extract_graph_uncached(
     normalized_py_file_set = {_normalize(f) for f in py_files_set}
 
     for file_path in py_files:
+        debug("Processing file: %s", file_path)
         # Add self-referencing edge (ensures the file appears as a node)
         edges.append(
             Edge(
@@ -177,39 +204,32 @@ def _extract_graph_uncached(
 
         imports = _extract_located_imports(file_path)
         for located_import in imports:
-            module_name = located_import.module_name
             import_kind = located_import.import_kind
-            if (
-                ignore_type_checking_imports
-                and import_kind == ImportKind.TYPE_IMPORT
-            ):
-                continue
-            resolution_kind = located_import.resolution_kind or import_kind
-            resolved, is_external = _resolve_import(
-                module_name, file_path, project_path, resolution_kind
-            )
-            if is_external and located_import.fallback_module_name is not None:
-                fallback, fallback_is_external = _resolve_import(
-                    located_import.fallback_module_name,
+            if ignore_type_checking_imports and import_kind == ImportKind.TYPE_IMPORT:
+                debug(
+                    "Skipped type-only import: %s:%s -> %s",
                     file_path,
-                    project_path,
-                    resolution_kind,
+                    located_import.line_number,
+                    located_import.module_name,
                 )
-                if fallback and not fallback_is_external:
-                    resolved, is_external = fallback, False
-            if resolved and resolved != _normalize(file_path):
-                # Check if the resolved path is in our project
-                if not is_external and resolved not in normalized_py_file_set:
-                    continue
-
-                edges.append(
-                    Edge(
-                        source=_normalize(file_path),
-                        target=resolved,
-                        external=is_external,
-                        import_kinds=_edge_import_kinds(located_import),
+                continue
+            for resolved, is_external in _resolve_import_targets(
+                located_import, file_path, project_path
+            ):
+                if resolved and resolved != _normalize(file_path):
+                    # Check if the resolved path is in our project
+                    if not is_external and resolved not in normalized_py_file_set:
+                        debug("Skipped excluded dependency: %s -> %s", file_path, resolved)
+                        continue
+
+                    edges.append(
+                        Edge(
+                            source=_normalize(file_path),
+                            target=resolved,
+                            external=is_external,
+                            import_kinds=_edge_import_kinds(located_import),
+                        )
                     )
-                )
 
     return _merge_edges(edges)
 
@@ -237,6 +257,7 @@ def _find_python_files(root: str, exclude: list[str]) -> list[str]:
                 full_path, root, exclude, is_dir=False
             ):
                 py_files.append(os.path.abspath(full_path))
+                debug("Discovered file: %s", full_path)
 
     return py_files
 
@@ -323,9 +344,7 @@ def _extract_located_imports(file_path: str) -> list[_LocatedImport]:
                 conditional_import_ranges,
             )
             for alias in node.names:
-                imports.append(
-                    _LocatedImport(alias.name, kind, node.lineno, syntax_kind)
-                )
+                imports.append(_LocatedImport(alias.name, kind, node.lineno, syntax_kind))
 
         elif isinstance(node, ast.ImportFrom):
             syntax_kind = (
@@ -339,17 +358,17 @@ def _extract_located_imports(file_path: str) -> list[_LocatedImport]:
                 type_checking_ranges,
                 conditional_import_ranges,
             )
-            fallback_module_name = (
-                "." * node.level if node.level and node.module is None else None
-            )
+            fallback_module_name = "." * node.level if node.level and node.module is None else None
+            aliases = _module_aliases(node) if node.module else ()
             for module_name in _import_from_module_names(node):
                 imports.append(
                     _LocatedImport(
-                        module_name,
-                        kind,
-                        node.lineno,
-                        syntax_kind,
-                        fallback_module_name,
+                        module_name=module_name,
+                        import_kind=kind,
+                        line_number=node.lineno,
+                        resolution_kind=syntax_kind,
+                        fallback_module_name=fallback_module_name,
+                        aliases=aliases,
                     )
                 )
 
@@ -362,15 +381,9 @@ def _extract_located_imports(file_path: str) -> list[_LocatedImport]:
                 conditional_import_ranges,
             )
             for module_name in _extract_dynamic_import_names(node):
-                imports.append(
-                    _LocatedImport(module_name, kind, node.lineno, syntax_kind)
-                )
+                imports.append(_LocatedImport(module_name, kind, node.lineno, syntax_kind))
 
-    return [
-        import_
-        for import_ in imports
-        if not _is_ignored_import(import_, ignore_directives)
-    ]
+    return [import_ for import_ in imports if not _is_ignored_import(import_, ignore_directives)]
 
 
 def _find_ignore_directives(source: str) -> dict[int, _IgnoreDirective]:
@@ -429,6 +442,11 @@ def _extract_dynamic_import_names(node: ast.Call) -> list[str]:
     return []
 
 
+def _module_aliases(node: ast.ImportFrom) -> tuple[str, ...]:
+    """Return aliases that may refer to imported submodules."""
+    return tuple(alias.name for alias in node.names if alias.name != "*")
+
+
 def _import_from_module_names(node: ast.ImportFrom) -> tuple[str, ...]:
     """Return resolvable module names for a from-import statement."""
     dots = "." * (node.level or 0)
@@ -558,14 +576,10 @@ def _resolve_import(
     Returns (resolved_path, is_external).
     The path is normalized with forward slashes.
     """
-    if (
-        kind
-        in (
-            ImportKind.RELATIVE_IMPORT,
-            ImportKind.TYPE_IMPORT,
-        )
-        and import_name.startswith(".")
-    ):
+    if kind in (
+        ImportKind.RELATIVE_IMPORT,
+        ImportKind.TYPE_IMPORT,
+    ) and import_name.startswith("."):
         # Relative import
         return _resolve_relative_import(import_name, source_file, project_root)
 
@@ -573,6 +587,58 @@ def _resolve_import(
     return _resolve_absolute_import(import_name, project_root)
 
 
+def _resolve_import_targets(
+    import_: _LocatedImport,
+    source_file: str,
+    project_root: str,
+) -> list[tuple[str, bool]]:
+    """Resolve an import, including namespace-package submodule aliases."""
+    resolution_kind = import_.resolution_kind or import_.import_kind
+    resolved, is_external = _resolve_import(
+        import_.module_name,
+        source_file,
+        project_root,
+        resolution_kind,
+    )
+    if is_external and import_.fallback_module_name is not None:
+        fallback, fallback_is_external = _resolve_import(
+            import_.fallback_module_name,
+            source_file,
+            project_root,
+            resolution_kind,
+        )
+        if fallback and not fallback_is_external:
+            resolved, is_external = fallback, False
+    if not is_external or not import_.aliases:
+        return [(resolved, is_external)]
+
+    alias_targets: list[tuple[str, bool]] = []
+    found_internal_alias = False
+    for alias in import_.aliases:
+        alias_module = _join_import_alias(import_.module_name, alias)
+        alias_resolved, alias_is_external = _resolve_import(
+            alias_module,
+            source_file,
+            project_root,
+            resolution_kind,
+        )
+        alias_targets.append((alias_resolved, alias_is_external))
+        found_internal_alias = found_internal_alias or not alias_is_external
+
+    if found_internal_alias:
+        return alias_targets
+    return [(resolved, is_external)]
+
+
+def _join_import_alias(module_name: str, alias: str) -> str:
+    """Join a from-import module name with a candidate submodule alias."""
+    if not module_name:
+        return alias
+    if set(module_name) == {"."}:
+        return f"{module_name}{alias}"
+    return f"{module_name}.{alias}"
+
+
 def _resolve_relative_import(
     import_name: str,
     source_file: str,