Specifications#

Specs are the write-side schema: validated (pydantic) descriptions of a table and its columns, consumed by Table.create and Table.add_column. Their fields are introduced, with examples, in the column datatypes and list columns chapters.

class h5col.TableSpec(*, columns: list[~h5col.specs.ColumnSpec | ~h5col.specs.ListColumnSpec], title: str | None = None, description: str | None = None, index_columns: list[str] = <factory>, column_order: list[str] | None = None, units_vocabulary: str | None = None, encoding_type: str | None = None, encoding_version: str | None = None)[source]#

Specification of a whole table: its columns and table-level attributes.

model_config = {'arbitrary_types_allowed': True}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property ordered_names: list[str]#: Column names in their logical order (column_order, else spec order).

column(name: str) → ColumnSpec | ListColumnSpec[source]#

Return the column spec named name.

Raises:: KeyError – If no column with that name is defined.

class h5col.ColumnSpec(*, name: str, dtype: Any = None, chunks: int | tuple[int, ...] | None = None, filters: FilterPipeline | None = None, fill_value: Any = None, valid_min: Any = None, valid_max: Any = None, units: str | None = None, units_vocabulary: str | None = None, description: str | None = None, categories: list[Any] | None = None, ordered: bool | None = None)[source]#

Specification of one column dataset.

dtype accepts a NumPy dtype-like, a FixedString, or the boolean dtype from bool_dtype(). For a categorical column, set categories (the label values); dtype is then the integer code type and may be omitted (a fitting signed int is chosen).

model_config = {'arbitrary_types_allowed': True}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

resolved_dtype() → dtype[source]#: Return the concrete NumPy dtype for this column.

property is_categorical: bool#: True if this is a categorical column.

property is_boolean: bool#: True if this is a H5Col boolean column.

Specification of a list column (a CLASS=LIST_COLUMN group).

values describes the VALUES member. nullable=True adds the top-level MASK distinguishing a null list from an empty list per row. chunks/filters apply to the top-level OFFSETS dataset.

model_config = {'arbitrary_types_allowed': True}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class h5col.LeafValuesSpec(*, dtype: Any, chunks: int | None = None, filters: FilterPipeline | None = None, fill_value: Any = None, valid_min: Any = None, valid_max: Any = None, units: str | None = None, units_vocabulary: str | None = None, description: str | None = None)[source]#

A leaf VALUES member of a list column: a rank-1 element dataset.

The element dtype may be any datatype permitted for a column dataset except a variable-length datatype (H5Col forbids those below a list column). Missing elements are expressed with the fill value, exactly as for column datasets; boolean leaves declare no fill (a boolean cannot be missing).

model_config = {'arbitrary_types_allowed': True}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

resolved_dtype() → dtype[source]#: Return the concrete NumPy dtype for this leaf’s elements.

property is_boolean: bool#: True if this leaf holds H5Col boolean values.

class h5col.StringValuesSpec(*, nullable: bool = False, chunks: int | None = None, filters: FilterPipeline | None = None)[source]#

A STRING_VALUES member: variable-length UTF-8 via OFFSETS + CHARS.

Set nullable=True to add a MASK that distinguishes a null string element from an empty one. filters applies to the CHARS byte buffer; chunks sets the chunk size of both the group’s OFFSETS dataset and CHARS.

model_config = {'arbitrary_types_allowed': True}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class h5col.NestedListSpec(*, values: LeafValuesSpec | StringValuesSpec | NestedListSpec, nullable: bool = False, chunks: int | None = None, filters: FilterPipeline | None = None)[source]#

A nested LIST_COLUMN level: its VALUES member plus this level’s mask.

values is the member stored under this level (leaf, string values, or a deeper list). nullable=True adds a MASK marking null inner lists at this level. Used recursively for lists of lists.

model_config = {'arbitrary_types_allowed': True}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].