h5rdmtoolbox 2.8.2__tar.gz → 2.8.3__tar.gz

h5rdmtoolbox-2.8.3/MANIFEST.in

@@ -0,0 +1,3 @@
+include _build.py
+include codemeta.json
+include LICENSE

{h5rdmtoolbox-2.8.2 → h5rdmtoolbox-2.8.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: h5rdmtoolbox
-Version: 2.8.2
+Version: 2.8.3
 Summary: Supporting a FAIR Research Data lifecycle using Python and HDF5.
 Author-email: Matthias Probst <matth.probst@gmail.com>
 License-Expression: MIT
@@ -56,6 +56,9 @@ Requires-Dist: SPARQLWrapper>=2.0.0; extra == "catalog"
 Provides-Extra: gui
 Requires-Dist: PyQt5==5.15.10; extra == "gui"
 Provides-Extra: test-core
+Requires-Dist: build>=1.2; extra == "test-core"
+Requires-Dist: setuptools>=78.1.1; extra == "test-core"
+Requires-Dist: wheel; extra == "test-core"
 Requires-Dist: toml>0.10.0; extra == "test-core"
 Requires-Dist: pytest>=8.3.3; extra == "test-core"
 Requires-Dist: pytest-cov>=5.0.0; extra == "test-core"
@@ -67,6 +70,9 @@ Requires-Dist: scikit-image>=0.21.0; extra == "test-core"
 Requires-Dist: scikit-learn; extra == "test-core"
 Provides-Extra: test
 Requires-Dist: h5rdmtoolbox[catalog,csv,database,snt,test-core]; extra == "test"
+Provides-Extra: test-server
+Requires-Dist: h5rdmtoolbox[server,test]; extra == "test-server"
+Requires-Dist: httpx; extra == "test-server"
 Provides-Extra: docs
 Requires-Dist: Sphinx==8.0.0; extra == "docs"
 Requires-Dist: sphinx_book_theme==1.1.3; extra == "docs"
@@ -436,14 +442,16 @@ Install optional dependencies by specifying them in square brackets after the pa
 - `python-gitlab`: Access to gitlab repositories
 - `pypandoc`: Conversion of markdown files to html
 
-Other supported extras are `layout_validation`, `catalog`, `gui`, `server`, `test`, `docs`, `complete`, and
+Other supported extras are `layout_validation`, `catalog`, `gui`, `server`, `test`, `test-server`, `docs`, `complete`, and
 `complete-with-docs`. See the [installation guide](https://h5rdmtoolbox.readthedocs.io/en/latest/gettingstarted/installation.html)
 for their purpose. The authoritative dependency lists and version constraints are in [`pyproject.toml`](./pyproject.toml).
 
 ## Citing the package
 
-If you intend to use the package in your work, you may cite the software itself as published on paper in the
-[Zenodo (latest version)](https://zenodo.org/records/13309253) repository. A related paper is published in the
+If you use the package in your work, cite the software using its version-specific
+[Zenodo DOI for version 2.8.3](https://doi.org/10.5281/zenodo.23854129).
+This DOI is reserved for the release and will resolve once the Zenodo record is published.
+A related paper is published in the
 journal [inggrid](https://www.inggrid.org/article/id/4028/). Thank you!
 
 Alternatively or additionally, you can consult the `CITATION.cff` file.
@@ -467,18 +475,144 @@ Here is the BibTeX entry:
 }
 ```
 
+## Attribute quantities
+
+Quantity-valued attribute strings keep their original HDF5 text.
+`attribute.to_pint()` accepts plain, parenthesized, and square-bracket unit
+annotations such as `1.2 m`, `1.2 (m)`, and `1.2 [m]`, including newer Pint parsers.
+
+## Decoded calibration data
+
+When a convention enables scale/offset decoding, returned xarray data omits the
+storage attributes `DATA_SCALE`, `DATA_OFFSET`, `IS_DATA_SCALE`, and
+`IS_DATA_OFFSET`. Calibration links, role flags, and raw values remain available
+on the HDF5 datasets.
+
+## Convention contexts
+
+`with convention:` restores the preceding convention on exit, including when
+the same Convention object is nested repeatedly or the body raises an exception.
+`h5tbx.use(...)` activates immediately when constructed; create a fresh `use`
+manager for each context.
+
+Convention-name lookup is context-local, but activation changes shared wrapper
+method signatures and decoder selection. Convention-dependent operations should
+run sequentially: different conventions are not isolated across concurrent
+threads or asynchronous tasks, and an open file is not an isolated decoding
+environment merely because it remembers its opening convention.
+
+## Configuration
+
+Use `h5tbx.set_config(...)` for persistent settings, or as a context manager for
+temporary overrides. Nested contexts restore both configuration and the shared
+Pint display format on exit, including when an exception is raised. Invalid
+keys or values are rejected before settings change.
+
+```python
+with h5tbx.set_config(hdf_compression=None, hdf_compression_opts=None):
+    # Create datasets without the configured default compression.
+    ...
+```
+
+`plotting_name_order` accepts a nonempty list or tuple of `plot_name`,
+`long_name`, and/or `standard_name` in the desired priority order.
+
 ## Contribution
 
-Feel free to contribute. Make sure to write `docstrings` to your methods and classes and please write tests and use PEP
-8 (https://peps.python.org/pep-0008/)
+Releases follow a **DOI-first** workflow: supply the reserved, version-specific
+Zenodo DOI before bumping the version, then update package and citation metadata
+together. See the [release checklist](./docs/development.md#doi-first-release-checklist)
+and [agent instructions](./AGENTS.md#fair-versioning-and-release-metadata).
+Release preparation and publication are separate steps.
+
+RDF storage refactoring preserves the existing HDF5 attribute representation.
+RDF validation and object preparation stay separate from shared mapping updates;
+the existing wrapper continues to encode attributes for HDF5.
+The compatibility checks in `tests/ld/test_rdf_storage.py` inspect raw h5py
+values, string types, shapes, and reopened files. See the
+[storage contract](./docs/development.md#rdf-metadata-storage-contract).
+
+Start with the [developer overview](./docs/development.md) for module responsibilities,
+initialization behavior, startup measurements, and maintenance priorities. The
+[repository guidelines](./AGENTS.md) map code areas to focused tests and describe
+the Git workflow. Work on a dedicated branch and keep changes in coherent commits.
+For the current modernization, Git operations are authorized without repeated
+confirmation, with `git merge` excluded and commits confined to the working branch.
+
+Subagent investigations require explicit approval before agents are started.
+Approved architecture, quality, feature, or difficult-problem discussions are
+documented under `.work/<topic>/`, with evidence, alternatives, and a final
+recommendation. See the repository guidelines for the delegation workflow.
+
+The [architecture and quality review](./.work/architecture-quality/README.md)
+records independently reviewed CI, installed-wheel, test-coverage, and convention
+state findings, with reproductions and prioritized follow-up checks.
+
+The toolbox loads the SHACL validation engine and notebook HTML display support
+when those features are first used. A normal package import avoids loading them;
+both remain included in the required dependencies. See the developer overview
+for the startup measurement protocol and local before/after results.
+
+Internally, wrappers and shared utilities access configuration through its
+defining module; public configuration helpers remain available on `h5tbx`.
+Utility logging continues to use the shared `h5rdmtoolbox` logger and handlers.
+
+Distribution builds copy the canonical root `codemeta.json` into package data,
+so `h5tbx.get_package_meta()` also works outside an editable checkout. The test
+extra includes the build frontend and backend needed to verify an sdist-built
+wheel without downloading build dependencies during the test:
+
+```bash
+python -m pytest tests/test_distribution.py -q
+```
+
+This check builds from a fresh source copy, verifies metadata and runtime assets,
+and imports the resulting package outside the checkout. Use clean source trees
+for release builds so stale local build files cannot enter a distribution.
 
-Please write tests for your code and put them into the `tests/` folder. Visit the [README file](./tests/README.md) in the
-tests folder for more information.
+From the repository root, install the test dependencies and run the local smoke checks:
 
-Please also add a Jupyter notebook in the `docs/` folder in order to document your code. Please visit
-the [README file](./docs/README.md) in the docs-folder for more information on how to compile the documentation.
+```bash
+python -m pip install -e ".[test]"
+python -m pytest tests/test_version.py tests/test_config.py tests/test_cli.py -q
+```
+
+Add regression tests in `tests/` for changed behavior and run the relevant test
+modules. The full suite includes downloads and external integrations; the developer
+overview explains test isolation and service requirements. Use existing code style
+and **NumPy-style docstrings** for public APIs.
+
+Live Zenodo uploads are opt-in: tests marked `zenodo_upload` require both
+`H5RDMTOOLBOX_RUN_ZENODO_UPLOAD_TESTS=1` and `ZENODO_SANDBOX_API_TOKEN`.
+Ordinary test runs skip these remote writes, even if a token is available.
+See the [testing guide](./tests/README.md) for commands and skip reasons.
+
+CI runs on pushes, pull requests, and manual dispatch with read-only repository
+permissions and without Zenodo write credentials or automatic account cleanup.
+Manual Sandbox cleanup requires an explicit list of deposition IDs; it never
+enumerates or deletes all drafts in an account.
+
+Server validation has its own CI job using `.[test-server]`, which includes HTTPX
+for FastAPI's TestClient. Missing optional dependencies are reported as a module
+skip in ordinary test runs, but fail when `H5RDMTOOLBOX_REQUIRE_SERVER_TESTS=1`.
+Broken installed dependencies always fail visibly. CI checks the JUnit report
+for actual passing test cases and rejects skips or an empty run. Workflow actions
+use Node 24-compatible versions; self-hosted runners need version 2.327.1 or newer.
+
+Catalog tests generate their HDF5 files and local indexes in per-test temporary
+directories, keeping checked-in sample data read-only and avoiding shared state
+between test cases.
+
+Keep this README, API documentation, affected guides, and developer instructions
+up to date in the same commit as the change. Add or update notebooks when they help
+explain user-facing behavior. See the [documentation guide](./docs/README.md) for
+build requirements. For prose-only changes, a build without notebook execution is:
+
+```bash
+python -m sphinx -W -b html -D nb_execution_mode=off docs docs/_build/html
+```
 
-Please use the **numpy style for the docstrings**:
-https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html#example-numpy
+For notebook behavior changes, omit `-D nb_execution_mode=off` to use the configured
+execution policy.
 
 

{h5rdmtoolbox-2.8.2 → h5rdmtoolbox-2.8.3}/README.md

@@ -350,14 +350,16 @@ Install optional dependencies by specifying them in square brackets after the pa
 - `python-gitlab`: Access to gitlab repositories
 - `pypandoc`: Conversion of markdown files to html
 
-Other supported extras are `layout_validation`, `catalog`, `gui`, `server`, `test`, `docs`, `complete`, and
+Other supported extras are `layout_validation`, `catalog`, `gui`, `server`, `test`, `test-server`, `docs`, `complete`, and
 `complete-with-docs`. See the [installation guide](https://h5rdmtoolbox.readthedocs.io/en/latest/gettingstarted/installation.html)
 for their purpose. The authoritative dependency lists and version constraints are in [`pyproject.toml`](./pyproject.toml).
 
 ## Citing the package
 
-If you intend to use the package in your work, you may cite the software itself as published on paper in the
-[Zenodo (latest version)](https://zenodo.org/records/13309253) repository. A related paper is published in the
+If you use the package in your work, cite the software using its version-specific
+[Zenodo DOI for version 2.8.3](https://doi.org/10.5281/zenodo.23854129).
+This DOI is reserved for the release and will resolve once the Zenodo record is published.
+A related paper is published in the
 journal [inggrid](https://www.inggrid.org/article/id/4028/). Thank you!
 
 Alternatively or additionally, you can consult the `CITATION.cff` file.
@@ -381,18 +383,144 @@ Here is the BibTeX entry:
 }
 ```
 
+## Attribute quantities
+
+Quantity-valued attribute strings keep their original HDF5 text.
+`attribute.to_pint()` accepts plain, parenthesized, and square-bracket unit
+annotations such as `1.2 m`, `1.2 (m)`, and `1.2 [m]`, including newer Pint parsers.
+
+## Decoded calibration data
+
+When a convention enables scale/offset decoding, returned xarray data omits the
+storage attributes `DATA_SCALE`, `DATA_OFFSET`, `IS_DATA_SCALE`, and
+`IS_DATA_OFFSET`. Calibration links, role flags, and raw values remain available
+on the HDF5 datasets.
+
+## Convention contexts
+
+`with convention:` restores the preceding convention on exit, including when
+the same Convention object is nested repeatedly or the body raises an exception.
+`h5tbx.use(...)` activates immediately when constructed; create a fresh `use`
+manager for each context.
+
+Convention-name lookup is context-local, but activation changes shared wrapper
+method signatures and decoder selection. Convention-dependent operations should
+run sequentially: different conventions are not isolated across concurrent
+threads or asynchronous tasks, and an open file is not an isolated decoding
+environment merely because it remembers its opening convention.
+
+## Configuration
+
+Use `h5tbx.set_config(...)` for persistent settings, or as a context manager for
+temporary overrides. Nested contexts restore both configuration and the shared
+Pint display format on exit, including when an exception is raised. Invalid
+keys or values are rejected before settings change.
+
+```python
+with h5tbx.set_config(hdf_compression=None, hdf_compression_opts=None):
+    # Create datasets without the configured default compression.
+    ...
+```
+
+`plotting_name_order` accepts a nonempty list or tuple of `plot_name`,
+`long_name`, and/or `standard_name` in the desired priority order.
+
 ## Contribution
 
-Feel free to contribute. Make sure to write `docstrings` to your methods and classes and please write tests and use PEP
-8 (https://peps.python.org/pep-0008/)
+Releases follow a **DOI-first** workflow: supply the reserved, version-specific
+Zenodo DOI before bumping the version, then update package and citation metadata
+together. See the [release checklist](./docs/development.md#doi-first-release-checklist)
+and [agent instructions](./AGENTS.md#fair-versioning-and-release-metadata).
+Release preparation and publication are separate steps.
+
+RDF storage refactoring preserves the existing HDF5 attribute representation.
+RDF validation and object preparation stay separate from shared mapping updates;
+the existing wrapper continues to encode attributes for HDF5.
+The compatibility checks in `tests/ld/test_rdf_storage.py` inspect raw h5py
+values, string types, shapes, and reopened files. See the
+[storage contract](./docs/development.md#rdf-metadata-storage-contract).
+
+Start with the [developer overview](./docs/development.md) for module responsibilities,
+initialization behavior, startup measurements, and maintenance priorities. The
+[repository guidelines](./AGENTS.md) map code areas to focused tests and describe
+the Git workflow. Work on a dedicated branch and keep changes in coherent commits.
+For the current modernization, Git operations are authorized without repeated
+confirmation, with `git merge` excluded and commits confined to the working branch.
+
+Subagent investigations require explicit approval before agents are started.
+Approved architecture, quality, feature, or difficult-problem discussions are
+documented under `.work/<topic>/`, with evidence, alternatives, and a final
+recommendation. See the repository guidelines for the delegation workflow.
+
+The [architecture and quality review](./.work/architecture-quality/README.md)
+records independently reviewed CI, installed-wheel, test-coverage, and convention
+state findings, with reproductions and prioritized follow-up checks.
+
+The toolbox loads the SHACL validation engine and notebook HTML display support
+when those features are first used. A normal package import avoids loading them;
+both remain included in the required dependencies. See the developer overview
+for the startup measurement protocol and local before/after results.
+
+Internally, wrappers and shared utilities access configuration through its
+defining module; public configuration helpers remain available on `h5tbx`.
+Utility logging continues to use the shared `h5rdmtoolbox` logger and handlers.
+
+Distribution builds copy the canonical root `codemeta.json` into package data,
+so `h5tbx.get_package_meta()` also works outside an editable checkout. The test
+extra includes the build frontend and backend needed to verify an sdist-built
+wheel without downloading build dependencies during the test:
+
+```bash
+python -m pytest tests/test_distribution.py -q
+```
+
+This check builds from a fresh source copy, verifies metadata and runtime assets,
+and imports the resulting package outside the checkout. Use clean source trees
+for release builds so stale local build files cannot enter a distribution.
 
-Please write tests for your code and put them into the `tests/` folder. Visit the [README file](./tests/README.md) in the
-tests folder for more information.
+From the repository root, install the test dependencies and run the local smoke checks:
 
-Please also add a Jupyter notebook in the `docs/` folder in order to document your code. Please visit
-the [README file](./docs/README.md) in the docs-folder for more information on how to compile the documentation.
+```bash
+python -m pip install -e ".[test]"
+python -m pytest tests/test_version.py tests/test_config.py tests/test_cli.py -q
+```
+
+Add regression tests in `tests/` for changed behavior and run the relevant test
+modules. The full suite includes downloads and external integrations; the developer
+overview explains test isolation and service requirements. Use existing code style
+and **NumPy-style docstrings** for public APIs.
+
+Live Zenodo uploads are opt-in: tests marked `zenodo_upload` require both
+`H5RDMTOOLBOX_RUN_ZENODO_UPLOAD_TESTS=1` and `ZENODO_SANDBOX_API_TOKEN`.
+Ordinary test runs skip these remote writes, even if a token is available.
+See the [testing guide](./tests/README.md) for commands and skip reasons.
+
+CI runs on pushes, pull requests, and manual dispatch with read-only repository
+permissions and without Zenodo write credentials or automatic account cleanup.
+Manual Sandbox cleanup requires an explicit list of deposition IDs; it never
+enumerates or deletes all drafts in an account.
+
+Server validation has its own CI job using `.[test-server]`, which includes HTTPX
+for FastAPI's TestClient. Missing optional dependencies are reported as a module
+skip in ordinary test runs, but fail when `H5RDMTOOLBOX_REQUIRE_SERVER_TESTS=1`.
+Broken installed dependencies always fail visibly. CI checks the JUnit report
+for actual passing test cases and rejects skips or an empty run. Workflow actions
+use Node 24-compatible versions; self-hosted runners need version 2.327.1 or newer.
+
+Catalog tests generate their HDF5 files and local indexes in per-test temporary
+directories, keeping checked-in sample data read-only and avoiding shared state
+between test cases.
+
+Keep this README, API documentation, affected guides, and developer instructions
+up to date in the same commit as the change. Add or update notebooks when they help
+explain user-facing behavior. See the [documentation guide](./docs/README.md) for
+build requirements. For prose-only changes, a build without notebook execution is:
+
+```bash
+python -m sphinx -W -b html -D nb_execution_mode=off docs docs/_build/html
+```
 
-Please use the **numpy style for the docstrings**:
-https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html#example-numpy
+For notebook behavior changes, omit `-D nb_execution_mode=off` to use the configured
+execution policy.
 
 

h5rdmtoolbox-2.8.3/_build.py

@@ -0,0 +1,16 @@
+"""Setuptools commands for generated package resources."""
+
+from pathlib import Path
+
+from setuptools.command.build_py import build_py
+
+
+class BuildPy(build_py):
+    """Copy canonical repository metadata into the built package."""
+
+    def run(self):
+        super().run()
+        source = Path(__file__).parent / 'codemeta.json'
+        destination = Path(self.build_lib) / 'h5rdmtoolbox' / 'data' / 'codemeta.json'
+        self.mkpath(str(destination.parent))
+        self.copy_file(str(source), str(destination))

h5rdmtoolbox-2.8.3/codemeta.json

@@ -0,0 +1,60 @@
+{
+    "@id": "https://doi.org/10.5281/zenodo.23854129",
+    "@context": "https://doi.org/10.5063/schema/codemeta-2.0",
+    "@type": "SoftwareSourceCode",
+    "license": "https://spdx.org/licenses/MIT",
+    "codeRepository": "git+https://github.com/matthiasprobst/h5RDMtoolbox.git",
+    "name": "h5RDMtoolbox",
+    "version": "2.8.3",
+    "description": "Supporting a FAIR Research Data lifecycle using Python and HDF5.",
+    "applicationCategory": "Engineering",
+    "programmingLanguage": [
+        "Python 3",
+        "Python 3.9",
+        "Python 3.10",
+        "Python 3.11",
+        "Python 3.12",
+        "Python 3.13"
+    ],
+    "operatingSystem": [
+        "Linux",
+        "Windows",
+        "macOS"
+    ],
+    "author": [
+        {
+            "@type": "Person",
+            "@id": "https://orcid.org/0000-0001-8729-0482",
+            "givenName": "Matthias",
+            "familyName": "Probst",
+            "email": "matth.probst@gmail.com",
+            "affiliation": {
+                "@type": "Organization",
+                "@id": "https://ror.org/04t3en479",
+                "name": "Karlsruhe Institute of Technology, Institute of Thermal Turbomachinery"
+            }
+        },
+        {
+            "@type": "Person",
+            "@id": "https://orcid.org/0000-0002-4116-0065",
+            "givenName": "Lucas",
+            "familyName": "Büttner",
+            "affiliation": {
+                "@type": "Organization",
+                "@id": "https://ror.org/04t3en479",
+                "name": "Karlsruhe Institute of Technology, Institute of Thermal Turbomachinery"
+            }
+        },
+        {
+            "@type": "Person",
+            "@id": "https://orcid.org/0000-0001-9560-500X",
+            "givenName": "Balazs",
+            "familyName": "Pritz",
+            "affiliation": {
+                "@type": "Organization",
+                "@id": "https://ror.org/04t3en479",
+                "name": "Karlsruhe Institute of Technology, Institute of Thermal Turbomachinery"
+            }
+        }
+    ]
+}

{h5rdmtoolbox-2.8.2 → h5rdmtoolbox-2.8.3}/h5rdmtoolbox/__init__.py

@@ -65,10 +65,22 @@ __author_orcid__ = 'https://orcid.org/0000-0001-8729-0482'
 
 
 def get_package_meta() -> Dict:
-    """Reads codemeta.json and returns it as dict"""
-    with open(__this_dir__ / '../codemeta.json', 'r') as f:
-        codemeta = json.loads(f.read())
-    return codemeta
+    """Return CodeMeta metadata from the installed package or editable checkout.
+
+    Builds copy the canonical repository ``codemeta.json`` into package data;
+    editable checkouts read that canonical source directly when needed.
+    """
+    from importlib_resources import files
+
+    resource = files(__package__).joinpath('data/codemeta.json')
+    try:
+        text = resource.read_text(encoding='utf-8')
+    except FileNotFoundError:
+        source_root = __this_dir__.parent
+        if not (source_root / 'pyproject.toml').is_file():
+            raise
+        text = (source_root / 'codemeta.json').read_text(encoding='utf-8')
+    return json.loads(text)
 
 
 cv_h5py = convention.Convention(name='h5py',
@@ -168,11 +180,6 @@ def compute_metrics(
     )
 
 
-def _optimize_ld_context(graph: rdflib.Graph, context: Optional[Dict]) -> Dict:
-    from .ld import optimize_context
-    return optimize_context(graph, context or {})
-
-
 def _resolve_serialize_format(fmt: str, kwargs: Dict) -> str:
     return kwargs.pop("format", fmt)
 
@@ -192,12 +199,8 @@ def dump_jsonld(
                    contextual=contextual,
                    file_uri=file_uri,
                    skipND=skipND)
-    return graph.serialize(
-        format="json-ld",
-        indent=indent,
-        auto_compact=True,
-        context=_optimize_ld_context(graph, context)
-    )
+    from .ld.utils import _serialize_graph
+    return _serialize_graph(graph, fmt="json-ld", indent=indent, context=context)
 
 
 # def shacl_validate(

{h5rdmtoolbox-2.8.2 → h5rdmtoolbox-2.8.3}/h5rdmtoolbox/_cfg.py

@@ -44,11 +44,11 @@ _VALIDATORS = {
     'return_xarray': lambda x: isinstance(x, bool),
     'advanced_shape_repr': lambda x: isinstance(x, bool),
     'natural_naming': lambda x: isinstance(x, bool),
-    'hdf_compression': lambda x: isinstance(x, str),
-    'hdf_compression_opts': lambda x: isinstance(x, int),
+    'hdf_compression': lambda x: x is None or isinstance(x, str),
+    'hdf_compression_opts': lambda x: x is None or isinstance(x, int),
     'xarray_unit_repr_in_plots': lambda x: x in ('/', '()', '(', '[]', '[', '//', 'in'),
-    'plotting_name_order': lambda x: isinstance(x, (tuple, list)) and [xx in ('plot_name', 'long_name', 'standard_name')
-                                                                       for xx in x],
+    'plotting_name_order': lambda x: isinstance(x, (tuple, list)) and bool(x) and all(
+        xx in ('plot_name', 'long_name', 'standard_name') for xx in x),
     'require_unit': lambda x: isinstance(x, bool),
     'ureg_format': lambda x: isinstance(x, str),
     'init_logger_level': lambda x: is_valid_logger_level(x),
@@ -62,7 +62,14 @@ _VALIDATORS = {
 
 
 class set_config:
-    """Set the configuration parameters."""
+    """Set configuration immediately, optionally restoring it as a context manager.
+
+    All keys and values are validated before configuration is changed. Context
+    exit restores previous values, including the shared Pint registry format.
+    Compression settings accept ``None`` to restore their uncompressed defaults.
+    ``plotting_name_order`` requires a nonempty list or tuple containing only
+    ``plot_name``, ``long_name``, or ``standard_name``.
+    """
 
     def __init__(self, **kwargs):
         self.old = {}
@@ -72,8 +79,6 @@ class set_config:
             if k not in CONFIG:
                 raise KeyError(f'Not a configuration key: "{k}"')
             self.old[k] = CONFIG[k]
-            if k == 'ureg_format':
-                get_ureg().formatter.default_format = str(v)
         self._update(kwargs)
 
     def __enter__(self):
@@ -83,6 +88,8 @@ class set_config:
         self._update(self.old)
 
     def _update(self, options_dict: Dict):
+        if 'ureg_format' in options_dict:
+            get_ureg().formatter.default_format = options_dict['ureg_format']
         CONFIG.update(options_dict)
 
 

{h5rdmtoolbox-2.8.2 → h5rdmtoolbox-2.8.3}/h5rdmtoolbox/_repr.py

@@ -10,14 +10,14 @@ import h5py
 import importlib_resources
 import numpy as np
 import xarray as xr
-from IPython.display import HTML, display
 from numpy import ndarray
 from ontolutils import M4I
 
 from h5rdmtoolbox.ld.rdf import (RDF_PREDICATE_ATTR_NAME,
                                  RDF_OBJECT_ATTR_NAME,
                                  RDF_TYPE_ATTR_NAME)
-from . import get_config, identifiers, protected_attributes
+from . import identifiers, protected_attributes
+from ._cfg import get_config
 
 H5PY_SPECIAL_ATTRIBUTES = ('DIMENSION_LIST', 'REFERENCE_LIST', 'NAME', 'CLASS', protected_attributes.COORDINATES)
 try:
@@ -734,6 +734,8 @@ class H5Repr:
 
     def __html__(self, group, collapsed: bool = True, preamble: str = None,
                  chunks: bool = False, maxshape: bool = False) -> None:
+        from IPython.display import HTML, display
+
         display(
             HTML(
                 self.html_repr(

{h5rdmtoolbox-2.8.2 → h5rdmtoolbox-2.8.3}/h5rdmtoolbox/convention/core.py

@@ -101,6 +101,12 @@ class Convention(AbstractConvention):
     Recommended initialization is via `Convention.from_yaml(<yaml_filename>)` or
     `Convention.from_json(<json_filename>)`.
 
+    Convention objects support sequential nested context use, including repeated
+    entry of the same object. Each exit restores the preceding convention.
+    Activation changes process-global wrapper signatures and decoder selection;
+    concurrent convention-dependent operations are not isolated across threads
+    or asynchronous tasks.
+
     Parameters
     ----------
     name : str
@@ -142,6 +148,7 @@ class Convention(AbstractConvention):
 
         self.contact = contact
         self.institution = institution
+        self._context_managers = []
 
         self._registered_standard_attributes = {}
         self.name = name
@@ -257,12 +264,12 @@ class Convention(AbstractConvention):
         return out
 
     def __enter__(self):
-        self._curr_cv = get_current_convention()
-        use(self)
+        manager = use(self)
+        self._context_managers.append(manager)
         return self
 
     def __exit__(self, exc_type, exc_val, exc_tb):
-        use(self._curr_cv.name)
+        return self._context_managers.pop().__exit__(exc_type, exc_val, exc_tb)
 
     @property
     def registered_standard_attributes(self):
@@ -677,7 +684,12 @@ def _ensure_builtin_convention(name: str) -> bool:
 
 class use:
     """Enable a convention.
-    To disable the convention, active an empty convention like so: cv.use(None)
+
+    Call ``use(None)`` to activate the default empty ``h5py`` convention.
+
+    Activation occurs when this manager is constructed. Use a fresh manager for
+    each context. Wrapper signatures and decoder selection are process-global;
+    this manager does not isolate concurrent convention-dependent operations.
 
     Parameters
     ----------
@@ -772,7 +784,12 @@ def add_convention(convention: Convention, name=None):
 
 
 def get_current_convention() -> Union[None, Convention]:
-    """Return the current convention (thread-safe)."""
+    """Return the context-local convention pointer.
+
+    Activation also changes process-global wrapper signatures and decoders.
+    Context-local lookup does not imply isolated file operations across threads
+    or asynchronous tasks.
+    """
     return cfg._current_convention.get()