# touch

Rich-powered terminal “micro-debugger” for Python.

- Inspect values with pretty, readable output.
- Peek the source of functions/classes with highlighted snippets.
- Wrap functions so every call prints a compact, useful trace.
- Hot-edit functions in your editor and swap them in at runtime.
- Open a scratch file, write code, inject it straight into your scope.

All from a tiny toolkit that plays nicely with your console.

## Install

```bash
pip install hyv-touch
```

Python 3.9+ recommended.

## TL;DR

```python
from touch import touch, embrace


# Wrap functions for pretty call/return/exception panels:
orig = embrace(globals())         # wraps everything in this scope



# Start an interactive loop over your current environment:
# Usually you want this at the point you want to inspect. Ex. at a `except` block.
touch(globals(), locals())

# If you used embrace() once touch is done 
release(globals(), orig)          # restore originals


# ------------- [ Inside the touch REPL ] ------------- #

# Pretty value inspection:
feel({"a": 1, "b": [2, 3, 4]})
feel(some_object) # Specially useful in objects, functions and Exceptions

# Show source snippet 
source(some_function) 


# Live-edit a function in VS Code 
edit(some_function) # by default has `touch's` scope, or pass `scope=globals()` 

# Open a temp file in VS Code, write new helpers, inject into scope:
retouch()

# If changes we're made to main file or it's dependencies, you can reload with:
# This will add any new symbols to the current scope, but will not overwrite existing ones.
tickle()

var_name # will show var_name's value 
function() # will call function() 

$exec a = (1, 2, 3)  # run statements with $exec prefix or use retouch() for more complex actions
```

## Why use this

You want quick, legible debugging without committing to a full debugger session. `touch` gives you:

- **Readable output** (Rich panels, tables, syntax highlighting)
- **Low friction** (one-liners, minimal API)
- **Reversibility** (wrappers can be released, edits are temporary)
- **Hot-editing** (Test and tweak without restarting or losing state)
- **Versatility** (All language and state available at all times)


## Editor integration

- **VS Code**: requires the `code` CLI on PATH. In VS Code, run “Shell Command: Install ‘code’ command” from the Command Palette.
- **Other editors**: set `$EDITOR` to your editor’s CLI. `edit()` and `retouch()` will use it when VS Code isn’t available.

## Examples
run `python -m touch.demo [--demo | --interactive]` to see a demo script showcasing `touch` features.


## Limits and notes

- Builtins and C-extensions don’t have Python source to show or edit.
- Editing nested closures can lose captured locals if you move them; keep edited functions top-level or use in-place file editing.
- The temporary trace hook used for line breakpoints is restored after each call and won’t clobber other tracers.
- Executing code you type or edit runs in your process. Don’t paste untrusted code.


## License

MIT
