Skip to content

abczarr.metadata.v2.codecs

Classes

Codec 

Codec(id: str | bytes = '', *, extra_items: Iterable[tuple[str | bytes, Any]] | Mapping[str | bytes, Any] = FrozenDict({}))

Bases: Metadata

A Codec names a numcodecs codec through id and carries that codec's own parameters.

A v2 codec's parameters sit directly alongside id, not nested under a separate key.

The three metadata versions spell the same codec differently. A v1 codec carries its numcodecs id as a class attribute and its parameters as fields. A v2 codec carries the id as a field alongside its parameters, as shown here. A v3 codec names itself through name and nests its parameters under a separate configuration object. The gzip codec, with its single level parameter, shows the three side by side:

>>> from abczarr.metadata import v1, v2, v3
>>> v1.GzipCodecOptions(level=1)
GzipCodecOptions(level=1)
>>> v2.GzipCodec(id="gzip", level=1)
GzipCodec(id='gzip', level=1)
>>> codec = v3.GzipCodec(name="gzip", configuration={"level": 1})
>>> codec.name, codec.configuration
('gzip', GzipConfig(level=1))

Attributes

id instance-attribute 
id: str

The numcodecs id of the codec, such as "zlib" or "blosc".

Methods:

to_version 
to_version(version: ZarrVersion) -> Codec

Convert this codec to another Zarr version.

Parameters:

Name Type Description Default
version ZarrVersion

The target Zarr format version: 1, 2 or 3.

 required

Returns:

Type Description
Codec

The equivalent codec for version: this object unchanged for version 2, or the corresponding v1 or v3 codec object otherwise.

Raises:

Type Description
ValueError

If version is not 1, 2 or 3.

CodecImpl 

CodecImpl(id: str | bytes = '')

Bases: Codec

This class is the base for a v2 codec whose options are all declared, not open-ended.

Methods:

BloscCodec 

BloscCodec(id: Literal['blosc'] = 'blosc', cname: Literal['blosclz', 'lz4', 'lz4hc', 'snappy', 'zlib', 'zstd'] = 'lz4', clevel: Literal[0, 1, 2, 3, 4, 5, 6, 7, 8, 9] = 5, shuffle: Literal[0, 1, 2, -1] = 1, blocksize: Integral | integer | bool = 0, typesize: Integral | integer | bool | None = None)

Bases: CodecImpl

Compresses data with Blosc, a meta-compressor that shuffles bytes and then applies an inner compressor.

Blosc groups same-typed bytes together before handing them to cname (one of blosclz, lz4, lz4hc, snappy, zlib or zstd), and compresses the result in blocks so multiple threads can be used.

Attributes

CodecName class-attribute instance-attribute 
CodecName: ClassVar = codecs.BloscCodecName
CompressionLevel class-attribute instance-attribute 
CompressionLevel: ClassVar = codecs.BloscCompressionLevel
Shuffle class-attribute instance-attribute 
Shuffle: ClassVar = codecs.BloscShuffle
id instance-attribute 
id: Literal['blosc']

Always "blosc".

cname class-attribute instance-attribute 
cname: CodecName = 'lz4'

The inner compressor Blosc applies.

clevel class-attribute instance-attribute 
clevel: CompressionLevel = 5

The compression level, from 0 to 9.

shuffle class-attribute instance-attribute 
shuffle: Shuffle = 1

The byte-shuffle filter applied before compression: 0 for none, 1 for byte shuffle, 2 for bit shuffle, or -1 to let Blosc choose automatically.

blocksize class-attribute instance-attribute 
blocksize: int = 0

The block size Blosc compresses in, in bytes. 0 lets Blosc choose automatically.

typesize class-attribute instance-attribute 
typesize: int | None = None

The size, in bytes, of the array's element type. Blosc uses this to group same-position bytes together when shuffling.

Methods:

to_version 
to_version(version: ZarrVersion) -> Metadata

Convert this codec to another Zarr version.

Parameters:

Name Type Description Default
version ZarrVersion

The target Zarr format version: 1, 2 or 3.

 required

Returns:

Type Description
Metadata

The equivalent Blosc codec for version.

Raises:

Type Description
ValueError

If version is not 1, 2 or 3.

GzipCodec 

GzipCodec(id: Literal['gzip'] = 'gzip', level: Literal[0, 1, 2, 3, 4, 5, 6, 7, 8, 9] = 5)

Bases: CodecImpl

Applies DEFLATE compression (gzip) at a configurable compression level.

Attributes

CompressionLevel class-attribute instance-attribute 
CompressionLevel: ClassVar = codecs.GzipCompressionLevel
id instance-attribute 
id: Literal['gzip']

Always "gzip".

level class-attribute instance-attribute 
level: CompressionLevel = 5

The compression level, from 0 to 9.

Methods:

Bz2Codec 

Bz2Codec(id: Literal['bz2'] = 'bz2', level: Literal[0, 1, 2, 3, 4, 5, 6, 7, 8, 9] = 0)

Bases: CodecImpl

Compresses each chunk with bzip2 at a configurable compression level.

Attributes

CompressionLevel class-attribute instance-attribute 
CompressionLevel: ClassVar = codecs.Bz2CompressionLevel
id instance-attribute 
id: Literal['bz2']

Always "bz2".

level instance-attribute 
level: CompressionLevel

The compression level, from 0 to 9.

Methods:

LZMACodec 

LZMACodec(id: Literal['lzma'] = 'lzma', format: Literal[0, 1, 2, 3] = 0, check: Literal[0, 1, 4, 10, 15, 16] = 0, preset: Literal[0, 1, 2, 3, 4, 5, 6, 7, 8, 9] = 0, filters: Iterable[Iterable[tuple[str | bytes, Any]] | Mapping[str | bytes, Any]] = ())

Bases: CodecImpl

Compresses each chunk with LZMA, the compression used by .xz/.7z files, via Python's lzma module.

filters carries the raw lzma filter chain for cases that need one, such as selecting a custom dictionary size. Most uses only need format, check and preset.

Attributes

Format class-attribute instance-attribute 
Format: ClassVar = codecs.LZMAFormat
Check class-attribute instance-attribute 
Check: ClassVar = codecs.LZMACheck
CompressionLevel class-attribute instance-attribute 
CompressionLevel: ClassVar = codecs.LZMACompressionLevel
id instance-attribute 
id: Literal['lzma']

Always "lzma".

format instance-attribute 
format: Format

The LZMA container format to write.

check instance-attribute 
check: Check

The integrity check to embed in the compressed stream.

preset instance-attribute 
preset: CompressionLevel

The compression level, from 0 to 9.

filters instance-attribute 
filters: tuple[FrozenJsonDict, ...]

The raw lzma filter chain, when a custom one is needed.

Methods:

LZ4Codec 

LZ4Codec(id: Literal['lz4'] = 'lz4', acceleration: Integral | integer | bool = 0)

Bases: CodecImpl

Compresses each chunk with LZ4, which is very fast at the cost of a lower compression ratio.

acceleration trades ratio for speed further. A higher value compresses faster and produces a lower ratio.

Attributes

id instance-attribute 
id: Literal['lz4']

Always "lz4".

acceleration instance-attribute 
acceleration: int

The speed-for-ratio trade-off. A higher value compresses faster and produces a lower ratio.

Methods:

PCodec 

PCodec(id: Literal['pcodec'] = 'pcodec', level: Literal[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12] = 0, mode_spec: Literal['auto', 'classic'] = 'auto', delta_spec: Literal['auto', 'none', 'try_consecutive', 'try_lookback'] = 'auto', paging_spec: Literal['equal_pages_up_to'] = 'equal_pages_up_to', delta_encoding_order: Literal[0, 1, 2, 3, 4, 5, 6, 7] = 0, equal_pages_up_to: Integral | integer | bool = 0)

