# Module H5T

HDF5 “`H5T`” data-type API

This module contains the datatype identifier class `TypeID`, and its subclasses which represent things like integer/float/compound identifiers. The majority of the `H5T` API is presented as methods on these identifiers.

## Functions specific to h5py

h5py.h5t.py_create(OBJECT dtype_in, BOOL logical=False) → TypeID

  Given a Numpy dtype object, generate a byte-for-byte memory-compatible HDF5 datatype object. The result is guaranteed to be transient and unlocked.

  Parameters:

    - dtype_in – may be a dtype object, or anything which can be converted to a dtype, including strings like ‘<i4’ or an “int”.

    - logical – when this flag is set, instead of returning a byte-for-byte identical representation of the type, the function returns the closest logically appropriate HDF5 type. For example, in the case of a “hinted” dtype of kind “O” representing a string, it would return an HDF5 variable- length string type.

h5py.h5t.string_dtype(encoding='utf-8', length=None)

  Make a numpy dtype for HDF5 strings

  encoding may be ‘utf-8’ or ‘ascii’.

  length may be an integer for a fixed length string dtype, or None for variable length strings. String lengths for HDF5 are counted in bytes, not unicode code points.

  For variable length strings, the data should be passed as Python str objects if the encoding is ‘utf-8’, and bytes if it is ‘ascii’. Starting from NumPy 2.0, it is preferred to pass utf-8 data as variable-width NumPy strings (`dtype=numpy.dtypes.StringDType()` or `dtype='T'` instead of `dtype=h5py.string_dtype()`).

  For fixed length strings, the data should be numpy fixed length bytes arrays, regardless of the encoding. Fixed length unicode data is not supported.

h5py.h5t.check_string_dtype(dt)

  If the dtype represents an HDF5 string, returns a string_info object.

  The returned string_info object holds the encoding and the length. The encoding can only be ‘utf-8’ or ‘ascii’. The length may be None for a variable-length string, or a fixed length in bytes.

  Returns None if the dtype does not represent an HDF5 string.

h5py.h5t.vlen_dtype(basetype)

  Make a numpy dtype for an HDF5 variable-length datatype

  For variable-length string dtypes, use `string_dtype()` instead.

h5py.h5t.check_vlen_dtype(dt)

  If the dtype represents an HDF5 vlen, returns the Python base class.

  Returns None if the dtype does not represent an HDF5 vlen.

h5py.h5t.enum_dtype(values_dict, basetype=<class 'numpy.uint8'>)

  Create a NumPy representation of an HDF5 enumerated type

  values_dict maps string names to integer values. basetype is an appropriate integer base dtype large enough to hold the possible options.

h5py.h5t.check_enum_dtype(dt)

  If the dtype represents an HDF5 enumerated type, returns the dictionary mapping string names to integer values.

  Returns None if the dtype does not represent an HDF5 enumerated type.

h5py.h5t.special_dtype(**kwds)

  Create a new h5py “special” type. Only one keyword may be given.

  Legal keywords are:

  vlen = basetype

    Base type for HDF5 variable-length datatype. This can be Python str type or instance of np.dtype. Example: special_dtype( vlen=str )

  enum = (basetype, values_dict)

    Create a NumPy representation of an HDF5 enumerated type. Provide a 2-tuple containing an (integer) base dtype and a dict mapping string names to integer values.

  ref = Reference | RegionReference

    Create a NumPy representation of an HDF5 object or region reference type.

h5py.h5t.check_dtype(**kwds)

  Check a dtype for h5py special type “hint” information. Only one keyword may be given.

  vlen = dtype

    If the dtype represents an HDF5 vlen, returns the Python base class. Currently only built-in string vlens (str) are supported. Returns None if the dtype does not represent an HDF5 vlen.

  enum = dtype

    If the dtype represents an HDF5 enumerated type, returns the dictionary mapping string names to integer values. Returns None if the dtype does not represent an HDF5 enumerated type.

  ref = dtype

    If the dtype represents an HDF5 reference type, returns the reference class (either Reference or RegionReference). Returns None if the dtype does not represent an HDF5 reference type.

## Functional API

h5py.h5t.create(INT classtype, UINT size) → TypeID

  Create a new HDF5 type object. Legal class values are `COMPOUND` and `OPAQUE`. Use enum_create for enums.

h5py.h5t.open(ObjectID group, STRING name) → TypeID

  Open a named datatype from a file. If present, tapl must be a datatype access property list.

