dvd-rw
Speed-optimized request recording and replaying for HTTPX.
dvd-rw aims to provide a vcrpy-like workflow with a focus on high scalability: efficient lookups and minimal overhead when recording/replaying thousands of requests. Core components use Pydantic v2 models for structured data and JSON serialization. A keyed index enables O(1)-ish replay lookups.
Quickstart
from dvd_rw.loader import DVDLoader
from dvd_rw.models import Matcher
with DVDLoader(
file_path="/tmp/example.dvd.json",
match_on=[Matcher.host, Matcher.method, Matcher.path, Matcher.query],
extra_matchers=[],
) as dvd:
# If the file did not exist yet, dvd.from_file will be False (recording allowed)
# On later runs when the file exists, dvd.from_file will be True (replay only)
# Do some requests here
...
Why dvd-rw?
If your use-case fits the request-replay features of the vcr(py), library, but you need faster performance, dvd-rw provides:
- Fast lookups for requestsvia a keyed index; only a small bucket is scanned per request
- Built in matchers (host, query, ...) are provided in a performance-optimized manner
- DVD loading is optimized for speed by leveraging Pydantic where possible
Next Steps
The current version has minimal functionality: only HTTPX support, no cassette modes, etc...
The next versions are focused on improving the experience for my primary use case, testing:
- PyTest integration (through a fixture and mark) to save DVDs for given test(s), allowing you to run against a real
server once, and store the results for the next test run
- A PyTest hook to only save the dvd in case of a successful test
- Filtering which requests/request parts to store (functionality similar to before record request/response in vcrpy)
Long-term, I want to keep performance as a main goal:
- Reduce dvd file size when saved through compression, if this is possible in a performant manner
- Move file IO into rust
Feel free to open an issue for functionality that would make this library better
Installation
Using uv (preferred):
uv pip install -e . --group dev
Notes:
- -e installs in editable mode for local development.
- --group dev will include pytest for running the test suite.
Using pip (alternative):
python -m venv .venv && source .venv/bin/activate
python -m pip install -e .
python -m pip install pytest
Functionality
DVDLoader only saves on successful exit when changes were made (tracked via dvd.dirty). If the DVD was loaded from file (from_file=True), calling dvd.record_request (i.e., encountering an unsaved request) raises CannotRecord to prevent accidental writes.
Exception semantics: when recording, if an httpx request raises, the patcher records the exception class and message. On replay, the same exception type is reconstructed and raised (falling back to httpx.RequestError if constructor signatures don’t match exactly). This is powered by RequestExceptionInfo in dvd_rw.models.
Matching and performance
- Builtin matchers are both hashed (for indexing) and compared (for equality) using these features: host, method, path, query, headers, scheme.
- You can customize match_on to include only what you need; e.g., not matching on host
- extra_matchers is a list of callables taking (recorded_request, incoming_request) and returning bool, applied after the hash bucket filter. Use this to build your own matching logic not supported by the base matcher(s)
- For high throughput:
- Use match on over extra matchers as much as possible. Generally, the more matchers you have, the faster request lookup can run.
Response selection semantics
DVD.get_response(request) returns the first matching response whose per-index _match_counts < 1, then increments. Each recorded pair is therefore returned at most once by default. If you need cycling or multiple uses, adapt the logic or build a higher-level helper.
Running tests
pytest -q
Metadata
Release files for dvd-rw 0.1.6
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| dvd_rw-0.1.6.tar.gz | 8.3 kB | Without provenance | Details for dvd_rw-0.1.6.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| dvd_rw-0.1.6-py3-none-any.whl | Python 3 | none | any | Details for dvd_rw-0.1.6-py3-none-any.whl |
Total release size: 17.8 kB
Release files / dvd_rw-0.1.6.tar.gz
| Download URL | dvd_rw-0.1.6.tar.gz |
|---|---|
| Size | 8.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a4d5c62bf435d7842019a942eff8d33cdbaec5c48835c665262beffae77172e4
|
|
BLAKE2b-256 checksum How to use checksums |
146e8c88d860a66cdca122ccfcbd524467d21f450043166b6f423b73ba8336fa
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.8.15
|
Release files / dvd_rw-0.1.6-py3-none-any.whl
| Download URL | dvd_rw-0.1.6-py3-none-any.whl |
|---|---|
| Size | 9.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
958c9a739c6b2cb4371c23ce9c3fe6a395336f1d47888ad9ed54a1a7d377fd44
|
|
BLAKE2b-256 checksum How to use checksums |
356a21239f31b90da2ea532bab2ee699533eb0c21b5e9a6bfdb9fa13856fc45a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.8.15
|
Security for dvd-rw 0.1.6
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.