h5netcdf 1.3.0__py3-none-any.whl → 1.4.0__py3-none-any.whl

h5netcdf/core.py

@@ -1,5 +1,5 @@
 # For details on how netCDF4 builds on HDF5:
-# http://www.unidata.ucar.edu/software/netcdf/docs/file_format_specifications.html#netcdf_4_spec
+# https://docs.unidata.ucar.edu/netcdf-c/current/file_format_specifications.html#netcdf_4_spec
 import os.path
 import warnings
 import weakref
@@ -54,9 +54,11 @@ def _transform_1d_boolean_indexers(key):
     # return key, if not iterable
     try:
         key = [
-            np.asanyarray(k).nonzero()[0]
-            if isinstance(k, (np.ndarray, list)) and type(k[0]) in (bool, np.bool_)
-            else k
+            (
+                np.asanyarray(k).nonzero()[0]
+                if isinstance(k, (np.ndarray, list)) and type(k[0]) in (bool, np.bool_)
+                else k
+            )
             for k in key
         ]
     except TypeError:
@@ -106,13 +108,11 @@ def _expanded_indexer(key, ndim):
     return key[k1] + res_dims + key[k2]
 
 
-class BaseVariable:
-    def __init__(self, parent, name, dimensions=None):
+class BaseObject:
+    def __init__(self, parent, name):
         self._parent_ref = weakref.ref(parent)
         self._root_ref = weakref.ref(parent._root)
         self._h5path = _join_h5paths(parent.name, name)
-        self._dimensions = dimensions
-        self._initialized = True
 
     @property
     def _parent(self):
@@ -128,11 +128,149 @@ class BaseVariable:
         # subclasses:
         return self._root._h5file[self._h5path]
 
+    @property
+    def name(self):
+        """Return object name."""
+        return self._h5ds.name
+
+    @property
+    def dtype(self):
+        """Return NumPy dtype giving object’s dtype."""
+        return self._h5ds.dtype
+
+
+_h5type_mapping = {
+    "H5T_COMPOUND": 6,
+    "H5T_ENUM": 8,
+    "H5T_VLEN": 9,
+}
+
+
+def _get_h5usertype_identifier(h5type):
+    """Return H5 Type Identifier from given H5 Datatype."""
+    try:
+        # h5py first
+        h5typeid = h5type.id.get_class()
+    except AttributeError:
+        # h5pyd second
+        h5typeid = _h5type_mapping[h5type.id.type_json["class"]]
+    return h5typeid
+
+
+def _get_h5dstype_identifier(h5type):
+    """Return H5 Type Identifier from given H5 Dataset."""
+    try:
+        # h5py first
+        h5typeid = h5type.id.get_type().get_class()
+    except AttributeError:
+        # h5pyd second
+        h5typeid = _h5type_mapping[h5type.id.type_json["class"]]
+    return h5typeid
+
+
+class UserType(BaseObject):
+    _cls_name = "h5netcdf.UserType"
+
+    @property
+    def name(self):
+        """Return user type name."""
+        # strip hdf5 path
+        return super().name.split("/")[-1]
+
+    def __repr__(self):
+        if self._parent._root._closed:
+            return f"<Closed {self._cls_name!r}>"
+        header = f"<class {self._cls_name!r}: name = {self.name!r}, numpy dtype = {self.dtype!r}"
+        return header
+
+    @property
+    def _h5type_identifier(self):
+        """Returns type identifier.
+
+        See https://api.h5py.org/h5t.html#datatype-class-codes and
+        https://docs.hdfgroup.org (enum H5T_class_t)
+
+        """
+        return _get_h5usertype_identifier(self._h5ds)
+
+    @property
+    def _h5datatype(self):
+        """Returns comparable h5type.
+
+        - DatatypeID for h5py
+        - (dtype, dtype.metadata) for h5pyd
+        """
+        if self._root._h5py.__name__ == "h5py":
+            return self._h5ds.id
+        else:
+            return self.dtype, self.dtype.metadata
+
+
+class EnumType(UserType):
+    _cls_name = "h5netcdf.EnumType"
+
+    @property
+    def enum_dict(self):
+        """Dictionary containing the Enum field/value pairs."""
+        return self.dtype.metadata["enum"]
+
+    def __repr__(self):
+        return super().__repr__() + f", fields / values = {self.enum_dict!r}"
+
+
+class VLType(UserType):
+    _cls_name = "h5netcdf.VLType"
+
+
+def _string_to_char_array_dtype(dtype):
+    """Converts fixed string to char array dtype."""
+    if dtype.kind == "c":
+        return None
+    return np.dtype(
+        {
+            name: (
+                np.dtype(("S1", fmt.itemsize)) if fmt.kind == "S" else fmt,
+                offset,
+            )
+            for name, (fmt, offset) in dtype.fields.items()
+        }
+    )
+
+
+def _char_array_to_string_dtype(dtype):
+    """Converts char array to fixed string dtype."""
+    if dtype.kind == "c":
+        return None
+    return np.dtype(
+        {
+            name: (
+                np.dtype(f"S{fmt.shape[0]}") if fmt.base == "S1" else fmt,
+                offset,
+            )
+            for name, (fmt, offset) in dtype.fields.items()
+        }
+    )
+
+
+class CompoundType(UserType):
+    _cls_name = "h5netcdf.CompoundType"
+
+    @property
+    def dtype_view(self):
+        return _char_array_to_string_dtype(self.dtype)
+
+
+class BaseVariable(BaseObject):
+    def __init__(self, parent, name, dimensions=None):
+        super().__init__(parent, name)
+        self._dimensions = dimensions
+        self._initialized = True
+
     @property
     def name(self):
         """Return variable name."""
         # fix name if _nc4_non_coord_
