pymap-cli 0.3.0__py3-none-any.whl

pymap/__init__.py

@@ -0,0 +1,37 @@
+"""pymap -- map a Python codebase in one command.
+
+It drives the tools that actually work on Python and gathers their output into
+a single page, plus a flow explorer that pymap builds itself:
+
+    pydeps      import graph between modules
+    pyreverse   class and package diagrams (ships with pylint)
+    code2flow   call graph at function level
+    tach        module graph + Mermaid, cycle detection
+
+The core depends only on the standard library: missing tools are reported and
+then skipped.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:  # imported lazily at runtime by __getattr__ below
+    from pymap.mapper import Report, map_codebase
+    from pymap.settings import Settings
+
+__version__ = "0.3.0"
+__all__ = ["Report", "Settings", "__version__", "map_codebase"]
+
+
+def __getattr__(name: str) -> Any:
+    # Lazy import, so `import pymap` stays instant when all you want is __version__.
+    if name in ("Report", "map_codebase"):
+        from pymap import mapper
+
+        return getattr(mapper, name)
+    if name == "Settings":
+        from pymap.settings import Settings
+
+        return Settings
+    raise AttributeError(f"module 'pymap' has no attribute {name!r}")

pymap/__main__.py

@@ -0,0 +1,8 @@
+"""Enables `python -m pymap`, useful when the console script is not on PATH."""
+
+import sys
+
+from pymap.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

pymap/analysis/__init__.py

@@ -0,0 +1 @@
+"""Static analysis: everything pymap works out on its own, without any tool."""

pymap/analysis/calls.py

@@ -0,0 +1,36 @@
+"""Reading the call graph produced by code2flow."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+Relations = dict[str, dict[str, list[str]]]
+
+
+def load_call_graph(path: str | Path) -> Relations:
+    """Read code2flow's JSON and return outgoing and incoming calls per symbol.
+
+    Result shape: ``{symbol: {"calls": [...], "called_by": [...]}}``. A missing
+    or unreadable file yields an empty graph: the explorer works without it, it
+    just loses navigation between functions.
+    """
+    try:
+        graph = json.loads(Path(path).read_text(encoding="utf-8"))["graph"]
+    except (OSError, ValueError, KeyError):
+        return {}
+
+    names = {node_id: node["name"] for node_id, node in graph["nodes"].items()}
+    relations: dict[str, dict[str, set[str]]] = {}
+    for edge in graph["edges"]:
+        source, target = names.get(edge["source"]), names.get(edge["target"])
+        if not source or not target:
+            continue
+        relations.setdefault(source, {"calls": set(), "called_by": set()})["calls"].add(target)
+        relations.setdefault(target, {"calls": set(), "called_by": set()})["called_by"].add(
+            source
+        )
+    return {
+        name: {side: sorted(values) for side, values in sides.items()}
+        for name, sides in relations.items()
+    }

pymap/analysis/cycles.py

