classmap-hanthink 0.1.0__tar.gz → 0.2.0__tar.gz

{classmap_hanthink-0.1.0 → classmap_hanthink-0.2.0}/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## [0.2.0] - 2026-06-04
+
+### Added
+
+- Added `--show-external` CLI option.
+- Added external and built-in base class detection.
+- Added `External Base Classes` output section.
+- Added external base support for Mermaid and explanation output.
+
+
 ## [0.1.0] - 2026-06-04
 
 ### Added

{classmap_hanthink-0.1.0 → classmap_hanthink-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: classmap-hanthink
-Version: 0.1.0
+Version: 0.2.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
@@ -106,3 +106,21 @@ uv build
 - Render optional explanation output
 - Render optional Mermaid classDiagram output
 - Provide CLI command: `classmap`
+
+
+## External Base Classes
+
+Use `--show-external` to show classes that inherit from external or built-in base classes.
+
+```bash
+classmap examples/sample_classes.py --show-external
+```
+
+Example output:
+
+```text
+External Base Classes
+
+dict
+└── ExternalChild [examples/sample_classes.py:21]
+```

{classmap_hanthink-0.1.0 → classmap_hanthink-0.2.0}/README.md

@@ -92,3 +92,21 @@ uv build
 - Render optional explanation output
 - Render optional Mermaid classDiagram output
 - Provide CLI command: `classmap`
+
+
+## External Base Classes
+
+Use `--show-external` to show classes that inherit from external or built-in base classes.
+
+```bash
+classmap examples/sample_classes.py --show-external
+```
+
+Example output:
+
+```text
+External Base Classes
+
+dict
+└── ExternalChild [examples/sample_classes.py:21]
+```

{classmap_hanthink-0.1.0 → classmap_hanthink-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "classmap-hanthink"
-version = "0.1.0"
+version = "0.2.0"
 authors = [{ name = "Han-think" }]
 description = "Scan Python class inheritance relationships and render them as readable maps."
 readme = "README.md"

{classmap_hanthink-0.1.0 → classmap_hanthink-0.2.0}/src/classmap_hanthink/__init__.py

@@ -1,6 +1,6 @@
 from .model import ClassInfo
 from .scanner import scan_file, scan_path
-from .tree import build_inheritance_map, find_roots, find_independent_classes
+from .tree import build_inheritance_map, build_external_base_map, find_roots, find_independent_classes
 from .render import render_text_tree, render_explanation, render_mermaid
 
 __all__ = [
@@ -8,6 +8,7 @@ __all__ = [
     "scan_file",
     "scan_path",
     "build_inheritance_map",
+    "build_external_base_map",
     "find_roots",
     "find_independent_classes",
     "render_text_tree",

{classmap_hanthink-0.1.0 → classmap_hanthink-0.2.0}/src/classmap_hanthink/cli.py

@@ -2,7 +2,7 @@ import argparse
 from pathlib import Path
 
 from .scanner import scan_path
-from .tree import build_inheritance_map
+from .tree import build_external_base_map, build_inheritance_map
 from .render import render_text_tree, render_explanation, render_mermaid
 
 
@@ -14,18 +14,20 @@ def main(argv: list[str] | None = None) -> int:
     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.")
+    parser.add_argument("--show-external", action="store_true", help="Show external or built-in base classes.")
 
     args = parser.parse_args(argv)
 
     target = Path(args.target)
     classes = scan_path(target)
     tree = build_inheritance_map(classes)
+    external_map = build_external_base_map(classes)
 
     if args.mermaid:
-        print(render_mermaid(classes, tree))
+        print(render_mermaid(classes, tree, external_map, show_external=args.show_external))
         if args.explain:
             print()
-            print(render_explanation(classes, tree))
+            print(render_explanation(classes, tree, external_map, show_external=args.show_external))
         return 0
 
     print("classmap report")
@@ -34,11 +36,11 @@ def main(argv: list[str] | None = None) -> int:
     print(f"Resolved path: {target.resolve()}")
     print(f"Classes found: {len(classes)}")
     print()
-    print(render_text_tree(classes, tree))
+    print(render_text_tree(classes, tree, external_map, show_external=args.show_external))
 
     if args.explain:
         print()
-        print(render_explanation(classes, tree))
+        print(render_explanation(classes, tree, external_map, show_external=args.show_external))
 
     return 0
 

classmap_hanthink-0.2.0/src/classmap_hanthink/render.py

@@ -0,0 +1,144 @@
+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_external_bases(external_map: dict[str, list[str]], locations: dict[str, str] | None = None) -> str:
+    """Render external or built-in base class relationships."""
+    if not external_map:
+        return ""
+
+    locations = locations or {}
+    lines = ["External Base Classes", ""]
+
+    for base, children in sorted(external_map.items()):
+        lines.append(base)
+        for index, child in enumerate(children):
+            connector = "└── " if index == len(children) - 1 else "├── "
+            lines.append(f"{connector}{child} [{locations.get(child, 'unknown')}]")
+        lines.append("")
+
+    return "\n".join(lines).rstrip()
+
+
+def render_text_tree(
+    classes: list[ClassInfo],
+    tree: dict[str, list[str]],
+    external_map: dict[str, list[str]] | None = None,
+    *,
+    show_external: bool = False,
+) -> str:
+    """Render the inheritance map as a readable text tree."""
+    if not classes:
+        return "No classes found."
+
+    locations = _location_map(classes)
+    roots = find_roots(classes, tree)
+    independent = find_independent_classes(classes, tree, external_map, exclude_external=show_external)
+
+    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 show_external and external_map:
+        lines.append(render_external_bases(external_map, locations))
+        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]],
+    external_map: dict[str, list[str]] | None = None,
+    *,
+    show_external: bool = False,
+) -> str:
+    """Render beginner-friendly explanation text."""
+    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}")
+
+    if show_external and external_map:
+        for base, children in sorted(external_map.items()):
+            joined = ", ".join(children)
+            lines.append(f"- {base} is an external or built-in base class for: {joined}")
+
+    independent = find_independent_classes(classes, tree, external_map, exclude_external=show_external)
+    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]],
+    external_map: dict[str, list[str]] | None = None,
+    *,
+    show_external: bool = False,
+) -> str:
+    """Render the inheritance map as Mermaid classDiagram syntax."""
+    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 show_external and external_map:
+        for base, children in sorted(external_map.items()):
+            for child in children:
+                lines.append(f"    {base} <|-- {child}")
+                added_edge = True
+
+    if not added_edge:
+        for item in classes:
+            lines.append(f"    class {item.name}")
+
+    return "\n".join(lines)

