lz4.block sub-package

This sub-package provides the capability to compress and decompress data using the LZ4 block specification <http://lz4.github.io/lz4/lz4_Block_format.html>

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:

>>> import lz4.block
>>> compressed_data = lz4.block.compress(data)
>>> data == lz4.block.decompress(compressed_data)
True
>>>

Contents

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

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
  • 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) – Python 3 only. If False (the default) then the function will return a bytes object. If True, then the function will return a bytearray object.
Returns:

Compressed data.

Return type:

bytes or bytearray

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

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
  • uncompressed_size (int) – If not specified or < 0, 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) – Python 3 only. If False (the default) then the function will return a bytes object. If True, then the function will return a bytearray object.
Returns:

Decompressed data.

Return type:

bytes or bytearray

Is it fast ?

Yes. Here are the results on my 2011 Macbook Pro i7 with lz4.c as input data:

$ python tests/bench.py
Data Size:
  Input: 24779
  LZ4: 10152 (0.41)
  Snappy: 9902 (0.40)
  LZ4 / Snappy: 1.025247
Benchmark: 200000 calls
  LZ4 Compression: 9.737272s
  Snappy Compression: 18.012336s
  LZ4 Decompression: 2.686854s
  Snappy Decompression : 5.146867s