Skip to main content

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)

Source distribution for dvd-rw 0.1.6
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)

Table of built distributions (wheels) for dvd-rw 0.1.6
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page