pymodularity 0.2.0__py3-none-any.whl

pymodularity/cli.py

@@ -0,0 +1,276 @@
+"""pymodularity: see and check a repo's real Python imports.
+
+Build one whole-repo Python import graph with ast (stdlib only) and
+render it as mermaid views, one per directory, with a markdown link list
+to zoom in/out. Nodes are file paths (or directory paths for namespace
+packages without __init__.py); edge labels count distinct (importer file,
+target file) pairs.
+A non-ancestor candidate's root must lack __init__.py only when the
+candidate itself is a single file (package candidates skip that filter).
+Test directories (tests/test) and test files (test_*.py, *_test.py,
+conftest.py) are skipped by default, no flag. `import a.b.c` must match
+exactly; `from a.b import c` tries submodule `a.b.c` then falls back to
+`a.b` exactly, never shorter. Each view opens with a summary: cycles are
+strongly connected components (size >= 2) among the view's inside children
+on the view's own edges, outside (dashed) nodes excluded; the node table
+lists one row per inside child. Both sections carry their own legend text
+in the rendered output defining each count; see that legend for units and
+for the _SCC_FULL_EDGE_LIMIT threshold controlling full vs. collapsed
+one-way-edge lists in Cycles.
+
+WARNING, blind spot: the graph shows import coupling only, a lower bound on
+logical coupling ("if A changes, must B?"). Coupling that bypasses Python
+imports stays invisible: HTTP APIs, shared database schemas and tables,
+config keys and env vars, message and file formats, string-keyed registries,
+runtime sys.path edits. Two services with no edge here can still force each
+other's edits. Never read a missing edge as independence.
+
+Three subcommands:
+
+`pymodularity graph <repo> --out DIR [--html]` writes the views under DIR.
+`--html` also writes an index.html per view (mermaid diagram, clickable
+directory nodes) alongside index.md; the browser needs network access to
+load mermaid from a CDN.
+
+`pymodularity check <repo>` runs five convention checks and prints findings
+to stdout, exit 1 on any finding: (1) no import cycles, at every directory
+level (any SCC with more than 1 node in any directory's view, computed the
+same way the view's own Cycles section is, TYPE_CHECKING and
+function-body imports counted, tests excluded as always; no baseline,
+existing cycles fail); (2) a Go-`internal/`-style privacy convention,
+applied to both modules and names (Rust's visibility rule on PEP 8
+underscores): a private item is visible in the thing that defines it and
+that thing's descendants, never in its parent or siblings. For modules: a
+file whose path, relative to the nearest ancestor directory with a
+pyproject.toml [project] table, has a component starting with a single `_`
+(not a dunder) may only be imported by files under the directory holding
+that component, repo-wide, across package boundaries. For names: `from m
+import _x` (or `_x as y`, absolute or relative) where `_x` is not itself a
+resolvable submodule of `m` (that case is the module rule above, not
+double-counted here) -- if `m` resolves to a single file, `_x` is private
+to that file and no other file may import it, including a sibling in the
+same directory or that directory's own `__init__.py`; if `m` resolves to a
+package (`__init__.py` or a namespace package directory), `_x` is private
+to that directory and only files under it may import it. The attribute
+form (`import a.b; a.b._x`) is out of scope here; ruff's SLF001 already
+flags it. (3) dependency declarations, on by default, skipped with
+`--no-deps`: per package root, shells out to a pinned deptry
+(`uv run --directory <pkg> --with deptry==<version> --frozen deptry .
+--json-output <tmp>`, nested package roots excluded via
+`--extend-exclude`), needs `uv` on PATH (exit 2 if missing, never a
+silent skip); the first run creates a `.venv` per scanned package and
+downloads its dependencies. A package is skipped, not scanned, if it
+declares no runtime dependencies or has no uv.lock of its own; any other
+deptry failure, or unparseable JSON, is a finding-level failure. (4) and
+(5) structure limits, fixed constants, no config, no baseline: at most 500
+physical lines per file, 10 entries per directory (`__init__.py`/
+`__main__.py` excluded), 100 scanned files per package root, 15 public
+top-level names per file, and a public top-level name that no scanned
+file imports (a file no scanned file imports at all, `__init__.py` and
+`__main__.py`, and a name reachable through a whole-module import, are all
+exempt).
+
+`pymodularity metrics <repo>` prints a coupling report to stdout on the same
+file graph (reach and score per file and per directory, interface width
+per file and per directory, exposure share, entry files, misplaced files)
+and always exits 0: it is a report, never a gate."""
+
+import argparse
+import sys
+from pathlib import Path
+
+from pymodularity._check import (
+    find_name_violations,
+    find_privacy_violations,
+    print_check_findings,
+)
+from pymodularity._cycles import count_file_level_cycles, find_all_cycle_findings
+from pymodularity._deps import UvMissing, print_deps_findings, run_dependency_checks
+from pymodularity._metrics import render_metrics
+from pymodularity._parse.graph import build_graph
+from pymodularity._parse.packages import find_package_roots
+from pymodularity._scores import compute_scores
+from pymodularity._structure import find_structure_findings, print_structure_findings
+from pymodularity._view_edges import build_view
+from pymodularity._views.render import write_view
+
+__version__ = "0.2.0"
+
+
+class _CheckArgs(argparse.Namespace):
+    # placeholder default for the static type only; argparse always
+    # overwrites it before parse_args() returns
+    repo: Path = Path()
+    deps: bool = True
+
+
+class _GraphArgs(argparse.Namespace):
+    repo: Path = Path()
+    out: Path = Path()
+    html: bool = False
+
+
+class _MetricsArgs(argparse.Namespace):
+    repo: Path = Path()
+
+
+def _run_check(repo: Path, run_deps: bool) -> int:
+    """`pymodularity check <repo>`: the import-cycle, privacy-convention and
+    (unless `--no-deps`) dependency-declaration checks, findings printed to
+    stdout, exit 1 on any finding, no views written."""
+    graph = build_graph(repo)
+
+    cycle_findings = find_all_cycle_findings(graph.dirs_with_py, graph.edge_names)
+
+    package_roots = find_package_roots(repo)
+    privacy_violations = find_privacy_violations(graph.edge_names, package_roots)
+    name_violations = find_name_violations(graph.edge_names)
+    distinct_file_cycles = count_file_level_cycles(graph.adj)
+    any_finding = print_check_findings(
+        cycle_findings, distinct_file_cycles, privacy_violations, name_violations
+    )
+
+    deps_finding = False
+    if run_deps:
+        deps_result = run_dependency_checks(repo)
+        if isinstance(deps_result, UvMissing):
+            print(
+                "error: `uv` not found on PATH; the dependency-declaration "
+                + "rule needs it (use --no-deps to skip)",
+                file=sys.stderr,
+            )
+            return 2
+        deps_finding = print_deps_findings(deps_result)
+
+    structure_findings = find_structure_findings(
+        repo,
+        graph.py_files,
+        graph.dirs_with_py,
+        graph.defined_names,
+        graph.registered_names,
+    )
+    structure_finding = print_structure_findings(structure_findings)
+
+    return 1 if any_finding or deps_finding or structure_finding else 0
+
+
+def _run_graph(repo: Path, out_dir: Path, write_html: bool) -> int:
+    """`pymodularity graph <repo> --out DIR [--html]`: writes one mermaid
+    view per directory under DIR."""
+    out_dir.mkdir(parents=True, exist_ok=True)
+    graph = build_graph(repo)
+    scores = compute_scores(graph.dirs_with_py, graph.adj, graph.radj)
+
+    written = 0
+    for directory in sorted(graph.dirs_with_py, key=str):
+        pair_edges = build_view(directory, graph.edge_names)
+        write_view(
+            out_dir,
+            repo,
+            directory,
+            graph.dirs_with_py,
+            pair_edges,
+            graph.edge_names,
+            write_html,
+            scores.file_scores,
+            scores.dir_scores,
+        )
+        written += 1
+
+    print(f"wrote {written} views under {out_dir}", file=sys.stderr)
+    return 0
+
+
+def _run_metrics(repo: Path) -> int:
+    """`pymodularity metrics <repo>`: prints a coupling report to stdout,
+    always exits 0."""
+    graph = build_graph(repo)
+    scores = compute_scores(graph.dirs_with_py, graph.adj, graph.radj)
+
+    print(
+        "\n".join(
+            render_metrics(
+                graph.dirs_with_py,
+                graph.edge_names,
+                scores.file_scores,
+                scores.dir_scores,
+                graph.defined_names,
+                graph.adj,
+                graph.radj,
+            )
+        )
+    )
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        prog="pymodularity",
+        description="Check and measure a Python repo's imports: no import cycles, "
+        + "underscore privacy scoped like Rust's pub(super)/pub(crate), coupling metrics.",
+        epilog="Rules, metrics and blind spots: https://github.com/dertilo/pymodularity",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"pymodularity {__version__}"
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    check_parser = subparsers.add_parser(
+        "check",
+        help=(
+            "run the import-cycle, privacy convention and dependency "
+            + "declaration checks, print findings to stdout, exit 1 on "
+            + "any finding"
+        ),
+    )
+    check_parser.add_argument("repo", type=Path)
+    check_parser.add_argument(
+        "--no-deps",
+        dest="deps",
+        action="store_false",
+        help="skip the dependency-declaration rule (deptry), on by default",
+    )
+
+    graph_parser = subparsers.add_parser("graph", help="write mermaid views")
+    graph_parser.add_argument("repo", type=Path)
+    graph_parser.add_argument("--out", type=Path, required=True)
+    graph_parser.add_argument(
+        "--html",
+        action="store_true",
+        help=(
+            "also write index.html per view; needs network access in the "
+            + "browser to load mermaid from a CDN"
+        ),
+    )
+
+    metrics_parser = subparsers.add_parser(
+        "metrics",
+        help=(
+            "print a coupling report (reach and score, interface "
+            + "width, exposure share, entry files, misplaced files) to "
+            + "stdout; always exits 0"
+        ),
+    )
+    metrics_parser.add_argument("repo", type=Path)
+
+    args = parser.parse_args()
+
+    if args.command == "check":
+        check_args = _CheckArgs()
+        check_args.repo = args.repo
+        check_args.deps = args.deps
+        return _run_check(check_args.repo.resolve(), check_args.deps)
+    if args.command == "graph":
+        graph_args = _GraphArgs()
+        graph_args.repo = args.repo
+        graph_args.out = args.out
+        graph_args.html = args.html
+        return _run_graph(graph_args.repo.resolve(), graph_args.out, graph_args.html)
+    metrics_args = _MetricsArgs()
+    metrics_args.repo = args.repo
+    return _run_metrics(metrics_args.repo.resolve())
+
+
+if __name__ == "__main__":
+    # nosemgrep: no-raise-outside-boundary  # boundary: CLI entry point, the process exit boundary
+    raise SystemExit(main())

