Skip to main content
`Ctrl`+`K`

# Codec API

This module defines the `Codec` base class, a common interface for all codec classes.

Codec classes must implement `Codec.encode()` and `Codec.decode()` methods. Inputs to and outputs from these methods may be any Python object exporting a contiguous buffer via the new-style Python protocol.

Codec classes must implement a `Codec.get_config()` method, which must return a dictionary holding all configuration parameters required to enable encoding and decoding of data. The expectation is that these configuration parameters will be stored or communicated separately from encoded data, and thus the codecs do not need to store all encoding parameters within the encoded data. For broad compatibility, the configuration object must contain only JSON-serializable values. The configuration object must also contain an ‘id’ field storing the codec identifier (see below).

Codec classes must implement a `Codec.from_config()` class method, which will return an instance of the class initialized from a configuration object.

Finally, codec classes must set a codec_id class-level attribute. This must be a string. Two different codec classes may set the same value for the codec_id attribute if and only if they are fully compatible, meaning that (1) configuration parameters are the same, and (2) given the same configuration, one class could correctly decode data encoded by the other and vice versa.

class numcodecs.abc.Codec

  Codec abstract base class.

  codec_id: str | None = None

    Codec identifier.

  abstractmethod encode(buf)

    Encode data in buf.

    Parameters:
      buf buffer-like

        Data to be encoded. May be any object supporting the new-style buffer protocol.

    Returns:
      enc buffer-like

        Encoded data. May be any object supporting the new-style buffer protocol.

  abstractmethod decode(buf, out=None)

    Decode data in buf.

    Parameters:
      buf buffer-like

        Encoded data. May be any object supporting the new-style buffer protocol.

      out buffer-like, optional

        Writeable buffer to store decoded data. N.B. if provided, this buffer must be exactly the right size to store the decoded data.

    Returns:
      dec buffer-like

        Decoded data. May be any object supporting the new-style buffer protocol.

  get_config()

    Return a dictionary holding configuration parameters for this codec. Must include an ‘id’ field with the codec identifier. All values must be compatible with JSON encoding.

  classmethod from_config(config)

    Instantiate codec from a configuration object.