genwatch 0.1.0

Decorator for tracing Python generator internals

Here’s a starter README.md for your genwatch package. Feel free to tweak wording, add badges, or expand the examples as you like.

# genwatch

Lightweight decorator and proxy for tracing Python generator internals  
(`send`, `throw`, `close`, and `yield from` delegation) with structured logs.

---

## Features

- **Decorator** (`@genwatch.Reporter`) to wrap any generator function
- **Automatic forwarding** of `send()`, `throw()`, and `close()` calls
- Logs **enter/exit** of each `yield from` delegation
- Captures **generator attributes** (`gi_code`, `gi_frame`, `gi_running`, `gi_suspended`, `gi_yieldfrom`)
- Handles both **generator** and **iterator** delegates (`range`, lists, etc.)
- Early **TypeError** if decorating a non-generator function

---

## Installation

```bash
pip install genwatch

Or, if you’re installing from source:

git clone https://github.com/yourusername/genwatch.git
cd genwatch
pip install -e .[test]

---

Quickstart

import logging
from genwatch import Reporter

# Create a logger (optional – Reporter will default to a StreamHandler)
logger = logging.getLogger("myapp")
logger.setLevel(logging.DEBUG)
handler = logging.StreamHandler()
handler.setFormatter(logging.Formatter("[%(asctime)s] %(message)s"))
logger.addHandler(handler)

@Reporter(logger=logger)
def countdown(n: int):
    """Yield numbers 0..n-1, then finish."""
    for i in range(n):
        yield i

# Drive the generator
gen = countdown(3)
for x in gen:
    print("Got:", x)
# Logs will show the internal state at each yield.

Delegation example

@Reporter(logger=logger)
def subgen():
    yield "a"
    yield "b"

@Reporter(logger=logger)
def outer():
    # Logs will show entry into `subgen`, its locals, and exit
    yield from subgen()
    yield "done"

for v in outer():
    print(v)

---

API

genwatch.Reporter

Decorator for generator functions. Wraps a function so that:

• Calling the wrapped function returns an iterator that proxies through a _ProxyReporter.
• On each next(), send(), throw(), and close(), logs generator internals.
• Requires Python 3.8+.

@Reporter
def mygen():
    yield 1
    yield 2

Raises TypeError if applied to a non-generator function.

---

Running Tests

Your tests live in the tests/ directory. To install test dependencies and run:

pip install -e .[test]
pytest

You’ll see a suite of passing tests, plus a few xfail demos highlighting current limitations.

---

Contributing

1. Fork the repo
2. Create a feature branch (git checkout -b feature/xyz)
3. Write code, add tests, update docs
4. Open a Pull Request

---

License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.