pymodularity-0.2.0.dist-info/METADATA

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: pymodularity
+Version: 0.2.0
+Summary: See and check a repo's real Python imports: a privacy convention on PEP 8 underscores, an import-cycle ban, and a coupling report, all derived from the code.
+Author: Tilo Himmelsbach
+License-Expression: MIT
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/dertilo/pymodularity
+Project-URL: Repository, https://github.com/dertilo/pymodularity
+Project-URL: Issues, https://github.com/dertilo/pymodularity/issues
+Description-Content-Type: text/markdown
+
+# pymodularity
+
+Formerly published as `underscope`.
+
+The underscore's position in a Python import path sets that import's scope — Rust's `pub(super)`/`pub(crate)`, applied to PEP 8 underscores.
+
+`pymodularity` draws a repo's real Python imports as mermaid diagrams, checks them against conventions derived from the code itself (no allow-list to maintain), and reports which files and directories carry the most structural coupling. It needs only the standard library to analyze your code — no runtime dependencies. `check`'s dependency-declaration rule additionally needs `uv` on PATH (see below).
+
+## Install and run
+
+```bash
+uvx pymodularity check .
+uvx pymodularity graph . --out docs/imports
+uvx pymodularity metrics .
+```
+
+Or, inside a project: `uv add --dev pymodularity` and run `pymodularity ...` in that project's venv.
+
+## The rules `check` enforces
+
+Given this tree:
+
+```
+shop/
+  __init__.py
+  billing/
+    __init__.py
+    invoice.py          # from shop.billing._pricing import compute_total
+    _pricing.py          # def compute_total(): ...
+  catalog/
+    __init__.py
+    listing.py           # from shop.billing._pricing import compute_total  <- finding
+```
+
+- **No import cycle**, at any directory level: between files, and between directories at every depth. Imports under `if TYPE_CHECKING:` and inside function bodies count. There is no baseline — an existing cycle fails too.
+- **A private item stays visible only to its owner and the owner's descendants** (Go's `internal/`, applied as Rust's visibility rule to PEP 8 underscores):
+  - a private module — a file, or a path component, named `_x` (single leading underscore, not a dunder) — belongs to the directory holding it; only files under that directory may import it, across package boundaries;
+  - a private name imported via `from m import _x` belongs to `m`; if `m` is a single file, no other file may import `_x`, not even a sibling in the same directory;
+  - if `m` is a package (an `__init__.py` or a namespace package directory), `_x` belongs to that directory, and files under it may import it.
+  - a parent never reaches into a child's private items, and neither do siblings.
+  - `shop/billing/invoice.py` above is allowed (it's under `shop/billing`, `_pricing`'s owner); `shop/catalog/listing.py` is a finding.
+  - the attribute form (`import shop.billing._pricing as p; p.compute_total`) is out of scope here — ruff's `SLF001` already flags it.
+
+`pymodularity check .` exits 1 on any finding and prints, per finding, the importing file, the target, and the directory or file that owns it.
+
+- **Dependency declarations are correct**, on by default, skipped with `check --no-deps`: for each package root (a directory with a `pyproject.toml` `[project]` table), runs [deptry](https://github.com/fpgmaas/deptry) (`uv run --directory <pkg> --with deptry==<pinned version> --frozen deptry . --json-output <tmp>`, a nested package root excluded from its parent's scan via `--extend-exclude`) and reports its findings (unused, missing, and transitive dependencies) the same way as the other rules. A package is skipped, not scanned, if it declares no runtime dependencies, or has no `uv.lock` of its own. This rule needs `uv` on PATH — `check` exits 2 with an error if it is missing, never a silent skip. The first run creates a `.venv` inside each scanned package and downloads its dependencies; later runs reuse it.
+
+- **Structure limits**, fixed constants, no config, no baseline — every one of these is a finding regardless of how long it's been true:
+  - a scanned file has at most 500 physical lines.
+  - a directory has at most 10 entries, where an entry is a scanned `.py` file directly in it or a subdirectory holding scanned `.py` files, transitively; `__init__.py` and `__main__.py` don't count as entries (they're still scanned and still count toward the other limits).
+  - a package root (the same `pyproject.toml` `[project]`-table directory the privacy and dependency rules anchor on) has at most 100 scanned files, each file counted against its nearest (innermost) package root.
+  - a file has at most 15 public top-level names (no leading `_`): `def`/`async def`/`class`, a plain or annotated assignment target (including tuple-unpacking), or a `type X = ...` alias, at top level or nested in a top-level `if`/`try` block (including `elif`/`else`, `except` handlers, `finally`). Imports never count. A top-level function (not a class — `@dataclass` sits on most models) a decorator registers doesn't count either: FastAPI, Typer/Click, Dagster, pytest and the like derive part of their contract (route `operationId`, CLI command name, asset key, fixture name) from the function's name, so counting it toward the width cap would pressure someone into renaming or restructuring around a name the framework, not this tool, owns. Any decorator counts — there's no list of framework names.
+
+## The 3 subcommands
+
+- `pymodularity check <repo> [--no-deps]` — run all four rules above, print findings, exit 1 on any finding (`--no-deps` skips the dependency-declaration rule).
+- `pymodularity graph <repo> --out DIR [--html]` — write one mermaid view per directory under `DIR`: `index.md` everywhere, plus a clickable `index.html` per view with `--html` (needs network access in the browser to load mermaid from a CDN).
+- `pymodularity metrics <repo>` — print a coupling report to stdout: reach (dependents/dependencies, transitive) and a `score` per file and per directory; interface width (names other code imports from a unit); exposure share (how much of what a file defines actually gets used elsewhere); entry files (how much of a directory outside code actually reaches into); misplaced files (files whose closest partners sit mostly in another directory). Always exits 0 — a report, never a gate.
+
+## Blind spots
+
+`pymodularity` shows import coupling only, a lower bound on logical coupling ("if A changes, must B?"). Coupling that bypasses Python imports stays invisible:
+
+- HTTP APIs, shared database schemas and tables, config keys and env vars, message and file formats, string-keyed registries, runtime `sys.path` edits.
+- Two files with no edge here can still force each other's edits. **Never read a missing edge as independence.**
+
+Other limits:
+
+- a `warning: ambiguous import` line (printed to stderr) means several files in the repo match one import; no edge is drawn for it.
+- an import that only resolves through a runtime `sys.path` edit is matched by file path, which can pick the wrong file.
+- a third-party name that happens to equal a package folder elsewhere in the repo draws a false edge.
+- test directories (`tests/`, `test/`) and test files (`test_*.py`, `*_test.py`, `conftest.py`) are always skipped, no flag — a test importing a sibling would otherwise draw a production dependency that production never has.
+- `metrics` is a report on numbers that keep moving even on a repo that passes `check` clean; gating on it rewards gaming the number (for example, replacing an import with a string-keyed registry) instead of actually lowering coupling.

