# Module H5S

Low-level interface to the “`H5S`” family of data-space functions.

## Functional API

h5py.h5s.create(INT class_code) → SpaceID

  Create a new HDF5 dataspace object, of the given class. Legal values are `SCALAR` and `SIMPLE`.

h5py.h5s.create_simple(TUPLE dims_tpl, TUPLE max_dims_tpl) → SpaceID

  Create a simple (slab) dataspace from a tuple of dimensions. Every element of dims_tpl must be a positive integer.

  You can optionally specify the maximum dataspace size. The special value `UNLIMITED`, as an element of max_dims, indicates an unlimited dimension.

h5py.h5s.decode(STRING buf) → SpaceID

  Unserialize a dataspace. Bear in mind you can also use the native Python pickling machinery to do this.

## Dataspace objects

class h5py.h5s.SpaceID

  Bases: `ObjectID`

  Represents a dataspace identifier.

  Properties:

  shape

    Numpy-style shape tuple with dimensions.

  - Hashable: No

  - Equality: Unimplemented

  combine_select(SpaceID space2, INT op=SELECT_OR) → SpaceID

    Combine two hyperslab selections with an operation, returning a new dataspace with the resulting selection. The default operation is a union, so the resulting selection includes everything selected in either input.

  copy() → SpaceID

    Create a new copy of this dataspace.

  encode() → STRING

    Serialize a dataspace, including its selection. Bear in mind you can also use the native Python pickling machinery to do this.

  extent_copy(SpaceID source)

    Replace this dataspace’s extent with another’s, changing its typecode if necessary.

  get_regular_hyperslab() -> (TUPLE start, TUPLE stride, TUPLE count, TUPLE block)

    Retrieve a regular hyperslab selection.

  get_select_bounds() -> (TUPLE start, TUPLE end)

    Determine the bounding box which exactly contains the current selection.

  get_select_elem_npoints() → LONG npoints

    Determine the number of elements selected in point-selection mode.

  get_select_elem_pointlist() → NDARRAY

    Get a list of all selected elements. Return is a Numpy array of unsigned ints, with shape `(<npoints>, <space rank)`.

  get_select_hyper_blocklist() → NDARRAY

    Get the current hyperslab selection. The returned array has shape:

        (<npoints>, 2, <rank>)

    and can be interpreted as a nested sequence:

        [ (corner_coordinate_1, opposite_coordinate_1), ... ]

    with length equal to the total number of blocks.

  get_select_hyper_nblocks() → LONG nblocks

    Get the number of hyperslab blocks currently selected.

  get_select_npoints() → LONG npoints

    Determine the total number of points currently selected. Works for all selection techniques.

  get_select_type() → INT select_code

    Determine selection type. Return values are:

    - `SEL_NONE`

    - `SEL_ALL`

    - `SEL_POINTS`

    - `SEL_HYPERSLABS`

  get_simple_extent_dims(BOOL maxdims=False) → TUPLE shape

    Determine the shape of a “simple” (slab) dataspace. If “maxdims” is True, retrieve the maximum dataspace size instead.

  get_simple_extent_ndims() → INT rank

    Determine the rank of a “simple” (slab) dataspace.

  get_simple_extent_npoints() → LONG npoints

    Determine the total number of elements in a dataspace.

  get_simple_extent_type() → INT class_code

    Class code is either `SCALAR` or `SIMPLE`.

  is_regular_hyperslab() → BOOL

    Determine whether a hyperslab selection is regular.

  is_simple() → BOOL is_simple

    Determine if an existing dataspace is “simple” (including scalar dataspaces). Currently all HDF5 dataspaces are simple.

  modify_select(SpaceID space2, INT op=SELECT_OR)

    Refines the hyperslab selection of this dataspace (self) using the hyperslab selection from a second dataspace. The default operation is a union, extending the selection to any parts selected in the second dataspace.

  offset_simple(TUPLE offset=None)

    Set the offset of a dataspace. The length of the given tuple must match the rank of the dataspace. If None is provided (default), the offsets on all axes will be set to 0.

  select_all()

    Select all points in the dataspace.

  select_copy(SpaceID src_id)

    Copies the selection from another dataspace to this one (self).

  select_elements(SEQUENCE coords, INT op=SELECT_SET)

    Select elements by specifying coordinates points. The argument “coords” may be an ndarray or any nested sequence which can be converted to an array of uints with the shape:

        (<npoints>, <space rank>)

    Examples:

        >>> obj.shape
        (10, 10)
        >>> obj.select_elements([(1,2), (3,4), (5,9)])

    A zero-length selection (i.e. shape `(0, <rank>)`) is not allowed by the HDF5 library.

  select_hyperslab(TUPLE start, TUPLE count, TUPLE stride=None, TUPLE block=None, INT op=SELECT_SET)

    Select a block region from an existing dataspace. See the HDF5 documentation for the meaning of the “block” and “op” keywords.

  select_none()

    Deselect entire dataspace.

  select_shape_same(SpaceID space2) → BOOL

    Check if two selections are the same shape. HDF5 may read data faster if the source & destination selections are the same shape.

  select_valid() → BOOL

    Determine if the current selection falls within the dataspace extent.

  set_extent_none()

    Remove the dataspace extent; typecode changes to `NO_CLASS`.

  set_extent_simple(TUPLE dims_tpl, TUPLE max_dims_tpl=None)

    Reset the dataspace extent via a tuple of dimensions. Every element of dims_tpl must be a positive integer.

    You can optionally specify the maximum dataspace size. The special value `UNLIMITED`, as an element of max_dims, indicates an unlimited dimension.

  shape

    Numpy-style shape tuple representing dimensions. () == scalar.

## Module constants

h5py.h5s.ALL

  Accepted in place of an actual dataspace; means “every point”

h5py.h5s.UNLIMITED

  Indicates an unlimited maximum dimension

### Dataspace class codes

h5py.h5s.NO_CLASS

h5py.h5s.SCALAR

h5py.h5s.SIMPLE

### Selection codes

h5py.h5s.SELECT_NOOP

h5py.h5s.SELECT_SET

h5py.h5s.SELECT_OR

h5py.h5s.SELECT_AND

h5py.h5s.SELECT_XOR

h5py.h5s.SELECT_NOTB

h5py.h5s.SELECT_NOTA

h5py.h5s.SELECT_APPEND

h5py.h5s.SELECT_PREPEND

h5py.h5s.SELECT_INVALID

### Existing selection type

h5py.h5s.SEL_NONE

h5py.h5s.SEL_POINTS

h5py.h5s.SEL_HYPERSLABS

h5py.h5s.SEL_ALL