`compress.gzip`

import compress

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

The is the GZip submodule for the compress module.

Functions

`compress()`

compress.gzip.compress(data) -> bytes

Compress data using the default options for GZip.

Parameters

data (bytes|string)

Returns bytes

`decompress()`

compress.gzip.decompress(data) -> bytes

Decompress a GZipped data using default options.

Parameters

data (bytes|string)

Returns bytes

Classes

`GzipEncoder`

class compress.gzip.GzipEncoder

A streaming GZip encoder.

Example:

%> import compress.gzip
%> var encoder = gzip.GzipEncoder()
%> encoder.write('hello world')
11
%> encoder.finish()
(1f 8b 08 00 00 00 00 00 04 03 cb 48 cd c9 c9 57 28 cf 2f ca 49 01 00 85 11 4a 0d 0b 00 00 00)

Constructor

compress.gzip.GzipEncoder(level)

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

Parameters

level (?number) — Default 1

`GzipEncoder.finish()`

compress.gzip.GzipEncoder.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.

`GzipEncoder.close()`

compress.gzip.GzipEncoder.close() -> bytes

Same as finish() for file API compartibility.

Returns bytes

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

`GzipEncoder.reset()`

compress.gzip.GzipEncoder.reset() -> bytes

Finishes the current frame and installs byte stream for the next one.

Returns the previous byte stream containing the completed frame. All internal buffers (hash tables, workspace, block scratch) stay allocated and are reused for the next frame.

Returns bytes

`GzipEncoder.write()`

compress.gzip.GzipEncoder.write(data) -> number

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

Parameters

data (bytes|string)

Returns number

`GzipEncoder.flush()`

compress.gzip.GzipEncoder.flush() -> bytes

Flushes this output stream and returns the remaining compressed data in the stream, ensuring that all intermediately buffered contents reach their destination.

Returns bytes

`GzipEncoder.available()`

compress.gzip.GzipEncoder.available() -> number

Returns the number of compressed bytes currently waiting in the encoder’s output buffer.

Returns number

`GzipEncoder.finished()`

compress.gzip.GzipEncoder.finished() -> bool

Returns whether finish() has completed the stream.

Returns bool

`GzipEncoder.total_in()`

compress.gzip.GzipEncoder.total_in() -> number

Number of uncompressed bytes consumed by the encoder.

Returns number

`GzipEncoder.total_out()`

compress.gzip.GzipEncoder.total_out() -> number

Number of compressed bytes generated by the encoder.

Returns number

`GzipDecoder`

class compress.gzip.GzipDecoder

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

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

Example:

%> import compress.gzip
%> var data = gzip.compress('hello world')
%> data
(1f 8b 08 00 00 00 00 00 00 03 cb 48 cd c9 c9 57 28 cf 2f ca 49 01 00 85 11 4a 0d 0b 00 00 00)
%>
%> var decoder = gzip.GzipDecoder(data)
%> decoder.read_as_string()
hello world

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

Constructor

compress.gzip.GzipDecoder(source)

Creates a Gzip decoder

Parameters

source (bytes)

`GzipDecoder.reset()`

compress.gzip.GzipDecoder.reset(new_source)

Installs a new data source for the next frame, keeping all internal buffers allocated.

Parameters

new_source (bytes)

`GzipDecoder.close()`

compress.gzip.GzipDecoder.close()

Closes the decoder by resetting it into an empty stream.

`GzipDecoder.read()`

compress.gzip.GzipDecoder.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

`GzipDecoder.read_exact()`

compress.gzip.GzipDecoder.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

`GzipDecoder.read_all()`

compress.gzip.GzipDecoder.read_all() -> bytes

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

Returns bytes

`GzipDecoder.read_as_string()`

compress.gzip.GzipDecoder.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

`GzipDecoder.available()`

compress.gzip.GzipDecoder.available() -> number

Returns the number of compressed bytes currently waiting in the decoder’s output buffer.

Returns number

`GzipDecoder.finished()`

compress.gzip.GzipDecoder.finished() -> bool

Returns whether finish() has completed the stream.

Returns bool

`GzipDecoder.total_in()`

compress.gzip.GzipDecoder.total_in() -> number

Number of compressed bytes consumed by the decoder.

Returns number

`GzipDecoder.total_out()`

compress.gzip.GzipDecoder.total_out() -> number

Number of uncompressed bytes generated by the decoder.

Returns number

`GzFile`

class compress.gzip.GzFile

The GzFile class implements a GZip based I/O system that allows you use treat Gzip streams (bytes) as if they were a file.

The class implements the essentials of a file except those that ties it to the operating system filesystem such as symbolic links, chmod and set time.

See the chapter on files in The Zuri Programming Language for more information.

Constructor

compress.gzip.GzFile(path: string, mode: ?string, _inner)

Returns a new GzFile object bounded to a physical file at the given path and opened in the given mode. See [[file]] for a description of the supported file modes.

Parameters

path (string)
mode (?string)

Returns GzFile

`GzFile.exists()`

compress.gzip.GzFile.exists() -> bool

Returns true if the underlying file bounded to GzFile actually exists or false otherwise.

Returns bool

`GzFile.close()`

compress.gzip.GzFile.close()

Closes the stream to an opened GzFile. You’ll rarely ever need to call this method yourself in most use cases.

`GzFile.flush()`

compress.gzip.GzFile.flush() -> bytes

Flushes the remaning data into the GzFile underlying file and returns the byte stream returned.

Returns bytes

`GzFile.open()`

compress.gzip.GzFile.open() -> bool