Bases: CodecImpl

Compresses numeric arrays with Pcodec (pco).

Pcodec models each chunk's value distribution directly, optionally after delta encoding, instead of treating the chunk as a byte stream. Pcodec typically outperforms general-purpose compressors on numeric data while remaining lossless.

Attributes

CompressionLevel class-attribute instance-attribute 
CompressionLevel: ClassVar = codecs.PCodecCompressionLevel
Mode class-attribute instance-attribute 
Mode: ClassVar = codecs.PCodecMode
Delta class-attribute instance-attribute 
Delta: ClassVar = codecs.PCodecDelta
Paging class-attribute instance-attribute 
Paging: ClassVar = codecs.PCodecPaging
DeltaOrder class-attribute instance-attribute 
DeltaOrder: ClassVar = codecs.PCodecDeltaOrder
id instance-attribute 
id: Literal['pcodec']

Always "pcodec".

level instance-attribute 
level: CompressionLevel

The compression level.

mode_spec instance-attribute 
mode_spec: Mode

How Pcodec chooses its numerical mode: "auto" or "classic".

delta_spec instance-attribute 
delta_spec: Delta

How Pcodec chooses whether to delta-encode values before modeling them.

paging_spec instance-attribute 
paging_spec: Paging

How Pcodec splits a chunk into pages for encoding.

delta_encoding_order instance-attribute 
delta_encoding_order: DeltaOrder

The order of delta encoding applied, when delta_spec selects one.

equal_pages_up_to instance-attribute 
equal_pages_up_to: int

The maximum page size, in elements, when paging_spec is "equal_pages_up_to".

Methods:

ZFPYCodec 

ZFPYCodec(id: Literal['zfpy'] = 'zfpy', mode: Literal[0, 1, 2, 3, 4] = 0, tolerance: Real | floating | bool = 0.0, rate: Integral | integer | bool = 0, precision: Integral | integer | bool = 0, compression_kwargs: Iterable[tuple[str | bytes, Any]] | Mapping[str | bytes, Any] = FrozenDict({}))

Bases: CodecImpl

Compresses floating-point arrays with ZFP, via the zfpy bindings.

mode selects which of tolerance, rate and precision governs the accuracy/size trade-off. Compression is lossy, except in the fixed-accuracy mode with a tolerance of zero.

Attributes

Mode class-attribute instance-attribute 
Mode: ClassVar = codecs.ZFPYMode
id instance-attribute 
id: Literal['zfpy']

Always "zfpy".

mode instance-attribute 
mode: Mode

The accuracy mode ZFP compresses in.

tolerance instance-attribute 
tolerance: float

The maximum absolute error allowed, in fixed-accuracy mode.

rate instance-attribute 
rate: int

The number of bits per value, in fixed-rate mode.

precision instance-attribute 
precision: int

The number of bits of precision retained, in fixed-precision mode.

compression_kwargs instance-attribute 
compression_kwargs: FrozenJsonDict

Extra keyword arguments forwarded to the underlying zfpy call.

Methods:

ZlibCodec 

ZlibCodec(id: Literal['zlib'] = 'zlib', level: Literal[0, 1, 2, 3, 4, 5, 6, 7, 8, 9] = 0)

Bases: CodecImpl

Applies DEFLATE compression (zlib) at a configurable compression level.

Attributes

CompressionLevel class-attribute instance-attribute 
CompressionLevel: ClassVar = codecs.ZlibCompressionLevel
id instance-attribute 
id: Literal['zlib']

Always "zlib".

level instance-attribute 
level: CompressionLevel

The compression level, from 0 to 9.

Methods:

ZstdCodec 

ZstdCodec(id: Literal['zstd'] = 'zstd', level: Integral | integer | bool = 0)

Bases: CodecImpl

Compresses each chunk with Zstandard at a configurable compression level.

Attributes

id instance-attribute 
id: Literal['zstd']

Always "zstd".

level instance-attribute 
level: int

The compression level.

Methods: