Skip to main content

compression - API Specification

Version: v1.1.9 | Status: Active | Last Updated: February 2026

Overview​

The compression module provides data compression and archive management utilities supporting multiple formats including gzip, zlib, and zip.

Classes​

Compressor​

Main compression utility class supporting multiple formats.

from codomyrmex.compression import Compressor

Constructor​

Compressor(format: str = "gzip")
ParameterTypeDefaultDescription
formatstr"gzip"Compression format: "gzip", "zlib", or "zip"

Methods​

compress​
def compress(data: bytes, level: int = 6) -> bytes

Compress data using the configured format.

ParameterTypeDefaultDescription
databytes-Data to compress
levelint6Compression level (0-9, higher = more compression)

Returns: bytes - Compressed data

Raises: CompressionError if compression fails

decompress​
def decompress(data: bytes) -> bytes

Decompress data using the configured format.

ParameterTypeDescription
databytesCompressed data

Returns: bytes - Decompressed data

Raises: CompressionError if decompression fails

compress_stream​
def compress_stream(input_stream: IO[bytes], output_stream: IO[bytes], level: int = 6) -> None

Compress data from input stream to output stream.

ParameterTypeDescription
input_streamIO[bytes]Input stream
output_streamIO[bytes]Output stream
levelintCompression level
decompress_stream​
def decompress_stream(input_stream: IO[bytes], output_stream: IO[bytes]) -> None

Decompress data from input stream to output stream.

detect_format​
def detect_format(data: bytes) -> Optional[str]

Detect compression format from data magic bytes.

Returns: Format name ("gzip", "zlib", "zip") or None if unknown

ArchiveManager​

Archive creation and extraction utility.

from codomyrmex.compression import ArchiveManager

Methods​

create_archive​
def create_archive(files: list[Path], output_path: Path, format: str = "zip") -> bool

Create an archive from files.

extract_archive​
def extract_archive(archive_path: Path, output_dir: Path) -> bool

Extract archive to directory.

Exceptions​

CompressionError​

from codomyrmex.compression import CompressionError

Raised when compression or decompression operations fail. Inherits from CodomyrmexError.

Usage Examples​

Basic Compression​

from codomyrmex.compression import Compressor

# Create gzip compressor
compressor = Compressor("gzip")

# Compress data
data = b"Hello, World!" * 100
compressed = compressor.compress(data, level=9)

# Decompress
decompressed = compressor.decompress(compressed)
assert decompressed == data

Format Detection​

from codomyrmex.compression import Compressor

compressor = Compressor()
format_name = compressor.detect_format(compressed_data)
print(f"Detected format: {format_name}")

Stream Compression​

from io import BytesIO
from codomyrmex.compression import Compressor

compressor = Compressor("zlib")

input_buffer = BytesIO(b"Large data to compress...")
output_buffer = BytesIO()

compressor.compress_stream(input_buffer, output_buffer)
compressed = output_buffer.getvalue()

Integration​

Dependencies​

  • Python standard library (gzip, zlib, zipfile)
  • codomyrmex.logging_monitoring for logging
  • codomyrmex.exceptions for error handling