dependaman 1.0.0__tar.gz

dependaman-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jacobo Mateo Bedoya Oquendo, Dependaman contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dependaman-1.0.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: dependaman
+Version: 1.0.0
+Summary: Understand your Python dependencies. Find cycles, dead modules, and architecture problems.
+Author-email: Jacobo Bedoya <jacobobedoya@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://codeberg.org/jacobitosuperstar/DependaMan
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# DependaMan
+
+Understand your Python project's internal structure. Find cycles, dead modules,
+hotspots, and architecture problems — visualized as an interactive graph.
+
+No external Python dependencies. Pure stdlib only.
+
+---
+
+## Goal
+
+Given a Python project directory, DependaMan produces an interactive HTML graph
+showing:
+
+- Which modules import which (directed dependency graph)
+- Which modules are never imported (dead code candidates)
+- Circular import chains
+- Modules with high fan-in (many dependents) or high fan-out (many dependencies)
+- Module size (lines of code, number of functions/classes)
+- Git churn: how often each module changes
+
+---
+
+## Architecture
+
+### Phase 1 — File Discovery
+Walk the project directory, collect all `.py` files, and determine the package
+root. Distinguish internal modules from external ones (stdlib + third-party are
+ignored).
+
+### Phase 2 — Import Parsing
+Use `ast` to parse each file and extract `import` and `from ... import`
+statements. Resolve relative imports. Filter to internal-only imports.
+
+### Phase 3 — Graph Construction
+Build a directed graph as an adjacency structure:
+- Node = internal module
+- Edge A → B = "module A imports module B"
+
+Attach metadata to each node: file path, line count, function/class count.
+
+### Phase 4 — Analysis
+Run these passes on the graph:
+
+- **Dead code**: nodes with no incoming edges and not an entry point
+- **Circular imports**: detect cycles (DFS-based)
+- **Hotspots**: nodes ranked by fan-in (most imported)
+- **Coupling**: nodes ranked by fan-out (imports the most)
+
+### Phase 5 — Git Integration
+Use `subprocess` + `git log` to compute per-file:
+- Commit frequency (how often it changes)
+- Lines added/removed over time (churn)
+- Last author that changed the file
+
+Attach this data to graph nodes. Optional: skipped if the project is not a git
+repo.
+
+### Phase 6 — HTML Output
+Generate a self-contained `.html` file (or return HTML as a string for web
+integration).
+
+The HTML template is a static string embedded in Python. Only the data changes
+between runs. Python serializes the graph to JSON and injects it into the
+template — no templating library needed:
+
+```python
+import json
+
+data = json.dumps({"nodes": [...], "edges": [...]})
+html = TEMPLATE.replace("__GRAPH_DATA__", data)
+```
+
+The template contains a `<script>` block that reads the injected data and
+renders the graph using the browser's `<canvas>` or SVG API. No external JS
+libraries required.
+
+The graph supports:
+- **Hover tooltips**: quick summary (import count, churn score)
+- **Click modals**: full detail panel (git log, list of dependents/dependencies,
+  size metrics)
+
+The output function signature is designed to be framework-agnostic:
+
+```python
+def render(graph, analysis) -> str:  # returns HTML string
+    ...
+```
+
+This makes it trivial to plug into FastAPI, Flask, or any other framework:
+
+```python
+# FastAPI example
+@app.get("/graph", response_class=HTMLResponse)
+def dependency_graph():
+    graph = build_graph(".")
+    analysis = analyze(graph)
+    return render(graph, analysis)
+```
+
+---
+
+## Package Structure
+
+DependaMan is distributed as a Python package (`dependaman`). The current layout:
+
+```
+dependaman/
+    __init__.py        # public API: dependaman()
+    __main__.py        # CLI entry point
+    core.py            # orchestration
+    discovery.py       # Phase 1 — file discovery
+    parser.py          # Phase 2 — import parsing
+    graph.py           # Phase 3 — graph construction
+    analysis.py        # Phase 4 — analysis passes
+    git.py             # Phase 5 — git integration
+    renderer.py        # Phase 6 — HTML output
+    pool.py            # GIL-aware executor selection
+```
+
+Entry point via `pyproject.toml`:
+```
+[project.scripts]
+dependaman = "dependaman.__main__:dependaman"
+```
+
+### Usage
+
+**CLI:**
+```bash
+dependaman              # analyzes current directory, opens browser
+dependaman /path/to/project
+```
+
+**Python API:**
+```python
+from dependaman import dependaman
+
+html = dependaman(".", in_memory=True)   # returns HTML string
+dependaman(".")                          # writes output.html + opens browser
+```
+
+---
+
+## Roadmap
+
+- [X] Phase 1: File discovery
+- [X] Phase 2: Import parsing (`ast`)
+- [X] Phase 3: Graph construction
+- [X] Phase 4: Analysis (dead code, cycles, hotspots)
+- [X] Phase 5: Git integration
+- [X] Phase 6: HTML renderer
+- [X] Phase 7: Unused symbol detection (functions, classes, methods never imported)
+- [X] Phase 8: Installable package (`uv pip install -e .`)
+- [X] Phase 9: CLI entry point with auto project root detection and browser open
+- [X] Phase 10: Performance — parallel git stats (ThreadPoolExecutor), GIL-aware pool for parsing and graph construction