h5py.h5t.array_create(TypeID base, TUPLE dimensions) → TypeArrayID

  Create a new array datatype, using and HDF5 parent type and dimensions given via a tuple of positive integers. “Unlimited” dimensions are not allowed.

h5py.h5t.enum_create(TypeID base) → TypeID

  Create a new enumerated type based on an (integer) parent type.

h5py.h5t.vlen_create(TypeID base) → TypeID

  Create a new variable-length datatype, using any HDF5 type as a base.

  Although the Python interface can manipulate these types, there is no provision for reading/writing vlen data.

h5py.h5t.decode(STRING buf) → TypeID

  Deserialize an HDF5 type. You can also do this with the native Python pickling machinery.

h5py.h5t.convert(TypeID src, TypeID dst, UINT n, NDARRAY buf, NDARRAY bkg=None, PropID dxpl=None)

  Convert n contiguous elements of a buffer in-place. The array dtype is ignored. The backing buffer is optional; for conversion of compound types, a temporary copy of conversion buffer will used for backing if one is not supplied.

h5py.h5t.find(TypeID src, TypeID dst) → TUPLE or None

  Determine if a conversion path exists from src to dst. Result is None or a tuple describing the conversion path. Currently tuple entries are:

  1. INT need_bkg: Whether this routine requires a backing buffer.

       Values are `BKG_NO`, BKG_TEMP and `BKG_YES`.

## Type classes

class h5py.h5t.TypeID

  Base class for type identifiers (implements common operations)

  - Hashable: If committed or locked

  - Equality: Logical `H5T` comparison

  commit(ObjectID group, STRING name, PropID lcpl=None)

    Commit this (transient) datatype to a named datatype in a file. If present, lcpl may be a `link creation property list`.

  committed() → BOOL is_comitted

    Determine if a given type object is named (T) or transient (F).

  copy() → TypeID

    Create a copy of this type object.

  detect_class(INT classtype) → BOOL class_is_present

    Determine if a member of the given class exists in a compound datatype. The search is recursive.

  dtype

    A Numpy-style dtype object representing this object.

  encode() → STRING

    Serialize an HDF5 type. Bear in mind you can also use the native Python pickle/unpickle machinery to do this. The returned string may contain binary values, including NULLs.

  equal(TypeID typeid) → BOOL

    Logical comparison between datatypes. Also called by Python’s “==” operator.

  get_class() → INT classcode

    Determine the datatype’s class code.

  get_create_plist() → PropTCID

    Create and return a new copy of the datatype creation property list used when this datatype was created.

  get_size() → INT size

    Determine the total size of a datatype, in bytes.

  get_super() → TypeID

    Determine the parent type of an array, enumeration or vlen datatype.

  lock()

    Lock this datatype, which makes it immutable and indestructible. Once locked, it can’t be unlocked.

  set_size(UINT size)

    Set the total size of the datatype, in bytes.

### Atomic classes

Atomic types are integers and floats. Much of the functionality for each is inherited from the base class `TypeAtomicID`.

class h5py.h5t.TypeAtomicID

  Bases: `TypeID`

  Base class for atomic datatypes (float or integer)

  get_offset() → INT offset

    Get the offset of the first significant bit.

  get_order() → INT order

    Obtain the byte order of the datatype; one of:

    - `ORDER_LE`

    - `ORDER_BE`

  get_pad() -> (INT lsb_pad_code, INT msb_pad_code)

    Determine the padding type. Possible values are:

    - `PAD_ZERO`

    - `PAD_ONE`

    - `PAD_BACKGROUND`

  get_precision() → UINT precision

    Get the number of significant bits (excludes padding).

  set_offset(UINT offset)

    Set the offset of the first significant bit.

  set_order(INT order)

    Set the byte order of the datatype; one of:

    - `ORDER_LE`

    - `ORDER_BE`

  set_pad(INT lsb_pad_code, INT msb_pad_code)

    Set the padding type. Possible values are:

    - `PAD_ZERO`

    - `PAD_ONE`

    - `PAD_BACKGROUND`

  set_precision(UINT precision)

    Set the number of significant bits (excludes padding).

class h5py.h5t.TypeIntegerID

  Bases: `TypeAtomicID`

  Integer atomic datatypes

  get_sign() → INT sign

    Get the “signedness” of the datatype; one of:

    `SGN_NONE`

      Unsigned

    `SGN_2`

      Signed 2’s complement

  set_sign(INT sign)

    Set the “signedness” of the datatype; one of:

    `SGN_NONE`

      Unsigned

    `SGN_2`

      Signed 2’s complement

