http-range-kit

Tiny utilities for parsing HTTP Range headers and formatting Content-Range values.

http-range-kit is a small Python library for applications that need to support partial content responses (206 Partial Content) without pulling in a full web framework helper.

Why

If you build:

• file download endpoints,
• media streaming APIs,
• proxy/middleware layers,
• storage adapters,
• custom ASGI/WSGI handlers,

...you often need two boring but error-prone pieces of logic:

1. parse Range: bytes=...
2. resolve the requested ranges against a known resource size

This package keeps that logic tiny, explicit, and framework-agnostic.

Features

• Parse bytes range headers
• Support closed ranges (0-99)
• Support open-ended ranges (500-)
• Support suffix ranges (-500)
• Resolve ranges against a resource size
• Build Content-Range header values
• No runtime dependencies

Installation

pip install http-range-kit

Quick start

from http_range_kit import resolve_byte_ranges

ranges = resolve_byte_ranges("bytes=100-199, -20", size=1000)

for item in ranges:
    print(item.start, item.end, item.length, item.content_range)

# 100 199 100 bytes 100-199/1000
# 980 999 20 bytes 980-999/1000

API

parse_range_header(value: str) -> list[ByteRangeSpec]

Parses the raw HTTP Range header value.

from http_range_kit import parse_range_header

specs = parse_range_header("bytes=0-99, 200-, -50")

Returned ByteRangeSpec values:

• start: inclusive start offset, or None
• end: inclusive end offset, or None
• suffix_length: set for suffix ranges like bytes=-50

resolve_byte_ranges(value: str, size: int) -> list[ResolvedByteRange]

Resolves the header against a known resource size.

• clamps ranges to the resource size when appropriate
• skips individual unsatisfiable members
• raises UnsatisfiableRange if nothing can be served

from http_range_kit import resolve_byte_ranges

resolved = resolve_byte_ranges("bytes=900-1200", size=1000)
print(resolved[0].start, resolved[0].end)
# 900 999

build_content_range(start: int, end: int, size: int) -> str

Builds a valid Content-Range header value.

from http_range_kit import build_content_range

header_value = build_content_range(0, 99, 1000)
# bytes 0-99/1000

Design notes

Supported scope

This library intentionally supports a focused MVP:

• only the bytes range unit
• parsing and resolution helpers
• no multipart/byteranges response body generation
• no direct framework integration

Unsatisfiable members

For multi-range inputs, individual ranges that cannot be satisfied are skipped if at least one valid range remains.

Example:

resolve_byte_ranges("bytes=999-1200, 5000-6000, -10", size=1000)

This resolves to the satisfiable parts only.

Development

python -m pip install -e . pytest
pytest

CI

GitHub Actions runs tests on Python 3.9-3.13.

License

MIT