Lz4 Class

Properties   Methods   Events   Config Settings   Errors  

The Lz4 class implements an LZ4 compressor and decompressor.

Syntax

class ipworkszip.Lz4

Remarks

The Lz4 class is compliant with the LZ4 Frame Format specification. Data compressed by the class can be decompressed by any standard LZ4-compatible tool or library, and the class can in turn decompress data produced by any standard LZ4 encoder, including frames using linked blocks, block checksums, or skippable frames. Note that the legacy LZ4 frame format and LZ4 dictionaries are not supported, and frames using either are rejected with an error.

The compression_level property selects the compression level to use, from 1 (fastest) to 6 (most compact).

Data may be operated on in multiple ways as discussed below.

Compression and Decompression Streams

The get_decompression_stream and get_compression_stream methods are used to retrieve streams that read or write compressed data, as appropriate. The underlying stream should be passed to either method as a parameter.

CompressBlock and DecompressBlock

The compress_block and decompress_block methods operate on blocks (chunks) of data. The methods may be used to compress and decompress data as they become available.

Note that when using blocks of data, the output_data property is not applicable. Instead, data are made available via the on_compressed_data and on_decompressed_data events.

If all data is available ahead of time, the compress_data and decompress_data methods may be called instead.

Compress Data

THe input_data property should be set to the current block to be compressed. Next, the compress_block method should be called to compress the current block. Note that this method takes a LastBlock parameter; if the block of data is the final block to be compressed, it must be set to True. For all other blocks, it must remain False.

During compression, the on_compressed_data event will fire with the compressed data. Note that this event may not fire for every call to compress_block due to the way the compression algorithm operates.

zipstream.InputDataB = MyDecompressedData; zipstream.CompressBlock(); Data are accumulated inside the on_compressed_data event: private static void Zipstream_OnCompressedData(object sender, ZipstreamCompressedDataEventArgs e) { DoSomethingWith(e.DataB); }

Note that the output_data property is not applicable when compressing block data.

Decompress Data

The input_data property should be set to the current block to be decompressed. Next, the decompress_block method should be called to decompress the current block.

During decompression, the on_decompressed_data event will fire with the decompressed data. Note that this event may not fire for every call to decompress_block due to the way the decompression algorithm operates.

zipstream.InputDataB = MyCompressedData; zipstream.DecompressBlock(); Data is accumulated inside the on_decompressed_data event: private static void Zipstream_OnDecompressedData(object sender, ZipstreamDecompressedDataEventArgs e) { DoSomethingWith(e.DataB); }

Note that the output_data property is not applicable when decompressing block data.

CompressData and DecompressData

The compress_data and decompress_data methods operate on the complete blob of data. The entire compressed or decompressed data must be set to the input_data property before calling either method.

To compress and decompress data in blocks (chunks), refer to the compress_block and decompress_block methods.

Compress Data

The input_data property should be set to the decompressed data. This should be the entire data to be compressed. Next, the compress_data method should be called, after which the output_data property will hold the compressed data.

zipstream.InputDataB = MyDecompressedData; zipstream.CompressData(); MyCompressedData = zipstream.OutputDataB;

In addition to output_data, the compressed data may also be accumulated within the on_compressed_data event.

Decompress Data

The input_data property should be set to the compressed data. This should be the entire data to be decompressed. Next, the decompress_data method should be called, after which the output_data property will hold the decompressed data.

zipstream.InputDataB = MyCompressedData; zipstream.DecompressData(); MyDecompressedData = zipstream.OutputDataB;

In addition to output_data, the decompressed data may also be accumulated within the on_decompressed_data event.

Property List

---

The following is the full list of the properties of the class with short descriptions. Click on the links for further details.

Method List

---

The following is the full list of the methods of the class with short descriptions. Click on the links for further details.

Event List

---

The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.

Config Settings

---

The following is a list of config settings for the class with short descriptions. Click on the links for further details.

close_base_stream property

Whether or not to close the underlying stream.

Syntax

def get_close_base_stream() -> bool: ...

def set_close_base_stream(value: bool) -> None: ...


close_base_stream = property(get_close_base_stream, set_close_base_stream)

Default Value

True

Remarks

This property controls whether streams created via the get_compression_stream and get_decompression_stream methods will close their underlying streams when their Close method is invoked.

When enabled, the underlying streams are closed; otherwise, they will remain open.

compression_level property

The compression level to use.

Syntax

def get_compression_level() -> int: ...

def set_compression_level(value: int) -> None: ...


compression_level = property(get_compression_level, set_compression_level)

Default Value

4

Remarks

