h5t 0.2.0__tar.gz

h5t-0.2.0/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.

h5t-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,131 @@
+# 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/pyproject.toml

@@ -0,0 +1,96 @@
+[project]
+name = "h5t"
+version = "0.2.0"
+description = "Load HDF5 groups as detached, typed Python records."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+keywords = [
+    "hdf5",
+    "h5py",
+    "schema",
+    "pydantic",
+    "typing",
+    "validation",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed",
+]
+dependencies = [
+    "h5py>=3.10",
+    "numpy>=1.26",
+    "pydantic>=2.4,<3",
+]
+
+[[project.authors]]
+name = "binado"
+email = "bernardopveronese@gmail.com"
+
+[project.urls]
+Homepage = "https://github.com/binado/h5t"
+Repository = "https://github.com/binado/h5t"
+Issues = "https://github.com/binado/h5t/issues"
+Changelog = "https://github.com/binado/h5t/blob/main/CHANGELOG.md"
+
+[project.scripts]
+h5t = "h5t._cli:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "hypothesis>=6",
+    "ty>=0.0.74",
+    "ruff>=0.6",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.5,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "UP",
+    "B",
+    "D",
+]
+ignore = [
+    "D105",
+    "D107",
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "numpy"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+    "D",
+    "B018",
+]
+
+[tool.ty.src]
+include = [
+    "src/h5t",
+    "tests/acceptance_example.py",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

h5t-0.2.0/pyproject.toml.orig

@@ -0,0 +1,76 @@
+[project]
+name = "h5t"
+version = "0.2.0"
+description = "Load HDF5 groups as detached, typed Python records."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "binado", email = "bernardopveronese@gmail.com" }
+]
+requires-python = ">=3.11"
+keywords = ["hdf5", "h5py", "schema", "pydantic", "typing", "validation"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed",
+]
+dependencies = [
+    "h5py>=3.10",
+    "numpy>=1.26",
+    "pydantic>=2.4,<3",
+]
+
+[project.urls]
+Homepage = "https://github.com/binado/h5t"
+Repository = "https://github.com/binado/h5t"
+Issues = "https://github.com/binado/h5t/issues"
+Changelog = "https://github.com/binado/h5t/blob/main/CHANGELOG.md"
+
+[project.scripts]
+h5t = "h5t._cli:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "hypothesis>=6",
+    "ty>=0.0.74",
+    "ruff>=0.6",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.5,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "D"]
+ignore = [
+    "D105", # missing docstring in magic method
+    "D107", # missing docstring in __init__
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "numpy"
+
+[tool.ruff.lint.per-file-ignores]
+# B018 fires on attribute access inside pytest.raises blocks.
+"tests/**" = ["D", "B018"]
+
+[tool.ty.src]
+include = ["src/h5t", "tests/acceptance_example.py"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

h5t-0.2.0/src/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-0.2.0/src/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())