dependaman-1.0.0/README.md

@@ -0,0 +1,156 @@
+# DependaMan
+
+Understand your Python project's internal structure. Find cycles, dead modules,
+hotspots, and architecture problems — visualized as an interactive graph.
+
+No external Python dependencies. Pure stdlib only.
+
+---
+
+## Goal
+
+Given a Python project directory, DependaMan produces an interactive HTML graph
+showing:
+
+- Which modules import which (directed dependency graph)
+- Which modules are never imported (dead code candidates)
+- Circular import chains
+- Modules with high fan-in (many dependents) or high fan-out (many dependencies)
+- Module size (lines of code, number of functions/classes)
+- Git churn: how often each module changes
+
+---
+
+## Architecture
+
+### Phase 1 — File Discovery
+Walk the project directory, collect all `.py` files, and determine the package
+root. Distinguish internal modules from external ones (stdlib + third-party are
+ignored).
+
+### Phase 2 — Import Parsing
+Use `ast` to parse each file and extract `import` and `from ... import`
+statements. Resolve relative imports. Filter to internal-only imports.
+
+### Phase 3 — Graph Construction
+Build a directed graph as an adjacency structure:
+- Node = internal module
+- Edge A → B = "module A imports module B"
+
+Attach metadata to each node: file path, line count, function/class count.
+
+### Phase 4 — Analysis
+Run these passes on the graph:
+
+- **Dead code**: nodes with no incoming edges and not an entry point
+- **Circular imports**: detect cycles (DFS-based)
+- **Hotspots**: nodes ranked by fan-in (most imported)
+- **Coupling**: nodes ranked by fan-out (imports the most)
+
+### Phase 5 — Git Integration
+Use `subprocess` + `git log` to compute per-file:
+- Commit frequency (how often it changes)
+- Lines added/removed over time (churn)
+- Last author that changed the file
+
+Attach this data to graph nodes. Optional: skipped if the project is not a git
+repo.
+
+### Phase 6 — HTML Output
+Generate a self-contained `.html` file (or return HTML as a string for web
+integration).
+
+The HTML template is a static string embedded in Python. Only the data changes
+between runs. Python serializes the graph to JSON and injects it into the
+template — no templating library needed:
+
+```python
+import json
+
+data = json.dumps({"nodes": [...], "edges": [...]})
+html = TEMPLATE.replace("__GRAPH_DATA__", data)
+```
+
+The template contains a `<script>` block that reads the injected data and
+renders the graph using the browser's `<canvas>` or SVG API. No external JS
+libraries required.
+
+The graph supports:
+- **Hover tooltips**: quick summary (import count, churn score)
+- **Click modals**: full detail panel (git log, list of dependents/dependencies,
+  size metrics)
+
+The output function signature is designed to be framework-agnostic:
+
+```python
+def render(graph, analysis) -> str:  # returns HTML string
+    ...
+```
+
+This makes it trivial to plug into FastAPI, Flask, or any other framework:
+
+```python
+# FastAPI example
+@app.get("/graph", response_class=HTMLResponse)
+def dependency_graph():
+    graph = build_graph(".")
+    analysis = analyze(graph)
+    return render(graph, analysis)
+```
+
+---
+
+## Package Structure
+
+DependaMan is distributed as a Python package (`dependaman`). The current layout:
+
+```
+dependaman/
+    __init__.py        # public API: dependaman()
+    __main__.py        # CLI entry point
+    core.py            # orchestration
+    discovery.py       # Phase 1 — file discovery
+    parser.py          # Phase 2 — import parsing
+    graph.py           # Phase 3 — graph construction
+    analysis.py        # Phase 4 — analysis passes
+    git.py             # Phase 5 — git integration
+    renderer.py        # Phase 6 — HTML output
+    pool.py            # GIL-aware executor selection
+```
+
+Entry point via `pyproject.toml`:
+```
+[project.scripts]
+dependaman = "dependaman.__main__:dependaman"
+```
+
+### Usage
+
+**CLI:**
+```bash
+dependaman              # analyzes current directory, opens browser
+dependaman /path/to/project
+```
+
+**Python API:**
+```python
+from dependaman import dependaman
+
+html = dependaman(".", in_memory=True)   # returns HTML string
+dependaman(".")                          # writes output.html + opens browser
+```
+
+---
+
+## Roadmap
+
+- [X] Phase 1: File discovery
+- [X] Phase 2: Import parsing (`ast`)
+- [X] Phase 3: Graph construction
+- [X] Phase 4: Analysis (dead code, cycles, hotspots)
+- [X] Phase 5: Git integration
+- [X] Phase 6: HTML renderer
+- [X] Phase 7: Unused symbol detection (functions, classes, methods never imported)
+- [X] Phase 8: Installable package (`uv pip install -e .`)
+- [X] Phase 9: CLI entry point with auto project root detection and browser open
+- [X] Phase 10: Performance — parallel git stats (ThreadPoolExecutor), GIL-aware pool for parsing and graph construction

