lz4.frame sub-package

This sub-package is an incomplete technology preview.

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

The frame specification is recommended for most applications. A key benefit of using the frame specification (compared to the block specification) is interoperability with other implementations.

Contents

A Python wrapper for the LZ4 frame protocol

lz4.frame.compress(source, compression_level=0, block_size=0, content_checksum=0, block_mode=0, frame_type=0, content_size_header=1)

Accepts a string, and compresses the string in one go, returning the compressed string as a string of bytes. The compressed string includes a header and endmark and so is suitable for writing to a file.

Parameters:

source (str) – String to compress

Keyword Arguments:
 
  • block_size (int) – Sepcifies the maximum blocksize to use. Options:

    • lz4.frame.BLOCKSIZE_DEFAULT or 0: the lz4 library default
    • lz4.frame.BLOCKSIZE_MAX64KB or 4: 64 kB
    • lz4.frame.BLOCKSIZE_MAX256KB or 5: 256 kB
    • lz4.frame.BLOCKSIZE_MAX1MB or 6: 1 MB
    • lz4.frame.BLOCKSIZE_MAX4MB or 7: 4 MB

    If unspecified, will default to lz4.frame.BLOCKSIZE_DEFAULT.

  • block_mode (int) – Specifies whether to use block-linked compression. Options:

    • lz4.frame.BLOCKMODE_LINKED or 0: linked mode
    • lz4.frame.BLOCKMODE_INDEPENDENT or 1: disable linked mode

    The default is lz4.frame.BLOCKMODE_LINKED.

  • compression_level (int) – Specifies the level of compression used. Values between 0-16 are valid, with 0 (default) being the lowest compression (0-2 are the same value), and 16 the highest. Values above 16 will be treated as 16. Values between 4-9 are recommended. The following module constants are provided as a convenience:

    • lz4.frame.COMPRESSIONLEVEL_MIN: Minimum compression (0, the default)
    • lz4.frame.COMPRESSIONLEVEL_MINHC: Minimum high-compression mode (3)
    • lz4.frame.COMPRESSIONLEVEL_MAX: Maximum compression (16)
  • content_checksum (int) – Specifies whether to enable checksumming of the payload content. Options:

    • lz4.frame.CONTENTCHECKSUM_DISABLED or 0: disables checksumming
    • lz4.frame.CONTENTCHECKSUM_ENABLED or 1: enables checksumming

    The default is CONTENTCHECKSUM_DISABLED.

  • frame_type (int) – Specifies whether user data can be injected between frames. Options:

    • lz4.frame.FRAMETYPE_FRAME or 0: disables user data injection
    • lz4.frame.FRAMETYPE_SKIPPABLEFRAME or 1: enables user data injection

    The default is lz4.frame.FRAMETYPE_FRAME.

  • content_size_header (bool) – Specifies whether to include an optional 8-byte header field that is the uncompressed size of data included within the frame. Including the content-size header is optional and is enabled by default.

Returns:

Compressed data as a string

Return type:

str

lz4.frame.decompress(source)

Decompressed a frame of data and returns it as a string of bytes. :param source: LZ4 frame as a string :type source: str

Returns:Uncompressed data as a string.
Return type:str
lz4.frame.create_compression_context()

Creates a Compression Context object, which will be used in all compression operations.

Returns:A compression context
Return type:cCtx
lz4.frame.compress_begin()
compress_begin(cCtx, source_size=0, compression_level=0, block_size=0,
content_checksum=0, content_size=1, block_mode=0, frame_type=0, auto_flush=1)

Creates a frame header from a compression context.

Parameters:

context (cCtx) – A compression context.

Keyword Arguments:
 
  • block_size (int) – Sepcifies the maximum blocksize to use. Options:

    • lz4.frame.BLOCKSIZE_DEFAULT or 0: the lz4 library default
    • lz4.frame.BLOCKSIZE_MAX64KB or 4: 64 kB
    • lz4.frame.BLOCKSIZE_MAX256KB or 5: 256 kB
    • lz4.frame.BLOCKSIZE_MAX1MB or 6: 1 MB
    • lz4.frame.BLOCKSIZE_MAX4MB or 7: 4 MB

    If unspecified, will default to lz4.frame.BLOCKSIZE_DEFAULT.

  • block_mode (int) – Specifies whether to use block-linked compression. Options:

    • lz4.frame.BLOCKMODE_LINKED or 0: linked mode
    • lz4.frame.BLOCKMODE_INDEPENDENT or 1: disable linked mode

    The default is lz4.frame.BLOCKMODE_LINKED.

  • compression_level (int) – Specifies the level of compression used. Values between 0-16 are valid, with 0 (default) being the lowest compression (0-2 are the same value), and 16 the highest. Values above 16 will be treated as 16. Values between 4-9 are recommended. The following module constants are provided as a convenience:

    • lz4.frame.COMPRESSIONLEVEL_MIN: Minimum compression (0, the default)
    • lz4.frame.COMPRESSIONLEVEL_MINHC: Minimum high-compression mode (3)
    • lz4.frame.COMPRESSIONLEVEL_MAX: Maximum compression (16)
  • content_checksum (int) – Specifies whether to enable checksumming of the payload content. Options:

    • lz4.frame.CONTENTCHECKSUM_DISABLED or 0: disables checksumming
    • lz4.frame.CONTENTCHECKSUM_ENABLED or 1: enables checksumming

    The default is CONTENTCHECKSUM_DISABLED.

  • frame_type (int) – Specifies whether user data can be injected between frames. Options:

    • lz4.frame.FRAMETYPE_FRAME or 0: disables user data injection
    • lz4.frame.FRAMETYPE_SKIPPABLEFRAME or 1: enables user data injection

    The default is lz4.frame.FRAMETYPE_FRAME.

  • auto_flush (int) – Enable (1, default) or disable (0) autoFlush. When autoFlush is disabled, the LZ4 library may buffer data until a block is full

  • source_size (int) – This optionally specifies the uncompressed size of the source content. This arument is optional, but if specified will be stored in the frame header for use during decompression.

Returns:

str – Frame header.

Return type:

str

lz4.frame.compress_update(context, source)

Compresses blocks of data and returns the compressed data in a string of bytes. :param context: compression context :type context: cCtx :param source: data to compress :type source: str

Returns:Compressed data as a string
Return type:str

Notes

If autoFlush is disabled (auto_flush=0 when calling compress_begin) this function may return an empty string if LZ4 decides to buffer. the input.

lz4.frame.compress_end(context)

Flushes a compression context returning an endmark and optional checksum as a string of bytes. :param context: compression context :type context: cCtx

Returns:Remaining (buffered) compressed data, end mark and optional checksum as a string
Return type:str
lz4.frame.get_frame_info(frame)

Given a frame of compressed data, returns information about the frame. :param frame: LZ4 frame as a string :type frame: str

Returns:
Dictionary with keys blockSizeID, blockMode, contentChecksumFlag
frameType and contentSize.
Return type:dict