Metadata-Version: 2.4
Name: belfry
Version: 0.1.2
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

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)

We all have folders full of `.py` files accumulated over months. Sometimes we've created these and in modern times coding agents often do.  These often include some combination of   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.

## 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

```bash
```
pip install belfry
```

```
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.
