h5t 0.2.0__py3-none-any.whl

h5t/__init__.py

@@ -0,0 +1,20 @@
+"""Detached, typed records for read-only HDF5 access."""
+
+from h5t._compile import Dataset, Group
+from h5t._errors import ConversionError, H5TError, SchemaError, ValidationError
+from h5t._spec import Attr, Eager, Name
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "Attr",
+    "ConversionError",
+    "Dataset",
+    "Eager",
+    "Group",
+    "H5TError",
+    "Name",
+    "SchemaError",
+    "ValidationError",
+    "__version__",
+]

h5t/_cli.py

@@ -0,0 +1,66 @@
+"""The ``h5t check`` command."""
+
+from __future__ import annotations
+
+import argparse
+import importlib
+import sys
+from typing import NoReturn
+
+from h5t._compile import Group
+from h5t._errors import SchemaError, ValidationError
+
+
+def _fail(message: str) -> NoReturn:
+    print(f"error: {message}", file=sys.stderr)
+    raise SystemExit(2)
+
+
+def _load_schema(ref: str) -> type[Group]:
+    module_name, separator, class_name = ref.partition(":")
+    if not separator or not module_name or not class_name:
+        _fail(f"--schema must look like pkg.module:ClassName, got {ref!r}")
+    try:
+        module = importlib.import_module(module_name)
+    except Exception as exc:
+        _fail(f"could not import module {module_name!r}: {exc}")
+    try:
+        schema = getattr(module, class_name)
+    except AttributeError:
+        _fail(f"module {module_name!r} has no attribute {class_name!r}")
+    if not (isinstance(schema, type) and issubclass(schema, Group)):
+        _fail(f"{ref!r} is not an h5t.Group schema class")
+    return schema
+
+
+def _cmd_check(args: argparse.Namespace) -> int:
+    schema = _load_schema(args.schema)
+    try:
+        schema.from_file(args.file, root=args.root)
+    except ValidationError as exc:
+        print(f"invalid: {args.file} against {schema.__name__}: {exc}")
+        return 1
+    except (OSError, ValueError, TypeError, SchemaError) as exc:
+        _fail(f"could not check {args.file!r}: {exc}")
+    print(f"ok: {args.file} validates against {schema.__name__} at {args.root}")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the command line interface and return its process exit code."""
+    parser = argparse.ArgumentParser(
+        prog="h5t",
+        description="Validate and materialize an HDF5 group schema.",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    check = subparsers.add_parser("check", help="check an HDF5 file against a Group schema")
+    check.add_argument("file", help="path to the HDF5 file")
+    check.add_argument("--schema", required=True, help="schema reference, e.g. pkg.schemas:Result")
+    check.add_argument("--root", default="/", help="absolute HDF5 group path (default: /)")
+    check.set_defaults(func=_cmd_check)
+    args = parser.parse_args(argv)
+    return int(args.func(args))
+
+
+if __name__ == "__main__":
+    sys.exit(main())

h5t/_compile.py

@@ -0,0 +1,840 @@
+"""Schema compilation and detached HDF5 loading."""
+
+from __future__ import annotations
+
+import inspect
+import os
+import posixpath
+import reprlib
+import sys
+import types
+import typing
+import weakref
+from collections.abc import Collection, Iterator, Mapping
+from contextlib import contextmanager
+from enum import Enum
+from types import MappingProxyType
+from typing import Annotated, Any, ClassVar, Literal, Self
+
+import h5py
+import numpy as np
+from pydantic import ConfigDict, TypeAdapter
+from pydantic import ValidationError as PydanticValidationError
+
+from h5t._errors import ConversionError, SchemaError, ValidationError
+from h5t._spec import (
+    _NO_DEFAULT,
+    Attr,
+    ClassSpec,
+    Eager,
+    Extras,
+    FieldSpec,
+    MemberKind,
+    Name,
+    attr_path,
+    child_path,
+)
+
+_SCALAR_TYPES = (str, int, float, bool, bytes, complex)
+_DATA_NOT_LOADED = object()
+
+
+def _schema_error(owner: type, field: str, message: str) -> SchemaError:
+    return SchemaError(f"{owner.__name__}.{field}: {message}")
+
+
+_ANNOTATION_FILE = "<h5t annotation>"
+
+
+class _UnresolvedAnnotation(Exception):
+    """An annotation names something not defined yet, so compilation must defer.
+
+    Private to this module: raised while resolving annotations and turned into the
+    user-visible ``SchemaError`` by ``_ensure_compiled`` if the name is still missing
+    when the spec is finally read.
+    """
+
+    def __init__(self, owner: type, name: str | None, message: str) -> None:
+        super().__init__(message)
+        self.owner = owner
+        self.name = name
+
+
+def _raised_by_annotation(exc: NameError, cls: type) -> bool:
+    """Report whether ``exc`` came from the annotation expression itself, not a callee.
+
+    Only an unbound name in the expression is a forward reference worth deferring for.
+    A ``NameError`` escaping a function the annotation calls is a bug in that function,
+    so it must take the ``SchemaError`` path instead. The frame that raised identifies
+    the two: a PEP 563 string annotation is compiled under ``_ANNOTATION_FILE``, and a
+    PEP 649 lazy annotation is evaluated by ``cls``'s own ``__annotate__`` function.
+    """
+    tb = exc.__traceback__
+    while tb is not None and tb.tb_next is not None:
+        tb = tb.tb_next
+    if tb is None:
+        return False
+    code = tb.tb_frame.f_code
+    if code.co_filename == _ANNOTATION_FILE:
+        return True
+    # A class with no annotations of its own has ``__annotate__ is None``.
+    return code is getattr(getattr(cls, "__annotate__", None), "__code__", None)
+
+
+def _code_names(code: types.CodeType) -> set[str]:
+    """Collect every name ``code`` and the code objects nested in it could load.
+
+    ``co_names`` over-approximates -- it also holds attribute names -- which is the
+    safe direction, since a name the snapshot drops is one resolution cannot find.
+    Nested code objects (a lambda inside an annotation) load their names the same way.
+
+    ``co_freevars`` is deliberately not collected. A class ``__annotate__`` has free
+    variables only when an enclosing function scope exists, which is exactly when its
+    closure keeps those cells reachable on its own -- so for that set the snapshot is
+    redundant, and adding it would only widen what ``_weak_scope`` holds strongly.
+    """
+    names: set[str] = set()
+    pending = [code]
+    while pending:
+        current = pending.pop()
+        names.update(current.co_names)
+        pending.extend(c for c in current.co_consts if isinstance(c, types.CodeType))
+    return names
+
+
+def _names_in_source(source: str) -> set[str]:
+    """Collect every name the annotation expression ``source`` could load."""
+    try:
+        code = compile(source, _ANNOTATION_FILE, "eval")
+    except SyntaxError:
+        # Unparseable: reading the spec raises SchemaError, so nothing is needed.
+        return set()
+    return _code_names(code)
+
+
+def _referenced_names(annotations: Mapping[str, Any]) -> set[str]:
+    """Collect every name the string annotations in ``annotations`` could load."""
+    names: set[str] = set()
+    for annotation in annotations.values():
+        if isinstance(annotation, str):
+            names.update(_names_in_source(annotation))
+    return names
+
+
+def _quoted_names(code: types.CodeType) -> set[str]:
+    """Collect every name the string constants in ``code`` could load.
+
+    A quoted annotation is a plain string constant in ``__annotate__``: the names it
+    mentions never reach ``co_names``, and the compiler makes no closure cell for them
+    either, so unlike a bare annotation it has nothing else to resolve through.
+    Reading them back out of the constants is what keeps a quoted forward reference
+    resolvable in a class that some *other* annotation forced onto the deferred path.
+    """
+    names: set[str] = set()
+    pending = [code]
+    while pending:
+        current = pending.pop()
+        for const in current.co_consts:
+            if isinstance(const, types.CodeType):
+                pending.append(const)
+            elif isinstance(const, str):
+                names.update(_names_in_source(const))
+    return names
+
+
+def _annotation_names(cls: type) -> set[str]:
+    """Collect every name ``cls``'s own annotations could load, however they failed.
+
+    Reading the annotations yields PEP 563 strings, which name what they mention. On
+    3.14 the read is itself the evaluation (PEP 649), so an annotation that could not
+    resolve has no value left to inspect: the names come straight off the
+    ``__annotate__`` code object instead, without re-running an expression that
+    already raised. ``annotationlib``'s ``STRING`` and ``FORWARDREF`` formats look
+    like the obvious source here and are not: both re-execute the annotation with the
+    real globals first and swallow whatever it raises, which would run a user's
+    annotation helper -- and hide its bug -- from inside an exception handler.
+    """
+    try:
+        annotations = inspect.get_annotations(cls, eval_str=False)
+    except Exception:
+        annotate = getattr(cls, "__annotate__", None)
+        code = getattr(annotate, "__code__", None)
+        if code is None:
+            return set()
+        # _weak_scope keeps only names the scope holds, so the compiler's own
+        # __classdict__ freevar drops out.
+        return _code_names(code) | _quoted_names(code)
+    return _referenced_names(annotations)
+
+
+def _weak_scope(scope: Mapping[str, Any], names: Collection[str]) -> dict[str, Any]:
+    """Snapshot the ``names`` entries of ``scope``, weakly wherever the value allows.
+
+    Scopes are only retained by the deferred path, where the snapshot may outlive the
+    frame it came from, so it keeps just the names the unresolved annotations mention.
+    Values that reject ``weakref.ref`` (``int``, ``str``, tuples, dicts) are stored
+    directly, and an unfiltered snapshot would let one of those containers pin an
+    unrelated local object graph for as long as the schema class lives.
+    """
+    snapshot: dict[str, Any] = {}
+    for name in names:
+        if name not in scope:
+            continue
+        value = scope[name]
+        try:
+            snapshot[name] = weakref.ref(value)
+        except TypeError:
+            snapshot[name] = value
+    return snapshot
+
+
+def _unpack_scope(snapshot: Mapping[str, Any]) -> dict[str, Any]:
+    """Reverse ``_weak_scope``, dropping entries whose referent was collected."""
+    scope: dict[str, Any] = {}
+    for name, value in snapshot.items():
+        if isinstance(value, weakref.ref):
+            referent = value()
+            if referent is not None:
+                scope[name] = referent
+        else:
+            scope[name] = value
+    return scope
+
+
+def _split_annotation(owner: type, py_name: str, annotation: Any) -> tuple[Any, list[Any], bool]:
+    """Extract h5t/constraint metadata and optionality from an annotation."""
+    metadata: list[Any] = []
+    optional = False
+    core = annotation
+    while True:
+        if typing.get_origin(core) is Annotated:
+            args = typing.get_args(core)
+            core = args[0]
+            metadata.extend(args[1:])
+            continue
+        origin = typing.get_origin(core)
+        if origin in (typing.Union, types.UnionType):
+            args = typing.get_args(core)
+            without_none = tuple(arg for arg in args if arg is not type(None))
+            if len(without_none) != len(args):
+                optional = True
+            if len(without_none) != 1:
+                raise _schema_error(
+                    owner,
+                    py_name,
+                    "only optional unions of the form 'T | None' are supported",
+                )
+            core = without_none[0]
+            continue
+        return core, metadata, optional
+
+
+def _adapter_annotation(core: Any, metadata: list[Any], optional: bool) -> Any:
+    foreign = tuple(item for item in metadata if not isinstance(item, (Name, Attr, Eager)))
+    annotation = Annotated[core, *foreign] if foreign else core
+    return annotation | None if optional else annotation
+
+
+def _build_adapter(owner: type, py_name: str, annotation: Any) -> TypeAdapter[Any]:
+    try:
+        return TypeAdapter(annotation, config=ConfigDict(arbitrary_types_allowed=True))
+    except Exception as exc:
+        raise _schema_error(owner, py_name, f"cannot construct a validator: {exc}") from exc
+
+
+def _marker(metadata: list[Any], marker_type: type, owner: type, py_name: str) -> Any | None:
+    found = [item for item in metadata if isinstance(item, marker_type)]
+    if len(found) > 1:
+        raise _schema_error(owner, py_name, f"{marker_type.__name__} may appear only once")
+    return found[0] if found else None
+
+
+# PEP 695 aliases are 3.12+; on 3.11 the empty tuple makes every isinstance False.
+_alias_type = getattr(typing, "TypeAliasType", None)
+_TYPE_ALIAS_TYPES: tuple[type, ...] = (_alias_type,) if isinstance(_alias_type, type) else ()
+_MAX_ALIAS_DEPTH = 16
+
+
+def _is_ndarray_annotation(core: Any) -> bool:
+    """Report whether ``core`` denotes ``np.ndarray``, however many aliases deep.
+
+    numpy >= 2.5 defines ``npt.NDArray`` as a PEP 695 ``TypeAliasType``, which defers
+    its right-hand side -- deferring is what lets an alias recurse -- so
+    ``typing.get_origin`` stops at the alias itself. numpy <= 2.4 built the same name
+    out of eager substitution, leaving ``np.ndarray`` directly visible as the origin.
+    Expanding ``__value__`` sees through either shape, and through a user's own alias
+    of one. The walk is depth-bounded because a PEP 695 alias may be self-referential.
+    """
+    for _ in range(_MAX_ALIAS_DEPTH):
+        if core is np.ndarray:
+            return True
+        origin = typing.get_origin(core)
+        if origin is np.ndarray:
+            return True
+        if isinstance(core, _TYPE_ALIAS_TYPES):
+            core = core.__value__
+        elif isinstance(origin, _TYPE_ALIAS_TYPES):
+            # A subscripted alias: __value__ carries the parameter, which is dropped
+            # here along with the dtype the classification already ignores.
+            core = origin.__value__
+        else:
+            return False
+    return False
+
+
+def _is_scalar_annotation(core: Any) -> bool:
+    if core in _SCALAR_TYPES or typing.get_origin(core) is Literal:
+        return True
+    return isinstance(core, type) and (issubclass(core, Enum) or issubclass(core, np.generic))
+
+
+def _field_spec(
+    owner: type,
+    py_name: str,
+    annotation: Any,
+    default: Any,
+    *,
+    dataset_owner: bool,
+) -> FieldSpec:
+    core, metadata, optional = _split_annotation(owner, py_name, annotation)
+    name_marker = _marker(metadata, Name, owner, py_name)
+    attr_marker = _marker(metadata, Attr, owner, py_name)
+    eager_marker = _marker(metadata, Eager, owner, py_name)
+
+    h5_name = name_marker.name if name_marker is not None else py_name
+    if not isinstance(h5_name, str) or not h5_name:
+        raise _schema_error(owner, py_name, "Name requires a non-empty string")
+    if attr_marker is not None and attr_marker.converter is not None:
+        if not callable(attr_marker.converter):
+            raise _schema_error(owner, py_name, "Attr.converter must be callable")
+    if attr_marker is not None and eager_marker is not None:
+        raise _schema_error(owner, py_name, "Attr and Eager cannot be combined")
+
+    is_dataset = isinstance(core, type) and issubclass(core, Dataset)
+    is_group = isinstance(core, type) and issubclass(core, Group)
+
+    if attr_marker is not None:
+        if is_dataset or is_group:
+            raise _schema_error(owner, py_name, "Attr cannot annotate a Group or Dataset field")
+        kind = MemberKind.ATTRIBUTE
+        member_type = None
+    elif is_dataset:
+        kind = MemberKind.DATASET
+        member_type = core
+    elif is_group:
+        kind = MemberKind.GROUP
+        member_type = core
+    elif _is_ndarray_annotation(core):
+        # Accept npt.NDArray[...] aliases. The dtype parameter is not validated
+        # (the adapter degrades to an isinstance check), so normalize to the
+        # plain type to keep declaration equivalence dtype-agnostic.
+        kind = MemberKind.ARRAY
+        member_type = None
+        core = np.ndarray
+    elif _is_scalar_annotation(core):
+        kind = MemberKind.ATTRIBUTE
+        member_type = None
+    else:
+        raise _schema_error(
+            owner,
+            py_name,
+            f"unsupported annotation {core!r}; containers require Attr(), and dynamic "
+            "collections are not supported",
+        )
+
+    if eager_marker is not None and kind is not MemberKind.DATASET:
+        raise _schema_error(owner, py_name, "Eager applies only to Dataset fields")
+    if dataset_owner and kind is not MemberKind.ATTRIBUTE:
+        raise _schema_error(owner, py_name, "a Dataset subclass may declare only attributes")
+    if kind is not MemberKind.ATTRIBUTE and "/" in h5_name:
+        raise _schema_error(owner, py_name, "a child Name cannot contain '/'")
+
+    adapter_ann = _adapter_annotation(core, metadata, optional)
+    return FieldSpec(
+        py_name=py_name,
+        h5_name=h5_name,
+        kind=kind,
+        annotation=adapter_ann,
+        adapter=_build_adapter(owner, py_name, adapter_ann),
+        optional=optional,
+        default=default,
+        converter=attr_marker.converter if attr_marker is not None else None,
+        eager=eager_marker is not None,
+        member_type=member_type,
+    )
+
+
+def _annotation_failure(cls: type, exc: Exception) -> Exception:
+    """Classify a failure to resolve ``cls``'s annotations."""
+    if isinstance(exc, NameError) and _raised_by_annotation(exc, cls):
+        return _UnresolvedAnnotation(cls, exc.name, str(exc))
+    return SchemaError(f"{cls.__name__}: could not resolve annotations: {exc}")
+
+
+def _resolved_annotations(cls: type, scope: Mapping[str, Any] | None = None) -> dict[str, Any]:
+    """Return ``cls``'s own annotations, evaluating PEP 563 strings.
+
+    Names resolve against the defining module, then ``scope`` -- the live locals of
+    the defining frame while the class is being created, or the weak snapshot kept
+    by the deferred path -- then the class body.
+    """
+    try:
+        annotations = inspect.get_annotations(cls, eval_str=False)
+    except Exception as exc:
+        # PEP 649 (3.14+): this call evaluates lazy annotations, so it fails here
+        # where older versions failed at the ``class`` statement itself.
+        raise _annotation_failure(cls, exc) from exc
+    if not any(isinstance(annotation, str) for annotation in annotations.values()):
+        return annotations
+    if scope is None:
+        scope = _unpack_scope(cls.__dict__.get("_h5t_scope", {}))
+    module = sys.modules.get(cls.__module__)
+    namespace: dict[str, Any] = dict(vars(module)) if module is not None else {}
+    namespace.update(scope)
+    namespace.update(vars(cls))
+    try:
+        return {
+            name: eval(compile(annotation, _ANNOTATION_FILE, "eval"), namespace)
+            if isinstance(annotation, str)
+            else annotation
+            for name, annotation in annotations.items()
+        }
+    except Exception as exc:
+        raise _annotation_failure(cls, exc) from exc
+
+
+def _own_fields(
+    cls: type, *, dataset_owner: bool, scope: Mapping[str, Any] | None = None
+) -> dict[str, FieldSpec]:
+    annotations = _resolved_annotations(cls, scope)
+    fields: dict[str, FieldSpec] = {}
+    for py_name, annotation in annotations.items():
+        if py_name.startswith("_") or typing.get_origin(annotation) is ClassVar:
+            continue
+        default = cls.__dict__.get(py_name, _NO_DEFAULT)
+        fields[py_name] = _field_spec(
+            cls,
+            py_name,
+            annotation,
+            default,
+            dataset_owner=dataset_owner,
+        )
+    return fields
+
+
+def _merged_fields(cls: type) -> dict[str, FieldSpec]:
+    merged: dict[str, tuple[type, FieldSpec]] = {}
+    for candidate in reversed(cls.__mro__):
+        own = candidate.__dict__.get("_h5t_own")
+        if not own:
+            continue
+        for name, field in own.items():
+            previous = merged.get(name)
+            if previous is None:
+                merged[name] = (candidate, field)
+                continue
+            previous_owner, previous_field = previous
+            if issubclass(candidate, previous_owner):
+                merged[name] = (candidate, field)
+            elif not _fields_equivalent(field, previous_field):
+                raise SchemaError(
+                    f"{cls.__name__}.{name}: conflicting declarations in bases "
+                    f"{previous_owner.__name__} and {candidate.__name__}"
+                )
+    return {name: field for name, (_, field) in merged.items()}
+
+
+def _fields_equivalent(left: FieldSpec, right: FieldSpec) -> bool:
+    """Compare declarations without adapter identity or array-valued equality."""
+    return (
+        left.py_name == right.py_name
+        and left.h5_name == right.h5_name
+        and left.kind is right.kind
+        and repr(left.annotation) == repr(right.annotation)
+        and left.optional == right.optional
+        and repr(left.default) == repr(right.default)
+        and left.converter is right.converter
+        and left.eager == right.eager
+        and left.member_type is right.member_type
+    )
+
+
+def _resolve_extras(cls: type) -> Extras:
+    requested = cls.__dict__.get("_h5t_extras")
+    if requested is not None:
+        try:
+            return Extras(requested)
+        except ValueError:
+            raise SchemaError(
+                f"{cls.__name__}: extras must be 'ignore' or 'forbid', got {requested!r}"
+            ) from None
+    for base in cls.__mro__[1:]:
+        spec = base.__dict__.get("_h5t_spec")
+        if spec is not None:
+            return spec.extras
+    return Extras.IGNORE
+
+
+def _reserved_names(base: type) -> frozenset[str]:
+    return frozenset(name for name in dir(base) if not name.startswith("_"))
+
+
+def _check_fields(cls: type, own: Mapping[str, FieldSpec], fields: Mapping[str, FieldSpec]) -> None:
+    base = Dataset if issubclass(cls, Dataset) else Group
+    reserved = _reserved_names(base)
+    for name in own:
+        if name in reserved:
+            raise _schema_error(
+                cls,
+                name,
+                f"field shadows the h5t API; rename it and use Name({name!r})",
+            )
+
+    attr_names: dict[str, str] = {}
+    child_names: dict[str, str] = {}
+    for py_name, field in fields.items():
+        namespace = attr_names if field.kind is MemberKind.ATTRIBUTE else child_names
+        if field.h5_name in namespace:
+            raise SchemaError(
+                f"{cls.__name__}: duplicate HDF5 name {field.h5_name!r} for fields "
+                f"{namespace[field.h5_name]!r} and {py_name!r}"
+            )
+        namespace[field.h5_name] = py_name
+
+
+def _compile_class(cls: SchemaMeta, scope: Mapping[str, Any] | None = None) -> None:
+    """Compile ``cls`` into its own fields and its flattened schema."""
+    for base in cls.__mro__[1:]:
+        if isinstance(base, SchemaMeta) and "_h5t_spec" not in base.__dict__:
+            # _merged_fields and _resolve_extras read compiled state off the bases.
+            # A base that is still waiting on a forward reference defers ``cls`` too.
+            _compile_class(base)
+    own = _own_fields(cls, dataset_owner=issubclass(cls, Dataset), scope=scope)
+    cls._h5t_own = own
+    fields = _merged_fields(cls)
+    _check_fields(cls, own, fields)
+    cls._h5t_spec = ClassSpec(tuple(fields.values()), _resolve_extras(cls))
+
+
+def _ensure_compiled(cls: SchemaMeta) -> None:
+    if "_h5t_spec" in cls.__dict__:
+        return
+    try:
+        _compile_class(cls)
+    except _UnresolvedAnnotation as exc:
+        raise SchemaError(f"{exc.owner.__name__}: could not resolve annotations: {exc}") from exc
+
+
+class SchemaMeta(type):
+    """Metaclass exposing a schema class's compiled spec.
+
+    Schemas compile at the ``class`` statement, so a bad declaration raises there.
+    This property is the fallback route for the classes that could not: one whose
+    annotations name something defined later compiles on the first read instead.
+    """
+
+    _h5t_own: dict[str, FieldSpec]
+    _h5t_spec: ClassSpec
+
+    @property
+    def __h5spec__(cls) -> ClassSpec:
+        """The flattened schema of this class, compiled on first access."""
+        _ensure_compiled(cls)
+        return cls._h5t_spec
+
+
+def _short_pydantic_error(exc: PydanticValidationError) -> str:
+    errors = exc.errors(include_url=False, include_context=False, include_input=False)
+    if not errors:
+        return str(exc).splitlines()[0]
+    first = errors[0]
+    location = ".".join(str(part) for part in first.get("loc", ()))
+    message = str(first.get("msg", "invalid value"))
+    return f"{location}: {message}" if location else message
+
+
+def _validate_value(field: FieldSpec, value: Any, path: str) -> Any:
+    try:
+        return field.adapter.validate_python(value)
+    except PydanticValidationError as exc:
+        raise ValidationError(path, _short_pydantic_error(exc)) from exc
+
+
+def _missing_value(field: FieldSpec, path: str) -> Any:
+    if field.has_default:
+        return _validate_value(field, field.default, path)
+    if field.optional:
+        return None
+    kind = field.kind.value
+    raise ValidationError(path, f"required {kind} {field.h5_name!r} is missing")
+
+
+def _raw_attrs(node: h5py.Group | h5py.Dataset) -> dict[str, Any]:
+    return {str(name): node.attrs[name] for name in node.attrs}
+
+
+def _check_group_extras(spec: ClassSpec, group: h5py.Group, path: str) -> None:
+    if spec.extras is Extras.IGNORE:
+        return
+    attrs = {field.h5_name for field in spec.fields if field.kind is MemberKind.ATTRIBUTE}
+    children = {field.h5_name for field in spec.fields if field.kind is not MemberKind.ATTRIBUTE}
+    for name in group.attrs:
+        rendered = str(name)
+        if rendered not in attrs:
+            raise ValidationError(attr_path(path, rendered), "unexpected attribute")
+    for name in group.keys():
+        rendered = str(name)
+        if rendered not in children:
+            raise ValidationError(child_path(path, rendered), "unexpected child node")
+
+
+def _check_dataset_extras(spec: ClassSpec, dataset: h5py.Dataset, path: str) -> None:
+    if spec.extras is Extras.IGNORE:
+        return
+    attrs = {field.h5_name for field in spec.fields}
+    for name in dataset.attrs:
+        rendered = str(name)
+        if rendered not in attrs:
+            raise ValidationError(attr_path(path, rendered), "unexpected attribute")
+
+
+def _load_attribute(
+    field: FieldSpec,
+    raw: Mapping[str, Any],
+    attrs: dict[str, Any],
+    parent_path: str,
+) -> Any:
+    path = attr_path(parent_path, field.h5_name)
+    if field.h5_name not in raw:
+        value = _missing_value(field, path)
+    else:
+        value = raw[field.h5_name]
+        if field.converter is not None:
+            try:
+                value = field.converter(value)
+            except Exception as exc:
+                raise ConversionError(path, f"attribute converter failed: {exc}") from exc
+        value = _validate_value(field, value, path)
+    attrs[field.h5_name] = value
+    return value
+
+
+def _load_dataset(
+    dataset_type: type[Dataset],
+    dataset: h5py.Dataset,
+    filename: str,
+    path: str,
+) -> Dataset:
+    spec = dataset_type.__h5spec__
+    _check_dataset_extras(spec, dataset, path)
+    raw = _raw_attrs(dataset)
+    attrs = dict(raw)
+    values: dict[str, Any] = {}
+    for field in spec.fields:
+        values[field.py_name] = _load_attribute(field, raw, attrs, path)
+
+    instance = object.__new__(dataset_type)
+    object.__setattr__(instance, "_h5t_filename", filename)
+    object.__setattr__(instance, "_h5t_path", path)
+    object.__setattr__(instance, "_h5t_shape", tuple(dataset.shape))
+    object.__setattr__(instance, "_h5t_dtype", np.dtype(dataset.dtype))
+    object.__setattr__(instance, "_h5t_attrs", MappingProxyType(attrs))
+    object.__setattr__(instance, "_h5t_data", _DATA_NOT_LOADED)
+    for name, value in values.items():
+        object.__setattr__(instance, name, value)
+    return instance
+
+
+def _load_group(group_type: type[Group], group: h5py.Group, filename: str, path: str) -> Group:
+    spec = group_type.__h5spec__
+    _check_group_extras(spec, group, path)
+    raw = _raw_attrs(group)
+    attrs = dict(raw)
+    values: dict[str, Any] = {}
+
+    for field in spec.fields:
+        if field.kind is MemberKind.ATTRIBUTE:
+            values[field.py_name] = _load_attribute(field, raw, attrs, path)
+            continue
+
+        member_path = child_path(path, field.h5_name)
+        if field.h5_name not in group:
+            values[field.py_name] = _missing_value(field, member_path)
+            continue
+        node = group[field.h5_name]
+        if field.kind is MemberKind.GROUP:
+            if not isinstance(node, h5py.Group):
+                raise ValidationError(member_path, "expected a group, found a dataset")
+            assert field.member_type is not None
+            nested_group_type = typing.cast(type[Group], field.member_type)
+            value = _load_group(nested_group_type, node, filename, member_path)
+        elif field.kind is MemberKind.DATASET:
+            if not isinstance(node, h5py.Dataset):
+                raise ValidationError(member_path, "expected a dataset, found a group")
+            assert field.member_type is not None
+            dataset_type = typing.cast(type[Dataset], field.member_type)
+            value = _load_dataset(dataset_type, node, filename, member_path)
+            if field.eager:
+                object.__setattr__(value, "_h5t_data", np.asarray(node[()]))
+        else:
+            if not isinstance(node, h5py.Dataset):
+                raise ValidationError(member_path, "expected a dataset, found a group")
+            value = np.asarray(node[()])
+        values[field.py_name] = _validate_value(field, value, member_path)
+
+    instance = object.__new__(group_type)
+    object.__setattr__(instance, "_h5t_attrs", MappingProxyType(attrs))
+    for name, value in values.items():
+        object.__setattr__(instance, name, value)
+    return instance
+
+
+class _Record(metaclass=SchemaMeta):
+    """Shared declaration handling and repr for detached schema records."""
+
+    _h5t_extras: ClassVar[str | None] = None
+    _h5t_scope: ClassVar[Mapping[str, Any]] = {}
+
+    def __init_subclass__(
+        cls,
+        *,
+        extras: Literal["ignore", "forbid"] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init_subclass__(**kwargs)
+        cls._h5t_extras = extras
+        if cls.__module__ == __name__:
+            # Group and Dataset themselves: the module globals _compile_class reads
+            # (issubclass(cls, Dataset)) are not bound yet. They compile on first use.
+            return
+        # The defining frame is still live, so its locals resolve annotations naming
+        # function-local classes without retaining anything. Only a genuine forward
+        # reference defers, and only that path keeps a (weak) snapshot of the scope.
+        frame = inspect.currentframe()
+        scope: Mapping[str, Any] = (
+            frame.f_back.f_locals if frame is not None and frame.f_back else {}
+        )
+        try:
+            _compile_class(cls, scope)
+        except _UnresolvedAnnotation:
+            cls._h5t_scope = _weak_scope(scope, _annotation_names(cls))
+
+    def _h5t_repr_fields(self) -> list[tuple[str, Any]]:
+        spec = type(self).__h5spec__
+        return [(field.py_name, getattr(self, field.py_name)) for field in spec.fields]
+
+    def __repr__(self) -> str:
+        fields = ", ".join(
+            f"{name}={reprlib.repr(value)}" for name, value in self._h5t_repr_fields()
+        )
+        return f"{type(self).__name__}({fields})"
+
+
+class Dataset(_Record):
+    """A detached HDF5 dataset with snapshotted metadata and lazy payload data."""
+
+    _h5t_filename: str
+    _h5t_path: str
+    _h5t_shape: tuple[int, ...]
+    _h5t_dtype: np.dtype[Any]
+    _h5t_attrs: Mapping[str, Any]
+    _h5t_data: object
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        raise TypeError(f"{type(self).__name__} objects are created by Group.from_file()")
+
+    @property
+    def attrs(self) -> Mapping[str, Any]:
+        """Immutable snapshot of all dataset attributes."""
+        return self._h5t_attrs
+
+    @property
+    def path(self) -> str:
+        """Absolute HDF5 path of this dataset."""
+        return self._h5t_path
+
+    @property
+    def shape(self) -> tuple[int, ...]:
+        """Dataset shape captured while the model was loaded."""
+        return self._h5t_shape
+
+    @property
+    def dtype(self) -> np.dtype[Any]:
+        """Dataset dtype captured while the model was loaded."""
+        return self._h5t_dtype
+
+    @property
+    def ndim(self) -> int:
+        """Number of dimensions in the captured shape."""
+        return len(self._h5t_shape)
+
+    @property
+    def data(self) -> np.ndarray:
+        """Read and cache the complete current payload as a NumPy array."""
+        if self._h5t_data is _DATA_NOT_LOADED:
+            with self.open() as dataset:
+                value = np.asarray(dataset[()])
+            object.__setattr__(self, "_h5t_data", value)
+        return typing.cast(np.ndarray, self._h5t_data)
+
+    def read(self) -> np.ndarray:
+        """Return the same cached complete payload as ``data``."""
+        return self.data
+
+    @contextmanager
+    def open(self) -> Iterator[h5py.Dataset]:
+        """Open the current source file and yield this dataset for live access."""
+        with h5py.File(self._h5t_filename, mode="r") as h5file:
+            node = h5file.get(self._h5t_path)
+            if node is None:
+                raise ValidationError(self._h5t_path, "dataset no longer exists")
+            if not isinstance(node, h5py.Dataset):
+                raise ValidationError(self._h5t_path, "expected a dataset, found a group")
+            yield node
+
+    def _h5t_repr_fields(self) -> list[tuple[str, Any]]:
+        fields: list[tuple[str, Any]] = [
+            ("path", self.path),
+            ("shape", self.shape),
+            ("dtype", self.dtype),
+        ]
+        fields.extend(super()._h5t_repr_fields())
+        return fields
+
+
+class Group(_Record):
+    """Base class for detached, typed HDF5 group records."""
+
+    _h5t_attrs: Mapping[str, Any]
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        raise TypeError(
+            f"{type(self).__name__} objects are created by {type(self).__name__}.from_file()"
+        )
+
+    @property
+    def attrs(self) -> Mapping[str, Any]:
+        """Immutable snapshot of all group attributes."""
+        return self._h5t_attrs
+
+    @classmethod
+    def from_file(cls, path: str | os.PathLike[str], root: str = "/") -> Self:
+        """Load this group schema from ``root`` and close the HDF5 file."""
+        _ensure_compiled(cls)  # compile a deferred schema before touching the filesystem
+        try:
+            filesystem_path = os.fsdecode(os.fspath(path))
+        except TypeError as exc:
+            raise TypeError("path must be a filesystem path") from exc
+        if not isinstance(root, str) or not posixpath.isabs(root):
+            raise ValueError("root must be an absolute HDF5 group path")
+        normalized_root = posixpath.normpath(root)
+        if normalized_root.startswith("//"):
+            normalized_root = "/" + normalized_root.lstrip("/")
+        filename = os.path.abspath(filesystem_path)
+        with h5py.File(filename, mode="r") as h5file:
+            node = h5file.get(normalized_root)
+            if node is None:
+                raise ValidationError(normalized_root, "root group does not exist")
+            if not isinstance(node, h5py.Group):
+                raise ValidationError(normalized_root, "expected a group, found a dataset")
+            return typing.cast(Self, _load_group(cls, node, filename, normalized_root))

h5t/_errors.py

@@ -0,0 +1,24 @@
+"""Public exception types for schema compilation and detached loading."""
+
+from __future__ import annotations
+
+
+class H5TError(Exception):
+    """Base class for h5t errors."""
+
+
+class SchemaError(H5TError):
+    """A schema class declaration is incoherent or unsupported."""
+
+
+class ValidationError(H5TError):
+    """An HDF5 node does not conform to a compiled schema."""
+
+    def __init__(self, path: str, message: str) -> None:
+        super().__init__(f"{path}: {message}")
+        self.path = path
+        self.message = message
+
+
+class ConversionError(ValidationError):
+    """An explicit ``Attr`` converter failed."""

h5t/_spec.py

@@ -0,0 +1,91 @@
+"""Compiled schema records and public annotation markers."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+from pydantic import TypeAdapter
+
+
+@dataclass(frozen=True)
+class Name:
+    """Use ``name`` for this member in the HDF5 file."""
+
+    name: str
+
+
+@dataclass(frozen=True)
+class Attr:
+    """Declare a field as an HDF5 attribute.
+
+    ``converter`` is applied to the value returned by h5py before Pydantic
+    validation. It is useful for serialized attributes such as JSON strings.
+    """
+
+    converter: Callable[[Any], Any] | None = None
+
+
+@dataclass(frozen=True)
+class Eager:
+    """Load a detached dataset's complete payload during ``from_file``."""
+
+
+class Extras(Enum):
+    """Policy for undeclared immediate HDF5 members."""
+
+    IGNORE = "ignore"
+    FORBID = "forbid"
+
+
+class MemberKind(Enum):
+    """How a declared field is represented in HDF5."""
+
+    ATTRIBUTE = "attribute"
+    ARRAY = "array"
+    DATASET = "dataset"
+    GROUP = "group"
+
+
+_NO_DEFAULT = object()
+
+
+@dataclass(frozen=True)
+class FieldSpec:
+    """The compiled loading instructions for one annotated field."""
+
+    py_name: str
+    h5_name: str
+    kind: MemberKind
+    annotation: Any
+    adapter: TypeAdapter[Any] = field(compare=False, repr=False)
+    optional: bool = False
+    default: Any = _NO_DEFAULT
+    converter: Callable[[Any], Any] | None = None
+    eager: bool = False
+    member_type: type | None = None
+
+    @property
+    def has_default(self) -> bool:
+        """Whether the class body supplied a default."""
+        return self.default is not _NO_DEFAULT
+
+
+@dataclass(frozen=True)
+class ClassSpec:
+    """The flattened schema compiled for a ``Group`` or ``Dataset`` class."""
+
+    fields: tuple[FieldSpec, ...] = ()
+    extras: Extras = Extras.IGNORE
+
+
+def child_path(parent: str, name: str) -> str:
+    """Join an absolute group path and one immediate child name."""
+    return f"/{name}" if parent == "/" else f"{parent.rstrip('/')}/{name}"
+
+
+def attr_path(parent: str, name: str) -> str:
+    """Return a display path for an HDF5 attribute."""
+    return f"{parent.rstrip('/') or '/'}@{name}"

h5t-0.2.0.dist-info/METADATA

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: h5t
+Version: 0.2.0
+Summary: Load HDF5 groups as detached, typed Python records.
+Keywords: hdf5,h5py,schema,pydantic,typing,validation
+Author: binado
+Author-email: binado <bernardopveronese@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Dist: h5py>=3.10
+Requires-Dist: numpy>=1.26
+Requires-Dist: pydantic>=2.4,<3
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/binado/h5t
+Project-URL: Repository, https://github.com/binado/h5t
+Project-URL: Issues, https://github.com/binado/h5t/issues
+Project-URL: Changelog, https://github.com/binado/h5t/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# h5t
+
+[![PyPI](https://img.shields.io/pypi/v/h5t.svg)](https://pypi.org/project/h5t/)
+[![Python versions](https://img.shields.io/pypi/pyversions/h5t.svg)](https://pypi.org/project/h5t/)
+[![CI](https://github.com/binado/h5t/actions/workflows/ci.yml/badge.svg)](https://github.com/binado/h5t/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/binado/h5t/blob/main/LICENSE)
+
+`h5t` loads HDF5 groups into detached, typed Python records. Group attributes and
+ordinary NumPy-array fields are materialized while the file is open. Typed datasets
+keep snapshot metadata and can read their payload lazily without retaining an open
+file descriptor.
+
+## Installation
+
+```bash
+pip install h5t     # or: uv add h5t
+```
+
+Requires Python 3.11+. `h5py`, `numpy`, and Pydantic v2 are installed automatically.
+
+## Example
+
+```python
+import json
+from pathlib import Path
+from typing import Annotated, Any
+
+import numpy as np
+
+import h5t
+
+
+class Measurement(h5t.Dataset, extras="forbid"):
+    unit: str
+
+
+class Nested(h5t.Group):
+    label: str
+
+
+class Result(h5t.Group, extras="ignore"):
+    version: int                              # implicit HDF5 attribute
+    title: Annotated[str, h5t.Name("name")] # renamed attribute
+    config: Annotated[
+        dict[str, Any],
+        h5t.Attr(converter=json.loads),
+    ]
+    array_attr: Annotated[np.ndarray, h5t.Attr()]
+    values: np.ndarray                        # eager dataset payload
+    measurement: Measurement                  # lazy detached dataset
+    eager_measurement: Annotated[Measurement, h5t.Eager()]
+    nested: Nested                            # recursively loaded group
+    note: str | None                          # absent becomes None
+    revision: int = 1                         # absent uses a validated default
+
+
+result = Result.from_file(Path("result.h5"), root="/")
+```
+
+`result.attrs` and `result.measurement.attrs` are immutable mappings keyed by their
+on-disk HDF5 names. Declared attributes contain their Pydantic-processed values;
+undeclared attributes retained under `extras="ignore"` contain the raw h5py values.
+
+Typed datasets expose snapshot metadata and explicit data access:
+
+```python
+dataset = result.measurement
+dataset.path, dataset.shape, dataset.dtype, dataset.ndim
+
+complete = dataset.data      # first access reads and caches an ndarray
+assert dataset.read() is complete
+
+with dataset.open() as live:
+    first_hundred = live[:100]  # fresh file view, useful for slices
+```
+
+Both `from_file()` and `Dataset.open()` close every handle on normal and exceptional
+exits. Schema objects cannot be directly constructed, written, or serialized by h5t.
+
+## Field rules
+
+| Annotation | HDF5 representation | Loading behavior |
+| --- | --- | --- |
+| `Group` subclass | child group | recursively materialized |
+| `Dataset` or subclass | child dataset | metadata/attrs snapshot, payload lazy |
+| `Annotated[DatasetSubtype, Eager()]` | child dataset | complete payload cached during loading |
+| `np.ndarray` | child dataset | complete payload loaded as an ndarray |
+| `Annotated[T, Attr(...)]` | attribute | converter, then Pydantic validation |
+| scalar or `Literal[...]` | attribute | Pydantic validation |
+
+`Name("stored-name")` renames any field kind. `Attr` is valid only for attributes and
+`Eager` only for typed datasets. A parameterized alias such as
+`numpy.typing.NDArray[np.floating]` is accepted wherever `np.ndarray` is; the dtype
+parameter is not validated. Unsupported collection-shaped child annotations raise
+`SchemaError`; dynamic collections are not yet supported. Declarations are compiled at
+the `class` statement, so a `SchemaError` surfaces there. A schema class that names a
+class defined later in its module instead compiles on first use.
+
+Each `Group` and `Dataset` subclass accepts `extras="ignore"` (the default) or
+`extras="forbid"`. A group policy applies to its immediate child and attribute
+names. A typed dataset policy applies to its attributes. Nested schemas keep their own
+policy, while a plain `np.ndarray` field never checks the dataset's attributes.
+
+## Snapshot consistency
+
+A loaded model is a snapshot, with one deliberate exception:
+
+- Group and dataset attributes, dataset shape/dtype/path, eager datasets, and plain
+  arrays reflect the file during `from_file()`.
+- A lazy dataset's first `.data`/`.read()` observes the file at that later moment and
+  caches the resulting array permanently.
+- `.open()` always opens the current file and current dataset. It may therefore observe
+  replacements or fail if the source was changed or deleted.
+
+## CLI
+
+```bash
+h5t check result.h5 --schema mypackage.schemas:Result --root /results/latest
+```
+
+Exit status is 0 on success, 1 for the first file/schema mismatch, and 2 for import,
+declaration, usage, or I/O errors.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run ty check
+uv run ruff check .
+```

h5t-0.2.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+h5t/__init__.py,sha256=DcO56_5dRsigvAw6Wq_RFgOJCG4T-uyx27donmFN84A,421
+h5t/_cli.py,sha256=4sVwhS038-u7wIodHEQDu3RMDNkkqXmhvkwrLaZ5bD4,2356
+h5t/_compile.py,sha256=yY67PE3xQSVdTKKsdsJOSLBAA4764uZeiuDk8Pzg9Bw,32925
+h5t/_errors.py,sha256=Pl-MbGtd1UECA66opjqjo0CBb6LVsyPhW8SBRMyfZDs,623
+h5t/_spec.py,sha256=3JTJwx65eYw7Wf7bEZEhxij8XUeLmb-HYfpxyF7ujkg,2211
+h5t/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+h5t-0.2.0.dist-info/licenses/LICENSE,sha256=qNMhJr4DHkvGr-u5gkjTT4rHf6Jx2fvMXQdmQgr_vNM,1063
+h5t-0.2.0.dist-info/WHEEL,sha256=WKk67IZPzp9uSkBO-iWoZzrqp9-AwH7FE9EB8EoJbf4,81
+h5t-0.2.0.dist-info/entry_points.txt,sha256=my7HaIw3FZOKSZS2vaE4G0BHPUMHPCS1g1vR338bA2s,39
+h5t-0.2.0.dist-info/METADATA,sha256=hwqG_eX_H5Nhn1HpaFbisziCvaw_o2sqgDfDlDxjrVk,6159
+h5t-0.2.0.dist-info/RECORD,,

h5t-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.12.12
+Root-Is-Purelib: true
+Tag: py3-none-any

h5t-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+h5t = h5t._cli:main
+

h5t-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 binado
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.