Mercurial > hg
view contrib/python-zstandard/README.rst @ 46192:25d11b24dedf
upgrade: move printing of unused optimizations to UpgradeOperation class
Differential Revision: https://phab.mercurial-scm.org/D9578
author | Pulkit Goyal <7895pulkit@gmail.com> |
---|---|
date | Mon, 14 Dec 2020 13:48:25 +0530 |
parents | de7838053207 |
children |
line wrap: on
line source
================ python-zstandard ================ This project provides Python bindings for interfacing with the `Zstandard <http://www.zstd.net>`_ compression library. A C extension and CFFI interface are provided. The primary goal of the project is to provide a rich interface to the underlying C API through a Pythonic interface while not sacrificing performance. This means exposing most of the features and flexibility of the C API while not sacrificing usability or safety that Python provides. The canonical home for this project lives in a Mercurial repository run by the author. For convenience, that repository is frequently synchronized to https://github.com/indygreg/python-zstandard. | |ci-status| Requirements ============ This extension is designed to run with Python 2.7, 3.5, 3.6, 3.7, and 3.8 on common platforms (Linux, Windows, and OS X). On PyPy (both PyPy2 and PyPy3) we support version 6.0.0 and above. x86 and x86_64 are well-tested on Windows. Only x86_64 is well-tested on Linux and macOS. Installing ========== This package is uploaded to PyPI at https://pypi.python.org/pypi/zstandard. So, to install this package:: $ pip install zstandard Binary wheels are made available for some platforms. If you need to install from a source distribution, all you should need is a working C compiler and the Python development headers/libraries. On many Linux distributions, you can install a ``python-dev`` or ``python-devel`` package to provide these dependencies. Packages are also uploaded to Anaconda Cloud at https://anaconda.org/indygreg/zstandard. See that URL for how to install this package with ``conda``. Performance =========== zstandard is a highly tunable compression algorithm. In its default settings (compression level 3), it will be faster at compression and decompression and will have better compression ratios than zlib on most data sets. When tuned for speed, it approaches lz4's speed and ratios. When tuned for compression ratio, it approaches lzma ratios and compression speed, but decompression speed is much faster. See the official zstandard documentation for more. zstandard and this library support multi-threaded compression. There is a mechanism to compress large inputs using multiple threads. The performance of this library is usually very similar to what the zstandard C API can deliver. Overhead in this library is due to general Python overhead and can't easily be avoided by *any* zstandard Python binding. This library exposes multiple APIs for performing compression and decompression so callers can pick an API suitable for their need. Contrast with the compression modules in Python's standard library (like ``zlib``), which only offer limited mechanisms for performing operations. The API flexibility means consumers can choose to use APIs that facilitate zero copying or minimize Python object creation and garbage collection overhead. This library is capable of single-threaded throughputs well over 1 GB/s. For exact numbers, measure yourself. The source code repository has a ``bench.py`` script that can be used to measure things. API === To interface with Zstandard, simply import the ``zstandard`` module:: import zstandard It is a popular convention to alias the module as a different name for brevity:: import zstandard as zstd This module attempts to import and use either the C extension or CFFI implementation. On Python platforms known to support C extensions (like CPython), it raises an ImportError if the C extension cannot be imported. On Python platforms known to not support C extensions (like PyPy), it only attempts to import the CFFI implementation and raises ImportError if that can't be done. On other platforms, it first tries to import the C extension then falls back to CFFI if that fails and raises ImportError if CFFI fails. To change the module import behavior, a ``PYTHON_ZSTANDARD_IMPORT_POLICY`` environment variable can be set. The following values are accepted: default The behavior described above. cffi_fallback Always try to import the C extension then fall back to CFFI if that fails. cext Only attempt to import the C extension. cffi Only attempt to import the CFFI implementation. In addition, the ``zstandard`` module exports a ``backend`` attribute containing the string name of the backend being used. It will be one of ``cext`` or ``cffi`` (for *C extension* and *cffi*, respectively). The types, functions, and attributes exposed by the ``zstandard`` module are documented in the sections below. .. note:: The documentation in this section makes references to various zstd concepts and functionality. The source repository contains a ``docs/concepts.rst`` file explaining these in more detail. ZstdCompressor -------------- The ``ZstdCompressor`` class provides an interface for performing compression operations. Each instance is essentially a wrapper around a ``ZSTD_CCtx`` from the C API. Each instance is associated with parameters that control compression behavior. These come from the following named arguments (all optional): level Integer compression level. Valid values are between 1 and 22. dict_data Compression dictionary to use. Note: When using dictionary data and ``compress()`` is called multiple times, the ``ZstdCompressionParameters`` derived from an integer compression ``level`` and the first compressed data's size will be reused for all subsequent operations. This may not be desirable if source data size varies significantly. compression_params A ``ZstdCompressionParameters`` instance defining compression settings. write_checksum Whether a 4 byte checksum should be written with the compressed data. Defaults to False. If True, the decompressor can verify that decompressed data matches the original input data. write_content_size Whether the size of the uncompressed data will be written into the header of compressed data. Defaults to True. The data will only be written if the compressor knows the size of the input data. This is often not true for streaming compression. write_dict_id Whether to write the dictionary ID into the compressed data. Defaults to True. The dictionary ID is only written if a dictionary is being used. threads Enables and sets the number of threads to use for multi-threaded compression operations. Defaults to 0, which means to use single-threaded compression. Negative values will resolve to the number of logical CPUs in the system. Read below for more info on multi-threaded compression. This argument only controls thread count for operations that operate on individual pieces of data. APIs that spawn multiple threads for working on multiple pieces of data have their own ``threads`` argument. ``compression_params`` is mutually exclusive with ``level``, ``write_checksum``, ``write_content_size``, ``write_dict_id``, and ``threads``. Unless specified otherwise, assume that no two methods of ``ZstdCompressor`` instances can be called from multiple Python threads simultaneously. In other words, assume instances are not thread safe unless stated otherwise. Utility Methods ^^^^^^^^^^^^^^^ ``frame_progression()`` returns a 3-tuple containing the number of bytes ingested, consumed, and produced by the current compression operation. ``memory_size()`` obtains the memory utilization of the underlying zstd compression context, in bytes.:: cctx = zstd.ZstdCompressor() memory = cctx.memory_size() Simple API ^^^^^^^^^^ ``compress(data)`` compresses and returns data as a one-shot operation.:: cctx = zstd.ZstdCompressor() compressed = cctx.compress(b'data to compress') The ``data`` argument can be any object that implements the *buffer protocol*. Stream Reader API ^^^^^^^^^^^^^^^^^ ``stream_reader(source)`` can be used to obtain an object conforming to the ``io.RawIOBase`` interface for reading compressed output as a stream:: with open(path, 'rb') as fh: cctx = zstd.ZstdCompressor() reader = cctx.stream_reader(fh) while True: chunk = reader.read(16384) if not chunk: break # Do something with compressed chunk. Instances can also be used as context managers:: with open(path, 'rb') as fh: with cctx.stream_reader(fh) as reader: while True: chunk = reader.read(16384) if not chunk: break # Do something with compressed chunk. When the context manager exits or ``close()`` is called, the stream is closed, underlying resources are released, and future operations against the compression stream will fail. The ``source`` argument to ``stream_reader()`` can be any object with a ``read(size)`` method or any object implementing the *buffer protocol*. ``stream_reader()`` accepts a ``size`` argument specifying how large the input stream is. This is used to adjust compression parameters so they are tailored to the source size.:: with open(path, 'rb') as fh: cctx = zstd.ZstdCompressor() with cctx.stream_reader(fh, size=os.stat(path).st_size) as reader: ... If the ``source`` is a stream, you can specify how large ``read()`` requests to that stream should be via the ``read_size`` argument. It defaults to ``zstandard.COMPRESSION_RECOMMENDED_INPUT_SIZE``.:: with open(path, 'rb') as fh: cctx = zstd.ZstdCompressor() # Will perform fh.read(8192) when obtaining data to feed into the # compressor. with cctx.stream_reader(fh, read_size=8192) as reader: ... The stream returned by ``stream_reader()`` is neither writable nor seekable (even if the underlying source is seekable). ``readline()`` and ``readlines()`` are not implemented because they don't make sense for compressed data. ``tell()`` returns the number of compressed bytes emitted so far. Streaming Input API ^^^^^^^^^^^^^^^^^^^ ``stream_writer(fh)`` allows you to *stream* data into a compressor. Returned instances implement the ``io.RawIOBase`` interface. Only methods that involve writing will do useful things. The argument to ``stream_writer()`` must have a ``write(data)`` method. As compressed data is available, ``write()`` will be called with the compressed data as its argument. Many common Python types implement ``write()``, including open file handles and ``io.BytesIO``. The ``write(data)`` method is used to feed data into the compressor. The ``flush([flush_mode=FLUSH_BLOCK])`` method can be called to evict whatever data remains within the compressor's internal state into the output object. This may result in 0 or more ``write()`` calls to the output object. This method accepts an optional ``flush_mode`` argument to control the flushing behavior. Its value can be any of the ``FLUSH_*`` constants. Both ``write()`` and ``flush()`` return the number of bytes written to the object's ``write()``. In many cases, small inputs do not accumulate enough data to cause a write and ``write()`` will return ``0``. Calling ``close()`` will mark the stream as closed and subsequent I/O operations will raise ``ValueError`` (per the documented behavior of ``io.RawIOBase``). ``close()`` will also call ``close()`` on the underlying stream if such a method exists. Typically usage is as follows:: cctx = zstd.ZstdCompressor(level=10) compressor = cctx.stream_writer(fh) compressor.write(b'chunk 0\n') compressor.write(b'chunk 1\n') compressor.flush() # Receiver will be able to decode ``chunk 0\nchunk 1\n`` at this point. # Receiver is also expecting more data in the zstd *frame*. compressor.write(b'chunk 2\n') compressor.flush(zstd.FLUSH_FRAME) # Receiver will be able to decode ``chunk 0\nchunk 1\nchunk 2``. # Receiver is expecting no more data, as the zstd frame is closed. # Any future calls to ``write()`` at this point will construct a new # zstd frame. Instances can be used as context managers. Exiting the context manager is the equivalent of calling ``close()``, which is equivalent to calling ``flush(zstd.FLUSH_FRAME)``:: cctx = zstd.ZstdCompressor(level=10) with cctx.stream_writer(fh) as compressor: compressor.write(b'chunk 0') compressor.write(b'chunk 1') ... .. important:: If ``flush(FLUSH_FRAME)`` is not called, emitted data doesn't constitute a full zstd *frame* and consumers of this data may complain about malformed input. It is recommended to use instances as a context manager to ensure *frames* are properly finished. If the size of the data being fed to this streaming compressor is known, you can declare it before compression begins:: cctx = zstd.ZstdCompressor() with cctx.stream_writer(fh, size=data_len) as compressor: compressor.write(chunk0) compressor.write(chunk1) ... Declaring the size of the source data allows compression parameters to be tuned. And if ``write_content_size`` is used, it also results in the content size being written into the frame header of the output data. The size of chunks being ``write()`` to the destination can be specified:: cctx = zstd.ZstdCompressor() with cctx.stream_writer(fh, write_size=32768) as compressor: ... To see how much memory is being used by the streaming compressor:: cctx = zstd.ZstdCompressor() with cctx.stream_writer(fh) as compressor: ... byte_size = compressor.memory_size() Thte total number of bytes written so far are exposed via ``tell()``:: cctx = zstd.ZstdCompressor() with cctx.stream_writer(fh) as compressor: ... total_written = compressor.tell() ``stream_writer()`` accepts a ``write_return_read`` boolean argument to control the return value of ``write()``. When ``False`` (the default), ``write()`` returns the number of bytes that were ``write()``en to the underlying object. When ``True``, ``write()`` returns the number of bytes read from the input that were subsequently written to the compressor. ``True`` is the *proper* behavior for ``write()`` as specified by the ``io.RawIOBase`` interface and will become the default value in a future release. Streaming Output API ^^^^^^^^^^^^^^^^^^^^ ``read_to_iter(reader)`` provides a mechanism to stream data out of a compressor as an iterator of data chunks.:: cctx = zstd.ZstdCompressor() for chunk in cctx.read_to_iter(fh): # Do something with emitted data. ``read_to_iter()`` accepts an object that has a ``read(size)`` method or conforms to the buffer protocol. Uncompressed data is fetched from the source either by calling ``read(size)`` or by fetching a slice of data from the object directly (in the case where the buffer protocol is being used). The returned iterator consists of chunks of compressed data. If reading from the source via ``read()``, ``read()`` will be called until it raises or returns an empty bytes (``b''``). It is perfectly valid for the source to deliver fewer bytes than were what requested by ``read(size)``. Like ``stream_writer()``, ``read_to_iter()`` also accepts a ``size`` argument declaring the size of the input stream:: cctx = zstd.ZstdCompressor() for chunk in cctx.read_to_iter(fh, size=some_int): pass You can also control the size that data is ``read()`` from the source and the ideal size of output chunks:: cctx = zstd.ZstdCompressor() for chunk in cctx.read_to_iter(fh, read_size=16384, write_size=8192): pass Unlike ``stream_writer()``, ``read_to_iter()`` does not give direct control over the sizes of chunks fed into the compressor. Instead, chunk sizes will be whatever the object being read from delivers. These will often be of a uniform size. Stream Copying API ^^^^^^^^^^^^^^^^^^ ``copy_stream(ifh, ofh)`` can be used to copy data between 2 streams while compressing it.:: cctx = zstd.ZstdCompressor() cctx.copy_stream(ifh, ofh) For example, say you wish to compress a file:: cctx = zstd.ZstdCompressor() with open(input_path, 'rb') as ifh, open(output_path, 'wb') as ofh: cctx.copy_stream(ifh, ofh) It is also possible to declare the size of the source stream:: cctx = zstd.ZstdCompressor() cctx.copy_stream(ifh, ofh, size=len_of_input) You can also specify how large the chunks that are ``read()`` and ``write()`` from and to the streams:: cctx = zstd.ZstdCompressor() cctx.copy_stream(ifh, ofh, read_size=32768, write_size=16384) The stream copier returns a 2-tuple of bytes read and written:: cctx = zstd.ZstdCompressor() read_count, write_count = cctx.copy_stream(ifh, ofh) Compressor API ^^^^^^^^^^^^^^ ``compressobj()`` returns an object that exposes ``compress(data)`` and ``flush()`` methods. Each returns compressed data or an empty bytes. The purpose of ``compressobj()`` is to provide an API-compatible interface with ``zlib.compressobj``, ``bz2.BZ2Compressor``, etc. This allows callers to swap in different compressor objects while using the same API. ``flush()`` accepts an optional argument indicating how to end the stream. ``zstd.COMPRESSOBJ_FLUSH_FINISH`` (the default) ends the compression stream. Once this type of flush is performed, ``compress()`` and ``flush()`` can no longer be called. This type of flush **must** be called to end the compression context. If not called, returned data may be incomplete. A ``zstd.COMPRESSOBJ_FLUSH_BLOCK`` argument to ``flush()`` will flush a zstd block. Flushes of this type can be performed multiple times. The next call to ``compress()`` will begin a new zstd block. Here is how this API should be used:: cctx = zstd.ZstdCompressor() cobj = cctx.compressobj() data = cobj.compress(b'raw input 0') data = cobj.compress(b'raw input 1') data = cobj.flush() Or to flush blocks:: cctx.zstd.ZstdCompressor() cobj = cctx.compressobj() data = cobj.compress(b'chunk in first block') data = cobj.flush(zstd.COMPRESSOBJ_FLUSH_BLOCK) data = cobj.compress(b'chunk in second block') data = cobj.flush() For best performance results, keep input chunks under 256KB. This avoids extra allocations for a large output object. It is possible to declare the input size of the data that will be fed into the compressor:: cctx = zstd.ZstdCompressor() cobj = cctx.compressobj(size=6) data = cobj.compress(b'foobar') data = cobj.flush() Chunker API ^^^^^^^^^^^ ``chunker(size=None, chunk_size=COMPRESSION_RECOMMENDED_OUTPUT_SIZE)`` returns an object that can be used to iteratively feed chunks of data into a compressor and produce output chunks of a uniform size. The object returned by ``chunker()`` exposes the following methods: ``compress(data)`` Feeds new input data into the compressor. ``flush()`` Flushes all data currently in the compressor. ``finish()`` Signals the end of input data. No new data can be compressed after this method is called. ``compress()``, ``flush()``, and ``finish()`` all return an iterator of ``bytes`` instances holding compressed data. The iterator may be empty. Callers MUST iterate through all elements of the returned iterator before performing another operation on the object. All chunks emitted by ``compress()`` will have a length of ``chunk_size``. ``flush()`` and ``finish()`` may return a final chunk smaller than ``chunk_size``. Here is how the API should be used:: cctx = zstd.ZstdCompressor() chunker = cctx.chunker(chunk_size=32768) with open(path, 'rb') as fh: while True: in_chunk = fh.read(32768) if not in_chunk: break for out_chunk in chunker.compress(in_chunk): # Do something with output chunk of size 32768. for out_chunk in chunker.finish(): # Do something with output chunks that finalize the zstd frame. The ``chunker()`` API is often a better alternative to ``compressobj()``. ``compressobj()`` will emit output data as it is available. This results in a *stream* of output chunks of varying sizes. The consistency of the output chunk size with ``chunker()`` is more appropriate for many usages, such as sending compressed data to a socket. ``compressobj()`` may also perform extra memory reallocations in order to dynamically adjust the sizes of the output chunks. Since ``chunker()`` output chunks are all the same size (except for flushed or final chunks), there is less memory allocation overhead. Batch Compression API ^^^^^^^^^^^^^^^^^^^^^ (Experimental. Not yet supported in CFFI bindings.) ``multi_compress_to_buffer(data, [threads=0])`` performs compression of multiple inputs as a single operation. Data to be compressed can be passed as a ``BufferWithSegmentsCollection``, a ``BufferWithSegments``, or a list containing byte like objects. Each element of the container will be compressed individually using the configured parameters on the ``ZstdCompressor`` instance. The ``threads`` argument controls how many threads to use for compression. The default is ``0`` which means to use a single thread. Negative values use the number of logical CPUs in the machine. The function returns a ``BufferWithSegmentsCollection``. This type represents N discrete memory allocations, eaching holding 1 or more compressed frames. Output data is written to shared memory buffers. This means that unlike regular Python objects, a reference to *any* object within the collection keeps the shared buffer and therefore memory backing it alive. This can have undesirable effects on process memory usage. The API and behavior of this function is experimental and will likely change. Known deficiencies include: * If asked to use multiple threads, it will always spawn that many threads, even if the input is too small to use them. It should automatically lower the thread count when the extra threads would just add overhead. * The buffer allocation strategy is fixed. There is room to make it dynamic, perhaps even to allow one output buffer per input, facilitating a variation of the API to return a list without the adverse effects of shared memory buffers. ZstdDecompressor ---------------- The ``ZstdDecompressor`` class provides an interface for performing decompression. It is effectively a wrapper around the ``ZSTD_DCtx`` type from the C API. Each instance is associated with parameters that control decompression. These come from the following named arguments (all optional): dict_data Compression dictionary to use. max_window_size Sets an uppet limit on the window size for decompression operations in kibibytes. This setting can be used to prevent large memory allocations for inputs using large compression windows. format Set the format of data for the decoder. By default, this is ``zstd.FORMAT_ZSTD1``. It can be set to ``zstd.FORMAT_ZSTD1_MAGICLESS`` to allow decoding frames without the 4 byte magic header. Not all decompression APIs support this mode. The interface of this class is very similar to ``ZstdCompressor`` (by design). Unless specified otherwise, assume that no two methods of ``ZstdDecompressor`` instances can be called from multiple Python threads simultaneously. In other words, assume instances are not thread safe unless stated otherwise. Utility Methods ^^^^^^^^^^^^^^^ ``memory_size()`` obtains the size of the underlying zstd decompression context, in bytes.:: dctx = zstd.ZstdDecompressor() size = dctx.memory_size() Simple API ^^^^^^^^^^ ``decompress(data)`` can be used to decompress an entire compressed zstd frame in a single operation.:: dctx = zstd.ZstdDecompressor() decompressed = dctx.decompress(data) By default, ``decompress(data)`` will only work on data written with the content size encoded in its header (this is the default behavior of ``ZstdCompressor().compress()`` but may not be true for streaming compression). If compressed data without an embedded content size is seen, ``zstd.ZstdError`` will be raised. If the compressed data doesn't have its content size embedded within it, decompression can be attempted by specifying the ``max_output_size`` argument.:: dctx = zstd.ZstdDecompressor() uncompressed = dctx.decompress(data, max_output_size=1048576) Ideally, ``max_output_size`` will be identical to the decompressed output size. If ``max_output_size`` is too small to hold the decompressed data, ``zstd.ZstdError`` will be raised. If ``max_output_size`` is larger than the decompressed data, the allocated output buffer will be resized to only use the space required. Please note that an allocation of the requested ``max_output_size`` will be performed every time the method is called. Setting to a very large value could result in a lot of work for the memory allocator and may result in ``MemoryError`` being raised if the allocation fails. .. important:: If the exact size of decompressed data is unknown (not passed in explicitly and not stored in the zstandard frame), for performance reasons it is encouraged to use a streaming API. Stream Reader API ^^^^^^^^^^^^^^^^^ ``stream_reader(source)`` can be used to obtain an object conforming to the ``io.RawIOBase`` interface for reading decompressed output as a stream:: with open(path, 'rb') as fh: dctx = zstd.ZstdDecompressor() reader = dctx.stream_reader(fh) while True: chunk = reader.read(16384) if not chunk: break # Do something with decompressed chunk. The stream can also be used as a context manager:: with open(path, 'rb') as fh: dctx = zstd.ZstdDecompressor() with dctx.stream_reader(fh) as reader: ... When used as a context manager, the stream is closed and the underlying resources are released when the context manager exits. Future operations against the stream will fail. The ``source`` argument to ``stream_reader()`` can be any object with a ``read(size)`` method or any object implementing the *buffer protocol*. If the ``source`` is a stream, you can specify how large ``read()`` requests to that stream should be via the ``read_size`` argument. It defaults to ``zstandard.DECOMPRESSION_RECOMMENDED_INPUT_SIZE``.:: with open(path, 'rb') as fh: dctx = zstd.ZstdDecompressor() # Will perform fh.read(8192) when obtaining data for the decompressor. with dctx.stream_reader(fh, read_size=8192) as reader: ... The stream returned by ``stream_reader()`` is not writable. The stream returned by ``stream_reader()`` is *partially* seekable. Absolute and relative positions (``SEEK_SET`` and ``SEEK_CUR``) forward of the current position are allowed. Offsets behind the current read position and offsets relative to the end of stream are not allowed and will raise ``ValueError`` if attempted. ``tell()`` returns the number of decompressed bytes read so far. Not all I/O methods are implemented. Notably missing is support for ``readline()``, ``readlines()``, and linewise iteration support. This is because streams operate on binary data - not text data. If you want to convert decompressed output to text, you can chain an ``io.TextIOWrapper`` to the stream:: with open(path, 'rb') as fh: dctx = zstd.ZstdDecompressor() stream_reader = dctx.stream_reader(fh) text_stream = io.TextIOWrapper(stream_reader, encoding='utf-8') for line in text_stream: ... The ``read_across_frames`` argument to ``stream_reader()`` controls the behavior of read operations when the end of a zstd *frame* is encountered. When ``False`` (the default), a read will complete when the end of a zstd *frame* is encountered. When ``True``, a read can potentially return data spanning multiple zstd *frames*. Streaming Input API ^^^^^^^^^^^^^^^^^^^ ``stream_writer(fh)`` allows you to *stream* data into a decompressor. Returned instances implement the ``io.RawIOBase`` interface. Only methods that involve writing will do useful things. The argument to ``stream_writer()`` is typically an object that also implements ``io.RawIOBase``. But any object with a ``write(data)`` method will work. Many common Python types conform to this interface, including open file handles and ``io.BytesIO``. Behavior is similar to ``ZstdCompressor.stream_writer()``: compressed data is sent to the decompressor by calling ``write(data)`` and decompressed output is written to the underlying stream by calling its ``write(data)`` method.:: dctx = zstd.ZstdDecompressor() decompressor = dctx.stream_writer(fh) decompressor.write(compressed_data) ... Calls to ``write()`` will return the number of bytes written to the output object. Not all inputs will result in bytes being written, so return values of ``0`` are possible. Like the ``stream_writer()`` compressor, instances can be used as context managers. However, context managers add no extra special behavior and offer little to no benefit to being used. Calling ``close()`` will mark the stream as closed and subsequent I/O operations will raise ``ValueError`` (per the documented behavior of ``io.RawIOBase``). ``close()`` will also call ``close()`` on the underlying stream if such a method exists. The size of chunks being ``write()`` to the destination can be specified:: dctx = zstd.ZstdDecompressor() with dctx.stream_writer(fh, write_size=16384) as decompressor: pass You can see how much memory is being used by the decompressor:: dctx = zstd.ZstdDecompressor() with dctx.stream_writer(fh) as decompressor: byte_size = decompressor.memory_size() ``stream_writer()`` accepts a ``write_return_read`` boolean argument to control the return value of ``write()``. When ``False`` (the default)``, ``write()`` returns the number of bytes that were ``write()``en to the underlying stream. When ``True``, ``write()`` returns the number of bytes read from the input. ``True`` is the *proper* behavior for ``write()`` as specified by the ``io.RawIOBase`` interface and will become the default in a future release. Streaming Output API ^^^^^^^^^^^^^^^^^^^^ ``read_to_iter(fh)`` provides a mechanism to stream decompressed data out of a compressed source as an iterator of data chunks.:: dctx = zstd.ZstdDecompressor() for chunk in dctx.read_to_iter(fh): # Do something with original data. ``read_to_iter()`` accepts an object with a ``read(size)`` method that will return compressed bytes or an object conforming to the buffer protocol that can expose its data as a contiguous range of bytes. ``read_to_iter()`` returns an iterator whose elements are chunks of the decompressed data. The size of requested ``read()`` from the source can be specified:: dctx = zstd.ZstdDecompressor() for chunk in dctx.read_to_iter(fh, read_size=16384): pass It is also possible to skip leading bytes in the input data:: dctx = zstd.ZstdDecompressor() for chunk in dctx.read_to_iter(fh, skip_bytes=1): pass .. tip:: Skipping leading bytes is useful if the source data contains extra *header* data. Traditionally, you would need to create a slice or ``memoryview`` of the data you want to decompress. This would create overhead. It is more efficient to pass the offset into this API. Similarly to ``ZstdCompressor.read_to_iter()``, the consumer of the iterator controls when data is decompressed. If the iterator isn't consumed, decompression is put on hold. When ``read_to_iter()`` is passed an object conforming to the buffer protocol, the behavior may seem similar to what occurs when the simple decompression API is used. However, this API works when the decompressed size is unknown. Furthermore, if feeding large inputs, the decompressor will work in chunks instead of performing a single operation. Stream Copying API ^^^^^^^^^^^^^^^^^^ ``copy_stream(ifh, ofh)`` can be used to copy data across 2 streams while performing decompression.:: dctx = zstd.ZstdDecompressor() dctx.copy_stream(ifh, ofh) e.g. to decompress a file to another file:: dctx = zstd.ZstdDecompressor() with open(input_path, 'rb') as ifh, open(output_path, 'wb') as ofh: dctx.copy_stream(ifh, ofh) The size of chunks being ``read()`` and ``write()`` from and to the streams can be specified:: dctx = zstd.ZstdDecompressor() dctx.copy_stream(ifh, ofh, read_size=8192, write_size=16384) Decompressor API ^^^^^^^^^^^^^^^^ ``decompressobj()`` returns an object that exposes a ``decompress(data)`` method. Compressed data chunks are fed into ``decompress(data)`` and uncompressed output (or an empty bytes) is returned. Output from subsequent calls needs to be concatenated to reassemble the full decompressed byte sequence. The purpose of ``decompressobj()`` is to provide an API-compatible interface with ``zlib.decompressobj`` and ``bz2.BZ2Decompressor``. This allows callers to swap in different decompressor objects while using the same API. Each object is single use: once an input frame is decoded, ``decompress()`` can no longer be called. Here is how this API should be used:: dctx = zstd.ZstdDecompressor() dobj = dctx.decompressobj() data = dobj.decompress(compressed_chunk_0) data = dobj.decompress(compressed_chunk_1) By default, calls to ``decompress()`` write output data in chunks of size ``DECOMPRESSION_RECOMMENDED_OUTPUT_SIZE``. These chunks are concatenated before being returned to the caller. It is possible to define the size of these temporary chunks by passing ``write_size`` to ``decompressobj()``:: dctx = zstd.ZstdDecompressor() dobj = dctx.decompressobj(write_size=1048576) .. note:: Because calls to ``decompress()`` may need to perform multiple memory (re)allocations, this streaming decompression API isn't as efficient as other APIs. For compatibility with the standard library APIs, instances expose a ``flush([length=None])`` method. This method no-ops and has no meaningful side-effects, making it safe to call any time. Batch Decompression API ^^^^^^^^^^^^^^^^^^^^^^^ (Experimental. Not yet supported in CFFI bindings.) ``multi_decompress_to_buffer()`` performs decompression of multiple frames as a single operation and returns a ``BufferWithSegmentsCollection`` containing decompressed data for all inputs. Compressed frames can be passed to the function as a ``BufferWithSegments``, a ``BufferWithSegmentsCollection``, or as a list containing objects that conform to the buffer protocol. For best performance, pass a ``BufferWithSegmentsCollection`` or a ``BufferWithSegments``, as minimal input validation will be done for that type. If calling from Python (as opposed to C), constructing one of these instances may add overhead cancelling out the performance overhead of validation for list inputs.:: dctx = zstd.ZstdDecompressor() results = dctx.multi_decompress_to_buffer([b'...', b'...']) The decompressed size of each frame MUST be discoverable. It can either be embedded within the zstd frame (``write_content_size=True`` argument to ``ZstdCompressor``) or passed in via the ``decompressed_sizes`` argument. The ``decompressed_sizes`` argument is an object conforming to the buffer protocol which holds an array of 64-bit unsigned integers in the machine's native format defining the decompressed sizes of each frame. If this argument is passed, it avoids having to scan each frame for its decompressed size. This frame scanning can add noticeable overhead in some scenarios.:: frames = [...] sizes = struct.pack('=QQQQ', len0, len1, len2, len3) dctx = zstd.ZstdDecompressor() results = dctx.multi_decompress_to_buffer(frames, decompressed_sizes=sizes) The ``threads`` argument controls the number of threads to use to perform decompression operations. The default (``0``) or the value ``1`` means to use a single thread. Negative values use the number of logical CPUs in the machine. .. note:: It is possible to pass a ``mmap.mmap()`` instance into this function by wrapping it with a ``BufferWithSegments`` instance (which will define the offsets of frames within the memory mapped region). This function is logically equivalent to performing ``dctx.decompress()`` on each input frame and returning the result. This function exists to perform decompression on multiple frames as fast as possible by having as little overhead as possible. Since decompression is performed as a single operation and since the decompressed output is stored in a single buffer, extra memory allocations, Python objects, and Python function calls are avoided. This is ideal for scenarios where callers know up front that they need to access data for multiple frames, such as when *delta chains* are being used. Currently, the implementation always spawns multiple threads when requested, even if the amount of work to do is small. In the future, it will be smarter about avoiding threads and their associated overhead when the amount of work to do is small. Prefix Dictionary Chain Decompression ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``decompress_content_dict_chain(frames)`` performs decompression of a list of zstd frames produced using chained *prefix* dictionary compression. Such a list of frames is produced by compressing discrete inputs where each non-initial input is compressed with a *prefix* dictionary consisting of the content of the previous input. For example, say you have the following inputs:: inputs = [b'input 1', b'input 2', b'input 3'] The zstd frame chain consists of: 1. ``b'input 1'`` compressed in standalone/discrete mode 2. ``b'input 2'`` compressed using ``b'input 1'`` as a *prefix* dictionary 3. ``b'input 3'`` compressed using ``b'input 2'`` as a *prefix* dictionary Each zstd frame **must** have the content size written. The following Python code can be used to produce a *prefix dictionary chain*:: def make_chain(inputs): frames = [] # First frame is compressed in standalone/discrete mode. zctx = zstd.ZstdCompressor() frames.append(zctx.compress(inputs[0])) # Subsequent frames use the previous fulltext as a prefix dictionary for i, raw in enumerate(inputs[1:]): dict_data = zstd.ZstdCompressionDict( inputs[i], dict_type=zstd.DICT_TYPE_RAWCONTENT) zctx = zstd.ZstdCompressor(dict_data=dict_data) frames.append(zctx.compress(raw)) return frames ``decompress_content_dict_chain()`` returns the uncompressed data of the last element in the input chain. .. note:: It is possible to implement *prefix dictionary chain* decompression on top of other APIs. However, this function will likely be faster - especially for long input chains - as it avoids the overhead of instantiating and passing around intermediate objects between C and Python. Multi-Threaded Compression -------------------------- ``ZstdCompressor`` accepts a ``threads`` argument that controls the number of threads to use for compression. The way this works is that input is split into segments and each segment is fed into a worker pool for compression. Once a segment is compressed, it is flushed/appended to the output. .. note:: These threads are created at the C layer and are not Python threads. So they work outside the GIL. It is therefore possible to CPU saturate multiple cores from Python. The segment size for multi-threaded compression is chosen from the window size of the compressor. This is derived from the ``window_log`` attribute of a ``ZstdCompressionParameters`` instance. By default, segment sizes are in the 1+MB range. If multi-threaded compression is requested and the input is smaller than the configured segment size, only a single compression thread will be used. If the input is smaller than the segment size multiplied by the thread pool size or if data cannot be delivered to the compressor fast enough, not all requested compressor threads may be active simultaneously. Compared to non-multi-threaded compression, multi-threaded compression has higher per-operation overhead. This includes extra memory operations, thread creation, lock acquisition, etc. Due to the nature of multi-threaded compression using *N* compression *states*, the output from multi-threaded compression will likely be larger than non-multi-threaded compression. The difference is usually small. But there is a CPU/wall time versus size trade off that may warrant investigation. Output from multi-threaded compression does not require any special handling on the decompression side. To the decompressor, data generated with single threaded compressor looks the same as data generated by a multi-threaded compressor and does not require any special handling or additional resource requirements. Dictionary Creation and Management ---------------------------------- Compression dictionaries are represented with the ``ZstdCompressionDict`` type. Instances can be constructed from bytes:: dict_data = zstd.ZstdCompressionDict(data) It is possible to construct a dictionary from *any* data. If the data doesn't begin with a magic header, it will be treated as a *prefix* dictionary. *Prefix* dictionaries allow compression operations to reference raw data within the dictionary. It is possible to force the use of *prefix* dictionaries or to require a dictionary header: dict_data = zstd.ZstdCompressionDict(data, dict_type=zstd.DICT_TYPE_RAWCONTENT) dict_data = zstd.ZstdCompressionDict(data, dict_type=zstd.DICT_TYPE_FULLDICT) You can see how many bytes are in the dictionary by calling ``len()``:: dict_data = zstd.train_dictionary(size, samples) dict_size = len(dict_data) # will not be larger than ``size`` Once you have a dictionary, you can pass it to the objects performing compression and decompression:: dict_data = zstd.train_dictionary(131072, samples) cctx = zstd.ZstdCompressor(dict_data=dict_data) for source_data in input_data: compressed = cctx.compress(source_data) # Do something with compressed data. dctx = zstd.ZstdDecompressor(dict_data=dict_data) for compressed_data in input_data: buffer = io.BytesIO() with dctx.stream_writer(buffer) as decompressor: decompressor.write(compressed_data) # Do something with raw data in ``buffer``. Dictionaries have unique integer IDs. You can retrieve this ID via:: dict_id = zstd.dictionary_id(dict_data) You can obtain the raw data in the dict (useful for persisting and constructing a ``ZstdCompressionDict`` later) via ``as_bytes()``:: dict_data = zstd.train_dictionary(size, samples) raw_data = dict_data.as_bytes() By default, when a ``ZstdCompressionDict`` is *attached* to a ``ZstdCompressor``, each ``ZstdCompressor`` performs work to prepare the dictionary for use. This is fine if only 1 compression operation is being performed or if the ``ZstdCompressor`` is being reused for multiple operations. But if multiple ``ZstdCompressor`` instances are being used with the dictionary, this can add overhead. It is possible to *precompute* the dictionary so it can readily be consumed by multiple ``ZstdCompressor`` instances:: d = zstd.ZstdCompressionDict(data) # Precompute for compression level 3. d.precompute_compress(level=3) # Precompute with specific compression parameters. params = zstd.ZstdCompressionParameters(...) d.precompute_compress(compression_params=params) .. note:: When a dictionary is precomputed, the compression parameters used to precompute the dictionary overwrite some of the compression parameters specified to ``ZstdCompressor.__init__``. Training Dictionaries ^^^^^^^^^^^^^^^^^^^^^ Unless using *prefix* dictionaries, dictionary data is produced by *training* on existing data:: dict_data = zstd.train_dictionary(size, samples) This takes a target dictionary size and list of bytes instances and creates and returns a ``ZstdCompressionDict``. The dictionary training mechanism is known as *cover*. More details about it are available in the paper *Effective Construction of Relative Lempel-Ziv Dictionaries* (authors: Liao, Petri, Moffat, Wirth). The cover algorithm takes parameters ``k` and ``d``. These are the *segment size* and *dmer size*, respectively. The returned dictionary instance created by this function has ``k`` and ``d`` attributes containing the values for these parameters. If a ``ZstdCompressionDict`` is constructed from raw bytes data (a content-only dictionary), the ``k`` and ``d`` attributes will be ``0``. The segment and dmer size parameters to the cover algorithm can either be specified manually or ``train_dictionary()`` can try multiple values and pick the best one, where *best* means the smallest compressed data size. This later mode is called *optimization* mode. If none of ``k``, ``d``, ``steps``, ``threads``, ``level``, ``notifications``, or ``dict_id`` (basically anything from the underlying ``ZDICT_cover_params_t`` struct) are defined, *optimization* mode is used with default parameter values. If ``steps`` or ``threads`` are defined, then *optimization* mode is engaged with explicit control over those parameters. Specifying ``threads=0`` or ``threads=1`` can be used to engage *optimization* mode if other parameters are not defined. Otherwise, non-*optimization* mode is used with the parameters specified. This function takes the following arguments: dict_size Target size in bytes of the dictionary to generate. samples A list of bytes holding samples the dictionary will be trained from. k Parameter to cover algorithm defining the segment size. A reasonable range is [16, 2048+]. d Parameter to cover algorithm defining the dmer size. A reasonable range is [6, 16]. ``d`` must be less than or equal to ``k``. dict_id Integer dictionary ID for the produced dictionary. Default is 0, which uses a random value. steps Number of steps through ``k`` values to perform when trying parameter variations. threads Number of threads to use when trying parameter variations. Default is 0, which means to use a single thread. A negative value can be specified to use as many threads as there are detected logical CPUs. level Integer target compression level when trying parameter variations. notifications Controls writing of informational messages to ``stderr``. ``0`` (the default) means to write nothing. ``1`` writes errors. ``2`` writes progression info. ``3`` writes more details. And ``4`` writes all info. Explicit Compression Parameters ------------------------------- Zstandard offers a high-level *compression level* that maps to lower-level compression parameters. For many consumers, this numeric level is the only compression setting you'll need to touch. But for advanced use cases, it might be desirable to tweak these lower-level settings. The ``ZstdCompressionParameters`` type represents these low-level compression settings. Instances of this type can be constructed from a myriad of keyword arguments (defined below) for complete low-level control over each adjustable compression setting. From a higher level, one can construct a ``ZstdCompressionParameters`` instance given a desired compression level and target input and dictionary size using ``ZstdCompressionParameters.from_level()``. e.g.:: # Derive compression settings for compression level 7. params = zstd.ZstdCompressionParameters.from_level(7) # With an input size of 1MB params = zstd.ZstdCompressionParameters.from_level(7, source_size=1048576) Using ``from_level()``, it is also possible to override individual compression parameters or to define additional settings that aren't automatically derived. e.g.:: params = zstd.ZstdCompressionParameters.from_level(4, window_log=10) params = zstd.ZstdCompressionParameters.from_level(5, threads=4) Or you can define low-level compression settings directly:: params = zstd.ZstdCompressionParameters(window_log=12, enable_ldm=True) Once a ``ZstdCompressionParameters`` instance is obtained, it can be used to configure a compressor:: cctx = zstd.ZstdCompressor(compression_params=params) The named arguments and attributes of ``ZstdCompressionParameters`` are as follows: * format * compression_level * window_log * hash_log * chain_log * search_log * min_match * target_length * strategy * compression_strategy (deprecated: same as ``strategy``) * write_content_size * write_checksum * write_dict_id * job_size * overlap_log * overlap_size_log (deprecated: same as ``overlap_log``) * force_max_window * enable_ldm * ldm_hash_log * ldm_min_match * ldm_bucket_size_log * ldm_hash_rate_log * ldm_hash_every_log (deprecated: same as ``ldm_hash_rate_log``) * threads Some of these are very low-level settings. It may help to consult the official zstandard documentation for their behavior. Look for the ``ZSTD_p_*`` constants in ``zstd.h`` (https://github.com/facebook/zstd/blob/dev/lib/zstd.h). 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. ``zstd.get_frame_parameters(data)`` parses a zstd *frame* header from a bytes instance and return a ``FrameParameters`` object describing the frame. 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. ``FrameParameters`` 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. ``zstd.frame_header_size(data)`` returns the size of the zstandard frame header. ``zstd.frame_content_size(data)`` returns the content size as parsed from the frame header. ``-1`` means the content size is unknown. ``0`` means an empty frame. The content size is usually correct. However, it may not be accurate. Misc Functionality ------------------ estimate_decompression_context_size() ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Estimate the memory size requirements for a decompressor instance. 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 Minimum value for compression parameter WINDOWLOG_MAX Maximum value for compression parameter CHAINLOG_MIN Minimum value for compression parameter CHAINLOG_MAX Maximum value for compression parameter HASHLOG_MIN Minimum value for compression parameter HASHLOG_MAX Maximum value for compression parameter SEARCHLOG_MIN Minimum value for compression parameter SEARCHLOG_MAX Maximum value for compression parameter MINMATCH_MIN Minimum value for compression parameter MINMATCH_MAX Maximum value for compression parameter SEARCHLENGTH_MIN Minimum value for compression parameter Deprecated: use ``MINMATCH_MIN`` SEARCHLENGTH_MAX Maximum value for compression parameter Deprecated: use ``MINMATCH_MAX`` TARGETLENGTH_MIN Minimum value for compression parameter STRATEGY_FAST Compression strategy STRATEGY_DFAST Compression strategy STRATEGY_GREEDY Compression strategy STRATEGY_LAZY Compression strategy STRATEGY_LAZY2 Compression strategy STRATEGY_BTLAZY2 Compression strategy STRATEGY_BTOPT Compression strategy STRATEGY_BTULTRA Compression strategy STRATEGY_BTULTRA2 Compression strategy FORMAT_ZSTD1 Zstandard frame format FORMAT_ZSTD1_MAGICLESS Zstandard frame format without magic header Performance Considerations -------------------------- The ``ZstdCompressor`` and ``ZstdDecompressor`` types maintain state to a persistent compression or decompression *context*. Reusing a ``ZstdCompressor`` or ``ZstdDecompressor`` instance for multiple operations is faster than instantiating a new ``ZstdCompressor`` or ``ZstdDecompressor`` for each operation. The differences are magnified as the size of data decreases. For example, the difference between *context* reuse and non-reuse for 100,000 100 byte inputs will be significant (possiby over 10x faster to reuse contexts) whereas 10 100,000,000 byte inputs will be more similar in speed (because the time spent doing compression dwarfs time spent creating new *contexts*). Buffer Types ------------ The API exposes a handful of custom types for interfacing with memory buffers. The primary goal of these types is to facilitate efficient multi-object operations. The essential idea is to have a single memory allocation provide backing storage for multiple logical objects. This has 2 main advantages: fewer allocations and optimal memory access patterns. This avoids having to allocate a Python object for each logical object and furthermore ensures that access of data for objects can be sequential (read: fast) in memory. BufferWithSegments ^^^^^^^^^^^^^^^^^^ The ``BufferWithSegments`` type represents a memory buffer containing N discrete items of known lengths (segments). It is essentially a fixed size memory address and an array of 2-tuples of ``(offset, length)`` 64-bit unsigned native endian integers defining the byte offset and length of each segment within the buffer. Instances behave like containers. ``len()`` returns the number of segments within the instance. ``o[index]`` or ``__getitem__`` obtains a ``BufferSegment`` representing an individual segment within the backing buffer. That returned object references (not copies) memory. This means that iterating all objects doesn't copy data within the buffer. The ``.size`` attribute contains the total size in bytes of the backing buffer. Instances conform to the buffer protocol. So a reference to the backing bytes can be obtained via ``memoryview(o)``. A *copy* of the backing bytes can also be obtained via ``.tobytes()``. The ``.segments`` attribute exposes the array of ``(offset, length)`` for segments within the buffer. It is a ``BufferSegments`` type. BufferSegment ^^^^^^^^^^^^^ The ``BufferSegment`` type represents a segment within a ``BufferWithSegments``. It is essentially a reference to N bytes within a ``BufferWithSegments``. ``len()`` returns the length of the segment in bytes. ``.offset`` contains the byte offset of this segment within its parent ``BufferWithSegments`` instance. The object conforms to the buffer protocol. ``.tobytes()`` can be called to obtain a ``bytes`` instance with a copy of the backing bytes. BufferSegments ^^^^^^^^^^^^^^ This type represents an array of ``(offset, length)`` integers defining segments within a ``BufferWithSegments``. The array members are 64-bit unsigned integers using host/native bit order. Instances conform to the buffer protocol. BufferWithSegmentsCollection ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``BufferWithSegmentsCollection`` type represents a virtual spanning view of multiple ``BufferWithSegments`` instances. Instances are constructed from 1 or more ``BufferWithSegments`` instances. The resulting object behaves like an ordered sequence whose members are the segments within each ``BufferWithSegments``. ``len()`` returns the number of segments within all ``BufferWithSegments`` instances. ``o[index]`` and ``__getitem__(index)`` return the ``BufferSegment`` at that offset as if all ``BufferWithSegments`` instances were a single entity. If the object is composed of 2 ``BufferWithSegments`` instances with the first having 2 segments and the second have 3 segments, then ``b[0]`` and ``b[1]`` access segments in the first object and ``b[2]``, ``b[3]``, and ``b[4]`` access segments from the second. Choosing an API =============== There are multiple APIs for performing compression and decompression. This is because different applications have different needs and the library wants to facilitate optimal use in as many use cases as possible. From a high-level, APIs are divided into *one-shot* and *streaming*: either you are operating on all data at once or you operate on it piecemeal. The *one-shot* APIs are useful for small data, where the input or output size is known. (The size can come from a buffer length, file size, or stored in the zstd frame header.) A limitation of the *one-shot* APIs is that input and output must fit in memory simultaneously. For say a 4 GB input, this is often not feasible. The *one-shot* APIs also perform all work as a single operation. So, if you feed it large input, it could take a long time for the function to return. The streaming APIs do not have the limitations of the simple API. But the price you pay for this flexibility is that they are more complex than a single function call. The streaming APIs put the caller in control of compression and decompression behavior by allowing them to directly control either the input or output side of the operation. With the *streaming input*, *compressor*, and *decompressor* APIs, the caller has full control over the input to the compression or decompression stream. They can directly choose when new data is operated on. With the *streaming ouput* APIs, the caller has full control over the output of the compression or decompression stream. It can choose when to receive new data. When using the *streaming* APIs that operate on file-like or stream objects, it is important to consider what happens in that object when I/O is requested. There is potential for long pauses as data is read or written from the underlying stream (say from interacting with a filesystem or network). This could add considerable overhead. Thread Safety ============= ``ZstdCompressor`` and ``ZstdDecompressor`` instances have no guarantees about thread safety. Do not operate on the same ``ZstdCompressor`` and ``ZstdDecompressor`` instance simultaneously from different threads. It is fine to have different threads call into a single instance, just not at the same time. Some operations require multiple function calls to complete. e.g. streaming operations. A single ``ZstdCompressor`` or ``ZstdDecompressor`` cannot be used for simultaneously active operations. e.g. you must not start a streaming operation when another streaming operation is already active. The C extension releases the GIL during non-trivial calls into the zstd C API. Non-trivial calls are notably compression and decompression. Trivial calls are things like parsing frame parameters. Where the GIL is released is considered an implementation detail and can change in any release. APIs that accept bytes-like objects don't enforce that the underlying object is read-only. However, it is assumed that the passed object is read-only for the duration of the function call. It is possible to pass a mutable object (like a ``bytearray``) to e.g. ``ZstdCompressor.compress()``, have the GIL released, and mutate the object from another thread. Such a race condition is a bug in the consumer of python-zstandard. Most Python data types are immutable, so unless you are doing something fancy, you don't need to worry about this. Note on Zstandard's *Experimental* API ====================================== Many of the Zstandard APIs used by this module are marked as *experimental* within the Zstandard project. It is unclear how Zstandard's C API will evolve over time, especially with regards to this *experimental* functionality. We will try to maintain backwards compatibility at the Python API level. However, we cannot guarantee this for things not under our control. Since a copy of the Zstandard source code is distributed with this module and since we compile against it, the behavior of a specific version of this module should be constant for all of time. So if you pin the version of this module used in your projects (which is a Python best practice), you should be shielded from unwanted future changes. Donate ====== A lot of time has been invested into this project by the author. If you find this project useful and would like to thank the author for their work, consider donating some money. Any amount is appreciated. .. image:: https://www.paypalobjects.com/en_US/i/btn/btn_donate_LG.gif :target: https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=gregory%2eszorc%40gmail%2ecom&lc=US&item_name=python%2dzstandard¤cy_code=USD&bn=PP%2dDonationsBF%3abtn_donate_LG%2egif%3aNonHosted :alt: Donate via PayPal .. |ci-status| image:: https://dev.azure.com/gregoryszorc/python-zstandard/_apis/build/status/indygreg.python-zstandard?branchName=master :target: https://dev.azure.com/gregoryszorc/python-zstandard/_apis/build/status/indygreg.python-zstandard?branchName=master