class h5py.h5t.TypeFloatID

  Bases: `TypeAtomicID`

  Floating-point atomic datatypes

  get_ebias() → UINT ebias

    Get the exponent bias.

  get_fields() → TUPLE field_info

    Get information about floating-point bit fields. See the HDF5 docs for a full description. Tuple has the following members:

    0. UINT spos

    1. UINT epos

    2. UINT esize

    3. UINT mpos

    4. UINT msize

  get_inpad() → INT pad_code

    Determine the internal padding strategy. Legal values are:

    - `PAD_ZERO`

    - `PAD_ONE`

    - `PAD_BACKGROUND`

  get_norm() → INT normalization_code

    Get the normalization strategy. Legal values are:

    - `NORM_IMPLIED`

    - `NORM_MSBSET`

    - `NORM_NONE`

  set_ebias(UINT ebias)

    Set the exponent bias.

  set_fields(UINT spos, UINT epos, UINT esize, UINT mpos, UINT msize)

    Set floating-point bit fields. Refer to the HDF5 docs for argument definitions.

  set_inpad(INT pad_code)

    Set the internal padding strategy. Legal values are:

    - `PAD_ZERO`

    - `PAD_ONE`

    - `PAD_BACKGROUND`

  set_norm(INT normalization_code)

    Set the normalization strategy. Legal values are:

    - `NORM_IMPLIED`

    - `NORM_MSBSET`

    - `NORM_NONE`

### Strings

class h5py.h5t.TypeStringID

  Bases: `TypeID`

  String datatypes, both fixed and vlen.

  get_cset() → INT character_set

    Retrieve the character set used for a string.

  get_strpad() → INT padding_type

    Get the padding type. Legal values are:

    `STR_NULLTERM`

      NULL termination only (C style)

    `STR_NULLPAD`

      Pad buffer with NULLs

    `STR_SPACEPAD`

      Pad buffer with spaces (FORTRAN style)

  is_variable_str() → BOOL is_variable

    Determine if the given string datatype is a variable-length string.

  set_cset(INT character_set)

    Set the character set used for a string.

  set_strpad(INT pad)

    Set the padding type. Legal values are:

    `STR_NULLTERM`

      NULL termination only (C style)

    `STR_NULLPAD`

      Pad buffer with NULLs

    `STR_SPACEPAD`

      Pad buffer with spaces (FORTRAN style)

### Compound Types

Traditional compound type (like NumPy record type) and enumerated types share a base class, `TypeCompositeID`.

class h5py.h5t.TypeCompositeID

  Bases: `TypeID`

  Base class for enumerated and compound types.

  get_member_index(STRING name) → INT index

    Determine the index of a member of a compound or enumerated datatype identified by a string name.

  get_member_name(INT member) → STRING name

    Determine the name of a member of a compound or enumerated type, identified by its index (0 <= member < nmembers).

  get_nmembers() → INT number_of_members

    Determine the number of members in a compound or enumerated type.

class h5py.h5t.TypeCompoundID

  Bases: `TypeCompositeID`

  Represents a compound datatype

  get_member_class(INT member) → INT class

    Determine the datatype class of the member of a compound type, identified by its index (0 <= member < nmembers).

  get_member_offset(INT member) → INT offset

    Determine the offset, in bytes, of the beginning of the specified member of a compound datatype.

  get_member_type(INT member) → TypeID

    Create a copy of a member of a compound datatype, identified by its index.

  insert(STRING name, UINT offset, TypeID field)

    Add a named member datatype to a compound datatype. The parameter offset indicates the offset from the start of the compound datatype, in bytes.

  pack()

    Recursively removes padding (introduced on account of e.g. compiler alignment rules) from a compound datatype.

class h5py.h5t.TypeEnumID

  Bases: `TypeCompositeID`

  Represents an enumerated type

  enum_insert(STRING name, INT/LONG value)

    Define a new member of an enumerated type. The value will be automatically converted to the base type defined for this enum. If the conversion results in overflow, the value will be silently clipped.

  enum_nameof(LONG value) → STRING name

    Determine the name associated with the given value. Due to a limitation of the HDF5 library, this can only retrieve names up to 1023 characters in length.

  enum_valueof(STRING name) → LONG value

    Get the value associated with an enum name.

  get_member_value(UINT index) → LONG value

    Determine the value for the member at the given zero-based index.

