ZipStream Class

Properties   Methods   Events   Config Settings   Errors  

The ZipStream class is used to perform compression or decompression.

Syntax

class ipworkszip.ZipStream

Remarks

The ZipStream class provides a way to compress and decompress streamed data.

Data may be operated on in multiple ways as discussed below. The stream_format property specifies the algorithm to us. Possible values are:

• Deflate
• Zlib
• Gzip

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 it becomes available.

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

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

Compress Data

Set input_data to the current block to be compressed. Next call compress_block to compress the current block. Note that compress_block takes a LastBlock parameter. If the block of data is the final block to be compressed set this to True. For all other blocks set this to 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. For example:

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

Note that output_data is not applicable when compressing block data.

Decompress Data

Set input_data to the current block to be decompressed. Next call decompress_block 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. For example:

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 output_data 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 input_data before calling either method.

To compress and decompress data in blocks (chunks) see compress_block and decompress_block.

Compress Data

Set input_data to the decompressed data. This should be the entire data to be compressed. Next call compress_data. After compression output_data will hold the compressed data. For example:

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

Set input_data to the compressed data. This should be the entire data to be decompressed. Next call decompress_data. After decompression output_data will hold the decompressed data. For example:

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

In addition to output_data, the compressed 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.

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

The compression level to use, from 1 to 6. Higher values will cause the component to compress better; lower values will cause the component to compress faster.

When get_compression_stream is invoked the stream will be created with the specified compression level. After a stream has been created it is independent of the control, and changing compression_level will have no effect on existing streams.

input_data Property

Specifies 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 calling decompress_data or decompress_block.

When compressing this should be set to the decompressed data before calling compress_data or compress_block.

When performing operations on multiple chunks of data, note that this property is not automatically cleared after each operation.

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 compress_data or decompress_data is called.

This property is not applicable when calling compress_block or decompress_block.

This property is read-only.

stream_format Property

The stream format to use.

Syntax

def get_stream_format() -> int: ...
def set_stream_format(value: int) -> None: ...

stream_format = property(get_stream_format, set_stream_format)

Default Value

0

Remarks

The stream format to use, by default Deflate.

All three stream formats use the Deflate algorithm specified in RFC 1951, which is the same algorithm used by Zip. The Zlib stream format adds a two-byte header and an Adler-32 checksum; the Gzip format adds a longer header and a CRC checksum, and is identical to the Gzip file format.

Caution: The terms zlib and deflate are sometimes used interchangeably (which is technically incorrect).

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 input_data.

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

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

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

Compress Data

Set input_data to the current block to be compressed. Next call compress_block to compress the current block. Note that compress_block takes a LastBlock parameter. If the block of data is the final block to be compressed set this to True. For all other blocks set this to 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. For example:

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

Note that output_data is not applicable when compressing block data.

Decompress Data

Set input_data to the current block to be decompressed. Next call decompress_block 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. For example:

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 output_data 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 input_data. After calling this method output_data 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 input_data before calling either method.

To compress and decompress data in blocks (chunks) see compress_block and decompress_block.

Compress Data

Set input_data to the decompressed data. This should be the entire data to be compressed. Next call compress_data. After compression output_data will hold the compressed data. For example:

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

Set input_data to the compressed data. This should be the entire data to be decompressed. Next call decompress_data. After decompression output_data will hold the decompressed data. For example:

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

In addition to output_data, the compressed 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 input_data.

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

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

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

Compress Data

Set input_data to the current block to be compressed. Next call compress_block to compress the current block. Note that compress_block takes a LastBlock parameter. If the block of data is the final block to be compressed set this to True. For all other blocks set this to 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. For example:

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

Note that output_data is not applicable when compressing block data.

Decompress Data

Set input_data to the current block to be decompressed. Next call decompress_block 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. For example:

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 output_data 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 input_data. After calling this method output_data 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 input_data before calling either method.

To compress and decompress data in blocks (chunks) see compress_block and decompress_block.

Compress Data

Set input_data to the decompressed data. This should be the entire data to be compressed. Next call compress_data. After compression output_data will hold the compressed data. For example:

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

Set input_data to the compressed data. This should be the entire data to be decompressed. Next call decompress_data. After decompression output_data will hold the decompressed data. For example:

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

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

reset Method

Resets the class.

Syntax

def reset() -> None: ...

Remarks

reset resets the state of the class. All properties will be set to their default values, and any files open will be closed.

on_compressed_data Event

This event fires with compressed data.

Syntax

class ZipStreamCompressedDataEventParams(object):
  @property
  def data() -> bytes: ...

# In class ZipStream:
@property
def on_compressed_data() -> Callable[[ZipStreamCompressedDataEventParams], None]: ...
@on_compressed_data.setter
def on_compressed_data(event_hook: Callable[[ZipStreamCompressedDataEventParams], None]) -> None: ...

Remarks

The on_compressed_data event fires as compressed data is available when compress_data or compress_block is called. This may fire one or more times when data is compressed.

Data holds the current block of compressed data.

on_decompressed_data Event

This event fires with decompressed data.

Syntax

class ZipStreamDecompressedDataEventParams(object):
  @property
  def data() -> bytes: ...

# In class ZipStream:
@property
def on_decompressed_data() -> Callable[[ZipStreamDecompressedDataEventParams], None]: ...
@on_decompressed_data.setter
def on_decompressed_data(event_hook: Callable[[ZipStreamDecompressedDataEventParams], None]) -> None: ...

Remarks

The on_decompressed_data event fires as compressed data is available when decompress_data or decompress_block is called. This may fire one or more times as data is decompressed.

Data holds the current block of decompressed data.

on_error Event

Information about errors during data delivery.

Syntax

class ZipStreamErrorEventParams(object):
  @property
  def error_code() -> int: ...

  @property
  def description() -> str: ...

# In class ZipStream:
@property
def on_error() -> Callable[[ZipStreamErrorEventParams], None]: ...
@on_error.setter
def on_error(event_hook: Callable[[ZipStreamErrorEventParams], None]) -> None: ...

Remarks

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

ErrorCode 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.

ZipStream 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

ZipStream Errors

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

ZipStream Errors