Metadata-Version: 2.4
Name: http-timer
Version: 0.2.0
Summary: A minimal, zero-dependency library for timing HTTP requests
Project-URL: Homepage, https://github.com/nilerbarcelos/http-timer
Project-URL: Repository, https://github.com/nilerbarcelos/http-timer
Author: Niler Barcelos
License-Expression: MIT
License-File: LICENSE
Keywords: debugging,http,profiling,requests,timer,timing
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# http-timer

A minimal, zero-dependency Python library for timing HTTP requests.

## Why?

Measuring HTTP request timing in Python is more complicated than it should be:

| Library | Issue |
|---------|-------|
| **requests** | No native timing metrics |
| **httpx** | Requires verbose event hooks |
| **aiohttp** | Async-only, requires boilerplate |
| **curl** | External tool, not Pythonic |

**http-timer** is designed to be:
- Zero dependencies (uses only stdlib)
- Minimal API
- Human-readable output
- Perfect for debugging and profiling

## Installation

```bash
pip install http-timer
```

## Usage

```python
from http_timer import timed_get

body, timing = timed_get("https://api.example.com/users")

print(f"Status: {timing.status}")
print(f"Time: {timing.total_ms:.2f}ms")
print(f"Size: {timing.size_bytes} bytes")
```

### POST with JSON

```python
from http_timer import timed_post

body, timing = timed_post(
    "https://api.example.com/users",
    json={"name": "Ana", "email": "ana@example.com"}
)

print(f"Created in {timing.total_ms:.2f}ms")
```

### Custom headers

```python
body, timing = timed_get(
    "https://api.example.com/users",
    headers={"Authorization": "Bearer token123"}
)
```

## Available functions

| Function | Description |
|----------|-------------|
| `timed_get(url, headers=None, timeout=30)` | GET request |
| `timed_post(url, headers=None, json=None, data=None, timeout=30)` | POST request |
| `timed_put(url, headers=None, json=None, data=None, timeout=30)` | PUT request |
| `timed_delete(url, headers=None, timeout=30)` | DELETE request |

## TimingResult

All functions return a tuple `(body, timing)` where `timing` is a `TimingResult`:

| Attribute | Type | Description |
|-----------|------|-------------|
| `total_ms` | float | Total request time in milliseconds |
| `dns_ms` | float | DNS resolution time |
| `connect_ms` | float | TCP connection time |
| `tls_ms` | float | TLS handshake time (HTTPS only) |
| `transfer_ms` | float | Response transfer time |
| `status` | int | HTTP status code |
| `size_bytes` | int | Response body size |
| `headers` | dict | Response headers |

### Detailed timing example

```python
from http_timer import timed_get

body, timing = timed_get("https://api.example.com")

print(f"DNS:      {timing.dns_ms:.1f}ms")
print(f"Connect:  {timing.connect_ms:.1f}ms")
print(f"TLS:      {timing.tls_ms:.1f}ms")
print(f"Transfer: {timing.transfer_ms:.1f}ms")
print(f"Total:    {timing.total_ms:.1f}ms")

# Or use the string representation
print(timing)
# Output: total=245.3ms | dns=12.1ms | connect=45.2ms | tls=89.4ms | transfer=98.6ms | status=200 | size=1234B
```

## Comparison with alternatives

```python
# With requests (no timing)
import requests
import time

start = time.time()
r = requests.get("https://api.example.com")
elapsed = (time.time() - start) * 1000
print(f"{elapsed:.2f}ms")

# With http-timer (simple!)
from http_timer import timed_get

body, timing = timed_get("https://api.example.com")
print(f"{timing.total_ms:.2f}ms")
```

## Limitations

Current version (v0.2.0) does **not** support:

- Async requests
- Session/connection pooling

These features are planned for future releases.

## Development

```bash
# Clone the repository
git clone https://github.com/nilerbarcelos/http-timer.git
cd http-timer

# Install dev dependencies
pip install hatch

# Run tests
hatch run test:run
```

## Roadmap

### v0.1.0 — MVP
- timed_get / timed_post / timed_put / timed_delete
- Total time measurement
- Response size and headers

### v0.2.0 — Detailed timing (current)
- DNS resolution time
- TCP connection time
- TLS handshake time
- Transfer time

### v0.3.0 — CLI
```bash
http-timer https://api.example.com/endpoint
```

### v0.4.0 — Async support
- httpx/aiohttp integration

## License

MIT