### Other types

class h5py.h5t.TypeArrayID

  Bases: `TypeID`

  Represents an array datatype

  get_array_dims() → TUPLE dimensions

    Get the dimensions of the given array datatype as a tuple of integers.

  get_array_ndims() → INT rank

    Get the rank of the given array datatype.

class h5py.h5t.TypeOpaqueID

  Bases: `TypeID`

  Represents an opaque type

  get_tag() → STRING tag

    Get the tag associated with an opaque datatype.

  set_tag(STRING tag)

    Set a string describing the contents of an opaque datatype. Limited to 256 characters.

class h5py.h5t.TypeVlenID

  Bases: `TypeID`

  Non-string vlen datatypes.

class h5py.h5t.TypeBitfieldID

  Bases: `TypeID`

  HDF5 bitfield type

  get_order() → INT order

    Obtain the byte order of the datatype; one of:

    - `ORDER_LE`

    - `ORDER_BE`

class h5py.h5t.TypeReferenceID

  Bases: `TypeID`

  HDF5 object or region reference

## Predefined Datatypes

These locked types are pre-allocated by the library.

### Floating-point

h5py.h5t.IEEE_F32LE

h5py.h5t.IEEE_F32BE

h5py.h5t.IEEE_F64LE

h5py.h5t.IEEE_F64BE

### Integer types

h5py.h5t.STD_I8LE

h5py.h5t.STD_I16LE

h5py.h5t.STD_I32LE

h5py.h5t.STD_I64LE

h5py.h5t.STD_I8BE

h5py.h5t.STD_I16BE

h5py.h5t.STD_I32BE

h5py.h5t.STD_I64BE

h5py.h5t.STD_U8LE

h5py.h5t.STD_U16LE

h5py.h5t.STD_U32LE

h5py.h5t.STD_U64LE

h5py.h5t.STD_U8BE

h5py.h5t.STD_U16BE

h5py.h5t.STD_U32BE

h5py.h5t.STD_U64BE

h5py.h5t.NATIVE_INT8

h5py.h5t.NATIVE_UINT8

h5py.h5t.NATIVE_INT16

h5py.h5t.NATIVE_UINT16

h5py.h5t.NATIVE_INT32

h5py.h5t.NATIVE_UINT32

h5py.h5t.NATIVE_INT64

h5py.h5t.NATIVE_UINT64

h5py.h5t.NATIVE_FLOAT

h5py.h5t.NATIVE_DOUBLE

### Reference types

h5py.h5t.STD_REF_OBJ

h5py.h5t.STD_REF_DSETREG

### String types

h5py.h5t.C_S1

  Null-terminated fixed-length string

h5py.h5t.FORTRAN_S1

  Zero-padded fixed-length string

h5py.h5t.VARIABLE

  Variable-length string

### Python object type

h5py.h5t.PYTHON_OBJECT

## Module constants

### Datatype class codes

h5py.h5t.NO_CLASS

h5py.h5t.INTEGER

h5py.h5t.FLOAT

h5py.h5t.TIME

h5py.h5t.STRING

h5py.h5t.BITFIELD

h5py.h5t.OPAQUE

h5py.h5t.COMPOUND

h5py.h5t.REFERENCE

h5py.h5t.ENUM

h5py.h5t.VLEN

h5py.h5t.ARRAY

### API Constants

h5py.h5t.SGN_NONE

h5py.h5t.SGN_2

h5py.h5t.ORDER_LE

h5py.h5t.ORDER_BE

h5py.h5t.ORDER_VAX

h5py.h5t.ORDER_NONE

h5py.h5t.ORDER_NATIVE

h5py.h5t.DIR_DEFAULT

h5py.h5t.DIR_ASCEND

h5py.h5t.DIR_DESCEND

h5py.h5t.STR_NULLTERM

h5py.h5t.STR_NULLPAD

h5py.h5t.STR_SPACEPAD

h5py.h5t.NORM_IMPLIED

h5py.h5t.NORM_MSBSET

h5py.h5t.NORM_NONE

h5py.h5t.CSET_ASCII

h5py.h5t.CSET_UTF8

h5py.h5t.PAD_ZERO

h5py.h5t.PAD_ONE

h5py.h5t.PAD_BACKGROUND

h5py.h5t.BKG_NO

h5py.h5t.BKG_TEMP

h5py.h5t.BKG_YES