-        return self._h5ds.name.replace("_nc4_non_coord_", "")
+        return super().name.replace("_nc4_non_coord_", "")
 
     def _lookup_dimensions(self):
         attrs = self._h5ds.attrs
@@ -253,6 +391,31 @@ class BaseVariable:
         if self._h5ds.shape != new_shape:
             self._h5ds.resize(new_shape)
 
+    def _add_fillvalue(self, fillvalue):
+        """Add _FillValue attribute.
+
+        This method takes care of adding fillvalue with the wanted
+        variable dtype.
+        """
+
+        # trying to create correct type of fillvalue
+        if self.dtype is str:
+            value = fillvalue
+        else:
+            # todo: this always checks for dtype.metadata
+            string_info = self._root._h5py.check_string_dtype(self.dtype)
+            enum_info = self._root._h5py.check_enum_dtype(self.dtype)
+            if (
+                string_info
+                and string_info.length is not None
+                and string_info.length > 1
+            ) or enum_info:
+                value = fillvalue
+            else:
+                value = self.dtype.type(fillvalue)
+
+        self.attrs["_FillValue"] = value
+
     @property
     def dimensions(self):
         """Return variable dimension names."""
@@ -268,16 +431,52 @@ class BaseVariable:
 
     @property
     def ndim(self):
-        """Return number variable dimensions"""
+        """Return number of variable dimensions."""
         return len(self.shape)
 
     def __len__(self):
         return self.shape[0]
 
     @property
-    def dtype(self):
-        """Return NumPy dtype object giving the variable’s type."""
-        return self._h5ds.dtype
+    def _h5type_identifier(self):
+        """Returns type identifier.
+
+        See https://api.h5py.org/h5t.html#datatype-class-codes and
+        https://docs.hdfgroup.org (enum H5T_class_t)
+
+        """
+        return _get_h5dstype_identifier(self._h5ds)
+
+    @property
+    def _h5datatype(self):
+        """Returns comparable h5type.
+
+        This property can be used to compare two variables/datatypes or
+        a variable and a datatype for equality of the underlying datatype.
+
+        - DatatypeID for h5py
+        - (dtype, dtype.metadata) for h5pyd
+        """
+        if self._root._h5py.__name__ == "h5py":
+            return self._h5ds.id.get_type()
+        else:
+            return self.dtype, self.dtype.metadata
+
+    @property
+    def datatype(self):
+        """Return datatype.
+
+        Returns numpy dtype (for primitive types) or VLType/CompoundType/EnumType
+        instance (for compound, vlen or enum data types).
+        """
+        # this is really painful as we have to iterate over all types
+        # and check equality
+        usertype = self._parent._get_usertype_dict(self._h5type_identifier)
+        if usertype is not None:
+            for tid in usertype.values():
+                if self._h5datatype == tid._h5datatype:
+                    return tid
+        return self.dtype
 
     def _get_padding(self, key):
         """Return padding if needed, defaults to False."""