dependaman-1.0.0/dependaman/__init__.py

@@ -0,0 +1,3 @@
+from .core import dependaman
+
+__all__: list[str] = ["dependaman"]

dependaman-1.0.0/dependaman/__main__.py

@@ -0,0 +1,20 @@
+"""__main__.py
+
+Orchestator. Here is where everything takes shape. In dependaman we build all
+tools that are needed to make the code analysis, here we put them together so
+with a simple command/function call we can execute the project analysis.
+"""
+
+import sys
+from pathlib import Path
+
+from .core import dependaman
+from .discovery import find_project_root
+
+if __name__ == "__main__":
+    path: Path = (
+        Path(sys.argv[1]).resolve()
+        if len(sys.argv) > 1
+        else find_project_root(Path.cwd())
+    )
+    dependaman(path)

dependaman-1.0.0/dependaman/analysis.py

@@ -0,0 +1,75 @@
+"""analysis.py"""
+
+from .discovery import Module
+from .parser import definition_collector
+
+
+def fanin_analyzer(
+    project_nodes: set[str],
+    graph: dict[str, set[str]],
+) -> dict[str, int]:
+    """Checks how many times each module is being imported."""
+    fanin = dict.fromkeys(project_nodes, 0)
+    for _, value in graph.items():
+        for edge in value:
+            fanin[edge] += 1
+    return fanin
+
+
+def fanout_analyzer(graph: dict[str, set[str]]) -> dict[str, int]:
+    """Checks how many imports each module has."""
+    fanout = dict.fromkeys(graph.keys(), 0)
+    for key, value in graph.items():
+        fanout[key] += len(value)
+    return fanout
+
+
+def _dfs(
+    key: str,
+    graph: dict[str, set[str]],
+    current_path: list[str],
+    visited_nodes: set[str],
+) -> list[str] | None:
+    """Walking the directed graph of dependencies."""
+    dfs = []
+    current_path.append(key)
+
+    for neighbor in graph[key]:
+        if neighbor in current_path:
+            dfs = current_path[current_path.index(neighbor) :].copy()
+            dfs.append(neighbor)
+            break
+        if neighbor not in visited_nodes and neighbor in graph:
+            dfs = _dfs(neighbor, graph, current_path, visited_nodes)
+            if dfs:
+                break
+    current_path.pop(current_path.index(key))
+    visited_nodes.add(key)
+    return dfs
+
+
+def circular_imports(graph: dict[str, set[str]]) -> list[list[str]]:
+    """Checks if there are any circular imports that we should worry about."""
+    visited_nodes = set()
+    circular_imports = []
+    for key in graph.keys():
+        current_path = []
+        if key in visited_nodes:
+            continue
+        eval = _dfs(key, graph, current_path, visited_nodes)
+        if eval:
+            circular_imports.append(eval)
+    return circular_imports
+
+
+def symbols_to_review_detector(
+    module: Module, project_import_strings: set[str]
+) -> set[str]:
+    """we get all the import strings that are in the project and match them
+    with all the function and class definitions that are in a module, we return
+    the defined functions/classes in the module that are not imported anywhere.
+    """
+    definitions: set[str] = set()
+    definitions.update(definition_collector(module))
+    symbols_to_review: set[str] = definitions - project_import_strings
+    return symbols_to_review

dependaman-1.0.0/dependaman/core.py