pymodularity-0.2.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+pymodularity/__init__.py,sha256=wzKw3Skwd2WRtwxz9xWCUySGFRrApqoE-syjYDbif7k,133
+pymodularity/__main__.py,sha256=ylHMhTlsxpfQSuBJfFufmceZYgYeIbRiDEGFrC7Yhxs,239
+pymodularity/_check.py,sha256=0lunUJ6GYe3twHJJbXg5v8U_Y1rTuaOiH47Tbormizc,5783
+pymodularity/_cycles.py,sha256=xLXx_ILuIVlqhKWn8oOpzRWTBxLiIsw4rJu70VENEFA,8142
+pymodularity/_deps.py,sha256=kV9uKemHhDiguUUxPbWDcSNFdd-hGhq-fevHsHh08-0,8584
+pymodularity/_metrics.py,sha256=Ivq6TQxjeA20pxGgj8G5XTL58wENyjwFpobZ2w9X31Y,16868
+pymodularity/_parse/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pymodularity/_parse/_resolve.py,sha256=GZ1xJC1LXSpK6f-5FYdpQfK6GRXCjNcOugRXNCOtDaE,6948
+pymodularity/_parse/graph.py,sha256=7IkbjzTLdP2HJAC9VEJOtK0u9N9zkt76XTdLJtSShDQ,13500
+pymodularity/_parse/names.py,sha256=i9I7GqRQqSD_qEuwM7W_d050x3FdjrUdT8ZKmpYDiTM,1001
+pymodularity/_parse/packages.py,sha256=k6EAKIASYikJPEZIiSkqH_NQIfWtGg1oaqcky8oCPVU,1225
+pymodularity/_scores.py,sha256=cCKybbv1bJyKJG1FEU_TutcvDIGB8MtK9jmgJbzVgxg,4533
+pymodularity/_structure.py,sha256=90ogHcLZAlBbvGudxsZ84RYEHStew7TI2vDHBkQ36gM,5455
+pymodularity/_view_edges.py,sha256=tP767BSDYXoJMMF5QwxpB5eSUyfzxL2sxJ0Pf-SAtsU,2513
+pymodularity/_views/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pymodularity/_views/_summary.py,sha256=3W37Gv1jkywLUUu4PlFvY6w9gxOR-trC7cMRQyIAAhI,9268
+pymodularity/_views/render.py,sha256=GOqcRtl6m8xNW8dTvxos4PJuD2gTcqjYWBa9RcYggrA,6802
+pymodularity/cli.py,sha256=2gWCRlvgNa7ZRG8xypvFc6C1TzuUtTykp99JC5BKPkY,11329
+pymodularity-0.2.0.dist-info/WHEEL,sha256=9IUYslYuG_asT4WlWvfk_K76nveuLvSTKDoLeL0cV-Q,80
+pymodularity-0.2.0.dist-info/entry_points.txt,sha256=AbfWSHOchayQJ7FbSPuiLgZciZz3bXnJFT1sYzDRkR4,56
+pymodularity-0.2.0.dist-info/METADATA,sha256=9bNeRPUo1bL722d1VBmnqXRwwrse-G-dGAME4YAOj2o,7631
+pymodularity-0.2.0.dist-info/RECORD,,

pymodularity-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.13.1
+Root-Is-Purelib: true
+Tag: py3-none-any

pymodularity-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+pymodularity = pymodularity.cli:main
+