Metadata-Version: 2.4
Name: perfclock
Version: 0.1.0
Summary: Tiny, dependency-free library for measuring execution time: stopwatch, context manager, and sync/async decorator.
License-Expression: MIT
License-File: LICENSE
Keywords: benchmark,perf_counter,profiling,stopwatch,timer,timing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.9
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Description-Content-Type: text/markdown

# perfclock

Tiny, dependency-free library for measuring execution time. Built on
`time.perf_counter`, fully typed, works with sync and async code.

## Install

```bash
pip install perfclock
```

## Usage

### Context manager

```python
from perfclock import Timer

with Timer() as t:
    do_work()

print(t.elapsed)   # seconds as a float, e.g. 0.03241
print(t)           # <Timer stopped, elapsed=32.410 ms>
```

### Decorator (sync or async)

```python
from perfclock import timed

@timed
def crunch():
    ...

@timed(label="fetch users", output=logger.info)
async def fetch_users():
    ...

crunch()
# crunch took 1.204 s
```

The report goes to `print` by default; pass any callable taking a string
(e.g. `logger.info`) via `output`.

### Manual stopwatch with laps

```python
t = Timer()
t.start()

step_one();  t.lap()
step_two();  t.lap()

t.stop()
print(t.laps)      # [0.51, 1.72] — seconds per step
print(t.elapsed)   # total; accumulates across start/stop until reset()
```

`elapsed` reads live while the timer is running, and `start()`/`stop()`
can be called repeatedly to accumulate time. `reset()` clears everything.

### Human-readable durations

```python
from perfclock import format_duration

format_duration(0.000004)  # '4.000 µs'
format_duration(2.5)       # '2.500 s'
format_duration(125)       # '2 min 5.0 s'
```

## Development

```bash
pip install -e ".[dev]"
pytest
```

## License

MIT
