classmap-hanthink 0.1.0__py3-none-any.whl

classmap_hanthink/__init__.py

@@ -0,0 +1,16 @@
+from .model import ClassInfo
+from .scanner import scan_file, scan_path
+from .tree import build_inheritance_map, find_roots, find_independent_classes
+from .render import render_text_tree, render_explanation, render_mermaid
+
+__all__ = [
+    "ClassInfo",
+    "scan_file",
+    "scan_path",
+    "build_inheritance_map",
+    "find_roots",
+    "find_independent_classes",
+    "render_text_tree",
+    "render_explanation",
+    "render_mermaid",
+]

classmap_hanthink/cli.py

@@ -0,0 +1,47 @@
+import argparse
+from pathlib import Path
+
+from .scanner import scan_path
+from .tree import build_inheritance_map
+from .render import render_text_tree, render_explanation, render_mermaid
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="classmap",
+        description="Scan Python classes and show inheritance relationships as a tree.",
+    )
+    parser.add_argument("target", nargs="?", default=".", help="Python file or folder to scan.")
+    parser.add_argument("--explain", action="store_true", help="Show beginner-friendly explanation.")
+    parser.add_argument("--mermaid", action="store_true", help="Render Mermaid classDiagram output.")
+
+    args = parser.parse_args(argv)
+
+    target = Path(args.target)
+    classes = scan_path(target)
+    tree = build_inheritance_map(classes)
+
+    if args.mermaid:
+        print(render_mermaid(classes, tree))
+        if args.explain:
+            print()
+            print(render_explanation(classes, tree))
+        return 0
+
+    print("classmap report")
+    print()
+    print(f"Target: {target}")
+    print(f"Resolved path: {target.resolve()}")
+    print(f"Classes found: {len(classes)}")
+    print()
+    print(render_text_tree(classes, tree))
+
+    if args.explain:
+        print()
+        print(render_explanation(classes, tree))
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

classmap_hanthink/model.py

@@ -0,0 +1,19 @@
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class ClassInfo:
+    """Information about one Python class definition."""
+
+    name: str
+    bases: tuple[str, ...] = field(default_factory=tuple)
+    file: str = ""
+    line: int = 0
+
+    @property
+    def location(self) -> str:
+        if self.file and self.line:
+            return f"{self.file}:{self.line}"
+        if self.file:
+            return self.file
+        return "unknown"

classmap_hanthink/render.py

@@ -0,0 +1,99 @@
+from .model import ClassInfo
+from .tree import find_independent_classes, find_roots
+
+
+def _location_map(classes: list[ClassInfo]) -> dict[str, str]:
+    return {item.name: item.location for item in classes}
+
+
+def _render_node(name, tree, locations, prefix="", is_last=True, is_root=True) -> list[str]:
+    label = f"{name} [{locations.get(name, 'unknown')}]"
+
+    if is_root:
+        lines = [label]
+    else:
+        connector = "└── " if is_last else "├── "
+        lines = [prefix + connector + label]
+
+    children = tree.get(name, [])
+
+    if not is_root:
+        prefix = prefix + ("    " if is_last else "│   ")
+
+    for index, child in enumerate(children):
+        lines.extend(
+            _render_node(
+                child,
+                tree,
+                locations,
+                prefix=prefix,
+                is_last=index == len(children) - 1,
+                is_root=False,
+            )
+        )
+
+    return lines
+
+
+def render_text_tree(classes: list[ClassInfo], tree: dict[str, list[str]]) -> str:
+    if not classes:
+        return "No classes found."
+
+    locations = _location_map(classes)
+    roots = find_roots(classes, tree)
+    independent = find_independent_classes(classes, tree)
+
+    lines: list[str] = ["Inheritance Tree", ""]
+
+    if roots:
+        for root in roots:
+            lines.extend(_render_node(root, tree, locations))
+            lines.append("")
+    else:
+        lines.append("No inheritance relationships found.")
+        lines.append("")
+
+    if independent:
+        lines.append("Independent Classes")
+        lines.append("")
+        for name in independent:
+            lines.append(f"- {name} [{locations.get(name, 'unknown')}]")
+        lines.append("")
+
+    return "\n".join(lines).rstrip()
+
+
+def render_explanation(classes: list[ClassInfo], tree: dict[str, list[str]]) -> str:
+    if not classes:
+        return "No classes were found in the target."
+
+    lines = ["Explanation", ""]
+
+    for parent, children in sorted(tree.items()):
+        joined = ", ".join(children)
+        lines.append(f"- {parent} has {len(children)} child class(es): {joined}")
+
+    independent = find_independent_classes(classes, tree)
+    for name in independent:
+        lines.append(f"- {name} is independent.")
+
+    if len(lines) == 2:
+        lines.append("- Classes were found, but no inheritance relationships were detected.")
+
+    return "\n".join(lines)
+
+
+def render_mermaid(classes: list[ClassInfo], tree: dict[str, list[str]]) -> str:
+    lines = ["classDiagram"]
+    added_edge = False
+
+    for parent, children in sorted(tree.items()):
+        for child in children:
+            lines.append(f"    {parent} <|-- {child}")
+            added_edge = True
+
+    if not added_edge:
+        for item in classes:
+            lines.append(f"    class {item.name}")
+
+    return "\n".join(lines)

