ddpl 1.3.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.
Files changed (10) hide show
  1. ddpl-1.3.0/LICENSE +21 -0
  2. ddpl-1.3.0/PKG-INFO +238 -0
  3. ddpl-1.3.0/README.md +204 -0
  4. ddpl-1.3.0/ddpl.egg-info/PKG-INFO +238 -0
  5. ddpl-1.3.0/ddpl.egg-info/SOURCES.txt +8 -0
  6. ddpl-1.3.0/ddpl.egg-info/dependency_links.txt +1 -0
  7. ddpl-1.3.0/ddpl.egg-info/entry_points.txt +2 -0
  8. ddpl-1.3.0/ddpl.egg-info/top_level.txt +1 -0
  9. ddpl-1.3.0/setup.cfg +4 -0
  10. ddpl-1.3.0/setup.py +39 -0
ddpl-1.3.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Suleiman
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
ddpl-1.3.0/PKG-INFO ADDED
@@ -0,0 +1,238 @@
1
+ Metadata-Version: 2.4
2
+ Name: ddpl
3
+ Version: 1.3.0
4
+ Summary: Deep Documentator for Python Libraries — inspect modules and PyPI sdists (C/C++/Rust/… sources, binaries, build files).
5
+ Author: DDPL contributors
6
+ License: MIT
7
+ Keywords: documentation inspect pypi sdist sources c rust binary elf macho coff
8
+ Classifier: Development Status :: 5 - Production/Stable
9
+ Classifier: Environment :: Console
10
+ Classifier: Intended Audience :: Developers
11
+ Classifier: License :: OSI Approved :: MIT License
12
+ Classifier: Operating System :: OS Independent
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Programming Language :: Python :: 3.8
15
+ Classifier: Programming Language :: Python :: 3.9
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Topic :: Software Development :: Documentation
21
+ Classifier: Topic :: Utilities
22
+ Requires-Python: >=3.8
23
+ Description-Content-Type: text/markdown
24
+ License-File: LICENSE
25
+ Dynamic: author
26
+ Dynamic: classifier
27
+ Dynamic: description
28
+ Dynamic: description-content-type
29
+ Dynamic: keywords
30
+ Dynamic: license
31
+ Dynamic: license-file
32
+ Dynamic: requires-python
33
+ Dynamic: summary
34
+
35
+ # ddpl — Deep Documentator for Python Libraries
36
+
37
+ Inspect Python modules and PyPI sdists — including **C/C++/Rust/Fortran/Cython/CUDA sources, build files, and binaries** — without installing the package.
38
+
39
+ Pure standard library. Zero dependencies. One file.
40
+
41
+ ## Why
42
+
43
+ `pydoc` and `pdoc` answer *"what does this API do"*. `ddpl` answers *"how is this package actually built"*:
44
+
45
+ - What languages are inside the sdist?
46
+ - Where is the C entry point?
47
+ - How does `setup.py` / `meson.build` / `Cargo.toml` put it together?
48
+ - What's in that `.o`, `.so`, `.a`, `.pkl`, `.pyc`, nested `.zip`?
49
+
50
+ `ddpl` works **before installation** — it downloads the sdist from PyPI and reads it in memory. No `pip install`, no compilation, no network beyond the download.
51
+
52
+ ## Install
53
+
54
+ pip install -e .
55
+
56
+ This puts `ddpl` on `PATH`.
57
+
58
+ Or without installing:
59
+
60
+ python ddpl.py <command>
61
+
62
+ ## Usage
63
+
64
+ ddpl # full help
65
+ ddpl --version # ddpl 1.3
66
+ ddpl help # same as above
67
+
68
+ ### Commands
69
+
70
+ ddpl doc <module> # inspect an importable Python module
71
+ --install # pip install if not importable
72
+ --search NAME # only list members whose name contains NAME
73
+ --no-color, --ascii
74
+
75
+ ddpl search <prefix> # prefix search on the PyPI simple index
76
+
77
+ ddpl info <package> # PyPI metadata + sdist URL
78
+
79
+ ddpl list <package> # download sdist, group files by language
80
+ --ext .c,.cpp # only show matching extensions
81
+ --max-mb N # download size limit (default 200)
82
+ --no-open # do not prompt to open a file
83
+ --no-color, --ascii
84
+
85
+ ddpl show <package> [path] # print one file (omit path to browse)
86
+ --ext .c,.h # restrict picker extensions
87
+ --max-mb N # download size limit (default 200)
88
+ --no-color, --ascii
89
+
90
+ ## Examples
91
+
92
+ ### What's inside a package
93
+
94
+ $ ddpl list numpy
95
+ ╔════════════════════════════════════╗
96
+ ║ numpy — 8527 files across 59 groups ║
97
+ ╚════════════════════════════════════╝
98
+ ┌──────────────────────┐
99
+ │ C │
100
+ ├──────────────────────┤
101
+ │ numpy-2.5.4/numpy/_core/... │
102
+ │ … +1646 more │
103
+ └──────────────────────┘
104
+ ┌──────────────────────┐
105
+ │ C++ │
106
+ │ … +487 more │
107
+ └──────────────────────┘
108
+ ┌──────────────────────┐
109
+ │ Fortran │
110
+ │ … +172 more │
111
+ └──────────────────────┘
112
+ ┌──────────────────────┐
113
+ │ Assembly │
114
+ │ … +133 more │
115
+ └──────────────────────┘
116
+
117
+ ### Read a specific C source
118
+
119
+ $ ddpl show pillow src/libImaging/Storage.c
120
+ ╔══════════════════════════════════════╗
121
+ ║ pillow :: pillow-13.0.0/src/libImaging/Storage.c ║
122
+ ╚══════════════════════════════════════╝
123
+ 1: #include "Imaging.h"
124
+ 2:
125
+ 3: Imaging
126
+ 4: ImagingNew(ImagingModule im, int mode, int xsize, int ysize)
127
+ 5: {
128
+ ...
129
+ [50/900] Enter=more, n=line, q=quit:
130
+
131
+ `n` jumps to a line number, `q` quits, Enter pages forward.
132
+
133
+ ### Search an installed module
134
+
135
+ $ ddpl doc json --search dump
136
+ ╔══════════════════════════════════════╗
137
+ ║ SEARCH: dump in json ║
138
+ ╚══════════════════════════════════════╝
139
+ dump (callable)
140
+ dumps (callable)
141
+
142
+ ### Only native sources
143
+
144
+ $ ddpl list pillow --ext .c,.h
145
+ $ ddpl list tokenizers --ext .rs
146
+ $ ddpl list scipy --ext .f,.f90,.pyx
147
+
148
+ ### Browse interactively
149
+
150
+ $ ddpl show pillow
151
+ ╔══════════════════════════════════════╗
152
+ ║ Files (1728) ║
153
+ ╚══════════════════════════════════════╝
154
+ 1. pillow-13.0.0/LICENSE
155
+ 2. pillow-13.0.0/README.md
156
+ ...
157
+ Open which file? [1..1728, part of name, Enter=cancel]: _imaging.c
158
+ ... pick by number if multiple matches ...
159
+
160
+ ## Supported archives (stdlib only)
161
+
162
+ tar: .tar .tar.gz .tgz .tar.bz2 .tbz2 .tar.xz .txz .tar.lzma .tlz
163
+ zip: .zip .whl .egg .jar .war .ear .apk .aab .xpi .nupkg .vsix
164
+ .docx .xlsx .pptx .odt .ods .odp .epub
165
+ single: .gz .bz2 .xz .lzma
166
+
167
+ Not supported without external tools (stdlib has no decoder):
168
+
169
+ .tar.zst .tzst .tar.zstd .tar.lz4 .tlz4 .tar.lz .tar.lzo
170
+
171
+ ## Binary inspection (by content, not by extension)
172
+
173
+ ELF Linux/Android/BSD .o, .so, executables
174
+ Mach-O macOS .o, .dylib, executables (including fat/universal)
175
+ COFF Windows .obj, Unix COFF
176
+ PE/COFF Windows .exe, .dll
177
+ WASM .wasm, .o built for wasm32
178
+ LLVM BC LLVM bitcode (sometimes named .o)
179
+ Java .class (magic cafebabe)
180
+ ar .a, .lib
181
+ zip nested .zip / .whl / .jar / etc.
182
+ pickle .pkl / .pickle opcode summary (no unpickling)
183
+ marshal safe repr preview
184
+ pyc/pyo header parse
185
+
186
+ Detection runs on file **content**, so a COFF `.obj` named `.o` is still detected as COFF, and an ELF named `.obj` is still detected as ELF.
187
+
188
+ ## File-type coverage
189
+
190
+ `ddpl list` groups files by language/purpose, not just by "programming language". For `numpy` that's 59 groups — because the sdist includes vendored Meson with tests in C#, D, Java, Rust, Swift, ObjC++, Coq, CUDA, QML, Protobuf, TypeScript, XML, PolicyKit, and more.
191
+
192
+ Categories include:
193
+
194
+ - **Native**: C, C++, Objective-C/C++, Rust, Go, Zig, D, Nim, Crystal, V, Swift, Kotlin, Scala, Java, C#, F#, VB.NET, Dart, Cython, Fortran, Pascal, Ada, Assembly, CUDA, OpenCL, shaders, WASM, Idris, Lean, Coq, Agda, Elm
195
+ - **Scripts**: JS/TS, Lua, Ruby, Perl, PHP, Python, R, Julia, MATLAB/Octave, Lisp/Clojure/Scheme, Haskell, OCaml, Erlang, Elixir, Prolog, Smalltalk, Tcl, Bash/Zsh/Fish, PowerShell, Batch, Awk, Sed, Groovy, GDScript, Solidity, Vyper, Move, Raku, Forth
196
+ - **Data**: SQL, HTML, CSS/SCSS/SASS/LESS, XML/XSD/XSL, JSON/JSON5/JSONC, YAML, TOML, INI/CFG, CSV/TSV, Protobuf, Thrift, Avro, GraphQL, FlatBuffers, CapnProto, HCL/Terraform, Nix, Jsonnet, Dhall, CUE, `.env`
197
+ - **Build**: Makefile, CMake, Meson, Bazel, Gradle, Maven, Cargo, Dockerfile, Nuspec, Autoconf
198
+ - **Docs**: Markdown, RST, TeX, AsciiDoc, Org, Textile, Wiki, man pages, plain text
199
+ - **Web**: Vue, Svelte, Astro, Elm, Pug, Handlebars, Jinja, Twig, EJS, ERB, Liquid, Nunjucks, Tera, Razor, Blade, XAML, QML
200
+ - **System**: systemd units, `.desktop`, PolicyKit, SELinux, AppArmor, plist, `.reg`
201
+ - **Binaries**: images, fonts, audio, video, archives, executables, PDF, Office docs, databases
202
+
203
+ Plus bare filenames: `Makefile`, `CMakeLists.txt`, `meson.build`, `BUILD`, `WORKSPACE`, `Dockerfile`, `Gemfile`, `Rakefile`, `Cargo.toml`, `pyproject.toml`, `setup.cfg`, `requirements.txt`, `README*`, `LICENSE*`, `CHANGELOG*`, `.gitignore`, `.env`, `docker-compose.yml`, and more.
204
+
205
+ ## Cache
206
+
207
+ Windows : %LOCALAPPDATA%\ddpl
208
+ Unix : ~/.cache/ddpl
209
+ Fallback: system temp dir
210
+
211
+ Clear with:
212
+
213
+ rm -rf ~/.cache/ddpl # Unix
214
+ rmdir /s %LOCALAPPDATA%\ddpl # Windows
215
+
216
+ ## Platform notes
217
+
218
+ - **Windows**: ANSI color enabled via `ctypes`; cache under `%LOCALAPPDATA%`.
219
+ - **macOS**: Mach-O / dylib headers detected; `afplay` for playback (if `ddpl` ever gains audio, it won't).
220
+ - **Linux**: ELF headers + `ar` members.
221
+ - **Android/Termux**: pure-stdlib fallbacks for tar/zip/gz/bz2/xz/lzma; no `zstd`/`lz4`/`lzo` without external tools.
222
+ - **Pydroid**: same as Android, but `subprocess` may be restricted in some contexts.
223
+
224
+ ## Limitations
225
+
226
+ `ddpl` reads sources — it does not compile, execute, or analyze them.
227
+
228
+ - No call graphs (use Doxygen).
229
+ - No symbol analysis (use `ctags`/`cscope`/`tree-sitter`).
230
+ - No HTML output (use Sphinx/pdoc).
231
+ - No private packages without a public PyPI sdist.
232
+ - `.tar.zst`/`.tar.lz4`/`.tar.lzo` require external decoders.
233
+
234
+ For **publication** documentation, use Sphinx or pdoc. For **understanding what's inside**, use `ddpl`.
235
+
236
+ ## License
237
+
238
+ MIT
ddpl-1.3.0/README.md ADDED
@@ -0,0 +1,204 @@
1
+ # ddpl — Deep Documentator for Python Libraries
2
+
3
+ Inspect Python modules and PyPI sdists — including **C/C++/Rust/Fortran/Cython/CUDA sources, build files, and binaries** — without installing the package.
4
+
5
+ Pure standard library. Zero dependencies. One file.
6
+
7
+ ## Why
8
+
9
+ `pydoc` and `pdoc` answer *"what does this API do"*. `ddpl` answers *"how is this package actually built"*:
10
+
11
+ - What languages are inside the sdist?
12
+ - Where is the C entry point?
13
+ - How does `setup.py` / `meson.build` / `Cargo.toml` put it together?
14
+ - What's in that `.o`, `.so`, `.a`, `.pkl`, `.pyc`, nested `.zip`?
15
+
16
+ `ddpl` works **before installation** — it downloads the sdist from PyPI and reads it in memory. No `pip install`, no compilation, no network beyond the download.
17
+
18
+ ## Install
19
+
20
+ pip install -e .
21
+
22
+ This puts `ddpl` on `PATH`.
23
+
24
+ Or without installing:
25
+
26
+ python ddpl.py <command>
27
+
28
+ ## Usage
29
+
30
+ ddpl # full help
31
+ ddpl --version # ddpl 1.3
32
+ ddpl help # same as above
33
+
34
+ ### Commands
35
+
36
+ ddpl doc <module> # inspect an importable Python module
37
+ --install # pip install if not importable
38
+ --search NAME # only list members whose name contains NAME
39
+ --no-color, --ascii
40
+
41
+ ddpl search <prefix> # prefix search on the PyPI simple index
42
+
43
+ ddpl info <package> # PyPI metadata + sdist URL
44
+
45
+ ddpl list <package> # download sdist, group files by language
46
+ --ext .c,.cpp # only show matching extensions
47
+ --max-mb N # download size limit (default 200)
48
+ --no-open # do not prompt to open a file
49
+ --no-color, --ascii
50
+
51
+ ddpl show <package> [path] # print one file (omit path to browse)
52
+ --ext .c,.h # restrict picker extensions
53
+ --max-mb N # download size limit (default 200)
54
+ --no-color, --ascii
55
+
56
+ ## Examples
57
+
58
+ ### What's inside a package
59
+
60
+ $ ddpl list numpy
61
+ ╔════════════════════════════════════╗
62
+ ║ numpy — 8527 files across 59 groups ║
63
+ ╚════════════════════════════════════╝
64
+ ┌──────────────────────┐
65
+ │ C │
66
+ ├──────────────────────┤
67
+ │ numpy-2.5.4/numpy/_core/... │
68
+ │ … +1646 more │
69
+ └──────────────────────┘
70
+ ┌──────────────────────┐
71
+ │ C++ │
72
+ │ … +487 more │
73
+ └──────────────────────┘
74
+ ┌──────────────────────┐
75
+ │ Fortran │
76
+ │ … +172 more │
77
+ └──────────────────────┘
78
+ ┌──────────────────────┐
79
+ │ Assembly │
80
+ │ … +133 more │
81
+ └──────────────────────┘
82
+
83
+ ### Read a specific C source
84
+
85
+ $ ddpl show pillow src/libImaging/Storage.c
86
+ ╔══════════════════════════════════════╗
87
+ ║ pillow :: pillow-13.0.0/src/libImaging/Storage.c ║
88
+ ╚══════════════════════════════════════╝
89
+ 1: #include "Imaging.h"
90
+ 2:
91
+ 3: Imaging
92
+ 4: ImagingNew(ImagingModule im, int mode, int xsize, int ysize)
93
+ 5: {
94
+ ...
95
+ [50/900] Enter=more, n=line, q=quit:
96
+
97
+ `n` jumps to a line number, `q` quits, Enter pages forward.
98
+
99
+ ### Search an installed module
100
+
101
+ $ ddpl doc json --search dump
102
+ ╔══════════════════════════════════════╗
103
+ ║ SEARCH: dump in json ║
104
+ ╚══════════════════════════════════════╝
105
+ dump (callable)
106
+ dumps (callable)
107
+
108
+ ### Only native sources
109
+
110
+ $ ddpl list pillow --ext .c,.h
111
+ $ ddpl list tokenizers --ext .rs
112
+ $ ddpl list scipy --ext .f,.f90,.pyx
113
+
114
+ ### Browse interactively
115
+
116
+ $ ddpl show pillow
117
+ ╔══════════════════════════════════════╗
118
+ ║ Files (1728) ║
119
+ ╚══════════════════════════════════════╝
120
+ 1. pillow-13.0.0/LICENSE
121
+ 2. pillow-13.0.0/README.md
122
+ ...
123
+ Open which file? [1..1728, part of name, Enter=cancel]: _imaging.c
124
+ ... pick by number if multiple matches ...
125
+
126
+ ## Supported archives (stdlib only)
127
+
128
+ tar: .tar .tar.gz .tgz .tar.bz2 .tbz2 .tar.xz .txz .tar.lzma .tlz
129
+ zip: .zip .whl .egg .jar .war .ear .apk .aab .xpi .nupkg .vsix
130
+ .docx .xlsx .pptx .odt .ods .odp .epub
131
+ single: .gz .bz2 .xz .lzma
132
+
133
+ Not supported without external tools (stdlib has no decoder):
134
+
135
+ .tar.zst .tzst .tar.zstd .tar.lz4 .tlz4 .tar.lz .tar.lzo
136
+
137
+ ## Binary inspection (by content, not by extension)
138
+
139
+ ELF Linux/Android/BSD .o, .so, executables
140
+ Mach-O macOS .o, .dylib, executables (including fat/universal)
141
+ COFF Windows .obj, Unix COFF
142
+ PE/COFF Windows .exe, .dll
143
+ WASM .wasm, .o built for wasm32
144
+ LLVM BC LLVM bitcode (sometimes named .o)
145
+ Java .class (magic cafebabe)
146
+ ar .a, .lib
147
+ zip nested .zip / .whl / .jar / etc.
148
+ pickle .pkl / .pickle opcode summary (no unpickling)
149
+ marshal safe repr preview
150
+ pyc/pyo header parse
151
+
152
+ Detection runs on file **content**, so a COFF `.obj` named `.o` is still detected as COFF, and an ELF named `.obj` is still detected as ELF.
153
+
154
+ ## File-type coverage
155
+
156
+ `ddpl list` groups files by language/purpose, not just by "programming language". For `numpy` that's 59 groups — because the sdist includes vendored Meson with tests in C#, D, Java, Rust, Swift, ObjC++, Coq, CUDA, QML, Protobuf, TypeScript, XML, PolicyKit, and more.
157
+
158
+ Categories include:
159
+
160
+ - **Native**: C, C++, Objective-C/C++, Rust, Go, Zig, D, Nim, Crystal, V, Swift, Kotlin, Scala, Java, C#, F#, VB.NET, Dart, Cython, Fortran, Pascal, Ada, Assembly, CUDA, OpenCL, shaders, WASM, Idris, Lean, Coq, Agda, Elm
161
+ - **Scripts**: JS/TS, Lua, Ruby, Perl, PHP, Python, R, Julia, MATLAB/Octave, Lisp/Clojure/Scheme, Haskell, OCaml, Erlang, Elixir, Prolog, Smalltalk, Tcl, Bash/Zsh/Fish, PowerShell, Batch, Awk, Sed, Groovy, GDScript, Solidity, Vyper, Move, Raku, Forth
162
+ - **Data**: SQL, HTML, CSS/SCSS/SASS/LESS, XML/XSD/XSL, JSON/JSON5/JSONC, YAML, TOML, INI/CFG, CSV/TSV, Protobuf, Thrift, Avro, GraphQL, FlatBuffers, CapnProto, HCL/Terraform, Nix, Jsonnet, Dhall, CUE, `.env`
163
+ - **Build**: Makefile, CMake, Meson, Bazel, Gradle, Maven, Cargo, Dockerfile, Nuspec, Autoconf
164
+ - **Docs**: Markdown, RST, TeX, AsciiDoc, Org, Textile, Wiki, man pages, plain text
165
+ - **Web**: Vue, Svelte, Astro, Elm, Pug, Handlebars, Jinja, Twig, EJS, ERB, Liquid, Nunjucks, Tera, Razor, Blade, XAML, QML
166
+ - **System**: systemd units, `.desktop`, PolicyKit, SELinux, AppArmor, plist, `.reg`
167
+ - **Binaries**: images, fonts, audio, video, archives, executables, PDF, Office docs, databases
168
+
169
+ Plus bare filenames: `Makefile`, `CMakeLists.txt`, `meson.build`, `BUILD`, `WORKSPACE`, `Dockerfile`, `Gemfile`, `Rakefile`, `Cargo.toml`, `pyproject.toml`, `setup.cfg`, `requirements.txt`, `README*`, `LICENSE*`, `CHANGELOG*`, `.gitignore`, `.env`, `docker-compose.yml`, and more.
170
+
171
+ ## Cache
172
+
173
+ Windows : %LOCALAPPDATA%\ddpl
174
+ Unix : ~/.cache/ddpl
175
+ Fallback: system temp dir
176
+
177
+ Clear with:
178
+
179
+ rm -rf ~/.cache/ddpl # Unix
180
+ rmdir /s %LOCALAPPDATA%\ddpl # Windows
181
+
182
+ ## Platform notes
183
+
184
+ - **Windows**: ANSI color enabled via `ctypes`; cache under `%LOCALAPPDATA%`.
185
+ - **macOS**: Mach-O / dylib headers detected; `afplay` for playback (if `ddpl` ever gains audio, it won't).
186
+ - **Linux**: ELF headers + `ar` members.
187
+ - **Android/Termux**: pure-stdlib fallbacks for tar/zip/gz/bz2/xz/lzma; no `zstd`/`lz4`/`lzo` without external tools.
188
+ - **Pydroid**: same as Android, but `subprocess` may be restricted in some contexts.
189
+
190
+ ## Limitations
191
+
192
+ `ddpl` reads sources — it does not compile, execute, or analyze them.
193
+
194
+ - No call graphs (use Doxygen).
195
+ - No symbol analysis (use `ctags`/`cscope`/`tree-sitter`).
196
+ - No HTML output (use Sphinx/pdoc).
197
+ - No private packages without a public PyPI sdist.
198
+ - `.tar.zst`/`.tar.lz4`/`.tar.lzo` require external decoders.
199
+
200
+ For **publication** documentation, use Sphinx or pdoc. For **understanding what's inside**, use `ddpl`.
201
+
202
+ ## License
203
+
204
+ MIT
ddpl-1.3.0/ddpl.egg-info/PKG-INFO ADDED
@@ -0,0 +1,238 @@
1
+ Metadata-Version: 2.4
2
+ Name: ddpl
3
+ Version: 1.3.0
4
+ Summary: Deep Documentator for Python Libraries — inspect modules and PyPI sdists (C/C++/Rust/… sources, binaries, build files).
5
+ Author: DDPL contributors
6
+ License: MIT
7
+ Keywords: documentation inspect pypi sdist sources c rust binary elf macho coff
8
+ Classifier: Development Status :: 5 - Production/Stable
9
+ Classifier: Environment :: Console
10
+ Classifier: Intended Audience :: Developers
11
+ Classifier: License :: OSI Approved :: MIT License
12
+ Classifier: Operating System :: OS Independent
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Programming Language :: Python :: 3.8
15
+ Classifier: Programming Language :: Python :: 3.9
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Topic :: Software Development :: Documentation
21
+ Classifier: Topic :: Utilities
22
+ Requires-Python: >=3.8
23
+ Description-Content-Type: text/markdown
24
+ License-File: LICENSE
25
+ Dynamic: author
26
+ Dynamic: classifier
27
+ Dynamic: description
28
+ Dynamic: description-content-type
29
+ Dynamic: keywords
30
+ Dynamic: license
31
+ Dynamic: license-file
32
+ Dynamic: requires-python
33
+ Dynamic: summary
34
+
35
+ # ddpl — Deep Documentator for Python Libraries
36
+
37
+ Inspect Python modules and PyPI sdists — including **C/C++/Rust/Fortran/Cython/CUDA sources, build files, and binaries** — without installing the package.
38
+
39
+ Pure standard library. Zero dependencies. One file.
40
+
41
+ ## Why
42
+
43
+ `pydoc` and `pdoc` answer *"what does this API do"*. `ddpl` answers *"how is this package actually built"*:
44
+
45
+ - What languages are inside the sdist?
46
+ - Where is the C entry point?
47
+ - How does `setup.py` / `meson.build` / `Cargo.toml` put it together?
48
+ - What's in that `.o`, `.so`, `.a`, `.pkl`, `.pyc`, nested `.zip`?
49
+
50
+ `ddpl` works **before installation** — it downloads the sdist from PyPI and reads it in memory. No `pip install`, no compilation, no network beyond the download.
51
+
52
+ ## Install
53
+
54
+ pip install -e .
55
+
56
+ This puts `ddpl` on `PATH`.
57
+
58
+ Or without installing:
59
+
60
+ python ddpl.py <command>
61
+
62
+ ## Usage
63
+
64
+ ddpl # full help
65
+ ddpl --version # ddpl 1.3
66
+ ddpl help # same as above
67
+
68
+ ### Commands
69
+
70
+ ddpl doc <module> # inspect an importable Python module
71
+ --install # pip install if not importable
72
+ --search NAME # only list members whose name contains NAME
73
+ --no-color, --ascii
74
+
75
+ ddpl search <prefix> # prefix search on the PyPI simple index
76
+
77
+ ddpl info <package> # PyPI metadata + sdist URL
78
+
79
+ ddpl list <package> # download sdist, group files by language
80
+ --ext .c,.cpp # only show matching extensions
81
+ --max-mb N # download size limit (default 200)
82
+ --no-open # do not prompt to open a file
83
+ --no-color, --ascii
84
+
85
+ ddpl show <package> [path] # print one file (omit path to browse)
86
+ --ext .c,.h # restrict picker extensions
87
+ --max-mb N # download size limit (default 200)
88
+ --no-color, --ascii
89
+
90
+ ## Examples
91
+
92
+ ### What's inside a package
93
+
94
+ $ ddpl list numpy
95
+ ╔════════════════════════════════════╗
96
+ ║ numpy — 8527 files across 59 groups ║
97
+ ╚════════════════════════════════════╝
98
+ ┌──────────────────────┐
99
+ │ C │
100
+ ├──────────────────────┤
101
+ │ numpy-2.5.4/numpy/_core/... │
102
+ │ … +1646 more │
103
+ └──────────────────────┘
104
+ ┌──────────────────────┐
105
+ │ C++ │
106
+ │ … +487 more │
107
+ └──────────────────────┘
108
+ ┌──────────────────────┐
109
+ │ Fortran │
110
+ │ … +172 more │
111
+ └──────────────────────┘
112
+ ┌──────────────────────┐
113
+ │ Assembly │
114
+ │ … +133 more │
115
+ └──────────────────────┘
116
+
117
+ ### Read a specific C source
118
+
119
+ $ ddpl show pillow src/libImaging/Storage.c
120
+ ╔══════════════════════════════════════╗
121
+ ║ pillow :: pillow-13.0.0/src/libImaging/Storage.c ║
122
+ ╚══════════════════════════════════════╝
123
+ 1: #include "Imaging.h"
124
+ 2:
125
+ 3: Imaging
126
+ 4: ImagingNew(ImagingModule im, int mode, int xsize, int ysize)
127
+ 5: {
128
+ ...
129
+ [50/900] Enter=more, n=line, q=quit:
130
+
131
+ `n` jumps to a line number, `q` quits, Enter pages forward.
132
+
133
+ ### Search an installed module
134
+
135
+ $ ddpl doc json --search dump
136
+ ╔══════════════════════════════════════╗
137
+ ║ SEARCH: dump in json ║
138
+ ╚══════════════════════════════════════╝
139
+ dump (callable)
140
+ dumps (callable)
141
+
142
+ ### Only native sources
143
+
144
+ $ ddpl list pillow --ext .c,.h
145
+ $ ddpl list tokenizers --ext .rs
146
+ $ ddpl list scipy --ext .f,.f90,.pyx
147
+
148
+ ### Browse interactively
149
+
150
+ $ ddpl show pillow
151
+ ╔══════════════════════════════════════╗
152
+ ║ Files (1728) ║
153
+ ╚══════════════════════════════════════╝
154
+ 1. pillow-13.0.0/LICENSE
155
+ 2. pillow-13.0.0/README.md
156
+ ...
157
+ Open which file? [1..1728, part of name, Enter=cancel]: _imaging.c
158
+ ... pick by number if multiple matches ...
159
+
160
+ ## Supported archives (stdlib only)
161
+
162
+ tar: .tar .tar.gz .tgz .tar.bz2 .tbz2 .tar.xz .txz .tar.lzma .tlz
163
+ zip: .zip .whl .egg .jar .war .ear .apk .aab .xpi .nupkg .vsix
164
+ .docx .xlsx .pptx .odt .ods .odp .epub
165
+ single: .gz .bz2 .xz .lzma
166
+
167
+ Not supported without external tools (stdlib has no decoder):
168
+
169
+ .tar.zst .tzst .tar.zstd .tar.lz4 .tlz4 .tar.lz .tar.lzo
170
+
171
+ ## Binary inspection (by content, not by extension)
172
+
173
+ ELF Linux/Android/BSD .o, .so, executables
174
+ Mach-O macOS .o, .dylib, executables (including fat/universal)
175
+ COFF Windows .obj, Unix COFF
176
+ PE/COFF Windows .exe, .dll
177
+ WASM .wasm, .o built for wasm32
178
+ LLVM BC LLVM bitcode (sometimes named .o)
179
+ Java .class (magic cafebabe)
180
+ ar .a, .lib
181
+ zip nested .zip / .whl / .jar / etc.
182
+ pickle .pkl / .pickle opcode summary (no unpickling)
183
+ marshal safe repr preview
184
+ pyc/pyo header parse
185
+
186
+ Detection runs on file **content**, so a COFF `.obj` named `.o` is still detected as COFF, and an ELF named `.obj` is still detected as ELF.
187
+
188
+ ## File-type coverage
189
+
190
+ `ddpl list` groups files by language/purpose, not just by "programming language". For `numpy` that's 59 groups — because the sdist includes vendored Meson with tests in C#, D, Java, Rust, Swift, ObjC++, Coq, CUDA, QML, Protobuf, TypeScript, XML, PolicyKit, and more.
191
+
192
+ Categories include:
193
+
194
+ - **Native**: C, C++, Objective-C/C++, Rust, Go, Zig, D, Nim, Crystal, V, Swift, Kotlin, Scala, Java, C#, F#, VB.NET, Dart, Cython, Fortran, Pascal, Ada, Assembly, CUDA, OpenCL, shaders, WASM, Idris, Lean, Coq, Agda, Elm
195
+ - **Scripts**: JS/TS, Lua, Ruby, Perl, PHP, Python, R, Julia, MATLAB/Octave, Lisp/Clojure/Scheme, Haskell, OCaml, Erlang, Elixir, Prolog, Smalltalk, Tcl, Bash/Zsh/Fish, PowerShell, Batch, Awk, Sed, Groovy, GDScript, Solidity, Vyper, Move, Raku, Forth
196
+ - **Data**: SQL, HTML, CSS/SCSS/SASS/LESS, XML/XSD/XSL, JSON/JSON5/JSONC, YAML, TOML, INI/CFG, CSV/TSV, Protobuf, Thrift, Avro, GraphQL, FlatBuffers, CapnProto, HCL/Terraform, Nix, Jsonnet, Dhall, CUE, `.env`
197
+ - **Build**: Makefile, CMake, Meson, Bazel, Gradle, Maven, Cargo, Dockerfile, Nuspec, Autoconf
198
+ - **Docs**: Markdown, RST, TeX, AsciiDoc, Org, Textile, Wiki, man pages, plain text
199
+ - **Web**: Vue, Svelte, Astro, Elm, Pug, Handlebars, Jinja, Twig, EJS, ERB, Liquid, Nunjucks, Tera, Razor, Blade, XAML, QML
200
+ - **System**: systemd units, `.desktop`, PolicyKit, SELinux, AppArmor, plist, `.reg`
201
+ - **Binaries**: images, fonts, audio, video, archives, executables, PDF, Office docs, databases
202
+
203
+ Plus bare filenames: `Makefile`, `CMakeLists.txt`, `meson.build`, `BUILD`, `WORKSPACE`, `Dockerfile`, `Gemfile`, `Rakefile`, `Cargo.toml`, `pyproject.toml`, `setup.cfg`, `requirements.txt`, `README*`, `LICENSE*`, `CHANGELOG*`, `.gitignore`, `.env`, `docker-compose.yml`, and more.
204
+
205
+ ## Cache
206
+
207
+ Windows : %LOCALAPPDATA%\ddpl
208
+ Unix : ~/.cache/ddpl
209
+ Fallback: system temp dir
210
+
211
+ Clear with:
212
+
213
+ rm -rf ~/.cache/ddpl # Unix
214
+ rmdir /s %LOCALAPPDATA%\ddpl # Windows
215
+
216
+ ## Platform notes
217
+
218
+ - **Windows**: ANSI color enabled via `ctypes`; cache under `%LOCALAPPDATA%`.
219
+ - **macOS**: Mach-O / dylib headers detected; `afplay` for playback (if `ddpl` ever gains audio, it won't).
220
+ - **Linux**: ELF headers + `ar` members.
221
+ - **Android/Termux**: pure-stdlib fallbacks for tar/zip/gz/bz2/xz/lzma; no `zstd`/`lz4`/`lzo` without external tools.
222
+ - **Pydroid**: same as Android, but `subprocess` may be restricted in some contexts.
223
+
224
+ ## Limitations
225
+
226
+ `ddpl` reads sources — it does not compile, execute, or analyze them.
227
+
228
+ - No call graphs (use Doxygen).
229
+ - No symbol analysis (use `ctags`/`cscope`/`tree-sitter`).
230
+ - No HTML output (use Sphinx/pdoc).
231
+ - No private packages without a public PyPI sdist.
232
+ - `.tar.zst`/`.tar.lz4`/`.tar.lzo` require external decoders.
233
+
234
+ For **publication** documentation, use Sphinx or pdoc. For **understanding what's inside**, use `ddpl`.
235
+
236
+ ## License
237
+
238
+ MIT
ddpl-1.3.0/ddpl.egg-info/SOURCES.txt ADDED
@@ -0,0 +1,8 @@
1
+ LICENSE
2
+ README.md
3
+ setup.py
4
+ ddpl.egg-info/PKG-INFO
5
+ ddpl.egg-info/SOURCES.txt
6
+ ddpl.egg-info/dependency_links.txt
7
+ ddpl.egg-info/entry_points.txt
8
+ ddpl.egg-info/top_level.txt
ddpl-1.3.0/ddpl.egg-info/entry_points.txt ADDED
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ ddpl = ddpl:main
ddpl-1.3.0/ddpl.egg-info/top_level.txt ADDED
@@ -0,0 +1 @@
1
+ ddpl
ddpl-1.3.0/setup.cfg ADDED
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
ddpl-1.3.0/setup.py ADDED
@@ -0,0 +1,39 @@
1
+ from setuptools import setup, find_packages
2
+
3
+ with open("README.md", "r", encoding="utf-8") as fh:
4
+ long_description = fh.read()
5
+
6
+ setup(
7
+ name="ddpl",
8
+ version="1.3.0",
9
+ author="DDPL contributors",
10
+ description="Deep Documentator for Python Libraries — inspect modules and PyPI sdists (C/C++/Rust/… sources, binaries, build files).",
11
+ long_description=long_description,
12
+ long_description_content_type="text/markdown",
13
+ license="MIT",
14
+ py_modules=["ddpl"],
15
+ python_requires=">=3.8",
16
+ install_requires=[],
17
+ entry_points={
18
+ "console_scripts": [
19
+ "ddpl = ddpl:main",
20
+ ],
21
+ },
22
+ classifiers=[
23
+ "Development Status :: 5 - Production/Stable",
24
+ "Environment :: Console",
25
+ "Intended Audience :: Developers",
26
+ "License :: OSI Approved :: MIT License",
27
+ "Operating System :: OS Independent",
28
+ "Programming Language :: Python :: 3",
29
+ "Programming Language :: Python :: 3.8",
30
+ "Programming Language :: Python :: 3.9",
31
+ "Programming Language :: Python :: 3.10",
32
+ "Programming Language :: Python :: 3.11",
33
+ "Programming Language :: Python :: 3.12",
34
+ "Programming Language :: Python :: 3.13",
35
+ "Topic :: Software Development :: Documentation",
36
+ "Topic :: Utilities",
37
+ ],
38
+ keywords="documentation inspect pypi sdist sources c rust binary elf macho coff",
39
+ )