httk.core.datastream.compression

Classes

CompressionCodec

A decompression codec for a single container format.

Functions

register_compression(codec)	Register (or replace) a codec under its name (case-insensitive).
known_compressions()	Return the registered codec names, in registration order.
codec_for_name(name)	Return the codec whose extension matches the trailing suffix of name, else None.
split_compression_suffix(name)	Split a trailing compression extension off name.
sniff_codec(stream)	Detect a codec from the leading magic bytes of stream without consuming data.
open_compressed(stream, *[, compression, name])	Return a decompressed view of stream according to the compression hint.
validate_compression(compression)	Raise ValueError unless compression is a known mode or registered codec name.
reject_text_native_compression(compression)	Validate a compression hint for a text-native source (an open text stream or a string).

Module Contents

class httk.core.datastream.compression.CompressionCodec

A decompression codec for a single container format.

A codec is an orthogonal layer below the datastream backends: it turns a compressed binary stream into an uncompressed binary stream, independently of where the compressed bytes come from (a filename, an open file, raw bytes, or a remote response).

Parameters:

• name – Canonical name used to select the codec explicitly.

• extensions – Filename suffixes that identify the codec.

• magics – Leading byte signatures used to detect the codec.

• open_stream – Function that wraps compressed bytes for reading.

name: str

Canonical, lower-case codec name (e.g. "gzip"); also how an explicit hint selects it.

extensions: tuple[str, Ellipsis]

Recognized filename suffixes including the leading dot (e.g. (".gz",)).

magics: tuple[bytes, Ellipsis]

Leading magic-byte signatures; an empty tuple means the format cannot be sniffed.

open_stream: collections.abc.Callable[[io.IOBase], io.IOBase]

Wrap a compressed binary stream and return a readable, decompressed binary stream.

httk.core.datastream.compression.register_compression(codec)

Register (or replace) a codec under its name (case-insensitive).

Parameters:

codec (CompressionCodec) – Codec to add to the registry.

httk.core.datastream.compression.known_compressions()

Return the registered codec names, in registration order.

Returns:

The registered codec names.

Return type:

list[str]

httk.core.datastream.compression.codec_for_name(name)

Return the codec whose extension matches the trailing suffix of name, else None.

Parameters:

name (str) – Filename or URL path to inspect.

Returns:

The matching codec, or None when no suffix is recognized.

Return type:

CompressionCodec | None

httk.core.datastream.compression.split_compression_suffix(name)

Split a trailing compression extension off name.

"data.json.gz" becomes ("data.json", <gzip codec>); a name with no recognized compression extension is returned unchanged with None.

Parameters:

name (str) – Filename or URL path to split.

Returns:

The name without its recognized suffix and the matching codec, if any.

Return type:

tuple[str, CompressionCodec | None]

httk.core.datastream.compression.sniff_codec(stream)

Detect a codec from the leading magic bytes of stream without consuming data.

A seekable stream is read and rewound; an unseekable stream is peeked (directly when it supports peek, otherwise via a wrapping io.BufferedReader). The returned stream must be used in place of the input, since it may be the wrapper.

Parameters:

stream (io.IOBase) – Binary stream whose leading bytes should be inspected.

Returns:

The stream to continue reading and the detected codec, if any.

Return type:

tuple[io.IOBase, CompressionCodec | None]

httk.core.datastream.compression.open_compressed(stream, *, compression='auto', name=None)

Return a decompressed view of stream according to the compression hint.

Values are "none" (passthrough), "extension" (decide from name only), "detect" (always sniff magic bytes), "auto" (extension if recognized, else sniff), or a registered codec name (force that codec; an unknown name raises ValueError). When no codec applies the stream is returned unchanged.

Parameters:

• stream (io.IOBase) – Compressed or uncompressed binary stream to expose.

• compression (str) – Mode or codec name controlling decompression.

• name (str | None) – Optional source name used for extension-based selection.

Returns:

A decompressed stream, or the original stream when no codec applies.

Raises:

ValueError – If compression names an unknown codec.

Return type:

io.IOBase

httk.core.datastream.compression.validate_compression(compression)

Raise ValueError unless compression is a known mode or registered codec name.

Parameters:

compression (str) – Mode or codec name to validate.

Raises:

ValueError – If compression is unknown.

httk.core.datastream.compression.reject_text_native_compression(compression)

Validate a compression hint for a text-native source (an open text stream or a string).

Such sources carry no compressed bytes to decode, so only the no-op modes "auto", "extension", and "none" are accepted; a codec name or "detect" raises ValueError. None (no hint given) is accepted.

Parameters:

compression (str | None) – Optional compression hint supplied for a text-native source.

Raises:

ValueError – If the hint requests native decompression or magic detection.