http-timer 0.3.0

A minimal, zero-dependency library for timing HTTP requests

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

pip install http-timer

Usage

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

from http_timer import timed_post

body, timing = timed_post(
    "https://api.example.com/users",
    json={"name": "Ana", "email": "[e-mail]"}
)

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

Custom headers

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

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

# 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

# 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

# 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