Column datatypes

Helpers for the two datatypes HDF5 does not hand to NumPy directly: the fixed-length UTF-8 string and the H5Col boolean enumeration. The column datatypes chapter explains when to reach for each.

Fixed-length strings

class h5col.FixedString(nbytes: int, encoding: str = 'utf-8')

A fixed-length HDF5 string datatype of nbytes bytes.

Parameters:

• nbytes (int) – Storage width in bytes (> 0).

• encoding (str) – "utf-8" (default) or "ascii".

Raises:

SchemaError – If nbytes is not a positive integer, or encoding is unsupported.

property dtype: dtype

The NumPy/h5py dtype for creating a dataset or attribute of this type.

encode_scalar(value: object, *, index: int | None = None) → bytes

Encode a single value to bytes, enforcing the byte budget.

Raises OversizedStringError if the encoding exceeds nbytes.

encode(values: Any) → NDArray[bytes_]

Encode an array-like of strings to a |S{nbytes} array.

No value is ever truncated: the first over-budget value raises OversizedStringError.

decode_scalar(raw: bytes | bytearray | bytes_) → str

Decode a single stored value to str (trailing NULs stripped).

decode(values: Any) → NDArray[object_]

Decode an array-like of stored bytes to an object array of str.

classmethod from_dtype(dtype: Any) → FixedString

Build a FixedString from an existing fixed-length string dtype.

Raises:

SchemaError – If dtype is not an HDF5 string dtype, or is a variable-length (not fixed-length) string dtype.

static is_fixed_string(dtype: Any) → bool

Return True if dtype is a fixed-length HDF5 string dtype.

h5col.ascii_token_dtype(value: str) → dtype

Return a fixed-length ASCII string dtype sized to hold value plus a NUL.

Used for H5Col reserved-token attributes (CLASS, VERSION, KIND), whose values are ASCII and are stored null-terminated/null-padded.

Booleans

h5col.bool_dtype() → dtype

Return the H5Col boolean dtype (enum over little-endian signed int8).

On little-endian platforms the <i1 base is byte-identical to H5T_STD_I8LE, which is what H5Col mandates.

h5col.is_bool_dtype(dtype: Any) → bool

Return True if dtype is an acceptable H5Col boolean datatype.

Applies the consumer-lenient rule: any one-byte integer enumeration, of either signedness, whose members are exactly FALSE = 0 and TRUE = 1. Also accepts NumPy bool: h5py normalizes its FALSE/TRUE-over-int8 enum (which is the H5Col boolean datatype on disk) back to bool on read.

h5col.encode_bool(values: Any) → NDArray[int8]

Encode a boolean/0-1 array-like to an int8 array of codes.

Raises SchemaError if an integer input holds a value other than 0 or 1 (H5Col boolean columns may hold only those two codes).

h5col.decode_bool(values: Any) → NDArray[bool]

Decode stored integer codes to a NumPy boolean array.

Every code must be 0 (FALSE) or 1 (TRUE). A code outside that domain is a non-conformant boolean value; H5Col forbids interpreting it as either FALSE or TRUE, so this raises ConformanceError instead of silently coercing (NumPy maps every nonzero code to True).