Metadata-Version: 2.4
Name: methodtracer
Version: 0.1.1
Summary: Zero-dependency tracer for function calls inside your own project.
Author: Chaitanya Varma Rudraraju
License-Expression: MIT
Project-URL: Homepage, https://github.com/RUDRARAJUCHAITANYAVARMA/methodtracer
Project-URL: Issues, https://github.com/RUDRARAJUCHAITANYAVARMA/methodtracer/issues
Keywords: tracing,debugging,settrace,call-tree
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Software Development :: Debuggers
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# methodtracer

A tiny, zero-dependency helper for tracing the function calls that happen
**inside your own project** while it runs. Standard-library and third-party
frames are ignored, so you only see your code.

It ships two modes:

| Mode | Entry point | What it does |
| --- | --- | --- |
| **Interactive** | `tracer.start()` | Pauses on every function call and drops you into a prompt where you can inspect arguments and the caller, step forward, or quit. Similar in spirit to `pdb` / `ipdb`. |
| **Tree** | `tracer.tree()` | Runs silently and writes an indented call/return tree of your project's execution to `method_tracer_log.txt`. |

---

## Requirements

- Python **3.9+**
- CPython; tree mode uses `sys.monitoring` on Python **3.12+** and falls back
  to `sys.settrace` on older versions
- Locally tested on Python **3.11**; the Python 3.12+ monitoring path requires
  validation on a Python 3.12+ interpreter
- No external dependencies

---

## Installation

Once published to PyPI:

```bash
pip install methodtracer
```

From source:

```bash
git clone https://github.com/RUDRARAJUCHAITANYAVARMA/methodtracer.git
cd methodtracer
pip install .
```

Or just drop `methodtracer.py` next to your code.

---

## Quick start

```python
from methodtracer import tracer

tracer.tree()          # or tracer.start() for interactive mode
run_the_code_you_want_to_inspect()
tracer.stop()
```

`tracer` is a ready-to-use shared instance created at import time. You normally
do not need to construct `Tracer` yourself.

> **Important:** the *project root* is the current working directory at the
> moment `methodtracer` is imported. Only files located under that directory are
> traced, and paths under `site-packages` are excluded. Import `methodtracer`
> from your project root.

---

## Interactive mode

```python
from methodtracer import tracer

def compute(a, b):
    return add(a, b)

tracer.start()
print(compute(2, 3))
tracer.stop()
```

Execution stops on each call to one of your functions and shows a prompt:

```
> [Function Call] - compute
>
```

### Prompt commands

| Command | Action |
| --- | --- |
| `n` | Resume until the next function call. |
| `<function_name>.args` | Print the local variables (arguments) of the current call. |
| `<function_name>.from` | Print the caller's function name, file and line number. |
| `exit()` | Terminate the whole process. |

`<function_name>` is the name shown in the most recent `[Function Call]` line,
e.g. `compute.args` or `compute.from`. Input is case-insensitive. Any
unrecognised input simply redisplays the prompt.

---

## Tree mode

```python
from methodtracer import tracer

tracer.tree()
compute(2, 3)
tracer.stop()
```

`tracer.tree()` truncates any existing `method_tracer_log.txt` in the project
root, then records every `call` and `return` event for your project's frames.
The file is flushed on every event, so the log stays useful even if the process
crashes. Call `tracer.stop()` to flush and close it.

Example `method_tracer_log.txt`:

```
--> [Call] - compute
----> [Call] - add
--> [Return] - add
> [Return] - compute
```

Indentation depth reflects the call-stack depth (`--` per level).

---

## API

| Call | Description |
| --- | --- |
| `tracer.start()` | Install the interactive trace hook. |
| `tracer.tree()` | Truncate `method_tracer_log.txt` and install the tree trace hook. |
| `tracer.stop()` | Remove the trace hook and close the log file. Safe to call anytime. |

---

## How it works & limitations

- Built on `sys.settrace`, so it **conflicts with other tracing tools** running
  at the same time — debuggers (`pdb`), coverage tools, profilers. Only one
  global trace function can be active.
- Tracing adds significant overhead; use it for inspection, not in production or
  performance-sensitive paths.
- Only frames whose source file path starts with `tracer.project_root` are
  followed, so code in a virtualenv or site-packages under the project directory
  will also be traced.
- Interactive mode reads from `stdin` via `input()`; it is meant for a real
  terminal session.
- CPython only. Alternative interpreters may not honour `sys.settrace` the same
  way.

---

## Status

Actively maintained by [Chaitanya Varma Rudraraju](https://github.com/RUDRARAJUCHAITANYAVARMA).
More features are planned. Issues and pull requests are welcome at
<https://github.com/RUDRARAJUCHAITANYAVARMA/methodtracer>.

---

## License

Released under the [MIT License](LICENSE).