classmap_hanthink/scanner.py

@@ -0,0 +1,85 @@
+import ast
+from pathlib import Path
+
+from .model import ClassInfo
+
+
+DEFAULT_SKIP_DIRS = {
+    ".git", ".venv", "venv", "__pycache__", ".pytest_cache",
+    "dist", "build", ".mypy_cache", ".ruff_cache",
+}
+
+
+def _base_name(base: ast.expr) -> str | None:
+    if isinstance(base, ast.Name):
+        return base.id
+
+    if isinstance(base, ast.Attribute):
+        parts: list[str] = []
+        node: ast.AST = base
+        while isinstance(node, ast.Attribute):
+            parts.append(node.attr)
+            node = node.value
+        if isinstance(node, ast.Name):
+            parts.append(node.id)
+        return ".".join(reversed(parts))
+
+    if isinstance(base, ast.Subscript):
+        return _base_name(base.value)
+
+    return None
+
+
+def scan_file(path: str | Path) -> list[ClassInfo]:
+    file_path = Path(path)
+
+    if file_path.suffix != ".py":
+        return []
+
+    source = file_path.read_text(encoding="utf-8")
+    tree = ast.parse(source, filename=str(file_path))
+
+    classes: list[ClassInfo] = []
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ClassDef):
+            bases = tuple(
+                name for base in node.bases
+                if (name := _base_name(base)) is not None
+            )
+            classes.append(
+                ClassInfo(
+                    name=node.name,
+                    bases=bases,
+                    file=str(file_path),
+                    line=node.lineno,
+                )
+            )
+
+    return sorted(classes, key=lambda item: (item.file, item.line, item.name))
+
+
+def _iter_python_files(path: Path) -> list[Path]:
+    if path.is_file():
+        return [path] if path.suffix == ".py" else []
+
+    files: list[Path] = []
+    for child in path.rglob("*.py"):
+        if any(part in DEFAULT_SKIP_DIRS for part in child.parts):
+            continue
+        files.append(child)
+
+    return sorted(files)
+
+
+def scan_path(path: str | Path) -> list[ClassInfo]:
+    target = Path(path)
+
+    if not target.exists():
+        raise FileNotFoundError(f"Path does not exist: {target}")
+
+    classes: list[ClassInfo] = []
+    for file_path in _iter_python_files(target):
+        classes.extend(scan_file(file_path))
+
+    return sorted(classes, key=lambda item: (item.file, item.line, item.name))

classmap_hanthink/tree.py

@@ -0,0 +1,35 @@
+from collections import defaultdict
+
+from .model import ClassInfo
+
+
+def build_inheritance_map(classes: list[ClassInfo]) -> dict[str, list[str]]:
+    known_names = {item.name for item in classes}
+    children: dict[str, list[str]] = defaultdict(list)
+
+    for item in classes:
+        for base in item.bases:
+            short_base = base.split(".")[-1]
+            if short_base in known_names:
+                children[short_base].append(item.name)
+
+    return {parent: sorted(child_list) for parent, child_list in children.items()}
+
+
+def find_roots(classes: list[ClassInfo], tree: dict[str, list[str]]) -> list[str]:
+    child_names = {child for children in tree.values() for child in children}
+    roots = [item.name for item in classes if item.name in tree and item.name not in child_names]
+    return sorted(set(roots))
+
+
+def find_independent_classes(classes: list[ClassInfo], tree: dict[str, list[str]]) -> list[str]:
+    known_names = {item.name for item in classes}
+    parent_names = set(tree.keys())
+    independent = []
+
+    for item in classes:
+        has_known_parent = any(base.split(".")[-1] in known_names for base in item.bases)
+        if not has_known_parent and item.name not in parent_names:
+            independent.append(item.name)
+
+    return sorted(independent)