This property dictates the compression level to use, from 1 to 6. Higher values will cause the class to compress better; lower values will cause the class to compress faster.

input_data property

The data to compress or decompress.

Syntax

def get_input_data() -> bytes: ...

def set_input_data(value: bytes) -> None: ...


input_data = property(get_input_data, set_input_data)

Default Value

""

Remarks

This property specifies the data to compress or decompress.

When decompressing, this should be set to the compressed data before the decompress_data or decompress_block methods are called.

When compressing, this should be set to the decompressed data before the compress_data or compress_block methods are called.

Note that this property is not automatically cleared after each operation when performing operations on multiple chunks of data.

output_data property

The output data after compression or decompression.

Syntax

def get_output_data() -> bytes: ...


output_data = property(get_output_data, None)

Default Value

""

Remarks

This property holds the compressed or decompressed data after the compress_data or decompress_data methods are called.

This property is not applicable when calling the compress_block or decompress_block methods.

This property is read-only.

compress_block method

Compresses a block of data.

Syntax

def compress_block(last_block: bool) -> None: ...

Remarks

This method compresses the block of data specified by the input_data property.

The compress_block and decompress_block methods operate on blocks (chunks) of data. The methods may be used to compress and decompress data as they become available.

Note that when using blocks of data, the output_data property is not applicable. Instead, data are made available via the on_compressed_data and on_decompressed_data events.

If all data is available ahead of time, the compress_data and decompress_data methods may be called instead.

Compress Data

The input_data property should be set to the current block to be compressed. Next, the compress_block method should be called to compress the current block. Note that this method takes a last_block parameter; if the block of data is the final block to be compressed, it must be set to True. For all other blocks, it must remain False.

During compression, the on_compressed_data event will fire with the compressed data. Note that this event may not fire for every call to compress_block due to the way the compression algorithm operates.

zipstream.InputDataB = MyDecompressedData; zipstream.CompressBlock(); Data are accumulated inside the on_compressed_data event: private static void Zipstream_OnCompressedData(object sender, ZipstreamCompressedDataEventArgs e) { DoSomethingWith(e.DataB); }

Note that the output_data property is not applicable when compressing block data.

Decompress Data

The input_data property should be set to the current block to be decompressed. Next, the decompress_block method should be called to decompress the current block.

During decompression, the on_decompressed_data event will fire with the decompressed data. Note that this event may not fire for every call to decompress_block due to the way the decompression algorithm operates.

zipstream.InputDataB = MyCompressedData; zipstream.DecompressBlock(); Data is accumulated inside the on_decompressed_data event: private static void Zipstream_OnDecompressedData(object sender, ZipstreamDecompressedDataEventArgs e) { DoSomethingWith(e.DataB); }

Note that the output_data property is not applicable when decompressing block data.

compress_data method

Compresses the specified data.

Syntax

def compress_data() -> None: ...

Remarks

This method compresses the data specified by the input_data property. After calling this method, the output_data property holds the compressed data.

The compress_data and decompress_data methods operate on the complete blob of data. The entire compressed or decompressed data must be set to the input_data property before calling either method.

To compress and decompress data in blocks (chunks), refer to the compress_block and decompress_block methods.

Compress Data

The input_data property should be set to the decompressed data. This should be the entire data to be compressed. Next, the compress_data method should be called, after which the output_data property will hold the compressed data.

zipstream.InputDataB = MyDecompressedData; zipstream.CompressData(); MyCompressedData = zipstream.OutputDataB;

In addition to output_data, the compressed data may also be accumulated within the on_compressed_data event.

Decompress Data

The input_data property should be set to the compressed data. This should be the entire data to be decompressed. Next, the decompress_data method should be called, after which the output_data property will hold the decompressed data.

zipstream.InputDataB = MyCompressedData; zipstream.DecompressData(); MyDecompressedData = zipstream.OutputDataB;

In addition to output_data, the decompressed data may also be accumulated within the on_decompressed_data event.

config method

Sets or retrieves a configuration setting.

Syntax

def config(configuration_string: str) -> str: ...

Remarks

config is a generic method available in every class. It is used to set and retrieve configuration settings for the class.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

decompress_block method

Decompresses a block of data.

Syntax

def decompress_block() -> None: ...

Remarks

This method decompresses the block of data specified by the input_data property.

The compress_block and decompress_block methods operate on blocks (chunks) of data. The methods may be used to compress and decompress data as they become available.

Note that when using blocks of data, the output_data property is not applicable. Instead, data are made available via the on_compressed_data and on_decompressed_data events.

If all data is available ahead of time, the compress_data and decompress_data methods may be called instead.