@@ -0,0 +1,62 @@
+"""core.py
+
+Orchestator. Here is where everything takes shape. In dependaman we build all
+tools that are needed to make the code analysis, here we put them together so
+with a simple command/function call we can execute the project analysis.
+"""
+
+import webbrowser
+from pathlib import Path
+
+from .analysis import (
+    circular_imports,
+    fanin_analyzer,
+    fanout_analyzer,
+)
+from .discovery import discover, module_level_node_generator
+from .git import git_commit_freq
+from .graph import speed_grapher
+from .parser import project_import_strings
+from .renderer import data_constructor, render
+
+
+def dependaman(path=".", in_memory=False) -> str | None:
+    """Given the path of the project found, the folder structure and nodes of
+    the project are generated. Then the different files are being parsed and
+    from them we get the import nodes of each one of them. After both nodes are
+    created, we match an see for each module, which other modules are imported
+    to them.
+
+    With that information we can analyze which modules are the ones that import
+    the most, which are the ones that are imported the most and if there are
+    circular imports detect them.
+    """
+
+    file_source = discover(path)
+    project_nodes: set[str] = module_level_node_generator(file_source)
+    project_imports: set[str] = project_import_strings(file_source)
+    directed_graph = speed_grapher(file_source, project_nodes)
+    fanin_analysis = fanin_analyzer(project_nodes, directed_graph)
+    fanout_analysis = fanout_analyzer(directed_graph)
+    circular_imports_analysis = circular_imports(directed_graph)
+    git_freq = git_commit_freq(file_source, project_nodes)
+
+    data = data_constructor(
+        file_source,
+        project_nodes,
+        directed_graph,
+        circular_imports_analysis,
+        fanin_analysis,
+        fanout_analysis,
+        git_freq,
+        project_imports,
+    )
+
+    rendered_data: str = render(data)
+
+    if in_memory:
+        return rendered_data
+
+    with open("output.html", "w") as f:
+        f.write(rendered_data)
+    webbrowser.open(f"file://{Path('output.html').resolve()}")

dependaman-1.0.0/dependaman/discovery.py

@@ -0,0 +1,105 @@
+"""discovery.py"""
+
+from dataclasses import dataclass
+from pathlib import Path
+
+EXCLUDED_DIRS: tuple = (
+    ".venv",
+    "__pycache__",
+    ".git",
+    "build",
+    "dist",
+    ".eggs",
+)
+
+PROJECT_MARKERS = (
+    "pyproject.toml",
+    "setup.py",
+    "requirements.txt",
+    "setup.cfg",
+)
+
+
+def find_project_root(start: Path) -> Path:
+    """We walk up the directory from start and try to find any of the files
+    that are in the PROJECT_MARKERS. When we find one, we found the origin
+    folder of the project.
+    """
+    for parent in [start, *start.parents]:
+        if any((parent / marker).exists() for marker in PROJECT_MARKERS):
+            return parent
+    return start
+
+
+@dataclass(slots=True)
+class Module:
+    name: str
+    path: Path
+
+
+@dataclass(slots=True)
+class Package:
+    name: str
+    modules: list[Module]
+
+
+def discover(root: str | Path) -> list[Package]:
+    """Walking throught the root directory matching all the *.py files and
+    removing all the files that may be in the excluded directories defined at
+    the package level.
+    """
+    root = Path(root).resolve()
+
+    packages: list[Package] = []
+
+    # Collecting root-level standalone scripts if there is not an init file in
+    # the root folder
+    if not (root / "__init__.py").exists():
+        root_modules: list[Module] = []
+        for file in root.iterdir():
+            if file.suffix == ".py" and file.name != "__init__.py":
+                root_modules.append(Module(file.stem, file.relative_to(root)))
+
+        if root_modules:
+            packages.append(Package(".", root_modules))
+
+    for path in root.rglob("__init__.py"):
+        # skipping the folders that are in the excluded directoreis list.
+        if any(part in EXCLUDED_DIRS for part in path.parts):
+            continue
+
+        package_dir: Path = path.parent
+        relative_path: Path = package_dir.relative_to(root)
+        package_name = ".".join(relative_path.parts)
+
+        # Iterating over the contents of each of the found directories.
+        modules: list[Module] = []
+        for file in package_dir.iterdir():
+            if file.suffix == ".py" and file.name != "__init__.py":
+                modules.append(Module(file.stem, file.relative_to(root)))
+
+        packages.append(Package(package_name, modules))
+
+    return packages
+
+
+def node_name_gen(
+    module: Module,
+) -> str:
+    """Creates the node string of a module."""
+    node: list[str] = list(module.path.parts)
+    node.pop(-1)
+    node.append(module.name)
+    return ".".join(node)
+
+
+def module_level_node_generator(packages: list[Package]) -> set[str]:
+    """Creating the set of nodes that we will use to filter out the internal
+    packages.
+    """
+    module_level_nodes = set()
+    for package in packages:
+        module_level_nodes.add(package.name)
+        for module in package.modules:
+            module_level_nodes.add(node_name_gen(module))
+    return module_level_nodes

dependaman-1.0.0/dependaman/git.py

