ntcompress.ese

ntcompress.ese

ESE (Extensible Storage Engine) record-compression formats.

Provides both Shape A (enum dispatch) and Shape B (direct module import) APIs for every ESE record-compression scheme. The Format enum values are the 5-bit scheme IDs extracted from the first byte of a compressed ESE cell, matching the CDataCompressor::COMPRESSION_SCHEME constants in the MIT ESE source.

Shape A (enum dispatch)::

import ntcompress.ese
compressed = ntcompress.ese.compress(data, ntcompress.ese.Format.XPRESS)
plain = ntcompress.ese.decompress(compressed)  # auto-detects format

Shape B (direct module)::

from ntcompress.ese import xpress
compressed = xpress.compress(data)
plain = xpress.decompress(compressed)

Format

Bases: IntEnum

ESE record-compression format identifiers.

Values are the 5-bit scheme IDs extracted from the first byte of a compressed ESE cell. See CDataCompressor::COMPRESSION_SCHEME in the MIT-licensed ESE source (compression.cxx:504-512).

NONE = 0 class-attribute instance-attribute

Sentinel -- uncompressed cell, no compression header.

SEVEN_BIT_ASCII = 1 class-attribute instance-attribute

7-bit ASCII packing (compression.cxx:1168-1387).

SEVEN_BIT_UNICODE = 2 class-attribute instance-attribute

7-bit Unicode packing over UTF-16LE code units (compression.cxx:1390-1504).

XPRESS = 3 class-attribute instance-attribute

Plain LZ77 ([MS-XCA] §2.1) with 3-byte ESE frame (compression.cxx:1507-1568).

SCRUB = 4 class-attribute instance-attribute

Erase marker -- not a compression format. Use :mod:ntcompress.ese.scrub.

XPRESS9 = 5 class-attribute instance-attribute

LZ77+Huffman9 with ESE frame (compression.cxx:1686-1759).

XPRESS10 = 6 class-attribute instance-attribute

LZ4 block + CRC-32C/CRC-64 integrity (compression.cxx:1935-2064).

LZ4 = 7 class-attribute instance-attribute

Raw LZ4 block with 3-byte ESE frame (compression.cxx:2070-2109).

MAXIMUM = 31 class-attribute instance-attribute

Sentinel -- upper bound of the 5-bit scheme space, not a real format.

compress(data: Buffer, fmt: Format) -> bytes

Encode plaintext into a framed ESE cell using the specified format.

Parameters:

Name	Type	Description	Default
data	Buffer	The plaintext to compress.	required
fmt	Format	The ESE compression format to use.	required

Raises:

Type	Description
CompressionError	The format is a sentinel (NONE, SCRUB, MAXIMUM), or the input cannot be encoded by the requested format.
FormatUnavailableError	No codec is registered, or the codec does not support compression (decode-only).

decompress(blob: Buffer, fmt: Format | None = None) -> bytes

Decode a framed ESE cell.

When fmt is None, the format is auto-detected from the header byte.

Parameters:

Name	Type	Description	Default
blob	Buffer	The framed cell, including the header byte.	required
fmt	Format | None	The format to use, or None for auto-detection.	None

Raises:

Type	Description
DecompressionError	Empty buffer, unknown format id, or decode failure.
ScrubDetectedError	The record is a SCRUB (0x4) erase marker.
FormatUnavailableError	The format is known but no codec is registered.

decompressed_size(blob: Buffer) -> int

Return a framed cell's recorded plaintext length without decoding.

Auto-detects the format from the header byte.

Raises:

Type	Description
DecompressionError	Empty buffer or unknown format id.
ScrubDetectedError	The record is a SCRUB erase marker.
FormatUnavailableError	The format is known but no codec is registered.

format_id(first_byte: int) -> int

Extract the 5-bit format ID from an ESE cell's header byte.

Returns first_byte >> 3 (0-31). Callers map this to a :class:Format member.

format_flags(first_byte: int) -> int

Extract the 3 format-specific flag bits from an ESE cell's header byte.

Returns first_byte & 0x7. Meaning is format-specific.

header_byte(fmt: Format, flags: int = 0) -> int

Build a record header byte from a format id and optional flag bits.

Returns (fmt << 3) | (flags & 0x7).