compress.lz4

import compress

compress exposes this as compress.lz4, so import compress is enough and the names are called as compress.lz4.*. import compress.lz4 reaches the same definitions directly.

This is the Lz4 submodule for the compress module.

This modules provides two ways to use lz4. The first way is through the Lz4Decoder and Lz4Encoder classes, which implement a streaming encoder and decoder with the lz4 frame format. Unless you have a specific reason to the contrary, you should only use the Lz4 classes which implement the lz4 frame format. Specifically, the lz4 frame format permits streaming compression or decompression.

The second way is through the compress and decompress functions. These functions provide access to the lz4 block format, and don’t support a streaming interface directly. You should only use these types if you know you specifically need the lz4 block format.

Functions

compress()

compress.lz4.compress(data) -> bytes

Compress data using the Lz4 block format. The uncompressed size will be prepended as a little endian unsigned integer 32.

Parameters

• data (bytes|string)
• level (?number)

Returns bytes

Note: This is the block format, not the frame format: Lz4Encoder/Lz4Decoder use a genuinely different, mutually incompatible binary layout. Data compressed here can only be decompressed with decompress(), never with Lz4Decoder, and vice versa.

decompress()

compress.lz4.decompress(data) -> bytes

Decompress a Lz4 compressed data. The first 4 bytes are expected to be the uncompressed size in little endian.

Parameters

• data (bytes|string)

Returns bytes

Note: This expects the block format compress() produces, not the frame format Lz4Encoder produces: passing Lz4Encoder output here will fail (and vice versa for Lz4Decoder given compress() output). See the module docs.

Classes

Lz4Encoder

class compress.lz4.Lz4Encoder

Streaming lz4 compressor implemention. Data written to this encoder are compressed using the LZ4 frame format and are automatically buffered.

To ensure a well formed stream the encoder must be finalized by calling the finish() method.

Example:

%> import compress.lz4
%> var encoder = lz4.Lz4Encoder()
%> encoder.write('hello world')
11
%> encoder.finish()
(04 22 4d 18 60 40 82 0b 00 00 80 68 65 6c 6c 6f 20 77 6f 72 6c 64 00 00 00 00)

Note: This produces the LZ4 frame format: decode it with Lz4Decoder, not the one-shot decompress() (which expects a different, incompatible block format). See the module docs.

Constructor

compress.lz4.Lz4Encoder()

Creates a new streaming Lz4 encoder.

Lz4Encoder.finish()

compress.lz4.Lz4Encoder.finish() -> bytes

Flushes remaining data, writes the content checksum, and returns the inner byte stream.

Returns bytes

Note: Once finish is called, the encoder can no longer be reused.

Lz4Encoder.close()

compress.lz4.Lz4Encoder.close() -> bytes

Same as finish() for file API compartibility.

Returns bytes

Note: Once finish is called, the encoder can no longer be reused.

Lz4Encoder.write()

compress.lz4.Lz4Encoder.write(data) -> number

Writes data into this encoder’s byte stream, returning how many bytes were written.

Parameters

• data (bytes|string)

Returns number

Lz4Encoder.write_all()

compress.lz4.Lz4Encoder.write_all(data)

Attempts to write an entire data into this encoder’s byte stream.

Parameters

• data (bytes|string)

Lz4Encoder.flush()

compress.lz4.Lz4Encoder.flush()

Flushes this output stream, ensuring that all intermediately buffered contents reach their destination.

Lz4Decoder

class compress.lz4.Lz4Decoder

Streaming reader for decompressing the LZ4 frame format. Bytes read will be decompressed according to the LZ4 frame format.

Example:

%> import compress.lz4
%> var x = lz4.Lz4Encoder()
%> x.write('hello world')
11
%> var g = x.finish()
%> g
(04 22 4d 18 60 40 82 0b 00 00 80 68 65 6c 6c 6f 20 77 6f 72 6c 64 00 00 00 00)
%> 
%> var f = lz4.Lz4Decoder(g)
%> f.read_as_string()
hello world

Note: This reads the LZ4 frame format produced by Lz4Encoder: it cannot decode the one-shot compress()’s block format (use decompress() for that instead). See the module docs.

Constructor

compress.lz4.Lz4Decoder(source)

Creates a Lz4 decoder

Parameters

• source (bytes)

Lz4Decoder.close()

compress.lz4.Lz4Decoder.close()

No op. Just for file API compartibility.

Lz4Decoder.read()

compress.lz4.Lz4Decoder.read(length) -> bytes

Reads some bytes up to the amount of bytes specified by length from the current source. Returns an empty byte stream when there is no more data to read.

This function does not block or wait waiting for data, but reads as much data as is available to read when it runs.

Parameters

• length (number)

Returns bytes

Lz4Decoder.read_exact()

compress.lz4.Lz4Decoder.read_exact(length) -> bytes

Reads the exact number of bytes from the buffer. This method will raise an error if it encounters an unexpected EOF (end of file) or there are insufficient data to read to complete the required number of bytes.

Parameters

• length (number)

Returns bytes

Lz4Decoder.read_all()

compress.lz4.Lz4Decoder.read_all() -> bytes

Reads all remaining bytes until EOF is encountered in the source.

Returns bytes

Lz4Decoder.read_as_string()

compress.lz4.Lz4Decoder.read_as_string() -> string

Reads all remaining bytes until EOF is encountered in the source and returns the data read as a string instead of a byte stream.

Returns string

2021, Richard Ore and Zuri contributors