@@ -334,28 +533,54 @@ class BaseVariable:
 
         # get padding
         padding = self._get_padding(key)
+
         # apply padding with fillvalue (both api)
         if padding:
             fv = self.dtype.type(self._h5ds.fillvalue)
-            return np.pad(
+            h5ds = np.pad(
                 self._h5ds,
                 pad_width=padding,
                 mode="constant",
                 constant_values=fv,
-            )[key]
+            )
+        else:
+            h5ds = self._h5ds
 
-        return self._h5ds[key]
+        if (
+            isinstance(self.datatype, CompoundType)
+            and (view := self.datatype.dtype_view) is not None
+        ):
+            return h5ds[key].view(view)
+        else:
+            return h5ds[key]
 
     def __setitem__(self, key, value):
         from .legacyapi import Dataset
 
+        # check if provided values match enumtype values
+        if enum_dict := self._root._h5py.check_enum_dtype(self.dtype):
+            mask = np.isin(value, list(enum_dict.values()))
+            wrong = set(np.asanyarray(value)[~mask])
+            if not mask.all():
+                raise ValueError(
+                    f"Trying to assign illegal value(s) {wrong!r} to Enum variable {self.name!r}."
+                    f" Valid values are {dict(enum_dict)!r}."
+                )
+
         if isinstance(self._parent._root, Dataset):
             # resize on write only for legacyapi
             key = _expanded_indexer(key, self.ndim)
             key = _transform_1d_boolean_indexers(key)
             # resize on write only for legacy API
             self._maybe_resize_dimensions(key, value)
-        self._h5ds[key] = value
+
+        if (
+            isinstance(self.datatype, CompoundType)
+            and (view := _string_to_char_array_dtype(self.datatype.dtype)) is not None
+        ):
+            self._h5ds[key] = value.view(view)
+        else:
+            self._h5ds[key] = value
 
     @property
     def attrs(self):
@@ -368,14 +593,8 @@ class BaseVariable:
 
     def __repr__(self):
         if self._parent._root._closed:
-            return "<Closed %s>" % self._cls_name
-        header = "<{} {!r}: dimensions {}, shape {}, dtype {}>".format(
-            self._cls_name,
-            self.name,
-            self.dimensions,
-            self.shape,
-            self.dtype,
-        )
+            return f"<Closed {self._cls_name}>"
+        header = f"<{self._cls_name} {self.name!r}: dimensions {self.dimensions}, shape {self.shape}, dtype {self.dtype}>"
         return "\n".join(
             [header]
             + ["Attributes:"]
@@ -467,9 +686,164 @@ def _unlabeled_dimension_mix(h5py_dataset):
     return status
 
 
+def _check_dtype(group, dtype):
+    """Check and handle dtypes when adding variable to given group.
+
+    Raises errors and issues warnings according to given dtype.
+    """
+
+    if dtype == np.bool_:
+        # never warn since h5netcdf has always errored here
+        _invalid_netcdf_feature(
+            "boolean dtypes",
+            group._root.invalid_netcdf,
+        )
+    else:
+        group._root._check_valid_netcdf_dtype(dtype)
+
+    # we only allow h5netcdf user types, not named h5py.Datatype
+    if isinstance(dtype, group._root._h5py.Datatype):
+        raise TypeError(
+            f"Argument dtype {dtype!r} is not allowed. "
+            f"Please provide h5netcdf user type or numpy compatible type."
+        )
+
+    # is user type is given extract underlying h5py object
+    # we just use the h5py user type here
+    if isinstance(dtype, (EnumType, VLType, CompoundType)):
+        h5type = dtype._h5ds
+        if dtype._root._h5file.filename != group._root._h5file.filename:
+            raise TypeError(
+                f"Given dtype {dtype} is not committed into current file"
+                f" {group._root._h5file.filename}. Instead it's committed into"
+                f" file {dtype._root._h5file.filename}"
+            )
+        # check if committed type can be accessed in current group hierarchy
+        user_type = group._get_usertype(h5type)
+        if user_type is None:
+            msg = (
+                f"Given dtype {dtype.name!r} is not accessible in current group"
+                f" {group._h5group.name!r} or any parent group. Instead it's defined at"
+                f" {h5type.name!r}. Please create it in the current or any parent group."
+            )
+            raise TypeError(msg)
+        # this checks for committed types which are overridden by re-definitions
+        elif (actual := user_type._h5ds.name) != h5type.name:
+            msg = (
+                f"Given dtype {dtype.name!r} is defined at {h5type.name!r}."
+                f" Another dtype with same name is defined at {actual!r} and"
+                f" would override it."
+            )
+            raise TypeError(msg)
+    elif np.dtype(dtype).kind == "c":
+        itemsize = np.dtype(dtype).itemsize
+        try:
+            width = {8: "FLOAT", 16: "DOUBLE"}[itemsize]
+        except KeyError as e:
+            raise TypeError(
+                "Currently only 'complex64' and 'complex128' dtypes are allowed."
+            ) from e
+        dname = f"_PFNC_{width}_COMPLEX_TYPE"
+        # todo check compound type for existing complex types
+        #  which may be used here
+        # if dname is not available in current group-path
+        # create and commit type in current group
+        if dname not in group._all_cmptypes:
+            dtype = group.create_cmptype(dtype, dname).dtype
+
+    return dtype
+
+
+def _check_fillvalue(group, fillvalue, dtype):
+    """Handles fillvalues when adding variable to given group.
+
+    Raises errors and issues warnings according to
+    given fillvalue and dtype.
+    """
+
+    # handling default fillvalues for legacyapi
+    # see https://github.com/h5netcdf/h5netcdf/issues/182
+    from .legacyapi import Dataset, _get_default_fillvalue
+
+    stacklevel = 5 if isinstance(group._root, Dataset) else 4
+
+    h5fillvalue = fillvalue
+
+    # if no fillvalue is provided take netcdf4 default values for legacyapi
+    if fillvalue is None:
+        if isinstance(group._root, Dataset):
+            h5fillvalue = _get_default_fillvalue(dtype)
+
+    # handling for EnumType
+    if dtype is not None and isinstance(dtype, EnumType):
+        if fillvalue is None:
+            # 1. we need to warn the user that writing enums with default values
+            # which are defined in the enum dict will mask those values
+            if (h5fillvalue or 0) in dtype.enum_dict.values():
+                reverse = dict((v, k) for k, v in dtype.enum_dict.items())
+                msg = (
+                    f"Creating variable with default fill_value {h5fillvalue or 0!r}"
+                    f" which IS defined in enum type {dtype!r}."
+                    f" This will mask entry {{{reverse[h5fillvalue or 0]!r}: {h5fillvalue or 0!r}}}."
+                )
+                warnings.warn(msg, stacklevel=stacklevel)
+            else:
+                # 2. we need to raise if the default fillvalue is not within the enum dict
+                if (
+                    h5fillvalue is not None
+                    and h5fillvalue not in dtype.enum_dict.values()
+                ):
+                    msg = (
+                        f"Creating variable with default fill_value {h5fillvalue!r}"
+                        f" which IS NOT defined in enum type {dtype!r}."
+                        f" Please provide a fitting fill_value or enum type."
+                    )
+                    raise ValueError(msg)
+                if h5fillvalue is None and 0 not in dtype.enum_dict.values():
+                    # 3. we should inform the user that a fillvalue of '0'
+                    # will be interpreted as _UNDEFINED in netcdf-c
+                    # if it is not defined in the enum dict
+                    msg = (
+                        f"Creating variable with default fill_value {0!r}"
+                        f" which IS NOT defined in enum type {dtype!r}."
+                        f" Value {0!r} will be interpreted as '_UNDEFINED' by netcdf-c."
+                    )
+                    warnings.warn(msg, stacklevel=stacklevel)
+        else:
+            if h5fillvalue not in dtype.enum_dict.values():
+                # 4. we should inform the user that a fillvalue of '0'
+                # will be interpreted as _UNDEFINED in netcdf-c
+                # if it is not defined in the enum dict
+                if h5fillvalue == 0:
+                    msg = (
+                        f"Creating variable with specified fill_value {h5fillvalue!r}"
+                        f" which IS NOT defined in enum type {dtype!r}."
+                        f" Value {0!r} will be interpreted as '_UNDEFINED' by netcdf-c."
+                    )
+                    warnings.warn(msg, stacklevel=stacklevel)
+                # 5. we need to raise if the fillvalue is not within the enum_dict
+                else:
+                    msg = (
+                        f"Creating variable with specified fill_value {h5fillvalue!r}"
+                        f" which IS NOT defined in enum type {dtype!r}."
+                        f" Please provide a matching fill_value or enum type."
+                    )
+                    raise ValueError(msg)
+
+    if fillvalue is not None:
+        # cast to wanted type
+        fillvalue = np.array(h5fillvalue).astype(dtype)
+        h5fillvalue = fillvalue
+
+    return fillvalue, h5fillvalue
+
+
 class Group(Mapping):
     _variable_cls = Variable
     _dimension_cls = Dimension
+    _enumtype_cls = EnumType
+    _vltype_cls = VLType
+    _cmptype_cls = CompoundType
 
     @property
     def _group_cls(self):
@@ -486,13 +860,23 @@ class Group(Mapping):
         self._h5path = _join_h5paths(parent._h5path, name)
 
         self._dimensions = Dimensions(self)
+        self._enumtypes = _LazyObjectLookup(self, self._enumtype_cls)
+        self._vltypes = _LazyObjectLookup(self, self._vltype_cls)
+        self._cmptypes = _LazyObjectLookup(self, self._cmptype_cls)
 
         # this map keeps track of all dimensions
         if parent is self:
             self._all_dimensions = ChainMap(self._dimensions)
+            self._all_enumtypes = ChainMap(self._enumtypes)
+            self._all_vltypes = ChainMap(self._vltypes)
+            self._all_cmptypes = ChainMap(self._cmptypes)
+
         else:
             self._all_dimensions = parent._all_dimensions.new_child(self._dimensions)
             self._all_h5groups = parent._all_h5groups.new_child(self._h5group)
+            self._all_enumtypes = parent._all_enumtypes.new_child(self._enumtypes)
+            self._all_vltypes = parent._all_vltypes.new_child(self._vltypes)
+            self._all_cmptypes = parent._all_cmptypes.new_child(self._cmptypes)
 
         self._variables = _LazyObjectLookup(self, self._variable_cls)
         self._groups = _LazyObjectLookup(self, self._group_cls)
@@ -506,6 +890,9 @@ class Group(Mapping):
                 # add to the groups collection if this is a h5py(d) Group
                 # instance
                 self._groups.add(k)
+            elif isinstance(v, self._root._h5py.Datatype):
+                # add usertypes (enum, vlen, compound)
+                self._add_usertype(v)
             else:
                 if v.attrs.get("CLASS") == b"DIMENSION_SCALE":
                     # add dimension and retrieve size
@@ -587,16 +974,16 @@ class Group(Mapping):
         for k, v in self._all_dimensions.maps[0].items():
             if k in value:
                 if v != value[k]:
-                    raise ValueError("cannot modify existing dimension %r" % k)
+                    raise ValueError(f"cannot modify existing dimension {k:!r}")
             else:
                 raise ValueError(
-                    "new dimensions do not include existing dimension %r" % k
+                    f"new dimensions do not include existing dimension {k:!r}"
                 )
         self._dimensions.update(value)
 
     def _create_child_group(self, name):
         if name in self:
-            raise ValueError("unable to create group %r (name already exists)" % name)
+            raise ValueError(f"unable to create group {name:!r} (name already exists)")
         kwargs = {}
         if self._root._h5py.__name__ == "h5py":
             kwargs.update(track_order=self._track_order)
@@ -641,7 +1028,7 @@ class Group(Mapping):
     ):
         if name in self:
             raise ValueError(
-                "unable to create variable %r " "(name already exists)" % name
+                f"unable to create variable {name:!r} (name already exists)"
             )
         if data is not None:
             data = np.asarray(data)
@@ -649,14 +1036,8 @@ class Group(Mapping):
         if dtype is None:
             dtype = data.dtype
 
-        if dtype == np.bool_:
-            # never warn since h5netcdf has always errored here
-            _invalid_netcdf_feature(
-                "boolean dtypes",
-                self._root.invalid_netcdf,
-            )
-        else:
-            self._root._check_valid_netcdf_dtype(dtype)
+        # check and handle dtypes
+        dtype = _check_dtype(self, dtype)
 
         if "scaleoffset" in kwargs:
             _invalid_netcdf_feature(
@@ -708,8 +1089,8 @@ class Group(Mapping):
                 pass
             else:
                 raise ValueError(
-                    "got unrecognized value %s for chunking_heuristic argument "
-                    '(has to be "h5py" or "h5netcdf")' % chunking_heuristic
+                    f"got unrecognized value {chunking_heuristic} for chunking_heuristic argument "
+                    '(has to be "h5py" or "h5netcdf")'
                 )
 
         # Clear dummy HDF5 datasets with this name that were created for a
@@ -724,13 +1105,8 @@ class Group(Mapping):
         if self._root._h5py.__name__ == "h5py":
             kwargs.update(dict(track_order=self._parent._track_order))
 
-        # handling default fillvalues for legacyapi
-        # see https://github.com/h5netcdf/h5netcdf/issues/182
-        from .legacyapi import Dataset, _get_default_fillvalue
-
-        fillval = fillvalue
-        if fillvalue is None and isinstance(self._parent._root, Dataset):
-            fillval = _get_default_fillvalue(dtype)
+        # fill value handling
+        fillvalue, h5fillvalue = _check_fillvalue(self, fillvalue, dtype)
 
         # create hdf5 variable
         self._h5group.create_dataset(
@@ -739,7 +1115,7 @@ class Group(Mapping):
             dtype=dtype,
             data=data,
             chunks=chunks,
-            fillvalue=fillval,
+            fillvalue=h5fillvalue,
             **kwargs,
         )
 
@@ -768,22 +1144,10 @@ class Group(Mapping):
         # Todo: get this consistent with netcdf-c/netcdf4-python
         variable._ensure_dim_id()
 
+        # add fillvalue attribute to variable
         if fillvalue is not None:
-            # trying to create correct type of fillvalue
-            if variable.dtype is str:
-                value = fillvalue
-            else:
-                string_info = self._root._h5py.check_string_dtype(variable.dtype)
-                if (
-                    string_info
-                    and string_info.length is not None
-                    and string_info.length > 1
-                ):
-                    value = fillvalue
-                else:
-                    value = variable.dtype.type(fillvalue)
+            variable._add_fillvalue(fillvalue)
 
-            variable.attrs._h5attrs["_FillValue"] = value
         return variable
 
     def create_variable(
@@ -807,8 +1171,8 @@ class Group(Mapping):
         dimensions : tuple
             Tuple containing dimension name strings. Defaults to empty tuple, effectively
             creating a scalar variable.
-        dtype : numpy.dtype, str, optional
-            Dataype of the new variable. Defaults to None.
+        dtype : numpy.dtype, str, UserType (Enum, VL, Compound), optional
+            Datatype of the new variable. Defaults to None.
         fillvalue : scalar, optional
             Specify fillvalue for uninitialized parts of the variable. Defaults to ``None``.
         chunks : tuple, optional
@@ -841,6 +1205,7 @@ class Group(Mapping):
         var : h5netcdf.Variable
             Variable class instance
         """
+
         # if root-variable
         if name.startswith("/"):
             # handling default fillvalues for legacyapi
@@ -918,6 +1283,48 @@ class Group(Mapping):
     def variables(self):
         return Frozen(self._variables)
 
+    def _add_usertype(self, h5type):
+        """Add usertype to related usertype dict.
+
+        The type is added by name to the dict attached to current group.
+        """
+        name = h5type.name.split("/")[-1]
+        h5typeid = _get_h5usertype_identifier(h5type)
+        # add usertype to corresponding dict
+        self._get_usertype_dict(h5typeid).maps[0].add(name)
+
+    def _get_usertype(self, h5type):
+        """Get usertype from related usertype dict."""
+        h5typeid = _get_h5usertype_identifier(h5type)
+        return self._get_usertype_dict(h5typeid).get(h5type.name.split("/")[-1])
+
+    def _get_usertype_dict(self, h5typeid):
+        """Return usertype-dict related to given h5 type identifier.
+
+        See https://api.h5py.org/h5t.html#datatype-class-codes and
+        https://docs.hdfgroup.org (enum H5T_class_t)
+        """
+        return {
+            6: self._all_cmptypes,
+            8: self._all_enumtypes,
+            9: self._all_vltypes,
+        }.get(h5typeid)
+
+    @property
+    def enumtypes(self):
+        """Return group defined enum types."""
+        return Frozen(self._enumtypes)
+
+    @property
+    def vltypes(self):
+        """Return group defined vlen types."""
+        return Frozen(self._vltypes)
+
+    @property
+    def cmptypes(self):
+        """Return group defined compound types."""
+        return Frozen(self._cmptypes)
+
     @property
     def dims(self):
         return Frozen(self._dimensions)
@@ -936,9 +1343,11 @@ class Group(Mapping):
             + [
                 "    {}: {}".format(
                     k,
-                    f"Unlimited (current: {self._dimensions[k].size})"
-                    if v is None
-                    else v,
+                    (
+                        f"Unlimited (current: {self._dimensions[k].size})"
+                        if v is None
+                        else v
+                    ),
                 )
                 for k, v in self.dimensions.items()
             ]
@@ -967,6 +1376,59 @@ class Group(Mapping):
         """
         self._dimensions[dim]._resize(size)
 
+    def create_enumtype(self, datatype, datatype_name, enum_dict):
+        """Create EnumType.
+
+        datatype: np.dtype
+            A numpy integer dtype object describing the base type for the Enum.
+        datatype_name: string
+            A Python string containing a description of the Enum data type.
+        enum_dict: dict
+            A Python dictionary containing the Enum field/value pairs.
+        """
+        et = self._root._h5py.enum_dtype(enum_dict, basetype=datatype)
+        self._h5group[datatype_name] = et
+        # create enumtype class instance
+        enumtype = self._enumtype_cls(self, datatype_name)
+        self._enumtypes[datatype_name] = enumtype
+        return enumtype
+
+    def create_vltype(self, datatype, datatype_name):
+        """Create VLType.
+
+        datatype: np.dtype
+            A numpy dtype object describing the base type.
+        datatype_name: string
+            A Python string containing a description of the VL data type.
+        """
+        # wrap in numpy dtype first
+        datatype = np.dtype(datatype)
+        et = self._root._h5py.vlen_dtype(datatype)
+        self._h5group[datatype_name] = et
+        # create vltype class instance
+        vltype = self._vltype_cls(self, datatype_name)
+        self._vltypes[datatype_name] = vltype
+        return vltype
+
+    def create_cmptype(self, datatype, datatype_name):
+        """Create CompoundType.
+
+        datatype: np.dtype
+            A numpy dtype object describing the structured type.
+        datatype_name: string
+            A Python string containing a description of the compound data type.
+        """
+        # wrap in numpy dtype first
+        datatype = np.dtype(datatype)
+        if (new_dtype := _string_to_char_array_dtype(datatype)) is not None:
+            # "SN" -> ("S1", (N,))
+            datatype = new_dtype
+        self._h5group[datatype_name] = datatype
+        # create compound class instance
+        cmptype = self._cmptype_cls(self, datatype_name)
+        self._cmptypes[datatype_name] = cmptype
+        return cmptype
+
 
 class File(Group):
     def __init__(self, path, mode="r", invalid_netcdf=False, phony_dims=None, **kwargs):
@@ -975,7 +1437,8 @@ class File(Group):
         Parameters
         ----------
         path: path-like
-            Location of the netCDF4 file to be accessed.
+            Location of the netCDF4 file to be accessed, or an h5py File object,
+            or a Python file-like object (which should read/write bytes).
 
         mode: "r", "r+", "a", "w"
             A valid file access mode. Defaults to "r".
@@ -1010,6 +1473,10 @@ class File(Group):
 
         Datasets created with h5netcdf version 0.12.0 that are opened with
         newer versions of h5netcdf will continue to disable order tracker.
+
+        If an h5py File object is passed in, closing the h5netcdf wrapper will
+        not close the h5py File. In other cases, closing the h5netcdf File object
+        does close the underlying file.
         """
         # 2022/01/09
         # netCDF4 wants the track_order parameter to be true
@@ -1027,6 +1494,7 @@ class File(Group):
         track_order = kwargs.pop("track_order", track_order_default)
 
         self.decode_vlen_strings = kwargs.pop("decode_vlen_strings", None)
+        self._close_h5file = True
         try:
             if isinstance(path, str):
                 if (
@@ -1054,6 +1522,12 @@ class File(Group):
                     self._h5file = self._h5py.File(
                         path, mode, track_order=track_order, **kwargs
                     )
+            elif isinstance(path, h5py.File):
+                self._preexisting_file = mode in {"r", "r+", "a"}
+                self._h5py = h5py
+                self._h5file = path
+                # h5py File passed in: let the caller decide when to close it
+                self._close_h5file = False
             else:  # file-like object
                 self._preexisting_file = mode in {"r", "r+", "a"}
                 self._h5py = h5py
@@ -1129,16 +1603,10 @@ class File(Group):
     def _check_valid_netcdf_dtype(self, dtype):
         dtype = np.dtype(dtype)
 
-        if dtype == bool:
+        if dtype == bool:  # noqa
             description = "boolean"
-        elif dtype == complex:
-            description = "complex"
-        elif h5py.check_dtype(enum=dtype) is not None:
-            description = "enum"
-        elif h5py.check_dtype(ref=dtype) is not None:
+        elif self._h5py.check_dtype(ref=dtype) is not None:
             description = "reference"
-        elif h5py.check_dtype(vlen=dtype) not in {None, str, bytes}:
-            description = "non-string variable length"
         else:
             description = None
 
@@ -1168,15 +1636,14 @@ class File(Group):
         if self._writable:
             # only write `_NCProperties` in newly created files
             if not self._preexisting_file and not self.invalid_netcdf:
-                _NC_PROPERTIES = "version=2,h5netcdf={},hdf5={},{}={}".format(
-                    __version__,
-                    self._h5py.version.hdf5_version,
-                    self._h5py.__name__,
-                    self._h5py.__version__,
+                _NC_PROPERTIES = (
+                    f"version=2,h5netcdf={__version__},"
+                    f"hdf5={self._h5py.version.hdf5_version},"
+                    f"{self._h5py.__name__}={self._h5py.__version__}"
                 )
                 self.attrs._h5attrs["_NCProperties"] = np.array(
                     _NC_PROPERTIES,
-                    dtype=h5py.string_dtype(
+                    dtype=self._h5py.string_dtype(
                         encoding="ascii", length=len(_NC_PROPERTIES)
                     ),
                 )
@@ -1200,7 +1667,9 @@ class File(Group):
     def close(self):
         if not self._closed:
             self.flush()
-            self._h5file.close()
+            if self._close_h5file:
+                self._h5file.close()
+            self._h5file = None
             self._closed = True
 
     __del__ = close
@@ -1215,11 +1684,9 @@ class File(Group):
 
     def __repr__(self):
         if self._closed:
-            return "<Closed %s>" % self._cls_name
-        header = "<{} {!r} (mode {})>".format(
-            self._cls_name,
-            self.filename.split("/")[-1],
-            self.mode,
+            return f"<Closed {self._cls_name}>"
+        header = (
+            f"<{self._cls_name} {os.path.basename(self.filename)!r} (mode {self.mode})>"
         )
         return "\n".join([header] + self._repr_body())