http-timer 0.3.0
A minimal, zero-dependency library for timing HTTP requests
Requires Python: >=3.10
Keywords: debugging, http, profiling, requests, timer, timing

# 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")
```

## CLI

```bash
# Basic usage
http-timer https://api.example.com

# POST with JSON
http-timer -X POST -j '{"name": "test"}' https://api.example.com

# With custom headers
http-timer -H "Authorization: Bearer token" https://api.example.com

# Quiet mode (one-liner output)
http-timer -q https://api.example.com
# Output: total=245.3ms | dns=12.1ms | connect=45.2ms | tls=89.4ms | transfer=98.6ms | status=200 | size=1234B

# Show response headers
http-timer --verbose https://api.example.com
```

### CLI options

| Option | Description |
|--------|-------------|
| `-X, --method` | HTTP method (GET, POST, PUT, DELETE) |
| `-d, --data` | Request body data |
| `-j, --json` | JSON request body |
| `-H, --header` | Request header (repeatable) |
| `-t, --timeout` | Timeout in seconds (default: 30) |
| `-q, --quiet` | One-liner output |
| `--verbose` | Show response headers |
| `--no-color` | Disable colors |
| `-v, --version` | Show version |

## Limitations

Current version (v0.3.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
- DNS resolution time
- TCP connection time
- TLS handshake time
- Transfer time

### v0.3.0 — CLI (current)
- Command-line interface
- Colored output
- Quiet mode for scripting

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

## License

MIT