@@ -0,0 +1,43 @@
+"""Circular dependency detection in a module graph."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+
+#: Past this point the list stops being actionable; show the first cycles only.
+MAX_CYCLES = 12
+
+
+def detect(deps: Mapping[str, Sequence[str]], limit: int = MAX_CYCLES) -> list[list[str]]:
+    """Find circular dependencies with a depth-first walk.
+
+    ``deps`` maps each node to the nodes it depends on. Returns closed paths
+    (the first node is repeated at the end), deduplicated by node set so the
+    same cycle is not reported once per entry point.
+    """
+    found: list[list[str]] = []
+    state: dict[str, int] = {}
+
+    def visit(node: str, stack: list[str]) -> None:
+        if state.get(node) == 1:
+            if node in stack:
+                found.append([*stack[stack.index(node) :], node])
+            return
+        if state.get(node) == 2:
+            return
+        state[node] = 1
+        for child in deps.get(node, []):
+            visit(child, [*stack, node])
+        state[node] = 2
+
+    for node in list(deps):
+        visit(node, [])
+
+    unique: list[list[str]] = []
+    seen: set[frozenset[str]] = set()
+    for cycle in found:
+        key = frozenset(cycle)
+        if key not in seen:
+            seen.add(key)
+            unique.append(cycle)
+    return unique[:limit]

pymap/analysis/flow.py

@@ -0,0 +1,175 @@
+"""Execution tree of a function: sequences, branches, loops, exits.
+
+code2flow tells you WHO gets called. This module tells you IN WHAT ORDER, UNDER
+WHICH CONDITION, and above all WHAT DATA flows in and out of each step.
+
+Every step is a dict with a ``k`` (kind) key. The shapes are:
+
+===========  ==========================================
+kind         payload
+===========  ==========================================
+``call``     ``name``, ``line``, ``args``, ``kw``, ``out``
+``branch``   ``test``, ``line``, ``then``, ``alt``
+``loop``     ``test``, ``line``, ``body``
+``try``      ``line``, ``body``, ``fallback``
+``return``   ``expr``, ``line``
+``raise``    ``expr``, ``line``
+===========  ==========================================
+
+These key names are a contract with ``templates/explorer.html``; see
+``tests/test_contract.py``, which fails if the two drift apart.
+"""
+
+from __future__ import annotations
+
+import ast
+import builtins
+from typing import Any
+
+Step = dict[str, Any]
+
+#: Calls too common to carry any signal in a diagram. Written as one string so
+#: the list stays dense: a set literal of 50 short names formats to 50 lines.
+TRIVIAL = set(dir(builtins)) | set(
+    """
+    get set pop append extend keys values items join split strip lower upper
+    format encode decode setdefault copy add remove insert index count replace
+    read write close seek rstrip lstrip find group match search sub dumps loads
+    deepcopy warn debug info warning error exception super partial wraps
+    strftime now cast len print
+    """.split()
+)
+
+#: Steps kept per function, so diagrams stay readable.
+BUDGET = 90
+
+
+def call_name(node: ast.expr) -> str | None:
+    """Readable name of a call target, or None when the expression is too indirect."""
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        return node.attr
+    if isinstance(node, ast.Call):
+        return call_name(node.func)
+    return None
+
+
+def short(node: ast.AST | None, limit: int = 34) -> str:
+    """Render an AST node as a short, readable one-liner."""
+    if node is None:
+        return ""
+    try:
+        text = " ".join(ast.unparse(node).split())
+    except Exception:
+        return "?"
+    return text if len(text) <= limit else text[: limit - 1] + "…"
+
+
+def call_flow(func: ast.AST, budget: list[int] | None = None) -> list[Step]:
+    """Build the execution tree of ``func``'s body.
+
+    ``budget`` is a single-item list used as a shared mutable counter, so that
+    nested blocks draw from the same allowance as the top level.
+    """
+    if budget is None:
+        budget = [BUDGET]
+
+    def calls(node: ast.AST, out: str | None = None) -> list[Step]:
+        steps = []
+        for sub in ast.walk(node):
+            if isinstance(sub, ast.Call):
+                name = call_name(sub.func)
+                if not name or name in TRIVIAL:
+                    continue
+                steps.append(
+                    {
+                        "k": "call",
+                        "name": name,
+                        "line": getattr(sub, "lineno", 0),
+                        "args": [short(a, 20) for a in sub.args][:4],
+                        "kw": [kw.arg for kw in sub.keywords if kw.arg][:3],
+                        "out": out,
+                    }
+                )
+        return steps
+
+    def visit(body: list[ast.stmt]) -> list[Step]:
+        block: list[Step] = []
+        for node in body:
+            if budget[0] <= 0:
+                break
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+                continue
+            if isinstance(node, ast.If):
+                budget[0] -= 1
+                block.append(
+                    {
+                        "k": "branch",
+                        "test": short(node.test, 44),
+                        "line": node.lineno,
+                        "then": visit(node.body),
+                        "alt": visit(node.orelse),
+                    }
+                )
+            elif isinstance(node, (ast.For, ast.AsyncFor)):
+                budget[0] -= 1
+                block.append(
+                    {
+                        "k": "loop",
+                        "test": f"for {short(node.target, 14)} in {short(node.iter, 22)}",
+                        "line": node.lineno,
+                        "body": visit(node.body),
+                    }
+                )
+            elif isinstance(node, ast.While):
+                budget[0] -= 1
+                block.append(
+                    {
+                        "k": "loop",
+                        "test": f"while {short(node.test, 28)}",
+                        "line": node.lineno,
+                        "body": visit(node.body),
+                    }
+                )
+            elif isinstance(node, ast.Try):
+                budget[0] -= 1
+                fallback: list[Step] = []
+                for handler in node.handlers:
+                    fallback += visit(handler.body)
+                block.append(
+                    {
+                        "k": "try",
+                        "line": node.lineno,
+                        "body": visit(node.body) + visit(node.orelse),
+                        "fallback": fallback + visit(node.finalbody),
+                    }
+                )
+            elif isinstance(node, (ast.With, ast.AsyncWith)):
+                for item in node.items:
+                    block += calls(item.context_expr)
+                block += visit(node.body)
+            elif isinstance(node, ast.Assign):
+                block += calls(node.value, short(node.targets[0], 18))
+            elif isinstance(node, ast.AnnAssign) and node.value is not None:
+                block += calls(node.value, short(node.target, 18))
+            elif isinstance(node, ast.Return):
+                block += calls(node)
+                block.append(
+                    {
+                        "k": "return",
+                        "expr": short(node.value, 36) or "None",
+                        "line": node.lineno,
+                    }
+                )
+            elif isinstance(node, ast.Raise):
+                block += calls(node)
+                block.append(
+                    {"k": "raise", "expr": short(node.exc, 32) or "?", "line": node.lineno}
+                )
+            else:
+                block += calls(node)
+            budget[0] -= 1
+        return block
+
+    return visit(func.body)

pymap/analysis/symbols.py

@@ -0,0 +1,175 @@
+"""Inventory of a codebase: modules, classes, functions, methods.
+
+Everything goes through the standard library's AST: no code from the analysed
+project is ever imported or executed, so there are no side effects and nothing
+to install on the target's behalf.
+
+Symbol keys are ``<module stem>::<qualified name>``, which is the naming scheme
+code2flow uses for its graph nodes -- that shared shape is what lets the two
+data sets be joined. It also means two files with the same basename share a
+namespace; see ``duplicate_modules``.
+"""
+
+from __future__ import annotations
+
+import ast
+from collections import Counter
+from collections.abc import Iterable
+from pathlib import Path
+from typing import Any
+
+from pymap.analysis.flow import call_flow, short
+
+Symbol = dict[str, Any]
+
+#: Parameters kept per signature in the input diagram.
+MAX_PARAMS = 10
+
+
+def parameters(func: ast.FunctionDef | ast.AsyncFunctionDef) -> list[dict[str, str]]:
+    """Incoming data: parameters, with their type when annotated."""
+    args = func.args
+    out = []
+    for arg in args.posonlyargs + args.args + args.kwonlyargs:
+        if arg.arg == "self":
+            continue
+        out.append({"n": arg.arg, "t": short(arg.annotation, 22) if arg.annotation else ""})
+    if args.vararg:
+        out.append({"n": "*" + args.vararg.arg, "t": ""})
+    if args.kwarg:
+        out.append({"n": "**" + args.kwarg.arg, "t": ""})
+    return out[:MAX_PARAMS]
+
+
+def signature(node: ast.FunctionDef | ast.AsyncFunctionDef) -> str:
+    """Rebuild a function's signature from its AST node."""
+    try:
+        args = node.args
+        parts: list[str] = []
+        positional = args.posonlyargs + args.args
+        defaults = [None] * (len(positional) - len(args.defaults)) + list(args.defaults)
+        for arg, default in zip(positional, defaults):
+            text = arg.arg
+            if arg.annotation:
+                text += f": {ast.unparse(arg.annotation)}"
+            if default is not None:
+                text += f"={ast.unparse(default)}"
+            parts.append(text)
+            if args.posonlyargs and arg is args.posonlyargs[-1]:
+                parts.append("/")
+        if args.vararg:
+            parts.append("*" + args.vararg.arg)
+        elif args.kwonlyargs:
+            parts.append("*")
+        for arg, default in zip(args.kwonlyargs, args.kw_defaults):
+            text = arg.arg
+            if arg.annotation:
+                text += f": {ast.unparse(arg.annotation)}"
+            if default is not None:
+                text += f"={ast.unparse(default)}"
+            parts.append(text)
+        if args.kwarg:
+            parts.append("**" + args.kwarg.arg)
+        returns = f" -> {ast.unparse(node.returns)}" if node.returns else ""
+        return f"({', '.join(parts)}){returns}"
+    except Exception:
+        return "(...)"
+
+
+def _descend(node: ast.AST, module: str, relative: str, prefix: str = "") -> list[Symbol]:
+    """Classes and functions declared directly under ``node``, depth first."""
+    symbols: list[Symbol] = []
+    for child in getattr(node, "body", []):
+        if isinstance(child, ast.ClassDef):
+            qualified = f"{prefix}{child.name}"
+            bases = [ast.unparse(base) for base in child.bases]
+            symbols.append(
+                {
+                    "key": f"{module}::{qualified}",
+                    "name": child.name,
+                    "kind": "class",
+                    "module": module,
+                    "file": relative,
+                    "line": child.lineno,
+                    "sig": f"({', '.join(bases)})" if bases else "",
+                    "doc": ast.get_docstring(child) or "",
+                    "parent": prefix.rstrip("."),
+                }
+            )
+        elif isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            qualified = f"{prefix}{child.name}"
+            symbols.append(
+                {
+                    "key": f"{module}::{qualified}",
+                    "name": child.name,
+                    "kind": "method" if prefix else "function",
+                    "module": module,
+                    "file": relative,
+                    "line": child.lineno,
+                    "sig": signature(child),
+                    "decorators": [ast.unparse(d) for d in child.decorator_list],
+                    "flow": call_flow(child),
+                    "params": parameters(child),
+                    "doc": ast.get_docstring(child) or "",
+                    "parent": prefix.rstrip("."),
+                }
+            )
+        else:
+            continue
+        symbols += _descend(child, module, relative, qualified + ".")
+    return symbols
+
+
+def extract(root: Path, files: Iterable[Path]) -> list[Symbol]:
+    """Walk each file's AST and collect modules, classes and functions.
+
+    ``root`` is used to compute the displayed relative paths; ``files`` is the
+    already filtered list of sources to read (see :mod:`pymap.settings`). Files
+    that fail to parse are skipped silently rather than aborting the run.
+    """
+    symbols: list[Symbol] = []
+    for path in sorted(files):
+        relative = path.relative_to(root).as_posix()
+        module = path.stem
+        try:
+            tree = ast.parse(path.read_text(encoding="utf-8", errors="ignore"))
+        except (SyntaxError, ValueError, OSError):
+            continue
+
+        symbols.append(
+            {
+                "key": f"{module}::(module)",
+                "name": module,
+                "kind": "module",
+                "module": module,
+                "file": relative,
+                "line": 1,
+                "sig": "",
+                "doc": ast.get_docstring(tree) or "",
+                "parent": "",
+            }
+        )
+        symbols += _descend(tree, module, relative)
+    return symbols
+
+
+def coverage(symbols: list[Symbol]) -> tuple[int, int, int]:
+    """(documentable, documented, percentage) -- modules do not count."""
+    documentable = [s for s in symbols if s["kind"] != "module"]
+    documented = sum(1 for s in documentable if s["doc"])
+    percent = round(100 * documented / len(documentable)) if documentable else 0
+    return len(documentable), documented, percent
+
+
+def duplicate_modules(files: Iterable[Path]) -> dict[str, int]:
+    """Basenames shared by several files, mapped to how many files share them.
+
+    Symbol keys are built from the file stem, so ``app/models.py`` and
+    ``blog/models.py`` land in the same namespace and their symbols merge in the
+    explorer. Callers surface this so the merge is visible rather than silent.
+
+    ``__init__.py`` is left out: every package has one, so reporting it would
+    fire on any well-structured project and teach readers to ignore the notice.
+    """
+    counts = Counter(path.stem for path in files if path.name != "__init__.py")
+    return {stem: n for stem, n in sorted(counts.items()) if n > 1}

