Miscellaneous APIs¶

Frame Inspection¶

Data emitted from zstd compression is encapsulated in a frame. This frame begins with a 4 byte magic number header followed by 2 to 14 bytes describing the frame in more detail. For more info, see https://github.com/facebook/zstd/blob/master/doc/zstd_compression_format.md.

zstandard.get_frame_parameters(data)¶

Parse a zstd frame header into frame parameters.

Depending on which fields are present in the frame and their values, the length of the frame parameters varies. If insufficient bytes are passed in to fully parse the frame parameters, ZstdError is raised. To ensure frame parameters can be parsed, pass in at least 18 bytes.

Parameters:	data – Data from which to read frame parameters.
Returns:	`FrameParameters`

zstandard.frame_header_size(data)¶

Obtain the size of a frame header.

Returns:	Integer size in bytes.

zstandard.frame_content_size(data)¶

Obtain the decompressed size of a frame.

The returned value is usually accurate. But strictly speaking it should not be trusted.

Returns:	`-1` if size unknown and a non-negative integer otherwise.

class zstandard.FrameParameters(fparams)¶

Information about a zstd frame.

Instances have the following attributes:

content_size: Integer size of original, uncompressed content. This will be 0 if the original content size isn’t written to the frame (controlled with the write_content_size argument to ZstdCompressor) or if the input content size was 0.
window_size: Integer size of maximum back-reference distance in compressed data.
dict_id: Integer of dictionary ID used for compression. 0 if no dictionary ID was used or if the dictionary ID was 0.
has_checksum: Bool indicating whether a 4 byte content checksum is stored at the end of the frame.

`estimate_decompression_context_size()`¶

zstandard.estimate_decompression_context_size()¶

Estimate the memory size requirements for a decompressor instance.

Returns:	Integer number of bytes.

`open()`¶

zstandard.open(filename, mode='rb', cctx=None, dctx=None, encoding=None, errors=None, newline=None, closefd=None)¶

Create a file object with zstd (de)compression.

The object returned from this function will be a ZstdDecompressionReader if opened for reading in binary mode, a ZstdCompressionWriter if opened for writing in binary mode, or an io.TextIOWrapper if opened for reading or writing in text mode.

Parameters:

filename – bytes, str, or os.PathLike defining a file to open or a file object (with a read() or write() method).
mode – str File open mode. Accepts any of the open modes recognized by open().
cctx – ZstdCompressor to use for compression. If not specified and file is opened for writing, the default ZstdCompressor will be used.
dctx – ZstdDecompressor to use for decompression. If not specified and file is opened for reading, the default ZstdDecompressor will be used.
encoding – str that defines text encoding to use when file is opened in text mode.
errors – str defining text encoding error handling mode.
newline – str defining newline to use in text mode.
closefd –

bool whether to close the file when the returned object is closed.

Only used if a file object is passed. If a filename is specified, the opened file is always closed when the returned object is closed.

`compress()`¶

zstandard.compress(data: ByteString, level: int = 3) → bytes¶

Compress source data using the zstd compression format.

This performs one-shot compression using basic/default compression settings.

This method is provided for convenience and is equivalent to calling ZstdCompressor(level=level).compress(data).

If you find yourself calling this function in a tight loop, performance will be greater if you construct a single ZstdCompressor and repeatedly call compress() on it.

`decompress()`¶

zstandard.decompress(data: ByteString, max_output_size: int = 0) → bytes¶

Decompress a zstd frame into its original data.

This performs one-shot decompression using basic/default compression settings.

This method is provided for convenience and is equivalent to calling ZstdDecompressor().decompress(data, max_output_size=max_output_size).

If you find yourself calling this function in a tight loop, performance will be greater if you construct a single ZstdDecompressor and repeatedly call decompress() on it.

Constants¶

The following module constants/attributes are exposed:

ZSTD_VERSION

This module attribute exposes a 3-tuple of the Zstandard version. e.g. (1, 0, 0)

MAX_COMPRESSION_LEVEL

Integer max compression level accepted by compression functions

COMPRESSION_RECOMMENDED_INPUT_SIZE

Recommended chunk size to feed to compressor functions

COMPRESSION_RECOMMENDED_OUTPUT_SIZE

Recommended chunk size for compression output

DECOMPRESSION_RECOMMENDED_INPUT_SIZE

Recommended chunk size to feed into decompresor functions

DECOMPRESSION_RECOMMENDED_OUTPUT_SIZE

Recommended chunk size for decompression output

FRAME_HEADER

bytes containing header of the Zstandard frame

MAGIC_NUMBER

Frame header as an integer

FLUSH_BLOCK

Flushing behavior that denotes to flush a zstd block. A decompressor will be able to decode all data fed into the compressor so far.

FLUSH_FRAME

Flushing behavior that denotes to end a zstd frame. Any new data fed to the compressor will start a new frame.

CONTENTSIZE_UNKNOWN

Value for content size when the content size is unknown.

CONTENTSIZE_ERROR

Value for content size when content size couldn’t be determined.

WINDOWLOG_MIN