classmap_hanthink-0.1.0.dist-info/METADATA

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: classmap-hanthink
+Version: 0.1.0
+Summary: Scan Python class inheritance relationships and render them as readable maps.
+Project-URL: Homepage, https://github.com/Han-think/classmap-hanthink
+Author: Han-think
+License: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# classmap-hanthink
+
+`classmap-hanthink` is a small Python developer tool that scans Python files and shows class inheritance relationships as a readable tree.
+
+Simple explanation:
+
+> It helps you see which class is the parent and which classes are children.
+
+Technical explanation:
+
+> It parses Python source code with the standard `ast` module, extracts class definitions and base classes, builds a parent-to-child inheritance map, and renders the result as a text tree.
+
+## Installation
+
+```bash
+pip install classmap-hanthink
+```
+
+## CLI Usage
+
+Scan the current folder:
+
+```bash
+classmap .
+```
+
+Scan a specific file:
+
+```bash
+classmap examples/sample_classes.py
+```
+
+Show explanation text:
+
+```bash
+classmap . --explain
+```
+
+Show Mermaid class diagram output:
+
+```bash
+classmap . --mermaid
+```
+
+## Python Usage
+
+```python
+from classmap_hanthink import scan_path, build_inheritance_map, render_text_tree
+
+classes = scan_path("examples/sample_classes.py")
+tree = build_inheritance_map(classes)
+print(render_text_tree(classes, tree))
+```
+
+## Example Output
+
+```text
+classmap report
+
+Target: examples/sample_classes.py
+Classes found: 6
+
+Inheritance Tree
+
+Animal [examples/sample_classes.py:1]
+├── Cat [examples/sample_classes.py:13]
+└── Dog [examples/sample_classes.py:5]
+    └── Puppy [examples/sample_classes.py:9]
+
+Independent Classes
+
+- Config [examples/sample_classes.py:17]
+- ExternalChild [examples/sample_classes.py:21]
+```
+
+## Development
+
+```bash
+uv sync --group dev
+uv run pytest tests/ -v
+uv build
+```
+
+## Release Roadmap
+
+### v0.1.0
+
+- Scan Python files and folders
+- Extract class names, base classes, file paths, and line numbers
+- Build parent-to-child inheritance relationships
+- Render text tree output
+- Render optional explanation output
+- Render optional Mermaid classDiagram output
+- Provide CLI command: `classmap`

classmap_hanthink-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+classmap_hanthink/__init__.py,sha256=dramHDI-wpL7WCy6sdNIqI0uzhj4UlZGx3Wtp67EqFA,439
+classmap_hanthink/cli.py,sha256=-vnCy4bnwaNazSG7-kvgQ0XgD5CDDNFSMgG_envG7wA,1398
+classmap_hanthink/model.py,sha256=K_vV55Q6XpoFD-yVELr-dCGpNolkg23TwTNqSZHjjRM,455
+classmap_hanthink/render.py,sha256=tr54hxLOH9VdpiYUQ9IFHKOAajNxz1_pWjve1jkztFY,2852
+classmap_hanthink/scanner.py,sha256=jf7oVGVEJeNCJ81nWB8oM8P226TE_nfeQ7cqKK3tzhU,2260
+classmap_hanthink/tree.py,sha256=Bun7WM_IDe5LGozWLC75j1ZAtlN8WK0z4RDGwp7LxpQ,1288
+classmap_hanthink-0.1.0.dist-info/METADATA,sha256=slOrzOu-Msg_SRWF3Hl4t8fkz3nmLbroC9PUZcrOiY4,2337
+classmap_hanthink-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+classmap_hanthink-0.1.0.dist-info/entry_points.txt,sha256=9abC2TA-GJJEVvCV-fmQS77Raj7hRu5RxxACijh0bJ4,56
+classmap_hanthink-0.1.0.dist-info/licenses/LICENSE,sha256=NHEqsMLJRDBrcNXbBpojCsOinRqPsxZjpxgvb0ZP_7w,218
+classmap_hanthink-0.1.0.dist-info/RECORD,,

classmap_hanthink-0.1.0.dist-info/WHEEL

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

classmap_hanthink-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+classmap = classmap_hanthink.cli:main

classmap_hanthink-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,7 @@
+MIT License
+
+Copyright (c) 2026 Han-think
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files, to deal in the Software
+without restriction.