Metadata-Version: 2.4
Name: vspdb
Version: 0.1.0
Summary: Run a Python script under the VS Code debugger from the terminal, halting on the first line.
Author-email: Kaustubh <kmhatre14@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/kmhatre14/vspdb
Project-URL: Repository, https://github.com/kmhatre14/vspdb
Project-URL: Issues, https://github.com/kmhatre14/vspdb/issues
Keywords: debugpy,vscode,debugger,pdb,debugging,cli,stopOnEntry
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Debuggers
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: debugpy>=1.6
Dynamic: license-file

# vspdb — VS Code pdb for the terminal

Debug any Python script (with arguments) in the VS Code debugger straight from
the terminal — no hand-written `launch.json`, no `debug.py` wrapper.

```bash
python -m vspdb my_script.py arg1 arg2
```

vspdb starts a `debugpy` debug server, gets VS Code to attach, and **halts on the
first line of your script** — just like `stopOnEntry`. It ships a small VS Code
helper (installed automatically) so this works with **zero clicks**.

---

## Install — one package, that's it

```bash
pip install vspdb            # (or: pip install -e .  from this folder)
```

That's the only thing you install. vspdb ships a tiny VS Code helper extension
**inside** the package and installs it into VS Code for you on first use. So:

```bash
python -m vspdb my_script.py 10      # explicit  (or: vspdb my_script.py 10)
```

The **first** run prints a one-time note that it installed the helper — **reload
the VS Code window once** (`Ctrl+Shift+P` → "Developer: Reload Window"). After
that it's fully automatic.

> Tip: install into the same interpreter VS Code uses for the workspace
> (`Ctrl+Shift+P` → "Python: Select Interpreter") so breakpoints line up. You can
> also pre-install the helper without running a script: `python -m vspdb --setup`.

---

## How you use it: zero clicks

Once the helper is active (after that one reload), just run scripts — each one
attaches and halts on its first line, **no debug panel, no F5**:

```bash
python -m vspdb my_script.py 10
python -m vspdb another.py --flag
```

The helper keeps a `debugpy` listener ready in VS Code (one per window, on a
per-project port) and vspdb connects to the right window automatically.

### Don't want the helper? (no-extension fallback)

Run with `--no-ext` (or set `VSPDB_NO_AUTO_EXTENSION=1`). Then vspdb won't touch
VS Code; instead it writes two configs to `.vscode/launch.json` and you attach
manually:

- **vspdb: Listen** — start it once per window (F5), then runs are zero-click.
- **vspdb: Attach** — vspdb waits; press F5 once per run.

---

## Options

```
python -m vspdb [options] <script.py> [script args...]
```

Everything **after** the script name is passed to your script untouched (so your
script can use `--port`, `--host`, etc. without clashing with vspdb).

| Option | Description |
| --- | --- |
| `--port, -p PORT` | Debug port (default: `5678`). |
| `--host HOST` | Debug host/interface (default: `127.0.0.1`). |
| `--listen` | Force listen mode (open the port, wait for VS Code). |
| `--connect` | Force connect mode (attach to a VS Code that is already listening). |
| `--no-wait` | Don't wait for VS Code; run immediately (disables stop-on-entry). |
| `--no-stop` | Attach, but don't halt on the first line. |
| `--no-launch-json` | Don't create/update `.vscode/launch.json`. |
| `--setup` | (Re)install the bundled VS Code helper extension and exit. |
| `--no-ext` | Don't auto-install the VS Code helper on this run. |

The `--port` default is read from `.vscode/vspdb.json` (written by the helper) if
present, else `5678`. Disable auto-install globally with `VSPDB_NO_AUTO_EXTENSION=1`.

Examples:

```bash
# Different port
python -m vspdb --port 5690 my_script.py 10

# Your script gets its own --port; vspdb does not consume it
python -m vspdb server.py --port 8080 --debug

# Run under the debugger but don't stop on entry (rely on your own breakpoints)
python -m vspdb --no-stop my_script.py 10
```

---

## How it works

1. Parses `vspdb` options, then treats the first positional as the script and the
   rest as the script's `argv`.
2. Installs the bundled VS Code helper into VS Code if it isn't there yet (unless
   `--no-ext`), and ensures `.vscode/launch.json` has the manual-fallback attach
   configs (merging, never clobbering, any existing file).
3. Resolves the port: if `--port` isn't given, it walks up from the script's
   directory for `.vscode/vspdb.json` (written by the auto-listen extension) so it
   attaches to the window that owns the script's project — important when several
   VS Code windows are open. Then it **connects** if that port is being listened
   on, otherwise **listens** and waits for VS Code.
4. Once the client is attached, it runs your script as `__main__` with the right
   `sys.argv`, having injected a `debugpy.breakpoint()` at the first executable
   line so the debugger halts there. Original line numbers are preserved, so
   tracebacks stay accurate.

---

## Requirements

- Python 3.8+
- `debugpy` (installed automatically)
- VS Code with the Python / Python Debugger extension

## Author

Kaustubh — [kmhatre14@gmail.com](mailto:kmhatre14@gmail.com) · [github.com/kmhatre14](https://github.com/kmhatre14)

## License

[MIT](LICENSE). Built with assistance from Claude Opus 4.8.
