pymodularity 0.2.0__py3-none-any.whl

pymodularity/_metrics.py

@@ -0,0 +1,455 @@
+"""The 4 coupling analyses beyond reach/scores (interface width, exposure
+share, entry files, misplaced files), and `render_metrics`, the printer
+for all 5 of `pymodularity metrics`'s sections."""
+
+from collections.abc import Mapping
+from collections.abc import Set as AbstractSet
+from dataclasses import dataclass
+from pathlib import Path
+
+from pymodularity._parse.graph import EdgeNames
+from pymodularity._scores import DirScore, FileScore, ancestor_dirs
+
+
+@dataclass(frozen=True, slots=True)
+class _CountedPath:
+    """A path with a count against it (dependents or dependencies)."""
+
+    path: Path
+    count: int
+
+
+def _top_n_by_count(counts: Mapping[Path, int], n: int = 10) -> tuple[_CountedPath, ...]:
+    ranked = sorted(counts.items(), key=lambda kv: (-kv[1], str(kv[0])))[:n]
+    return tuple(_CountedPath(p, c) for p, c in ranked)
+
+
+@dataclass(frozen=True, slots=True)
+class _FileWidth:
+    """A target file's interface width: distinct names other files import
+    from it, and distinct files importing any of those names."""
+
+    target: Path
+    names: int
+    importers: int
+
+
+def _compute_file_widths(
+    nodes: AbstractSet[Path], edge_names: EdgeNames
+) -> tuple[_FileWidth, ...]:
+    names_by_target: dict[Path, set[str]] = {}
+    bare_targets: set[Path] = set()
+    importers_by_target: dict[Path, set[Path]] = {}
+    for (importer_rel, target_rel), names in edge_names.items():
+        if importer_rel == target_rel or target_rel not in nodes:
+            continue
+        importers_by_target.setdefault(target_rel, set()).add(importer_rel)
+        if names:
+            names_by_target.setdefault(target_rel, set()).update(names)
+        else:
+            bare_targets.add(target_rel)
+
+    widths: list[_FileWidth] = []
+    for target in nodes:
+        name_count = len(names_by_target.get(target, set())) + (
+            1 if target in bare_targets else 0
+        )
+        importer_count = len(importers_by_target.get(target, set()))
+        widths.append(_FileWidth(target, name_count, importer_count))
+    return tuple(widths)
+
+
+def _compute_wrapper_dirs(
+    nodes: AbstractSet[Path], dirs_with_py: AbstractSet[Path]
+) -> frozenset[Path]:
+    """Directories that hold no .py file of their own and have exactly one
+    child directory with Python code, so their file set is identical to
+    that child's (and, up a wrapper chain, to the file set of every other
+    wrapper in the chain). `metrics`'s directory tables skip these,
+    keeping only the deepest directory of each such chain."""
+    direct_file_count: dict[Path, int] = {}
+    for f in nodes:
+        d = f.parent
+        direct_file_count[d] = direct_file_count.get(d, 0) + 1
+
+    children: dict[Path, list[Path]] = {}
+    for d in dirs_with_py:
+        if d == Path("."):
+            continue
+        children.setdefault(d.parent, []).append(d)
+
+    return frozenset(
+        d
+        for d in dirs_with_py
+        if direct_file_count.get(d, 0) == 0 and len(children.get(d, [])) == 1
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class _DirWidth:
+    """A directory's interface width: distinct (target file, name) pairs
+    files outside it import from files inside it, and distinct outside
+    importing files."""
+
+    directory: Path
+    names: int
+    importers: int
+
+
+def _compute_dir_widths(
+    dirs_with_py: AbstractSet[Path], edge_names: EdgeNames
+) -> tuple[_DirWidth, ...]:
+    named_pairs: dict[Path, set[tuple[Path, str]]] = {}
+    bare_targets: dict[Path, set[Path]] = {}
+    importers: dict[Path, set[Path]] = {}
+    for (importer_rel, target_rel), names in edge_names.items():
+        for directory in ancestor_dirs(target_rel):
+            if directory not in dirs_with_py:
+                continue
+            if importer_rel.is_relative_to(directory):
+                continue
+            importers.setdefault(directory, set()).add(importer_rel)
+            if names:
+                named_pairs.setdefault(directory, set()).update(
+                    (target_rel, name) for name in names
+                )
+            else:
+                bare_targets.setdefault(directory, set()).add(target_rel)
+
+    widths: list[_DirWidth] = []
+    for directory in dirs_with_py:
+        name_count = len(named_pairs.get(directory, set())) + len(
+            bare_targets.get(directory, set())
+        )
+        importer_count = len(importers.get(directory, set()))
+        widths.append(_DirWidth(directory, name_count, importer_count))
+    return tuple(widths)
+
+
+@dataclass(frozen=True, slots=True)
+class _Exposure:
+    """A file's exposure share: how many of its top-level defined names
+    (def, async def, class, plain/annotated assignment to a bare name;
+    imports don't count) at least one other file actually imports."""
+
+    path: Path
+    used: int
+    defined: int
+    share: float
+    importers: int
+
+
+def _compute_exposure(
+    nodes: AbstractSet[Path],
+    edge_names: EdgeNames,
+    defined_names: Mapping[Path, AbstractSet[str]],
+) -> Mapping[Path, _Exposure]:
+    imported_names: dict[Path, set[str]] = {}
+    importers_by_name: dict[Path, dict[str, set[Path]]] = {}
+    for (importer_rel, target_rel), names in edge_names.items():
+        if not names or importer_rel == target_rel:
+            continue
+        imported_names.setdefault(target_rel, set()).update(names)
+        per_name = importers_by_name.setdefault(target_rel, {})
+        for name in names:
+            per_name.setdefault(name, set()).add(importer_rel)
+
+    exposures: dict[Path, _Exposure] = {}
+    for f in nodes:
+        if f.name == "__init__.py":
+            continue
+        defined = defined_names.get(f, frozenset())
+        used_names = defined & imported_names.get(f, set())
+        per_name = importers_by_name.get(f, {})
+        importer_set: set[Path] = set()
+        for name in used_names:
+            importer_set.update(per_name.get(name, set()))
+        used = len(used_names)
+        total = len(defined)
+        share = used / total if total else 0.0
+        exposures[f] = _Exposure(f, used, total, share, len(importer_set))
+    return exposures
+
+
+@dataclass(frozen=True, slots=True)
+class _EntryFiles:
+    """A directory's entry-file share: how many of its files at least one
+    file outside the directory imports directly, out of all files inside
+    it; outside_importers is the distinct outside files doing so."""
+
+    directory: Path
+    entry: int
+    files: int
+    share: float
+    outside_importers: int
+
+
+def _compute_entry_files(
+    dirs_with_py: AbstractSet[Path], nodes: AbstractSet[Path], edge_names: EdgeNames
+) -> Mapping[Path, _EntryFiles]:
+    entry_by_dir: dict[Path, set[Path]] = {}
+    outside_importers_by_dir: dict[Path, set[Path]] = {}
+    for importer_rel, target_rel in edge_names:
+        for directory in ancestor_dirs(target_rel):
+            if directory not in dirs_with_py:
+                continue
+            if importer_rel.is_relative_to(directory):
+                continue
+            entry_by_dir.setdefault(directory, set()).add(target_rel)
+            outside_importers_by_dir.setdefault(directory, set()).add(importer_rel)
+
+    files_by_dir: dict[Path, int] = {}
+    for f in nodes:
+        for directory in ancestor_dirs(f):
+            if directory in dirs_with_py:
+                files_by_dir[directory] = files_by_dir.get(directory, 0) + 1
+
+    out: dict[Path, _EntryFiles] = {}
+    for directory in dirs_with_py:
+        files = files_by_dir.get(directory, 0)
+        entry = len(entry_by_dir.get(directory, set()))
+        share = entry / files if files else 0.0
+        outside = len(outside_importers_by_dir.get(directory, set()))
+        out[directory] = _EntryFiles(directory, entry, files, share, outside)
+    return out
+
+
+@dataclass(frozen=True, slots=True)
+class _Misplaced:
+    """A file whose direct import partners (files it imports plus files
+    importing it, from the same file graph the scores use) cluster more
+    heavily in some other directory than in its own."""
+
+    path: Path
+    own: int
+    other: int
+    other_dir: Path
+    imported_by: int
+    imports: int
+
+
+def _compute_misplaced(
+    nodes: AbstractSet[Path],
+    adj: Mapping[Path, AbstractSet[Path]],
+    radj: Mapping[Path, AbstractSet[Path]],
+) -> tuple[_Misplaced, ...]:
+    results: list[_Misplaced] = []
+    for f in nodes:
+        importers = radj.get(f, set()) - {f}
+        imports_of = adj.get(f, set()) - {f}
+        partners = importers | imports_of
+        own_dir = f.parent
+        own = 0
+        other_counts: dict[Path, int] = {}
+        for p in partners:
+            d = p.parent
+            if d == own_dir:
+                own += 1
+            else:
+                other_counts[d] = other_counts.get(d, 0) + 1
+        other = 0
+        other_dir = Path(".")
+        if other_counts:
+            best = max(other_counts.values())
+            # tie-break deterministically: smallest path among the ties
+            other_dir = min(d for d, c in other_counts.items() if c == best)
+            other = best
+        if other >= 3 and other > own:
+            imported_by = sum(1 for p in importers if p.parent == other_dir)
+            imports = sum(1 for p in imports_of if p.parent == other_dir)
+            results.append(_Misplaced(f, own, other, other_dir, imported_by, imports))
+    return tuple(results)
+
+
+def render_metrics(
+    dirs_with_py: AbstractSet[Path],
+    edge_names: EdgeNames,
+    file_scores: Mapping[Path, FileScore],
+    dir_scores: Mapping[Path, DirScore],
+    defined_names: Mapping[Path, AbstractSet[str]],
+    adj: Mapping[Path, AbstractSet[Path]],
+    radj: Mapping[Path, AbstractSet[Path]],
+) -> tuple[str, ...]:
+    nodes = set(adj)
+    n = len(nodes)
+    dependents = {p: fs.dependents for p, fs in file_scores.items()}
+    dependencies = {p: fs.dependencies for p, fs in file_scores.items()}
+    wrapper_dirs = _compute_wrapper_dirs(nodes, dirs_with_py)
+
+    lines: list[str] = ["# Coupling report", ""]
+    lines.append("## Reach")
+    lines.append("")
+    lines.append(
+        "dependents(f): other files with an import path to f, direct or "
+        + "transitive; dependencies(f): other files f has an import path "
+        + "to; score(f) = dependents(f) x dependencies(f)."
+    )
+    lines.append("")
+    lines.append(f"- N (non-test .py files): {n}")
+    lines.append(f"- file-level edges: {len(edge_names)}")
+    lines.append("")
+
+    lines.append("Top 10 by dependents:")
+    lines.append("")
+    for cp in _top_n_by_count(dependents):
+        share = cp.count / n * 100 if n else 0.0
+        lines.append(f"- {cp.path}: {cp.count} ({share:.1f}% of N)")
+    lines.append("")
+
+    lines.append("Top 10 by dependencies:")
+    lines.append("")
+    for cp in _top_n_by_count(dependencies):
+        share = cp.count / n * 100 if n else 0.0
+        lines.append(f"- {cp.path}: {cp.count} ({share:.1f}% of N)")
+    lines.append("")
+
+    lines.append(
+        "All files by score (dependents x dependencies), ties: dependents "
+        + "desc, then path:"
+    )
+    lines.append("")
+    lines.append("| file | dependents | dependencies | score |")
+    lines.append("| --- | --- | --- | --- |")
+    for fs in sorted(
+        file_scores.values(), key=lambda s: (-s.score, -s.dependents, str(s.path))
+    ):
+        lines.append(f"| {fs.path} | {fs.dependents} | {fs.dependencies} | {fs.score} |")
+    lines.append("")
+
+    lines.append(
+        "All directories by score (in x out, measured across the "
+        + "directory's own boundary, repo-wide); a directory whose file "
+        + "set is identical to its one child directory's is skipped, "
+        + "keeping only the deepest directory of such a wrapper chain:"
+    )
+    lines.append("")
+    lines.append("| directory | in | out | score |")
+    lines.append("| --- | --- | --- | --- |")
+    for ds in sorted(
+        (s for s in dir_scores.values() if s.path not in wrapper_dirs),
+        key=lambda s: (-s.score, str(s.path)),
+    ):
+        directory_label = "repo root" if ds.path == Path(".") else str(ds.path)
+        lines.append(
+            f"| {directory_label} | {ds.reach_in} | {ds.reach_out} | {ds.score} |"
+        )
+    lines.append("")
+
+    lines.append("## Interface width")
+    lines.append("")
+    lines.append(
+        "distinct names other files import from a file or directory "
+        + "(a nameless import, e.g. `import x`, counts the target as 1 "
+        + "name), and the distinct files importing any of them."
+    )
+    lines.append("")
+
+    file_widths = sorted(
+        _compute_file_widths(nodes, edge_names),
+        key=lambda w: (-w.names, str(w.target)),
+    )[:10]
+    lines.append("Top 10 files by name count:")
+    lines.append("")
+    for w in file_widths:
+        lines.append(f"- {w.target}: {w.names} names, {w.importers} importers")
+    lines.append("")
+
+    dir_widths = sorted(
+        (
+            w
+            for w in _compute_dir_widths(dirs_with_py, edge_names)
+            if w.directory not in wrapper_dirs
+        ),
+        key=lambda w: (-w.names, str(w.directory)),
+    )[:10]
+    lines.append(
+        "Top 10 directories by name count (wrapper directories, see " + "above, skipped):"
+    )
+    lines.append("")
+    for w in dir_widths:
+        directory_label = "repo root" if w.directory == Path(".") else str(w.directory)
+        lines.append(f"- {directory_label}: {w.names} names, {w.importers} importers")
+    lines.append("")
+
+    lines.append("## Exposure share")
+    lines.append("")
+    lines.append(
+        "Per file (`__init__.py` excluded): defined = top-level names it "
+        + "defines (def, async def, class, plain/annotated assignment to a "
+        + "bare name; imports don't count); used = those names at least one "
+        + "other file imports; share = used / defined. Files with defined "
+        + ">= 10, sorted by share desc, then defined desc."
+    )
+    lines.append("")
+    exposures = [
+        e
+        for e in _compute_exposure(nodes, edge_names, defined_names).values()
+        if e.defined >= 10
+    ]
+    exposures.sort(key=lambda e: (-e.share, -e.defined, str(e.path)))
+    lines.append("| file | used | defined | share | importing files |")
+    lines.append("| --- | --- | --- | --- | --- |")
+    for e in exposures:
+        lines.append(
+            f"| {e.path} | {e.used} | {e.defined} | {e.share * 100:.1f}% "
+            + f"| {e.importers} |"
+        )
+    lines.append("")
+
+    lines.append("## Entry files")
+    lines.append("")
+    lines.append(
+        "Per directory (directories with >= 5 files): entry files = files "
+        + "inside the directory at least one file outside it imports "
+        + "directly; share = entry files / files; outside importers = "
+        + "distinct outside files importing anything inside. Sorted by "
+        + "share desc, then outside importers desc. Wrapper directories, "
+        + "see above, skipped."
+    )
+    lines.append("")
+    entries = [
+        e
+        for e in _compute_entry_files(dirs_with_py, nodes, edge_names).values()
+        if e.files >= 5 and e.directory not in wrapper_dirs
+    ]
+    entries.sort(key=lambda e: (-e.share, -e.outside_importers, str(e.directory)))
+    lines.append("| directory | entry files | files | share | outside importers |")
+    lines.append("| --- | --- | --- | --- | --- |")
+    for e in entries:
+        directory_label = "repo root" if e.directory == Path(".") else str(e.directory)
+        lines.append(
+            f"| {directory_label} | {e.entry} | {e.files} | {e.share * 100:.1f}% "
+            + f"| {e.outside_importers} |"
+        )
+    lines.append("")
+
+    lines.append("## Misplaced files")
+    lines.append("")
+    misplaced = sorted(
+        _compute_misplaced(nodes, adj, radj),
+        key=lambda m: (-(m.other - m.own), str(m.path)),
+    )
+    lines.append(f"{len(misplaced)} of {n} files misplaced.")
+    lines.append("")
+    lines.append(
+        "partners(f) = files f imports directly plus files importing f "
+        + "directly; own = partners in f's own parent directory; other = "
+        + "the largest count among all other parent directories, naming "
+        + "that directory; misplaced when other >= 3 and other > own. "
+        + "'imported by' = those other-directory partners that import f; "
+        + "'imports' = those other-directory partners f imports; a "
+        + "partner doing both counts in both, so the two may sum to more "
+        + "than other. Sorted by other - own desc, then path."
+    )
+    lines.append("")
+    lines.append("| file | own | other | imported by | imports | other directory |")
+    lines.append("| --- | --- | --- | --- | --- | --- |")
+    for m in misplaced:
+        other_dir_label = "repo root" if m.other_dir == Path(".") else str(m.other_dir)
+        lines.append(
+            f"| {m.path} | {m.own} | {m.other} | {m.imported_by} | {m.imports} "
+            + f"| {other_dir_label} |"
+        )
+    lines.append("")
+
+    return tuple(lines)

pymodularity/_parse/_resolve.py

@@ -0,0 +1,225 @@
+"""The module index (`Index`/`build_index`) and import resolution
+(`resolve_exact`/`resolve_relative`, returning the `Resolved | Ambiguous |
+_Unresolved` sum) that `graph._collect_edges` drives one ast walk with."""
+
+import sys
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+from pymodularity._parse.names import module_comp
+
+# dotted module path components, e.g. ("shop", "billing", "pricing")
+_PathParts = tuple[str, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class _ModuleCandidate:
+    """A resolvable module: its file/dir path, and whether it's a namespace
+    package directory (True) or a single .py file / __init__.py (False)."""
+
+    path: Path
+    is_namespace_dir: bool
+
+
+ModuleCandidates = Mapping[_PathParts, _ModuleCandidate]
+
+
+@dataclass(frozen=True, slots=True)
+class _SuffixEntry:
+    """A module candidate indexed by dotted suffix."""
+
+    comp: _PathParts
+    path: Path
+    is_namespace_dir: bool
+
+
+SuffixIndex = Mapping[_PathParts, tuple[_SuffixEntry, ...]]
+
+
+@dataclass(frozen=True, slots=True)
+class Resolved:
+    """A single unambiguous module match."""
+
+    path: Path
+
+
+@dataclass(frozen=True, slots=True)
+class Ambiguous:
+    """Several module matches equally plausible for the importer; the
+    caller records a warning and treats the import as unresolved."""
+
+    candidates: tuple[Path, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class _Unresolved:
+    """No module matched (stdlib, third-party, or a dotted path with no
+    candidate in the repo)."""
+
+
+_Resolution = Resolved | Ambiguous | _Unresolved
+
+
+@dataclass(frozen=True, slots=True)
+class _ScoredCandidate:
+    """A module candidate scored for disambiguation against the importer."""
+
+    root_depth: int
+    is_ancestor: bool
+    path: Path
+    root: _PathParts
+    is_namespace_dir: bool
+
+
+@dataclass(frozen=True, slots=True)
+class Index:
+    """What a repo's file list indexes into: the directories holding Python
+    code, every resolvable module candidate, and that candidate set indexed
+    by dotted suffix for lookup."""
+
+    dirs_with_py: frozenset[Path]
+    module_candidates: ModuleCandidates
+    suffix_index: SuffixIndex
+
+
+def build_index(repo: Path, py_files: Sequence[Path]) -> Index:
+    dirs_with_py: set[Path] = set()
+    for f in py_files:
+        d = f.relative_to(repo).parent
+        while True:
+            dirs_with_py.add(d)
+            if d == Path("."):
+                break
+            d = d.parent
+
+    module_candidates: dict[_PathParts, _ModuleCandidate] = {}
+    for f in py_files:
+        rel = f.relative_to(repo)
+        comp = module_comp(rel.parts)
+        module_candidates[comp] = _ModuleCandidate(f, False)
+
+    for d in dirs_with_py:
+        comp = () if d == Path(".") else d.parts
+        if comp not in module_candidates:
+            module_candidates[comp] = _ModuleCandidate(
+                repo / d if d != Path(".") else repo, True
+            )
+
+    suffix_index: dict[_PathParts, list[_SuffixEntry]] = {}
+    for comp, cand in module_candidates.items():
+        for k in range(1, len(comp) + 1):
+            suf = comp[-k:]
+            suffix_index.setdefault(suf, []).append(
+                _SuffixEntry(comp, cand.path, cand.is_namespace_dir)
+            )
+    frozen_suffix_index: SuffixIndex = {suf: tuple(v) for suf, v in suffix_index.items()}
+
+    return Index(frozenset(dirs_with_py), module_candidates, frozen_suffix_index)
+
+
+def path_components(p: Path) -> _PathParts:
+    return () if p == Path(".") else p.parts
+
+
+def _disambiguate(
+    cands: Sequence[_SuffixEntry],
+    importer_dir_parts: _PathParts,
+    suf: _PathParts,
+    module_candidates: ModuleCandidates,
+) -> _Resolution:
+    uniq: dict[tuple[_PathParts, Path], bool] = {}
+    for entry in cands:
+        uniq[(entry.comp, entry.path)] = entry.is_namespace_dir
+    entries = [_SuffixEntry(comp, path, isd) for (comp, path), isd in uniq.items()]
+
+    # Python prefers a regular package/module over a namespace-package
+    # directory portion, wherever on the path the two sit: if any candidate
+    # here is a real .py module or an __init__.py package, drop the
+    # namespace-dir candidates before scoring.
+    regular = [e for e in entries if not e.is_namespace_dir]
+    if regular:
+        entries = regular
+
+    scored: list[_ScoredCandidate] = []
+    for entry in entries:
+        root = entry.comp[: len(entry.comp) - len(suf)]
+        is_ancestor = root == importer_dir_parts[: len(root)]
+        scored.append(
+            _ScoredCandidate(
+                len(root), is_ancestor, entry.path, root, entry.is_namespace_dir
+            )
+        )
+
+    ancestors = [s for s in scored if s.is_ancestor]
+    if ancestors:
+        best_depth = max(s.root_depth for s in ancestors)
+        best = [s for s in ancestors if s.root_depth == best_depth]
+        return Resolved(best[0].path)
+
+    # a non-ancestor root is only valid if it is not itself inside a package:
+    # a module nested in someone else's package is not importable as a
+    # top-level name from another project. This filter only applies to
+    # single-file candidates (x.py); package candidates (x/__init__.py or a
+    # namespace dir x/) skip it.
+    def is_package(root: _PathParts) -> bool:
+        cand = module_candidates.get(root)
+        return (
+            cand is not None
+            and not cand.is_namespace_dir
+            and cand.path.name == "__init__.py"
+        )
+
+    def is_single_file_candidate(path: Path, isd: bool) -> bool:
+        return not isd and path.name != "__init__.py"
+
+    non_package_root = [
+        s
+        for s in scored
+        if not (
+            is_single_file_candidate(s.path, s.is_namespace_dir) and is_package(s.root)
+        )
+    ]
+    if len(non_package_root) == 1:
+        return Resolved(non_package_root[0].path)
+
+    if not non_package_root:
+        return _Unresolved()
+
+    return Ambiguous(tuple(s.path for s in non_package_root))
+
+
+def resolve_exact(
+    dotted_parts: Sequence[str],
+    importer_dir_parts: _PathParts,
+    suffix_index: SuffixIndex,
+    module_candidates: ModuleCandidates,
+) -> _Resolution:
+    if not dotted_parts or dotted_parts[0] in sys.stdlib_module_names:
+        return _Unresolved()
+    suf = tuple(dotted_parts)
+    cands = suffix_index.get(suf)
+    if not cands:
+        return _Unresolved()
+    return _disambiguate(cands, importer_dir_parts, suf, module_candidates)
+
+
+def resolve_relative(
+    module_parts: _PathParts,
+    level: int,
+    importer_dir_parts: _PathParts,
+    module_candidates: ModuleCandidates,
+) -> _Resolution:
+    drop = level - 1
+    if drop > len(importer_dir_parts):
+        return _Unresolved()
+    target_dir = (
+        importer_dir_parts[: len(importer_dir_parts) - drop]
+        if drop
+        else importer_dir_parts
+    )
+    comp = target_dir + module_parts
+    cand = module_candidates.get(comp)
+    if cand is None:
+        return _Unresolved()
+    return Resolved(cand.path)