Implementation Details

Everything here is an implementation detail and subject to volatile change. I would not rely on anything here for any mission critical code.

Gzip Content-Encoding

By default, requests sets an Accept-Encoding header value that includes gzip (specifically, unless overridden, requests always sends Accept-Encoding: gzip, deflate, compress). When a server supports this and responds with a response that has the Content-Encoding header set to gzip, urllib3 automatically decompresses the body for requests. This can only be prevented in the case where the stream parameter is set to True. Since Betamax refuses to alter the headers on the response object in any way, we force stream to be True so we can capture the compressed data before it is decompressed. We then properly repopulate the response object so you perceive no difference in the interaction.

To preserve the response exactly as is, we then must base64 encode the body of the response before saving it to the file object. In other words, whenever a server responds with a compressed body, you will not have a human readable response body. There is, at the present moment, no way to configure this so that this does not happen and because of the way that Betamax works, you can not remove the Content-Encoding header to prevent this from happening.

Class Details

class betamax.cassette.Cassette(cassette_name, serialization_format, **kwargs)
cassette_name = None

Short name of the cassette


The earliest date of all of the interactions this cassette.


Find a matching interaction based on the matchers and request.

This uses all of the matchers selected via configuration or use_cassette and passes in the request currently in progress.


Determine if the cassette was empty when loaded.


Return whether the cassette is recording.

class betamax.cassette.Interaction(interaction, response=None)

The Interaction object represents the entirety of a single interaction.

The interaction includes the date it was recorded, its JSON representation, and the requests.Response object complete with its request attribute.

This object also handles the filtering of sensitive data.

No methods or attributes on this object are considered public or part of the public API. As such they are entirely considered implementation details and subject to change. Using or relying on them is not wise or advised.


Return the Interaction as a Response object.


Turn a serialized interaction into a Response.


Ignore this interaction.

This is only to be used from a before_record or a before_playback callback.


Return whether this interaction is a match.

replace(text_to_replace, placeholder)

Replace sensitive data in this interaction.

replace_all(replacements, serializing)

Easy way to accept all placeholders registered.