deps-viz 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,5 @@
1
+ TODO*
2
+ .venv/
3
+ __pycache__/
4
+ .pytest_cache/
5
+ .rut_cache/
deps_viz-0.1.0/LICENSE ADDED
@@ -0,0 +1,23 @@
1
+
2
+
3
+ The MIT License
4
+
5
+ Copyright (c) 2026 Eduardo Naufel Schettino
6
+
7
+ Permission is hereby granted, free of charge, to any person obtaining a copy
8
+ of this software and associated documentation files (the "Software"), to deal
9
+ in the Software without restriction, including without limitation the rights
10
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
11
+ copies of the Software, and to permit persons to whom the Software is
12
+ furnished to do so, subject to the following conditions:
13
+
14
+ The above copyright notice and this permission notice shall be included in
15
+ all copies or substantial portions of the Software.
16
+
17
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
20
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
21
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
22
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
23
+ THE SOFTWARE.
@@ -0,0 +1,112 @@
1
+ Metadata-Version: 2.5
2
+ Name: deps-viz
3
+ Version: 0.1.0
4
+ Summary: Interactive HTML visualization for Python import dependencies
5
+ Project-URL: Homepage, https://github.com/schettino72/deps-viz-html
6
+ Project-URL: Repository, https://github.com/schettino72/deps-viz-html
7
+ Project-URL: Issues, https://github.com/schettino72/deps-viz-html/issues
8
+ Author-email: Eduardo Naufel Schettino <schettino72@gmail.com>
9
+ License: MIT
10
+ License-File: LICENSE
11
+ Keywords: dependencies,graph,import,visualization
12
+ Classifier: Development Status :: 3 - Alpha
13
+ Classifier: Environment :: Console
14
+ Classifier: Environment :: Web Environment
15
+ Classifier: Intended Audience :: Developers
16
+ Classifier: License :: OSI Approved :: MIT License
17
+ Classifier: Operating System :: OS Independent
18
+ Classifier: Programming Language :: Python :: 3
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Classifier: Programming Language :: Python :: 3.13
21
+ Classifier: Programming Language :: Python :: 3.14
22
+ Classifier: Topic :: Software Development :: Quality Assurance
23
+ Requires-Python: >=3.12
24
+ Requires-Dist: import-deps>=0.5
25
+ Description-Content-Type: text/markdown
26
+
27
+ # deps-viz
28
+
29
+ Interactive HTML visualization for Python import dependencies.
30
+
31
+ Analyzes your code with `import_deps` and opens an interactive graph in the browser.
32
+
33
+ ## Install
34
+
35
+ ```bash
36
+ pip install deps-viz
37
+
38
+ # or as a standalone command with uv
39
+ uv tool install deps-viz
40
+
41
+ # or run without installing
42
+ uvx deps-viz app tests
43
+ ```
44
+
45
+ ## Usage
46
+
47
+ ```bash
48
+ # Analyze and open in browser (writes a temp file in /tmp)
49
+ deps-viz app tests
50
+
51
+ # Write a self-contained HTML file, then open it in your browser
52
+ deps-viz app tests -o deps.html
53
+ xdg-open deps.html # Linux; macOS: open deps.html
54
+
55
+ # Read import_deps JSON from stdin
56
+ import_deps app --json | deps-viz -o deps.html
57
+ ```
58
+
59
+ You can also drag `deps.html` into a browser window.
60
+
61
+ **Snap browsers (default Firefox and Chromium on Ubuntu):** opening directly
62
+ (without `-o`) fails with "file not found", because snaps have a private `/tmp`.
63
+ Use `-o` and keep the HTML file somewhere under your home directory.
64
+
65
+ ## Input format
66
+
67
+ deps-viz reads the JSON produced by `import_deps --json`: a list with one entry per module.
68
+
69
+ ```json
70
+ [
71
+ {"module": "foo.__init__", "imports": []},
72
+ {"module": "foo.foo_a", "imports": ["foo.foo_b", "foo.sub.sub_a"]},
73
+ {"module": "foo.foo_b", "imports": []},
74
+ {"module": "foo.sub.sub_a", "imports": ["foo.foo_b"]}
75
+ ]
76
+ ```
77
+
78
+ - `module`: dotted module name. Its package is everything before the last dot
79
+ (`foo.sub.sub_a` -> `foo.sub`), used for package colors, filters and collapsing.
80
+ - `imports`: names of modules it imports.
81
+ Imports of modules not in the list (stdlib, third-party) are ignored.
82
+ - Other fields (e.g. `filepath`, `all_imports`) are ignored.
83
+
84
+ The format is not Python specific: any tool producing this JSON can use deps-viz
85
+ (`deps-viz -o deps.html < graph.json`). `import_deps` is only used by `deps-viz PATH`.
86
+
87
+ ## Examples
88
+
89
+ Open in your browser, no install needed:
90
+
91
+ - [sample](https://raw.githack.com/schettino72/deps-viz-html/main/examples/sample.html) - small sample (7 modules)
92
+ - [rich](https://raw.githack.com/schettino72/deps-viz-html/main/examples/rich.html) - the [rich](https://github.com/Textualize/rich) library (100 modules)
93
+
94
+ Source files are in [examples/](https://github.com/schettino72/deps-viz-html/tree/main/examples).
95
+
96
+ ## Features
97
+
98
+ - **Layout options**: Hierarchical (LR/TB) using dagre, or force-directed
99
+ - **Zoom/pan**: Mouse wheel and drag
100
+ - **Click node**: Highlights its imports and importers
101
+ - **Search**: Filter modules by name
102
+ - **Package filters**: Toggle packages on/off (recalculates layout)
103
+ - **Cycle detection**: Circular dependencies highlighted in red
104
+
105
+ ## Dependencies
106
+
107
+ [import_deps](https://github.com/schettino72/import-deps) (no dependencies of its own), used to analyze code with `deps-viz PATH`.
108
+ The HTML loads Cytoscape.js and cytoscape-dagre from CDN.
109
+
110
+ ## Related
111
+
112
+ - [import_deps](https://github.com/schettino72/import-deps) - Analyzes Python import dependencies
@@ -0,0 +1,86 @@
1
+ # deps-viz
2
+
3
+ Interactive HTML visualization for Python import dependencies.
4
+
5
+ Analyzes your code with `import_deps` and opens an interactive graph in the browser.
6
+
7
+ ## Install
8
+
9
+ ```bash
10
+ pip install deps-viz
11
+
12
+ # or as a standalone command with uv
13
+ uv tool install deps-viz
14
+
15
+ # or run without installing
16
+ uvx deps-viz app tests
17
+ ```
18
+
19
+ ## Usage
20
+
21
+ ```bash
22
+ # Analyze and open in browser (writes a temp file in /tmp)
23
+ deps-viz app tests
24
+
25
+ # Write a self-contained HTML file, then open it in your browser
26
+ deps-viz app tests -o deps.html
27
+ xdg-open deps.html # Linux; macOS: open deps.html
28
+
29
+ # Read import_deps JSON from stdin
30
+ import_deps app --json | deps-viz -o deps.html
31
+ ```
32
+
33
+ You can also drag `deps.html` into a browser window.
34
+
35
+ **Snap browsers (default Firefox and Chromium on Ubuntu):** opening directly
36
+ (without `-o`) fails with "file not found", because snaps have a private `/tmp`.
37
+ Use `-o` and keep the HTML file somewhere under your home directory.
38
+
39
+ ## Input format
40
+
41
+ deps-viz reads the JSON produced by `import_deps --json`: a list with one entry per module.
42
+
43
+ ```json
44
+ [
45
+ {"module": "foo.__init__", "imports": []},
46
+ {"module": "foo.foo_a", "imports": ["foo.foo_b", "foo.sub.sub_a"]},
47
+ {"module": "foo.foo_b", "imports": []},
48
+ {"module": "foo.sub.sub_a", "imports": ["foo.foo_b"]}
49
+ ]
50
+ ```
51
+
52
+ - `module`: dotted module name. Its package is everything before the last dot
53
+ (`foo.sub.sub_a` -> `foo.sub`), used for package colors, filters and collapsing.
54
+ - `imports`: names of modules it imports.
55
+ Imports of modules not in the list (stdlib, third-party) are ignored.
56
+ - Other fields (e.g. `filepath`, `all_imports`) are ignored.
57
+
58
+ The format is not Python specific: any tool producing this JSON can use deps-viz
59
+ (`deps-viz -o deps.html < graph.json`). `import_deps` is only used by `deps-viz PATH`.
60
+
61
+ ## Examples
62
+
63
+ Open in your browser, no install needed:
64
+
65
+ - [sample](https://raw.githack.com/schettino72/deps-viz-html/main/examples/sample.html) - small sample (7 modules)
66
+ - [rich](https://raw.githack.com/schettino72/deps-viz-html/main/examples/rich.html) - the [rich](https://github.com/Textualize/rich) library (100 modules)
67
+
68
+ Source files are in [examples/](https://github.com/schettino72/deps-viz-html/tree/main/examples).
69
+
70
+ ## Features
71
+
72
+ - **Layout options**: Hierarchical (LR/TB) using dagre, or force-directed
73
+ - **Zoom/pan**: Mouse wheel and drag
74
+ - **Click node**: Highlights its imports and importers
75
+ - **Search**: Filter modules by name
76
+ - **Package filters**: Toggle packages on/off (recalculates layout)
77
+ - **Cycle detection**: Circular dependencies highlighted in red
78
+
79
+ ## Dependencies
80
+
81
+ [import_deps](https://github.com/schettino72/import-deps) (no dependencies of its own), used to analyze code with `deps-viz PATH`.
82
+ The HTML loads Cytoscape.js and cytoscape-dagre from CDN.
83
+
84
+ ## Related
85
+
86
+ - [import_deps](https://github.com/schettino72/import-deps) - Analyzes Python import dependencies
@@ -0,0 +1,106 @@
1
+ """
2
+ Interactive HTML visualization for import_deps JSON output.
3
+
4
+ Usage:
5
+ deps-viz app tests # analyze and open in browser
6
+ deps-viz app -o deps.html # write self-contained HTML file
7
+ import_deps app --json | deps-viz # read import_deps JSON from stdin
8
+ """
9
+
10
+ import argparse
11
+ import base64
12
+ import json
13
+ import subprocess
14
+ import sys
15
+ import tempfile
16
+ import webbrowser
17
+ import zlib
18
+ from pathlib import Path
19
+
20
+
21
+ # Longest URL passed to the browser. Windows limits a command line to 32767 chars.
22
+ MAX_URL_LENGTH = 30_000
23
+
24
+
25
+ def slim_results(results):
26
+ """Keep only fields used by the viewer (drops local file paths)"""
27
+ return [{'module': res['module'], 'imports': res['imports']} for res in results]
28
+
29
+
30
+ def format_html(results):
31
+ """Format import_deps JSON results as interactive HTML visualization"""
32
+ template_path = Path(__file__).parent / 'template.html'
33
+ template = template_path.read_text()
34
+ # escape "<" so data can never close the <script> tag
35
+ graph_json = json.dumps(slim_results(results)).replace('<', '\\u003c')
36
+ return template.replace('/*GRAPH_DATA*/null', graph_json)
37
+
38
+
39
+ def encode_fragment(results):
40
+ """Encode results as URL fragment "d=<base64url(deflate-raw(json))>"
41
+
42
+ The fragment is never sent to the server, so the data stays in the browser.
43
+ """
44
+ raw = json.dumps(slim_results(results), separators=(',', ':')).encode()
45
+ compressor = zlib.compressobj(level=9, wbits=-15)
46
+ packed = compressor.compress(raw) + compressor.flush()
47
+ return 'd=' + base64.urlsafe_b64encode(packed).decode().rstrip('=')
48
+
49
+
50
+ def viewer_url(base_url, results, max_length=None):
51
+ """URL of hosted viewer with results in the fragment, None if too long"""
52
+ url = base_url + '#' + encode_fragment(results)
53
+ if len(url) > (max_length or MAX_URL_LENGTH):
54
+ return None
55
+ return url
56
+
57
+
58
+ def run_import_deps(paths):
59
+ """Run import_deps on paths, return its JSON results.
60
+
61
+ On failure import_deps already printed the error, exit with its code.
62
+ """
63
+ cmd = [sys.executable, '-m', 'import_deps', *paths, '--json']
64
+ proc = subprocess.run(cmd, stdout=subprocess.PIPE, text=True)
65
+ if proc.returncode != 0:
66
+ sys.exit(proc.returncode)
67
+ return json.loads(proc.stdout)
68
+
69
+
70
+ def write_temp_html(results):
71
+ """Write self-contained HTML to a temp file (kept for the browser), return its path"""
72
+ with tempfile.NamedTemporaryFile('w', prefix='deps-viz-', suffix='.html', delete=False) as html_file:
73
+ html_file.write(format_html(results))
74
+ return Path(html_file.name)
75
+
76
+
77
+ def main(argv=None):
78
+ parser = argparse.ArgumentParser(
79
+ prog='deps-viz',
80
+ description='Visualize Python import dependencies in the browser.')
81
+ parser.add_argument('path', metavar='PATH', nargs='*',
82
+ help='Python file(s) or package directory(s) to analyze. '
83
+ 'If omitted, read import_deps JSON from stdin.')
84
+ parser.add_argument('-o', '--output', metavar='FILE',
85
+ help='Write self-contained HTML to FILE ("-" for stdout) instead of opening a browser')
86
+ parser.add_argument('--viewer', metavar='URL',
87
+ help='Open hosted viewer at URL, data passed in the URL fragment '
88
+ '(falls back to a local file if the URL is too long)')
89
+ config = parser.parse_args(argv)
90
+
91
+ if config.path:
92
+ results = run_import_deps(config.path)
93
+ else:
94
+ results = json.load(sys.stdin)
95
+
96
+ if config.output == '-':
97
+ print(format_html(results))
98
+ return
99
+ if config.output:
100
+ Path(config.output).write_text(format_html(results))
101
+ return
102
+
103
+ url = viewer_url(config.viewer, results) if config.viewer else None
104
+ if url is None:
105
+ url = write_temp_html(results).as_uri()
106
+ webbrowser.open(url)
@@ -0,0 +1,3 @@
1
+ from deps_viz import main
2
+
3
+ main()