framed

numcodecs_combinators.framed

This module defines the FramedCodecStack class, which exposes a framed stack of codecs as a combined codec.

Classes:

  • FramedCodecStack –

    A framed stack of codecs, which makes up a combined codec.

FramedCodecStack 

FramedCodecStack(*args: dict | Codec)

Bases: Codec, CodecCombinatorMixin, tuple[Codec]

A framed stack of codecs, which makes up a combined codec.

On encoding, the result of applying the codecs from left to right to encode is framed s.t. the data types and shapes of all arrays (input, intermediary, encoded) are stored as part of the encoding, which is output as a bytestring.

On decoding, this framing information is used to apply the codecs from right to left to decode into known output data types and shapes.

Therefore, the FramedCodecStack can be used to combine codecs which require knowing the output data type and shape during decoding. It can also be used to encode arrays into bytestrings.

Unlike the CodecStack, this class does not provide an additional encode_decode(buf) method, since it is equivalent to framed.decode(stack.encode(buf)) due to the framing.

Methods:

  • encode –

    Encode the data in buf.

  • decode –

    Decode the data in buf.

  • get_config –

    Returns the configuration of the framed codec stack.

  • from_config –

    Instantiate the framed codec stack from a configuration dict.

  • map –

    Apply the mapper to all codecs that are in this framed stack.

codec_id class-attribute instance-attribute 

codec_id: str = 'combinators.framed'

encode 

encode(buf: Buffer) -> bytes

Encode the data in buf.

Parameters:
  • buf (Buffer) –

    Data to be encoded. May be any object supporting the new-style buffer protocol.
Returns:
  • enc( bytes ) –

    Encoded and framed data as a bytestring.

decode 

decode(buf: Buffer, out: Optional[Buffer] = None) -> Buffer

Decode the data in buf.

Parameters:
  • buf (Buffer) –

    Encoded data. Must be an object representing a bytestring, e.g. bytes or a 1D array of np.uint8s etc.

  • out (Buffer, default: None ) –

    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 ) –

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

get_config 

get_config() -> dict

Returns the configuration of the framed codec stack.

numcodecs.registry.get_codec(config) can be used to reconstruct this stack from the returned config.

Returns:
  • config( dict ) –

    Configuration of the framed codec stack.

from_config classmethod 

from_config(config: dict) -> Self

Instantiate the framed codec stack from a configuration dict.

Parameters:
  • config (dict) –

    Configuration of the framed codec stack.
Returns:

map 

map(mapper: Callable[[Codec], Codec]) -> FramedCodecStack

Apply the mapper to all codecs that are in this framed stack. In the returned stack, each codec is replaced by its mapped codec.

The mapper should recursively apply itself to any inner codecs that also implement the CodecCombinatorMixin mixin.

To automatically handle the recursive application as a caller, you can use 

numcodecs_combinators.map_codec(stack, mapper)
instead.

Parameters:
  • mapper (Callable[[Codec], Codec]) –

    The callable that should be applied to each codec to map over this framed codec stack.
Returns: