Metadata-Version: 2.4
Name: timetap
Version: 0.1.0
Summary: A lightweight, thread-safe Python profiler for hierarchical code timing with GPU support
Author: Johan Olsson
License-Expression: MIT
License-File: LICENSE
Requires-Dist: torch>=2.1.0 ; extra == 'torch'
Requires-Python: >=3.8
Project-URL: Homepage, https://github.com/JohanOlsson99/TimeTap
Project-URL: Issues, https://github.com/JohanOlsson99/TimeTap/issues
Provides-Extra: torch
Description-Content-Type: text/markdown

# TimeTap

A lightweight, thread-safe Python profiler for hierarchical code timing — with optional GPU support.

- Hierarchical timings: nest blocks, functions, and lines.
- Two ways to use: decorator or with context manager.
- Thread-safe: collect timings across threads.
- Optional GPU support to measure PyTorch CUDA sections (install extra).
- Easy reporting: print or get a formatted string; reset anytime.

## Installation

```
# CPU-only
pip install timetap

# With GPU helpers (PyTorch >= 2.1)
pip install "timetap[torch]"
```

## Quick start

```
import time
import TimeTap  # package exposes timing utilities


@TimeTap.timeTap_log(name="compute-sum")
def compute_sum(n=1_000_000):
    total = 0
    for i in range(n):
        total += i
    return total


with TimeTap.timeTap_log("session"):
    compute_sum()
    time.sleep(0.1)
    compute_sum()


# Or print directly
TimeTap.timeTap_print()

# Reset collected metrics
TimeTap.timeTap_reset()

with TimeTap.timeTap_log("session-2"):
    compute_sum()

    # You can temporarily disable collection any time
    TimeTap.disable_timeTap()
    time.sleep(0.1)
    compute_sum()

    # And re-enable all again
    TimeTap.enable_timeTap()
    time.sleep(0.1)
    compute_sum()

TimeTap.timeTap_print()
```

#### Output:
```
-----------------------------------------------------------------------------------------------
Function                 Runs    Total(ms)   Median(ms)      Avg(ms)      Min(ms)      Max(ms)
-----------------------------------------------------------------------------------------------
session                    1        132.6        132.6        132.6        132.6        132.6
└─compute-sum              2         32.4         16.2         16.2         16.2         16.2

WARNING:root:Disabling TimeTap timing measurements globally.
-----------------------------------------------------------------------------------------------
Function                 Runs    Total(ms)   Median(ms)      Avg(ms)      Min(ms)      Max(ms)
-----------------------------------------------------------------------------------------------
session-2                  1        250.9        250.9        250.9        250.9        250.9
└─compute-sum              2         33.7         16.8         16.8         16.7         17.0
```

## Nested & GPU timing

```
import time
import TimeTap

# Nested sections automatically appear as a hierarchy in the report
with TimeTap.timeTap_log("pipeline"):
    with TimeTap.timeTap_log("stage-1"):
        with TimeTap.timeTap_log("stage-2"):
            with TimeTap.timeTap_log("stage-3"):
                time.sleep(0.1)
            time.sleep(0.1)
        time.sleep(0.05)

    # If installed with timetap[torch], set gpu=True to time CUDA work
    with TimeTap.timeTap_log("forward-pass", gpu=True):
        time.sleep(0.02)

TimeTap.timeTap_print()
```
> Tip: When gpu=True and PyTorch is available, TimeTap accounts for CUDA work so your timings include GPU kernels.

#### Output:
```
-----------------------------------------------------------------------------------------------
Function                 Runs    Total(ms)   Median(ms)      Avg(ms)      Min(ms)      Max(ms)
-----------------------------------------------------------------------------------------------
pipeline                   1        270.6        270.6        270.6        270.6        270.6
├─stage-1                  1        250.4        250.4        250.4        250.4        250.4
├───stage-2                1        200.2        200.2        200.2        200.2        200.2
├─────stage-3              1        100.1        100.1        100.1        100.1        100.1
└─forward-pass             1         20.1         20.1         20.1         20.1         20.1
```

## API

All functions are available off the TimeTap package:

- timeTap_log(name: str, enable: bool = True, verbose: bool = False, gpu: bool = False)
    - Decorator or context manager for timing.
    - As a decorator: @TimeTap.timeTap_log(name="...")
    - As a context manager: with TimeTap.timeTap_log("..."): ...

- timeTap_get_str() -> str
Get a formatted, hierarchical summary of collected timings.

- timeTap_print() -> None
Print the current summary to stdout.

- timeTap_reset() -> None
Clear all collected metrics.

- disable_timeTap() / enable_timeTap()
Globally toggle collection (no-op when disabled).

## Project metadata
```
[project]
name = "TimeTap"
version = "0.1.0"
description = "A lightweight, thread-safe Python profiler for hierarchical code timing with GPU support"
readme = "README.md"
requires-python = ">=3.8"
dependencies = []

[project.optional-dependencies]
torch = ["torch>=2.1.0"]
```