Metadata-Version: 2.4
Name: magichash
Version: 0.1.0
Summary: Line-level debug hook decorator driven by ### comments.
Project-URL: Homepage, https://github.com/tingqli/magichash
Project-URL: Repository, https://github.com/tingqli/magichash
Author: tingqli
License: MIT
License-File: LICENSE
Keywords: ast,debug,decorator,instrumentation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Debuggers
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# magichash

`magichash` is a tiny debugging decorator that injects print statements at runtime based on `###` markers in your function body — no manual `print` calls needed.

## Install

```bash
pip install magichash
```

For local development:

```bash
pip install -e .
```

## Quick Start

```python
from magichash import register

@register
def foo(x, y):
    z = x + y  ###
    w = z * 2  ### z,w
    return w

foo(2, 3)
# foo.py:3: z: 5
# foo.py:4: 
#     z: 5, 
#     w: 10, 
```

### Marker rules

| Marker | Behaviour |
|---|---|
| `z = x + y  ###` | Auto-print assignment targets (`z`) |
| `z = x + y  ### z,w` | Print the listed expressions (`z`, `w`) |
| `x, y  ###` | On non-assignment lines, print the comma-separated names before `###` |

## Custom mark and callback

Use `register(mark=..., callback=...)` to override the marker string or the print handler:

```python
from magichash import register

def my_print(loc, var_dict):
    print(f"[DEBUG] {loc}: {var_dict}")

@register(mark="#//", callback=my_print)
def bar(x, y):
    z = x * y  #// x,y
    z = x + y  #//
    return z

bar(2, 3)
# [DEBUG] bar.py:3: {'x': 2, 'y': 3}
# [DEBUG] bar.py:4: {'z': 5}
```

## API

### `register(func=None, *, mark="###", callback=do_print)`

Decorator that instruments a function.  Can be used in two ways:

```python
@register                          # default mark=### and built-in printer
@register(mark="#==", callback=fn) # custom mark / callback
```

### `do_print(loc, var_dict)`

The default callback.  Prints coloured `file:line: name: value` output to stdout.

## Build and Publish

```bash
python -m build
python -m twine upload dist/*
```