Opens the stream to a GzFile for the operation originally specified on the GzFile object during creation.

You may need to call this method after a call to read() if the length isn’t specified or write() if you wish to read or write again as the GzFile will already be closed.

Returns bool

`GzFile.read()`

compress.gzip.GzFile.read(length: ?number) -> bytes

Reads the content of an opened GzFile up to the specified length and returns it as string or bytes if the GzFile was opened in the binary mode. If the length is not specified, the GzFile will be read to the end.

This method requires that the GzFile be opened in the read mode (default mode) or a mode that supports reading. If you aren’t reading the full length of the GzFile, you’ll need to call the close() method to free the GzFile for further reading, otherwise, the close() method will be automatically called for you.

Parameters

length (number) — Default = -1

Returns bytes

Raises Error

`GzFile.gets()`

compress.gzip.GzFile.gets(length: ?number) -> bytes

Same as read(), but doesn’t close the GzFile automatically.

Parameters

length (?number) — Default = -1, meaning read to the end.

Returns bytes

Raises Error

`GzFile.write()`

compress.gzip.GzFile.write(data: bytes|string) -> number

Writes a string or bytes to an opened GzFile at the current insertion point. When the GzFile is opened with the a mode enabled, write will always start from the end of the GzFile.

If the seek() method has been previously called, write will begin from the seeked position, otherwise it will start at the beginning of the GzFile.

Parameters

`` (bytes|string)

Returns number

`GzFile.puts()`

compress.gzip.GzFile.puts(data: bytes|string) -> number

Same as write(), but doesn’t open or close the GzFile automatically.

Parameters

`` (bytes|string)

Returns number

`GzFile.number()`

compress.gzip.GzFile.number() -> number

Returns the integer file descriptor number that is used by the underlying implementation to request I/O operations from the operating system. This can be very useful for low-level interfaces that uses or act as GzFile descriptors.

Returns number

`GzFile.is_tty()`

compress.gzip.GzFile.is_tty() -> bool

Returns true if the underlying file of GzFile is a TTY device or false otherwise.

Returns bool

`GzFile.is_open()`

compress.gzip.GzFile.is_open() -> bool

Returns true if the GzFile is open for reading or writing and false otherwise.

Returns bool

`GzFile.is_closed()`

compress.gzip.GzFile.is_closed()

Returns true if the GzFile is closed for reading or writing and false otherwise.

`GzFile.symlink()`

compress.gzip.GzFile.symlink(path: string) -> bool

See [[file.symlink]]

Returns bool

`GzFile.stats()`

compress.gzip.GzFile.stats() -> dict

Returns the statistics or details of the GzFile.

See the working with files documentation for more information about the stats() method.

Returns dict

`GzFile.delete()`

compress.gzip.GzFile.delete() -> bool

Deletes the underlying file pointed to by GzFile

Any further attempt to perform most operations on the GzFile after calling delete() will raise an error.

Returns bool

`GzFile.rename()`

compress.gzip.GzFile.rename(new_name) -> bool

Renames the underlying file pointed to by GzFile to the new name and returns true if it succeeds or false otherwise.

Returns bool

`GzFile.copy()`

compress.gzip.GzFile.copy() -> [[io.GzFile]]

Returns a new GzFile reading (or writing) the same underlying path independently of this one, with its own decoder/encoder state and its own position.

Returns [[io.GzFile]]

`GzFile.path()`

compress.gzip.GzFile.path() -> string

Returns the physical path of the file pointed to by GzFile.

Returns string

`GzFile.abs_path()`

compress.gzip.GzFile.abs_path() -> string

Returns the absolute path of the physical file pointed to by GzFile.

Returns string

`GzFile.truncate()`

compress.gzip.GzFile.truncate(length: ?int) -> bool

Truncates the entire GzFile if length is not given or truncates the GzFile such that only length number of bytes is left in it.

Returns bool

`GzFile.chmod()`

compress.gzip.GzFile.chmod(number: int) -> bool

Updates the permission for the file bounded by GzFile.

Returns bool

`GzFile.set_times()`

compress.gzip.GzFile.set_times(atime: int, mtime: int) -> bool

Sets the last access time and last modified time of the GzFile.

Returns bool

`GzFile.seek()`

compress.gzip.GzFile.seek(position: int, seek_type: int) -> bool

Sets the position of a GzFile reader in the decompressed byte stream (not the raw, still-compressed bytes on disk, which have no useful correspondence to a decompressed offset). The seek_type argument must be one of [[io.SEEK_SET]], [[io.SEEK_CUR]] or [[io.SEEK_END]].

Seeking forward simply discards decompressed bytes until the target position, since a streaming decoder has no way to skip ahead without producing them. Seeking backward (or SEEK_END, which has to fully decode the stream once to learn its length) re-opens the underlying file and restarts decompression from the beginning, discarding up to the target position: an inherently expensive operation for a compressed stream, same as with any other streaming (de)compressor.

Not supported on a GzFile opened for writing.

Returns bool

`GzFile.tell()`

compress.gzip.GzFile.tell() -> number

Returns the current position of the reader in the decompressed byte stream (bytes already consumed via read()/gets()/seek()), or of the writer in the uncompressed input already fed to write()/puts() for a GzFile opened for writing.

Returns number

`GzFile.mode()`

compress.gzip.GzFile.mode() -> string

Returns the mode in which the current GzFile was opened.

Returns string

`GzFile.name()`

compress.gzip.GzFile.name() -> string

Returns the name of the file pointed to by GzFile.

Returns string

2021, Richard Ore and Zuri contributors

Keyboard shortcuts

The Zuri Standard Library