@@ -0,0 +1,120 @@
+"""git.py"""
+
+import subprocess
+from collections import defaultdict
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from typing import TypedDict
+
+from .discovery import Module, Package, node_name_gen
+
+
+def check_git_project() -> bool:
+    """Checks if we are in a directory with git."""
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--is-inside-work-tree"],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        return result.stdout.strip() == "true"
+    except subprocess.CalledProcessError:
+        return False
+
+
+# TODO: the main issue is that we are doing a subprocess call per each file
+# that is in the project. Because we are waiting for IO, we could throw all of
+# this to a threadpool or a coroutine to make all of this in parallel, as doing
+# the complete `git log` would require a full parse change and we would also
+# need a way to get the last person that worked on that node, which would
+# complicate the process greatly.
+
+
+class GitStats(TypedDict):
+    node: str
+    n_commits: int
+    added_lines: int
+    removed_lines: int
+    last_author: str
+
+
+def _get_git_stats(
+    node: str,
+    module: Module,
+) -> GitStats:
+    """returns the git stats for each module, which compose for our case,
+    number of commits, added lines, removed lines, last author that touched
+    that module.
+    """
+    git_freq = subprocess.run(
+        [
+            "git",
+            "log",
+            "--numstat",
+            "--pretty=format:",
+            "--",
+            f"{module.path}",
+        ],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    raw_commits = git_freq.stdout.strip().split()
+    # here we are taking the first two values of the iteration even
+    # thought we are jumping them in range of 3
+    commits = [raw_commits[i : i + 2] for i in range(0, len(raw_commits), 3)]
+    added_lines = sum([int(commit[0]) for commit in commits])
+    removed_lines = sum([int(commit[1]) for commit in commits])
+    n_commits = len(commits)
+    git_last_author = subprocess.run(
+        [
+            "git",
+            "log",
+            "-1",
+            "--pretty=format:%ae",
+            "--",
+            f"{module.path}",
+        ],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    git_stats = GitStats(
+        node=node,
+        n_commits=n_commits,
+        added_lines=added_lines,
+        removed_lines=removed_lines,
+        last_author=git_last_author.stdout.strip(),
+    )
+    return git_stats
+
+
+def git_commit_freq(
+    file_source: list[Package],
+    project_nodes: set[str],
+) -> defaultdict[str, dict[str, int | str]]:
+    """Checks the amount of commits that each node has."""
+    if not check_git_project():
+        return defaultdict(dict)
+
+    freq = defaultdict(dict)
+
+    # DROWN ME IN A POOL BROTHER!!!!!!!
+    with ThreadPoolExecutor() as pool:
+        futures = []
+        for package in file_source:
+            for module in package.modules:
+                node: str = node_name_gen(module)
+
+                if node not in project_nodes:
+                    continue
+
+                # send me to hell
+                futures.append(pool.submit(_get_git_stats, node, module))
+
+        # the party is over, pick me up when you are done
+        for future in as_completed(futures):
+            results: GitStats = future.result()
+            r_node = results.pop("node")
+            freq[r_node] = results
+    return freq

dependaman-1.0.0/dependaman/graph.py

@@ -0,0 +1,51 @@
+"""graph.py"""
+
+from collections import defaultdict
+from concurrent.futures import Future, as_completed
+
+from .discovery import Module, Package, node_name_gen
+from .parser import parse
+from .pool import MIN_FILES_FOR_POOL, executor
+
+
+def _parse_module_edges(
+    module: Module, project_nodes: set[str]
+) -> tuple[str, set[str]]:
+    """module edges creator."""
+    return node_name_gen(module), {e for e in parse(module) if e in project_nodes}
+
+
+# NOTE: DROWN ME BABY!!!, another pool optimization.
+def speed_grapher(
+    file_source: list[Package],
+    project_nodes: set[str],
+) -> dict[str, set]:
+    """Given the file source we create the directed graph of dependencies for
+    each one of the nodes.
+    """
+
+    # creating a default dict that creates an empty set on missing keys.
+    directed_graph = defaultdict(set)
+
+    modules: list[Module] = [
+        module for package in file_source for module in package.modules
+    ]
+
+    # looking at the pool from afar
+    if len(modules) < MIN_FILES_FOR_POOL:
+        for module in modules:
+            node, edge = _parse_module_edges(module, project_nodes)
+            directed_graph[node] = edge
+        return directed_graph
+
+    # drowned!!
+    with executor() as pool:
+        futures: list[Future[tuple[str, set[str]]]] = [
+            pool.submit(_parse_module_edges, module, project_nodes)
+            for module in modules
+        ]
+
+        for future in as_completed(futures):
+            node, edge = future.result()
+            directed_graph[node] = edge
+    return directed_graph

dependaman-1.0.0/dependaman/parser.py

@@ -0,0 +1,121 @@
+"""parser.py"""
+
+import ast
+from concurrent.futures import Future, as_completed
+from dataclasses import dataclass
+
+from .discovery import Module, Package, node_name_gen
+from .pool import MIN_FILES_FOR_POOL, executor
+
+
+@dataclass(slots=True)
+class DpdmanImport:
+    module: str | None
+    names: list[str]
+    level: int
+
+
+def node_generator(
+    module: Module,
+    dpdman_import: DpdmanImport,
+) -> set[str]:
+    """With the DpdmanImport corresponding to a module, we can create the
+    import string nodes corresponding to it.
+    """
+    import_strings: set[str] = set()
+    parents = []
+    if dpdman_import.level != 0:
+        module_path = list(module.path.parts)
+        module_path.pop(-1)
+        n = len(module_path)
+        parents = module_path[: (n - (dpdman_import.level - 1))]
+    if dpdman_import.module:
+        parents.append(dpdman_import.module)
+    import_str = ".".join(parents)
+
+    # NOTE: Because we are in the module level, we are taking the functions and
+    # classes too, which is good for the future. So for now, we will add also
+    # the initial parents concatenation to the list, as we cannot differenciate
+    # sym names from modules.
+    # if not dpdman_import.names:
+    #     import_strings.append(import_str)
+    #     return import_strings
+    import_strings.add(import_str)
+
+    for name in dpdman_import.names:
+        import_strings.add(f"{import_str}.{name}")
+    return import_strings
+
+
+def parse(module: Module) -> set[str]:
+    """Analizes the imports a Module and returns its corresponding list of
+    import string nodes.
+    """
+    text_source = module.path.read_text(encoding="utf-8")
+    tree = ast.parse(text_source)
+
+    # Creating DpdmanImport
+    import_strings: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for imported_package in node.names:
+                dpdman_import = DpdmanImport(
+                    module=imported_package.name,
+                    names=[],
+                    level=0,
+                )
+                import_strings.update(node_generator(module, dpdman_import))
+        elif isinstance(node, ast.ImportFrom):
+            dpdman_import = DpdmanImport(
+                module=node.module,
+                names=[alias.name for alias in node.names],
+                level=node.level,
+            )
+            import_strings.update(node_generator(module, dpdman_import))
+    return import_strings
+
+
+# NOTE: The project needs to be large for this optimization to take place, else
+# the memory of creating a new process/thread pool and their shutting down will
+# take away the gains.
+def project_import_strings(file_source: list[Package]) -> set[str]:
+    """Returns all the import nodes of the project."""
+    project_imports = set()
+
+    modules: list[Module] = [
+        module for package in file_source for module in package.modules
+    ]
+
+    # Be vigilant of how many files are the ones needed for the sweet spot.
+    if len(modules) < MIN_FILES_FOR_POOL:
+        for module in modules:
+            project_imports.update(parse(module))
+        return project_imports
+
+    with executor() as pool:
+        futures: list[Future[set[str]]] = [
+            pool.submit(parse, module) for module in modules
+        ]
+        for future in as_completed(futures):
+            project_imports.update(future.result())
+    return project_imports
+
+
+def definition_collector(module: Module) -> set[str]:
+    """Getting all the functions and class definitions that are in each of the
+    modules.
+    """
+    text_source = module.path.read_text(encoding="utf-8")
+    tree = ast.parse(text_source)
+
+    # Creating the functions and classes definitions
+    definitions: set[str] = set()
+
+    # creating the node string
+    module_name = node_name_gen(module)
+    # we will only walk the top level nodes, not all the code.
+    for node in ast.iter_child_nodes(tree):
+        if isinstance(node, (ast.AsyncFunctionDef, ast.FunctionDef, ast.ClassDef)):
+            definition = f"{module_name}.{node.name}"
+            definitions.add(definition)
+    return definitions

dependaman-1.0.0/dependaman/pool.py

@@ -0,0 +1,20 @@
+"""pool.py
+
+Drown me baby!!
+"""
+
+import sys
+from concurrent.futures import ProcessPoolExecutor, ThreadPoolExecutor
+
+try:
+    gil_enabled: bool = sys._is_gil_enabled()
+except AttributeError:
+    gil_enabled = True
+
+
+MIN_FILES_FOR_POOL: int = 100
+
+
+executor: type[ProcessPoolExecutor | ThreadPoolExecutor] = (
+    ProcessPoolExecutor if gil_enabled else ThreadPoolExecutor
+)

dependaman-1.0.0/dependaman/renderer.py

@@ -0,0 +1,69 @@
+"""renderer.py"""
+
+import json
+from pathlib import Path
+
+from .analysis import symbols_to_review_detector
+from .discovery import Package, node_name_gen
+
+CURRENT_FOLDER_LOCATION: Path = Path(__file__).parent
+
+
+def data_constructor(
+    file_source: list[Package],
+    project_nodes: set[str],
+    directed_graph: dict[str, set],
+    cycles: list[list[str]],
+    fanin: dict[str, int],
+    fanout: dict[str, int],
+    git_frequency: dict[str, dict[str, int | str]],
+    project_imports: set[str],
+) -> dict:
+    """Returns the nodes with all the information"""
+
+    data: dict = {}
+
+    data["packages"] = []
+    data["cycles"] = cycles
+
+    for package in file_source:
+        package_info = {"id": package.name, "modules": []}
+        for module in package.modules:
+            node: str = node_name_gen(module)
+
+            if node not in project_nodes:
+                continue
+
+            git_info = git_frequency.get(node, {})
+            package_info["modules"].append(
+                {
+                    "id": node,
+                    "edges": list(directed_graph.get(node, set())),
+                    "fan_in": fanin.get(node, 0),
+                    "fan_out": fanout.get(node, 0),
+                    "n_commits": git_info.get("n_commits", 0),
+                    "added_lines": git_info.get("added_lines", 0),
+                    "removed_lines": git_info.get("removed_lines", 0),
+                    "last_author": git_info.get("last_author", ""),
+                    "symbols_to_review": list(
+                        symbols_to_review_detector(module, project_imports)
+                    ),
+                }
+            )
+        data["packages"].append(package_info)
+
+    return data
+
+
+def render(data: dict) -> str:
+    """Creates a HTML string"""
+    json_data: str = json.dumps(data)
+    html_path = f"{CURRENT_FOLDER_LOCATION}/dependaman_template.html"
+    js_path = f"{CURRENT_FOLDER_LOCATION}/dependaman_graph.js"
+    with open(html_path) as html:
+        with open(js_path) as js:
+            js_data = js.read()
+            html_data = html.read()
+            html_data = html_data.replace("__GRAPH_DATA__", json_data)
+            html_data = html_data.replace("__GRAPH_JS__", f"<script>{js_data}</script>")
+            return html_data

dependaman-1.0.0/dependaman.egg-info/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: dependaman
+Version: 1.0.0
+Summary: Understand your Python dependencies. Find cycles, dead modules, and architecture problems.
+Author-email: Jacobo Bedoya <jacobobedoya@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://codeberg.org/jacobitosuperstar/DependaMan
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# DependaMan
+
+Understand your Python project's internal structure. Find cycles, dead modules,
+hotspots, and architecture problems — visualized as an interactive graph.
+
+No external Python dependencies. Pure stdlib only.
+
+---
+
+## Goal
+
+Given a Python project directory, DependaMan produces an interactive HTML graph
+showing:
+
+- Which modules import which (directed dependency graph)
+- Which modules are never imported (dead code candidates)
+- Circular import chains
+- Modules with high fan-in (many dependents) or high fan-out (many dependencies)
+- Module size (lines of code, number of functions/classes)
+- Git churn: how often each module changes
+
+---
+
+## Architecture
+
+### Phase 1 — File Discovery
+Walk the project directory, collect all `.py` files, and determine the package
+root. Distinguish internal modules from external ones (stdlib + third-party are
+ignored).
+
+### Phase 2 — Import Parsing
+Use `ast` to parse each file and extract `import` and `from ... import`
+statements. Resolve relative imports. Filter to internal-only imports.
+
+### Phase 3 — Graph Construction
+Build a directed graph as an adjacency structure:
+- Node = internal module
+- Edge A → B = "module A imports module B"
+
+Attach metadata to each node: file path, line count, function/class count.
+
+### Phase 4 — Analysis
+Run these passes on the graph:
+
+- **Dead code**: nodes with no incoming edges and not an entry point
+- **Circular imports**: detect cycles (DFS-based)
+- **Hotspots**: nodes ranked by fan-in (most imported)
+- **Coupling**: nodes ranked by fan-out (imports the most)
+
+### Phase 5 — Git Integration
+Use `subprocess` + `git log` to compute per-file:
+- Commit frequency (how often it changes)
+- Lines added/removed over time (churn)
+- Last author that changed the file
+
+Attach this data to graph nodes. Optional: skipped if the project is not a git
+repo.
+
+### Phase 6 — HTML Output
+Generate a self-contained `.html` file (or return HTML as a string for web
+integration).
+
+The HTML template is a static string embedded in Python. Only the data changes
+between runs. Python serializes the graph to JSON and injects it into the
+template — no templating library needed:
+
+```python
+import json
+
+data = json.dumps({"nodes": [...], "edges": [...]})
+html = TEMPLATE.replace("__GRAPH_DATA__", data)
+```
+
+The template contains a `<script>` block that reads the injected data and
+renders the graph using the browser's `<canvas>` or SVG API. No external JS
+libraries required.
+
+The graph supports:
+- **Hover tooltips**: quick summary (import count, churn score)
+- **Click modals**: full detail panel (git log, list of dependents/dependencies,
+  size metrics)
+
+The output function signature is designed to be framework-agnostic:
+
+```python
+def render(graph, analysis) -> str:  # returns HTML string
+    ...
+```
+
+This makes it trivial to plug into FastAPI, Flask, or any other framework:
+
+```python
+# FastAPI example
+@app.get("/graph", response_class=HTMLResponse)
+def dependency_graph():
+    graph = build_graph(".")
+    analysis = analyze(graph)
+    return render(graph, analysis)
+```
+
+---
+
+## Package Structure
+
+DependaMan is distributed as a Python package (`dependaman`). The current layout:
+
+```
+dependaman/
+    __init__.py        # public API: dependaman()
+    __main__.py        # CLI entry point
+    core.py            # orchestration
+    discovery.py       # Phase 1 — file discovery
+    parser.py          # Phase 2 — import parsing
+    graph.py           # Phase 3 — graph construction
+    analysis.py        # Phase 4 — analysis passes
+    git.py             # Phase 5 — git integration
+    renderer.py        # Phase 6 — HTML output
+    pool.py            # GIL-aware executor selection
+```
+
+Entry point via `pyproject.toml`:
+```
+[project.scripts]
+dependaman = "dependaman.__main__:dependaman"
+```
+
+### Usage
+
+**CLI:**
+```bash
+dependaman              # analyzes current directory, opens browser
+dependaman /path/to/project
+```
+
+**Python API:**
+```python
+from dependaman import dependaman
+
+html = dependaman(".", in_memory=True)   # returns HTML string
+dependaman(".")                          # writes output.html + opens browser
+```
+
+---
+
+## Roadmap
+
+- [X] Phase 1: File discovery
+- [X] Phase 2: Import parsing (`ast`)
+- [X] Phase 3: Graph construction
+- [X] Phase 4: Analysis (dead code, cycles, hotspots)
+- [X] Phase 5: Git integration
+- [X] Phase 6: HTML renderer
+- [X] Phase 7: Unused symbol detection (functions, classes, methods never imported)
+- [X] Phase 8: Installable package (`uv pip install -e .`)
+- [X] Phase 9: CLI entry point with auto project root detection and browser open
+- [X] Phase 10: Performance — parallel git stats (ThreadPoolExecutor), GIL-aware pool for parsing and graph construction

dependaman-1.0.0/dependaman.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+LICENSE
+README.md
+pyproject.toml
+dependaman/__init__.py
+dependaman/__main__.py
+dependaman/analysis.py
+dependaman/core.py
+dependaman/discovery.py
+dependaman/git.py
+dependaman/graph.py
+dependaman/parser.py
+dependaman/pool.py
+dependaman/renderer.py
+dependaman.egg-info/PKG-INFO
+dependaman.egg-info/SOURCES.txt
+dependaman.egg-info/dependency_links.txt
+dependaman.egg-info/entry_points.txt
+dependaman.egg-info/top_level.txt
+test/test_discovery.py

dependaman-1.0.0/dependaman.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

dependaman-1.0.0/dependaman.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+dependaman = dependaman.__main__:dependaman

dependaman-1.0.0/dependaman.egg-info/top_level.txt

@@ -0,0 +1 @@
+dependaman

dependaman-1.0.0/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "dependaman"
+version = "1.0.0"
+description = "Understand your Python dependencies. Find cycles, dead modules, and architecture problems."
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = []
+license = "MIT"
+license-files = ["LICENSE"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+
+[[project.authors]]
+name = "Jacobo Bedoya"
+email = "jacobobedoya@gmail.com"
+
+[project.urls]
+Homepage = "https://codeberg.org/jacobitosuperstar/DependaMan"
+
+[project.scripts]
+dependaman = "dependaman.__main__:dependaman"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+]
+
+[tool.setuptools.packages.find]
+include = ["dependaman*"]

dependaman-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

dependaman-1.0.0/test/test_discovery.py

@@ -0,0 +1,38 @@
+from pathlib import PosixPath
+
+from dependaman import discovery
+
+
+def test_discover(tmp_path):
+    """Testing file discovery with"""
+    # Files that we should find
+    # main dir
+    (tmp_path / "testing_project").mkdir()
+    (tmp_path / "testing_project/__init__.py").touch()
+    (tmp_path / "testing_project/project.py").touch()
+    # nested package
+    (tmp_path / "testing_project/nested_package").mkdir()
+    (tmp_path / "testing_project/nested_package/__init__.py").touch()
+    (tmp_path / "testing_project/nested_package/nested_project.py").touch()
+
+    # Files that we should ignore
+    (tmp_path / ".venv").mkdir()
+    (tmp_path / ".venv/file_inside_ignored.py").touch()
+    (tmp_path / ".venv/another_file_inside_ignored.py").touch()
+
+    result: list[discovery.Package] = discovery.discover(tmp_path)
+    assert len(result) == 2
+
+    testing_packages = [package.name for package in result]
+    assert (
+        "testing_project" in testing_packages
+        and "testing_project.nested_package" in testing_packages
+    )
+
+    testing_modules = []
+    for package in result:
+        testing_modules.extend(package.modules)
+    assert (
+        discovery.Module("project", PosixPath("testing_project/project.py")) in testing_modules
+        and discovery.Module("nested_project", PosixPath("testing_project/nested_package/nested_project.py")) in testing_modules
+    )