belfry 0.1.0__tar.gz

belfry-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brendan Meade
+
+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.

belfry-0.1.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: belfry
+Version: 0.1.0
+Summary: A Textual TUI for rediscovering what your Python scripts do — their arguments, inputs, and outputs
+Author-email: Brendan Meade <brendanjmeade@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/brendanjmeade/belfry
+Project-URL: Repository, https://github.com/brendanjmeade/belfry
+Project-URL: Issues, https://github.com/brendanjmeade/belfry/issues
+Keywords: tui,textual,scripts,static-analysis,ast,developer-tools,cli
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: textual>=0.60
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# belfry
+
+**Ring a bell.** A [Textual](https://github.com/Textualize/textual) TUI for
+rediscovering what your Python scripts actually do.
+
+![belfry in action](https://raw.githubusercontent.com/brendanjmeade/belfry/main/docs/screenshot.png)
+
+You know the folder: dozens of `.py` files accumulated over months — mainline
+analyses, throwaway one-offs, and half-remembered experiments. Which ones take
+arguments? What files do they read? What do they write? `belfry` answers those
+questions at a glance, without you opening a single file.
+
+A *belfry* is a bell tower — and, as in "bats in the belfry," a place where
+things hang half-forgotten until you go and ring them.
+
+## What it shows
+
+Run `belfry` in any folder. It lists every `.py` file (recursively, honoring
+`.gitignore`) with a script-type badge, last-modified date, and git provenance.
+Select a file and belfry shows you:
+
+- the **CLI arguments** it accepts — parsed from `argparse` / `click` / `typer`,
+  or `sys.argv` indexing, even when there's no `--help` text to be found;
+- the **hardcoded input filenames** it reads (`pd.read_csv`, `open`,
+  `xr.open_dataset`, `np.load`, …);
+- the **output files** it writes (`.to_csv`, `plt.savefig`, `json.dump`,
+  `gmsh.write`, …);
+- its **docstring and leading comments**;
+- a **script-type badge** — `cli`, `cell-script` (Jupyter `# %%`), `script`, or
+  `error`;
+- the module-level constants ("knobs") for scripts driven by hardcoded values
+  instead of CLI flags;
+- a **syntax-highlighted source preview**.
+
+It even resolves f-strings and `Path(...)` expressions, so
+`f"./runs/{RUN_NAME}/"` shows up as the real path and unresolved values are
+clearly flagged.
+
+## How it works
+
+belfry reads each script with Python's `ast` module and **never executes it** —
+safe to point at code you don't trust or barely remember. Analysis and git
+lookups happen lazily as you move through the list and are cached, so it stays
+responsive in large trees. Git provenance falls back cleanly to filesystem
+mtime when a file is untracked or you're not in a git repo.
+
+## Install
+
+belfry is not on PyPI yet. Install from source:
+
+```bash
+git clone git@github.com:brendanjmeade/belfry.git
+cd belfry
+pip install -e .
+```
+
+Requires Python 3.10+ (the only runtime dependency is `textual`).
+
+## Usage
+
+```bash
+belfry [PATH] [--no-recurse]
+```
+
+- `PATH` — directory to scan (defaults to the current directory).
+- `--no-recurse` — only scan the top level instead of descending into subdirectories.
+
+You can also run it as a module: `python -m belfry`.
+
+## Key bindings
+
+| Key | Action |
+| --- | --- |
+| `j` / `k`, arrows | navigate the file list (or scroll the details when the lower pane is focused) |
+| `J` / `K` | jump focus to the lower / upper pane |
+| `h` / `l` | switch tabs in the lower pane (Summary / Source) |
+| `/` | filter files by name |
+| `r` | toggle recursion / rescan |
+| `enter` | open the selected file in `$EDITOR` |
+| `q` | quit |
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+The static analyzer (`src/belfry/analyzer.py`) is covered by a focused test
+suite with fixtures for each pattern it handles.
+
+## License
+
+Not yet licensed — a license will be added before the first release.

belfry-0.1.0/README.md

@@ -0,0 +1,94 @@
+# belfry
+
+**Ring a bell.** A [Textual](https://github.com/Textualize/textual) TUI for
+rediscovering what your Python scripts actually do.
+
+![belfry in action](https://raw.githubusercontent.com/brendanjmeade/belfry/main/docs/screenshot.png)
+
+You know the folder: dozens of `.py` files accumulated over months — mainline
+analyses, throwaway one-offs, and half-remembered experiments. Which ones take
+arguments? What files do they read? What do they write? `belfry` answers those
+questions at a glance, without you opening a single file.
+
+A *belfry* is a bell tower — and, as in "bats in the belfry," a place where
+things hang half-forgotten until you go and ring them.
+
+## What it shows
+
+Run `belfry` in any folder. It lists every `.py` file (recursively, honoring
+`.gitignore`) with a script-type badge, last-modified date, and git provenance.
+Select a file and belfry shows you:
+
+- the **CLI arguments** it accepts — parsed from `argparse` / `click` / `typer`,
+  or `sys.argv` indexing, even when there's no `--help` text to be found;
+- the **hardcoded input filenames** it reads (`pd.read_csv`, `open`,
+  `xr.open_dataset`, `np.load`, …);
+- the **output files** it writes (`.to_csv`, `plt.savefig`, `json.dump`,
+  `gmsh.write`, …);
+- its **docstring and leading comments**;
+- a **script-type badge** — `cli`, `cell-script` (Jupyter `# %%`), `script`, or
+  `error`;
+- the module-level constants ("knobs") for scripts driven by hardcoded values
+  instead of CLI flags;
+- a **syntax-highlighted source preview**.
+
+It even resolves f-strings and `Path(...)` expressions, so
+`f"./runs/{RUN_NAME}/"` shows up as the real path and unresolved values are
+clearly flagged.
+
+## How it works
+
+belfry reads each script with Python's `ast` module and **never executes it** —
+safe to point at code you don't trust or barely remember. Analysis and git
+lookups happen lazily as you move through the list and are cached, so it stays
+responsive in large trees. Git provenance falls back cleanly to filesystem
+mtime when a file is untracked or you're not in a git repo.
+
+## Install
+
+belfry is not on PyPI yet. Install from source:
+
+```bash
+git clone git@github.com:brendanjmeade/belfry.git
+cd belfry
+pip install -e .
+```
+
+Requires Python 3.10+ (the only runtime dependency is `textual`).
+
+## Usage
+
+```bash
+belfry [PATH] [--no-recurse]
+```
+
+- `PATH` — directory to scan (defaults to the current directory).
+- `--no-recurse` — only scan the top level instead of descending into subdirectories.
+
+You can also run it as a module: `python -m belfry`.
+
+## Key bindings
+
+| Key | Action |
+| --- | --- |
+| `j` / `k`, arrows | navigate the file list (or scroll the details when the lower pane is focused) |
+| `J` / `K` | jump focus to the lower / upper pane |
+| `h` / `l` | switch tabs in the lower pane (Summary / Source) |
+| `/` | filter files by name |
+| `r` | toggle recursion / rescan |
+| `enter` | open the selected file in `$EDITOR` |
+| `q` | quit |
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+The static analyzer (`src/belfry/analyzer.py`) is covered by a focused test
+suite with fixtures for each pattern it handles.
+
+## License
+
+Not yet licensed — a license will be added before the first release.

belfry-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "belfry"
+version = "0.1.0"
+description = "A Textual TUI for rediscovering what your Python scripts do — their arguments, inputs, and outputs"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Brendan Meade", email = "brendanjmeade@gmail.com" }]
+keywords = ["tui", "textual", "scripts", "static-analysis", "ast", "developer-tools", "cli"]
+dependencies = ["textual>=0.60"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development",
+    "Topic :: Utilities",
+]
+
+[project.optional-dependencies]
+dev = ["pytest"]
+
+[project.urls]
+Homepage = "https://github.com/brendanjmeade/belfry"
+Repository = "https://github.com/brendanjmeade/belfry"
+Issues = "https://github.com/brendanjmeade/belfry/issues"
+
+[project.scripts]
+belfry = "belfry.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

belfry-0.1.0/setup.cfg

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

belfry-0.1.0/src/belfry/__init__.py

@@ -0,0 +1,3 @@
+"""belfry -- Ring a Bell: a Textual TUI for rediscovering what your Python scripts do."""
+
+__version__ = "0.1.0"

belfry-0.1.0/src/belfry/__main__.py

@@ -0,0 +1,4 @@
+"""Enable ``python -m belfry``."""
+from belfry.cli import main
+
+raise SystemExit(main())