Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

compress.zlib

import compress

Everything here is re-exported by compress, so import compress is enough and the names are called as compress.*. Importing compress.zlib on its own works too and reaches the same definitions.

This is the Zlib submodule for the compress module.

Constants

NO_COMPRESSION

compress.NO_COMPRESSION: number = 0

No compression level.

BEST_SPEED

compress.BEST_SPEED: number = 1

Best speed compression.

BEST_COMPRESSION

compress.BEST_COMPRESSION: number = 9

Best compression level.

DEFAULT_COMPRESSION

compress.DEFAULT_COMPRESSION: number

Default compression level.

FILTERED

compress.FILTERED: number = 1

Filtered compression strategy.

HUFFMAN_ONLY

compress.HUFFMAN_ONLY = 2

huffman only compression strategy

RLE

compress.RLE: number = 3

Rle compression strategy.

FIXED

compress.FIXED: number = 4

Fixed compression strategy.

DEFAULT_STRATEGY

compress.DEFAULT_STRATEGY: number = 0

Default compression strategy.

DEFAULT_MEMORY_LEVEL

compress.DEFAULT_MEMORY_LEVEL: number = 8

Default memory level

MAX_WBITS

compress.MAX_WBITS: number = 15

Maximum windows bit.

Functions

compress()

compress.compress(data, level, strategy, wbits, memory_level) -> bytes

Compress compresses as much data as possible, and stops when the input buffer becomes empty or the output buffer becomes full.

  • The compression level must be DEFAULT_COMPRESSION, or between 0 and 9: 1 gives best speed, 9 gives best compression, 0 gives no compression at all (the input data is simply copied a block at a time). DEFAULT_COMPRESSION requests a default compromise between speed and compression (currently equivalent to level 6)

  • The wbits parameter is the base two logarithm of the window size (the size of the history buffer). It should be in the range 8..15 for this version of the library. Larger values of this parameter result in better compression at the expense of memory usage. The default value is 15.

For the current implementation of compress(), a wbits value of 8 (a window size of 256 bytes) is not supported. As a result, a request for 8 will result in 9 (a 512-byte window).

wbits can also be -8..-15 for raw compress. In this case, -wbits determines the window size. compress() will then generate raw compress data with no zlib header or trailer, and will not compute a check value.

wbits can also be greater than 15 for optional gzip encoding. Add 16 to wbits to write a simple gzip header and trailer around the compressed data instead of a zlib wrapper. The gzip header will have no file name, no extra data, no comment, no modification time (set to zero), no header crc, and the operating system will be set to the appropriate value, if the operating system can be determined by the runtime.

For raw compress or gzip encoding, a request for a 256-byte window is rejected as invalid, since only the zlib header provides a means of transmitting the window size to the uncompressor.

  • The strategy parameter is used to tune the compression algorithm. Use the value DEFAULT_STRATEGY for normal data, FILTERED for data produced by a filter (or predictor), HUFFMAN_ONLY to force Huffman encoding only (no string match), or RLE to limit match distances to one (run-length encoding). Filtered data consists mostly of small values with a somewhat random distribution. In this case, the compression algorithm is tuned to compress them better. The effect of FILTERED is to force more Huffman coding and less string matching; it is somewhat intermediate between DEFAULT_STRATEGY and HUFFMAN_ONLY. RLE is designed to be almost as fast as HUFFMAN_ONLY, but give better compression for PNG image data. The strategy parameter only affects the compression ratio but not the correctness of the compressed output even if it is not set appropriately. FIXED prevents the use of dynamic Huffman codes, allowing for a simpler decoder for special applications.

  • The memory_level parameter specifies how much memory should be allocated for the internal compression state. memory_level 1 uses minimum memory but is slow and reduces compression ratio; memory_level 9 uses maximum memory for optimal speed. The default value is 8.

{.list}

Parameters

  • data (bytes|string)
  • level (?int) — Default value is DEFAULT_COMPRESSION.
  • strategy (?int) — Default value is DEFAULT_STRATEGY.
  • wbits (?int) — Default value is MAX_WBITS.
  • memory_level (?int) — Default value is DEFAULT_MEMORY_LEVEL.

Returns bytes

decompress()

compress.decompress(data, wbits) -> bytes

Decompress decompresses as much data as possible, and stops when the input buffer becomes empty or the output buffer becomes full.

  • In this implementation, decompress() always flushes as much output as possible to the output buffer, and always uses the faster approach on the first call.

  • The wbits parameter is the base two logarithm of the maximum window size (the size of the history buffer). It should be in the range 8..15 for this version of the library. The default value is

  1. wbits must be greater than or equal to the wbits value provided to compress() while compressing, or it must be equal to 15 if compress() is used with the default values. If a compressed stream with a larger window size is given as input, decompress() will return with the error code data error instead of trying to allocate a larger window.

wbits can also be zero to request that decompress use the window size in the zlib header of the compressed stream.

wbits can also be -8..-15 for raw decompress. In this case, -wbits determines the window size. decompress() will then process raw compress data, not looking for a zlib or gzip header, not generating a check value, and not looking for any check values for comparison at the end of the stream. This is for use with other formats that use the compress compressed data format such as zip. Those formats provide their own check values. If a custom format is developed using the raw compress format for compressed data, it is recommended that a check value such as an Adler-32 or a CRC-32 be applied to the uncompressed data as is done in the zlib, gzip, and zip formats. For most applications, the zlib format should be used as is. Note that comments on the use in compress() applies to the magnitude of wbits.

wbits can also be greater than 15 for optional gzip decoding. Add 32 to wbits to enable zlib and gzip decoding with automatic header detection, or add 16 to decode only the gzip format (the zlib format will return a data error). decompress() will not automatically decode concatenated gzip streams.

  • decompress() can decompress either zlib-wrapped or gzip-wrapped compress data. If the compression uses gzip-wrapper, the correct wbits may need to be set.

Parameters

  • data (bytes|string)
  • wbits (?int) — Default value is MAX_WBITS.

Returns bytes

Classes

ZlibEncoder

class compress.ZlibEncoder < GzipEncoder

A streaming Deflate encoder.

Example:

%> import compress.zlib
%> var encoder = zlib.ZlibEncoder()
%> encoder.write('hello world')
11
%> encoder.finish()
(78 01 cb 48 cd c9 c9 57 28 cf 2f ca 49 01 00 1a 0b 04 5d)

Constructor

compress.ZlibEncoder(level)

Creates a new streaming Deflate encoder at the given level (0..=9).

Parameters

  • level (?number) — Default 1

ZlibDecoder

class compress.ZlibDecoder < GzipDecoder

Streaming zlib decompressor implemention. This decoder reads standard zlib blocks and frames produced at any zlib compression level.

Wraps a byte stream of compressed data and yields decompressed bytes.

Example:

%> import compress.zlib
%> var data = zlib.compress('hello world')
%> data
(78 9c cb 48 cd c9 c9 57 28 cf 2f ca 49 01 00 1a 0b 04 5d)
%>
%> var decoder = zlib.ZlibDecoder(data)
%> decoder.read_as_string()
hello world

This decoder is level-independent and supports standard zlib frames produced by all zlib compression levels.

Constructor

compress.ZlibDecoder(source)

Creates a Zlib decoder

Parameters

  • source (bytes)

2021, Richard Ore and Zuri contributors