Compress Data

The input_data property should be set to the current block to be compressed. Next, the compress_block method should be called to compress the current block. Note that this method takes a LastBlock parameter; if the block of data is the final block to be compressed, it must be set to True. For all other blocks, it must remain False.

During compression, the on_compressed_data event will fire with the compressed data. Note that this event may not fire for every call to compress_block due to the way the compression algorithm operates.

zipstream.InputDataB = MyDecompressedData; zipstream.CompressBlock(); Data are accumulated inside the on_compressed_data event: private static void Zipstream_OnCompressedData(object sender, ZipstreamCompressedDataEventArgs e) { DoSomethingWith(e.DataB); }

Note that the output_data property is not applicable when compressing block data.

Decompress Data

The input_data property should be set to the current block to be decompressed. Next, the decompress_block method should be called to decompress the current block.

During decompression, the on_decompressed_data event will fire with the decompressed data. Note that this event may not fire for every call to decompress_block due to the way the decompression algorithm operates.

zipstream.InputDataB = MyCompressedData; zipstream.DecompressBlock(); Data is accumulated inside the on_decompressed_data event: private static void Zipstream_OnDecompressedData(object sender, ZipstreamDecompressedDataEventArgs e) { DoSomethingWith(e.DataB); }

Note that the output_data property is not applicable when decompressing block data.

decompress_data method

Decompresses the specified data.

Syntax

def decompress_data() -> None: ...

Remarks

This method decompresses the data specified by the input_data property. After calling this method, the output_data property holds the decompressed data.

The compress_data and decompress_data methods operate on the complete blob of data. The entire compressed or decompressed data must be set to the input_data property before calling either method.

To compress and decompress data in blocks (chunks), refer to the compress_block and decompress_block methods.

Compress Data

The input_data property should be set to the decompressed data. This should be the entire data to be compressed. Next, the compress_data method should be called, after which the output_data property will hold the compressed data.

zipstream.InputDataB = MyDecompressedData; zipstream.CompressData(); MyCompressedData = zipstream.OutputDataB;

In addition to output_data, the compressed data may also be accumulated within the on_compressed_data event.

Decompress Data

The input_data property should be set to the compressed data. This should be the entire data to be decompressed. Next, the decompress_data method should be called, after which the output_data property will hold the decompressed data.

zipstream.InputDataB = MyCompressedData; zipstream.DecompressData(); MyDecompressedData = zipstream.OutputDataB;

In addition to output_data, the decompressed data may also be accumulated within the on_decompressed_data event.

reset method

Resets the class.

Syntax

def reset() -> None: ...

Remarks

This method is used to reset the state of the class. All properties are set to their default values, and any open files are closed.

on_compressed_data event

Fires with compressed data.

Syntax

class Lz4CompressedDataEventParams(object):
  @property
  def data() -> bytes: ...
# In class Lz4:
@property
def on_compressed_data() -> Callable[[Lz4CompressedDataEventParams], None]: ...
@on_compressed_data.setter
def on_compressed_data(event_hook: Callable[[Lz4CompressedDataEventParams], None]) -> None: ...

Remarks

This event is fired one or more times as compressed data become available when the compress_data or compress_block methods are called.

data holds the current block of compressed data.

on_decompressed_data event

Fires with decompressed data.

Syntax

class Lz4DecompressedDataEventParams(object):
  @property
  def data() -> bytes: ...
# In class Lz4:
@property
def on_decompressed_data() -> Callable[[Lz4DecompressedDataEventParams], None]: ...
@on_decompressed_data.setter
def on_decompressed_data(event_hook: Callable[[Lz4DecompressedDataEventParams], None]) -> None: ...

Remarks

This event is fired one or more times as decompressed data become available when the decompress_data or decompress_block methods are called.

data holds the current block of decompressed data.

on_error event

Fires with information about errors during data delivery.

Syntax

class Lz4ErrorEventParams(object):
  @property
  def error_code() -> int: ...
  @property
  def description() -> str: ...
# In class Lz4:
@property
def on_error() -> Callable[[Lz4ErrorEventParams], None]: ...
@on_error.setter
def on_error(event_hook: Callable[[Lz4ErrorEventParams], None]) -> None: ...

Remarks

This event is fired in case of exceptional conditions during message processing. Normally, the class fails with an error.

error_code contains an error code and description contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

Lz4 Config Settings

The class accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the config method.

No configuration settings defined.

Base Config Settings

Lz4 Errors

Note that the streams returned by get_compression_stream and get_decompression_stream will throw standard IOExceptions in case of error.

ZipStream Errors