classmap_hanthink-0.2.0/src/classmap_hanthink/tree.py

@@ -0,0 +1,72 @@
+from collections import defaultdict
+
+from .model import ClassInfo
+
+
+def build_inheritance_map(classes: list[ClassInfo]) -> dict[str, list[str]]:
+    """Build a parent-to-children inheritance map using only scanned classes."""
+    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 build_external_base_map(classes: list[ClassInfo]) -> dict[str, list[str]]:
+    """Build an external-base-to-children map.
+
+    External base classes are base classes that appear in class definitions
+    but are not defined inside the scanned target.
+    """
+    known_names = {item.name for item in classes}
+    external: dict[str, list[str]] = defaultdict(list)
+
+    for item in classes:
+        for base in item.bases:
+            short_base = base.split(".")[-1]
+            if short_base not in known_names:
+                external[base].append(item.name)
+
+    return {base: sorted(child_list) for base, child_list in sorted(external.items())}
+
+
+def find_roots(classes: list[ClassInfo], tree: dict[str, list[str]]) -> list[str]:
+    """Find root classes that have internal children but no internal parent."""
+    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]],
+    external_map: dict[str, list[str]] | None = None,
+    *,
+    exclude_external: bool = False,
+) -> list[str]:
+    """Find classes that are not connected to known inheritance relationships."""
+    known_names = {item.name for item in classes}
+    child_names = {child for children in tree.values() for child in children}
+    parent_names = set(tree.keys())
+    external_children = set()
+
+    if exclude_external and external_map:
+        external_children = {child for children in external_map.values() for child in children}
+
+    independent = []
+
+    for item in classes:
+        has_known_parent = any(base.split(".")[-1] in known_names for base in item.bases)
+        has_child = item.name in parent_names
+        is_child = item.name in child_names
+        has_external_parent = item.name in external_children
+
+        if not has_known_parent and not has_child and not is_child and not has_external_parent:
+            independent.append(item.name)
+
+    return sorted(independent)

classmap_hanthink-0.2.0/tests/test_external.py

@@ -0,0 +1,36 @@
+from classmap_hanthink.model import ClassInfo
+from classmap_hanthink.tree import build_external_base_map, build_inheritance_map, find_independent_classes
+from classmap_hanthink.render import render_text_tree, render_mermaid
+
+
+def test_build_external_base_map():
+    classes = [ClassInfo("Animal"), ClassInfo("Dog", ("Animal",)), ClassInfo("ExternalChild", ("dict",))]
+    external = build_external_base_map(classes)
+    assert external == {"dict": ["ExternalChild"]}
+
+
+def test_external_child_removed_from_independent_when_enabled():
+    classes = [ClassInfo("Config"), ClassInfo("ExternalChild", ("dict",))]
+    tree = build_inheritance_map(classes)
+    external = build_external_base_map(classes)
+    independent = find_independent_classes(classes, tree, external, exclude_external=True)
+    assert independent == ["Config"]
+
+
+def test_render_text_tree_show_external():
+    classes = [ClassInfo("ExternalChild", ("dict",), file="sample.py", line=1)]
+    tree = build_inheritance_map(classes)
+    external = build_external_base_map(classes)
+    output = render_text_tree(classes, tree, external, show_external=True)
+    assert "External Base Classes" in output
+    assert "dict" in output
+    assert "ExternalChild [sample.py:1]" in output
+    assert "Independent Classes" not in output
+
+
+def test_render_mermaid_show_external():
+    classes = [ClassInfo("ExternalChild", ("dict",))]
+    tree = build_inheritance_map(classes)
+    external = build_external_base_map(classes)
+    output = render_mermaid(classes, tree, external, show_external=True)
+    assert "dict <|-- ExternalChild" in output

{classmap_hanthink-0.1.0 → classmap_hanthink-0.2.0}/uv.lock

@@ -4,7 +4,7 @@ requires-python = ">=3.10"
 
 [[package]]
 name = "classmap-hanthink"
-version = "0.1.0"
+version = "0.2.0"
 source = { editable = "." }
 
 [package.dev-dependencies]

classmap_hanthink-0.1.0/src/classmap_hanthink/render.py

@@ -1,99 +0,0 @@
-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-0.1.0/src/classmap_hanthink/tree.py

@@ -1,35 +0,0 @@
-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)