pymap/cli.py

@@ -0,0 +1,143 @@
+"""Command-line interface.
+
+pymap                      # guess the current project's package
+pymap src/mypkg -o map/ --open
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import webbrowser
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any, Callable
+
+from pymap import __version__
+from pymap.mapper import map_codebase
+from pymap.runner import missing
+from pymap.settings import EDITORS, EXCLUDED, Settings, detect_target, read_pyproject
+
+DEFAULTS = {"output": "pymap-out", "editor": "vscode", "timeout": 300}
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="pymap",
+        description="Map a Python codebase in one command.",
+        epilog="Options can also live in [tool.pymap] in pyproject.toml.",
+    )
+    parser.add_argument(
+        "target", nargs="?", help="package directory to analyse (guessed when omitted)"
+    )
+    parser.add_argument(
+        "-o", "--out", dest="output", help="output directory (default: pymap-out)"
+    )
+    parser.add_argument(
+        "--exclude",
+        action="append",
+        metavar="PATTERN",
+        help="directory or file pattern to skip (repeatable)",
+    )
+    parser.add_argument(
+        "--editor",
+        metavar="NAME",
+        help="editor for code links: "
+        + ", ".join(EDITORS)
+        + ", or a URI template containing {f} and {l}",
+    )
+    parser.add_argument(
+        "--timeout", type=int, metavar="S", help="max seconds per external tool (default: 300)"
+    )
+    parser.add_argument(
+        "--open",
+        dest="open_in_browser",
+        action="store_true",
+        help="open the map in a browser when done",
+    )
+    parser.add_argument("--version", action="version", version=f"pymap {__version__}")
+    return parser
+
+
+def _resolve_path(value: str, base: Path) -> Path:
+    path = Path(value).expanduser()
+    return path if path.is_absolute() else base / path
+
+
+def build_settings(args: argparse.Namespace, cwd: Path | None = None) -> Settings:
+    """Merge command-line arguments, pyproject.toml and defaults.
+
+    The command line always wins. Relative paths coming from a pyproject.toml
+    are resolved against that file; those from the command line against the
+    current directory.
+    """
+    current = Path(cwd or Path.cwd()).resolve()
+    data, config = read_pyproject(current)
+    from_file: dict[str, Any] = data.get("tool", {}).get("pymap", {})
+    root = config.parent if config else current
+
+    if args.target:
+        target = _resolve_path(args.target, current)
+    else:
+        guessed = detect_target(current)
+        if guessed is None:
+            raise SystemExit(
+                "No Python package found.\n"
+                "  pymap looks for src/<package>/, the package named after the "
+                "project,\n"
+                '  or [tool.pymap] target = "..." in pyproject.toml.\n'
+                "  Point at it explicitly:  pymap path/to/my_package"
+            )
+        target = guessed
+
+    if args.output:
+        output = _resolve_path(args.output, current)
+    else:
+        output = _resolve_path(from_file.get("output", DEFAULTS["output"]), root)
+
+    editor = args.editor or from_file.get("editor", DEFAULTS["editor"])
+    if editor not in EDITORS and "{f}" not in editor:
+        raise SystemExit(
+            f"Unknown editor: {editor}\n"
+            f"  known: {', '.join(EDITORS)}\n"
+            "  or a URI template, e.g. 'myeditor://{f}:{l}'"
+        )
+
+    return Settings(
+        target=target,
+        output=output,
+        excluded=EXCLUDED + tuple(from_file.get("exclude", ())) + tuple(args.exclude or ()),
+        editor=editor,
+        timeout=args.timeout or from_file.get("timeout", DEFAULTS["timeout"]),
+        open_in_browser=args.open_in_browser,
+    )
+
+
+def warn_missing_tools(log: Callable[[str], Any] = print) -> None:
+    """Report missing tools without blocking: every step knows how to skip itself."""
+    absent = missing()
+    if not absent:
+        return
+    log("Missing tools (the matching steps will be skipped):")
+    for tool in absent:
+        log(f"  {tool.name:12} {tool.role:24} {tool.install}")
+    log("")
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    settings = build_settings(args)
+    warn_missing_tools()
+    try:
+        report = map_codebase(settings, log=print)
+    except (NotADirectoryError, FileNotFoundError) as exc:
+        print(exc, file=sys.stderr)
+        return 1
+    print(f"\nMap ready: {report.index}")
+    if settings.open_in_browser and report.index:
+        webbrowser.open(report.index.as_uri())
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())