lz4.block sub-package

This sub-package provides the capability to compress and decompress data using the block specification.

Because the LZ4 block format doesn’t define a container format, the Python bindings will by default insert the original data size as an integer at the start of the compressed payload, like most other bindings do (Java…). However, it is possible to disable this functionality.

Example usage

To use the lz4 block format bindings is straightforward:

.. doctest::
>>> import lz4.block
>>> import os
>>> input_data = 20 * 128 * os.urandom(1024)  # Read 20 * 128kb
>>> compressed_data = lz4.block.compress(input_data)
>>> output_data = lz4.block.decompress(compressed_data)
>>> input_data == output_data
True

Contents

lz4.block.compress(source, mode='default', acceleration=1, compression=0, return_bytearray=False)

Compress source, returning the compressed data as a string. Raises an exception if any error occurs.

Parameters:

source (str, bytes or buffer-compatible object) – Data to compress

Keyword Arguments:
 
  • mode (str) – If 'default' or unspecified use the default LZ4 compression mode. Set to 'fast' to use the fast compression LZ4 mode at the expense of compression. Set to 'high_compression' to use the LZ4 high-compression mode at the exepense of speed.
  • acceleration (int) – When mode is set to 'fast' this argument specifies the acceleration. The larger the acceleration, the faster the but the lower the compression. The default compression corresponds to a value of 1.
  • compression (int) – When mode is set to high_compression this argument specifies the compression. Valid values are between 1 and 12. Values between 4-9 are recommended, and 9 is the default.
  • store_size (bool) – If True (the default) then the size of the uncompressed data is stored at the start of the compressed block.
  • return_bytearray (bool) – If False (the default) then the function will return a bytes object. If True, then the function will return a bytearray object.
  • dict (str, bytes or buffer-compatible object) – If specified, perform compression using this initial dictionary.
Returns:

Compressed data.

Return type:

bytes or bytearray

lz4.block.decompress(source, uncompressed_size=-1, return_bytearray=False)

Decompress source, returning the uncompressed data as a string. Raises an exception if any error occurs.

Parameters:

source (str, bytes or buffer-compatible object) – Data to decompress.

Keyword Arguments:
 
  • uncompressed_size (int) – If not specified or negative, the uncompressed data size is read from the start of the source block. If specified, it is assumed that the full source data is compressed data.
  • return_bytearray (bool) – If False (the default) then the function will return a bytes object. If True, then the function will return a bytearray object.
  • dict (str, bytes or buffer-compatible object) – If specified, perform decompression using this initial dictionary.
Returns:

Decompressed data.

Return type:

bytes or bytearray