bpack.np module

Numpy based codec for binary data structures.

class bpack.np.Codec(descriptor)

Bases: Codec

Numpy based codec.

(Unicode) strings are treated as “utf-8” encoded byte strings. UCS4 encoded strings are not supported.

decode(data: bytes, count: int = 1)

Decode binary data and return a record object.

encode(record)

Encode record (Python object) into binary data.

baseunits: EBaseUnits = 'bytes'

property dtype

Return the numpy dtype corresponding to the codec.descriptor.

bpack.np.Decoder

alias of Codec

class bpack.np.ESignMode(value)

Bases: IntEnum

Enumeration for sign encoding convention.

SIGNED = 1

SIGN_AND_MOD = 2

UNSIGNED = 0

bpack.np.Encoder

alias of Codec

bpack.np.codec(cls)

Class decorator to add (de)coding methods to a descriptor class.

The decorator automatically generates a Codec object form the input descriptor class and attach to it methods for conversion form/to bytes.

bpack.np.decoder(cls)

Class decorator to add (de)coding methods to a descriptor class.

The decorator automatically generates a Codec object form the input descriptor class and attach to it methods for conversion form/to bytes.

bpack.np.descriptor_to_dtype(descriptor) → numpy.dtype

Convert the descriptor of a binary record into a numpy.dtype.

Please note that (unicode) strings are treated as “utf-8” encoded byte strings. UCS4 encoded strings are not supported.

Sequences (typing.Sequence and typing.List) are always converted into numpy.ndarray.

See also

bpack.descriptors.descriptor().

bpack.np.encoder(cls)

Class decorator to add (de)coding methods to a descriptor class.

The decorator automatically generates a Codec object form the input descriptor class and attach to it methods for conversion form/to bytes.

bpack.np.unpackbits(data: bytes, bits_per_sample: int, samples_per_block: Optional[int] = None, bit_offset: int = 0, blockstride: Optional[int] = None, sign_mode: ESignMode = ESignMode.UNSIGNED, byteorder: str = '>', use_lut: bool = True) → numpy.ndarray

Unpack packed (integer) values form a string of bytes.

Takes in input a string of bytes in which (integer) samples have been stored using bits_per_sample bit for each sample, and returns the sequence of corresponding Python integers.

Example:

           3 bytes                            4 samples

|------|------|------|------| --> [samp_1, samp_2, samp_3, samp_4]

4 samples (6 bits per sample)

Parameters:

• data – bytes string of bytes containing the packed data

• bits_per_sample – int the number of bits used to encode each sample

• samples_per_block – int, optional the number of samples in each data block contained in the input string of bytes. This parameter is mostly relevant if the data block contains other information (or padding bits) in addition to the data samples. The number of blocks is deduced from the length of the input string of bytes, the number of samples per block and the number of bits per sample. If samples_per_block is not provided it is assumed a single block, and the number of samples is derived from the length of the input string of bytes and the number of bits per sample.

• bit_offset – int, optional the number of bits after which the sequence of samples (data blocks) starts (default: 0). It can be used e.g. to take into account of a possible binary header at the beginning of the sequence of samples.

• blockstride – int, optional the number of bits between the start of a data block and the start of the following one. This parameter is mostly relevant if the data block contains other information (or padding bits) in addition to the data samples. If not provided the blockstride is assumed to be equal to the size of the data block i.e. bits_per_sample * samples_per_block.

• sign_mode – ESignMode, optional specifies how the sign of the integer samples shall is encoded. Dy default unsigned samples are assumed. .. seealso:: ESignMode.

• byteorder – str, optional Byte order of the encoded integers. Only relevant for multi byte samples. Default: “>” (big endian).

• use_lut – bool, optional specifies whenever the decoding of signed samples shall exploit look-up tables (typically faster). Default: True.