h5rdmtoolbox 2.7.3__tar.gz → 2.8.0__tar.gz

{h5rdmtoolbox-2.7.3 → h5rdmtoolbox-2.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: h5rdmtoolbox
-Version: 2.7.3
+Version: 2.8.0
 Summary: Supporting a FAIR Research Data lifecycle using Python and HDF5.
 Author-email: Matthias Probst <matth.probst@gmail.com>
 License-Expression: MIT
@@ -61,7 +61,7 @@ Requires-Dist: pytest>=8.3.3; extra == "test-core"
 Requires-Dist: pytest-cov>=5.0.0; extra == "test-core"
 Requires-Dist: pylint; extra == "test-core"
 Requires-Dist: ssnolib<3.0.0,>=2.2.0.2; extra == "test-core"
-Requires-Dist: mongomock==4.1.2; extra == "test-core"
+Requires-Dist: mongomock==4.3.0; extra == "test-core"
 Requires-Dist: scipy>=1.10.1; extra == "test-core"
 Requires-Dist: scikit-image>=0.21.0; extra == "test-core"
 Requires-Dist: scikit-learn; extra == "test-core"
@@ -75,9 +75,13 @@ Requires-Dist: sphinx_design==0.6.1; extra == "docs"
 Requires-Dist: myst_nb==1.2.0; extra == "docs"
 Requires-Dist: sphinxcontrib_bibtex==2.6.3; extra == "docs"
 Provides-Extra: complete
-Requires-Dist: h5rdmtoolbox[catalog,csv,database,gui,layout_validation,snt,test]; extra == "complete"
+Requires-Dist: h5rdmtoolbox[gui,test]; extra == "complete"
 Provides-Extra: complete-with-docs
 Requires-Dist: h5rdmtoolbox[complete,docs]; extra == "complete-with-docs"
+Provides-Extra: server
+Requires-Dist: fastapi>=0.95; extra == "server"
+Requires-Dist: uvicorn[standard]>=0.22; extra == "server"
+Requires-Dist: jinja2>=3.1; extra == "server"
 Dynamic: license-file
 
 # HDF5 Research Data Management Toolbox
@@ -233,18 +237,37 @@ hdf:H5T_INTEL_I64 a hdf:Datatype .
     hdf:size 4 .
 ```
 
-[//]: # (The "HDF5 Research Data Management Toolbox" &#40;h5RDMtoolbox&#41; is a Python package supporting everybody who is working with)
+## Command Line Interface
 
-[//]: # (HDF5 to achieve a sustainable data lifecycle which follows)
+The `h5tbx` command provides quick access to linked-data serialization and local inspection from the shell.
 
-[//]: # (the [FAIR &#40;Findable, Accessible, Interoperable, Reusable&#41;]&#40;https://www.nature.com/articles/sdata201618&#41;)
+Use `h5tbx ld dump example.h5` to print Turtle RDF, or write a specific format with:
 
-[//]: # (principles. It specifically supports the five main steps of *planning*, *collecting*, *analyzing*, *sharing* and)
+```bash
+h5tbx ld dump example.h5 -o example.jsonld
+```
+
+The dump command accepts `--format`, `--file-uri`, `--prefix`, `--structural=false`, and `--contextual=false`, so you can choose RDF output, assign stable RDF subject URIs, bind a compact prefix, and include only structural or user-provided contextual metadata when needed.
+
+To inspect files in a browser, run:
+
+```bash
+h5tbx serve example.h5
+h5tbx serve data/ --h5ext=.h5 --h5ext=.hdf5
+```
+
+The local web app links to Turtle, JSON-LD, N-Triples, RDF/XML, an interactive graph view, SPARQL query editor, graph metrics, and SHACL validation. Per-file buttons are scoped to that file; the landing page also offers a separate combined graph section for all served files plus loaded enrichment. Combined graph visualization is reduced by default with node/edge limits and search controls, and combined metrics skip exact largest-distance computation on very large graphs to keep the local server responsive. HDF5 object URLs such as `/example.h5/group/dataset` dereference to a browser HTML page by default, while `Accept: text/turtle`, `Accept: application/ld+json`, or `?format=ttl|jsonld|nt|xml|html` return the requested representation. For published DOI-style file URIs, use `/resolve?iri=https://doi.org/...%23path` to resolve an exact external RDF subject locally. The resolver uses the first matching served HDF5 subject, caches all served files in one shared query graph, and enriches that graph with known ontology TTL sources, QUDT unit definitions, Zenodo RDF attachments, generic ontology documents, and Wikidata direct claims where applicable. URI values in resource pages link back into `/resolve?iri=...` so browsing stays inside the local app; if a browser request cannot be resolved locally, the app opens the original IRI in a new tab as a fallback. `h5tbx serve` accepts files and folders; folder discovery uses `.h5`, `.hdf`, and `.hdf5` by default, or repeated `--h5ext` values. `--local-iri-pattern` is optional and only limits which external IRIs get local resolver links in the graph view. If no filename is provided, `h5tbx serve` lists all matching HDF5 files in the current directory.
+
+The same graph metrics are available from Python:
 
-[//]: # (*reusing* data. Please visit the [documentation]&#40;https://h5rdmtoolbox.readthedocs.io/en/latest/&#41; for detailed)
+```python
+import h5rdmtoolbox as h5tbx
 
-[//]: # (information of try the [quickstart using colab]&#40;#quickstart&#41;.)
+metrics = h5tbx.compute_metrics("example.h5")
 
+with h5tbx.File("example.h5") as h5:
+    metrics = h5.metrics()
+```
 
 ## 🚀 Key Features
 

{h5rdmtoolbox-2.7.3 → h5rdmtoolbox-2.8.0}/README.md

@@ -151,18 +151,37 @@ hdf:H5T_INTEL_I64 a hdf:Datatype .
     hdf:size 4 .
 ```
 
-[//]: # (The "HDF5 Research Data Management Toolbox" (h5RDMtoolbox) is a Python package supporting everybody who is working with)
+## Command Line Interface
 
-[//]: # (HDF5 to achieve a sustainable data lifecycle which follows)
+The `h5tbx` command provides quick access to linked-data serialization and local inspection from the shell.
 
-[//]: # (the [FAIR (Findable, Accessible, Interoperable, Reusable)](https://www.nature.com/articles/sdata201618))
+Use `h5tbx ld dump example.h5` to print Turtle RDF, or write a specific format with:
 
-[//]: # (principles. It specifically supports the five main steps of *planning*, *collecting*, *analyzing*, *sharing* and)
+```bash
+h5tbx ld dump example.h5 -o example.jsonld
+```
+
+The dump command accepts `--format`, `--file-uri`, `--prefix`, `--structural=false`, and `--contextual=false`, so you can choose RDF output, assign stable RDF subject URIs, bind a compact prefix, and include only structural or user-provided contextual metadata when needed.
+
+To inspect files in a browser, run:
+
+```bash
+h5tbx serve example.h5
+h5tbx serve data/ --h5ext=.h5 --h5ext=.hdf5
+```
+
+The local web app links to Turtle, JSON-LD, N-Triples, RDF/XML, an interactive graph view, SPARQL query editor, graph metrics, and SHACL validation. Per-file buttons are scoped to that file; the landing page also offers a separate combined graph section for all served files plus loaded enrichment. Combined graph visualization is reduced by default with node/edge limits and search controls, and combined metrics skip exact largest-distance computation on very large graphs to keep the local server responsive. HDF5 object URLs such as `/example.h5/group/dataset` dereference to a browser HTML page by default, while `Accept: text/turtle`, `Accept: application/ld+json`, or `?format=ttl|jsonld|nt|xml|html` return the requested representation. For published DOI-style file URIs, use `/resolve?iri=https://doi.org/...%23path` to resolve an exact external RDF subject locally. The resolver uses the first matching served HDF5 subject, caches all served files in one shared query graph, and enriches that graph with known ontology TTL sources, QUDT unit definitions, Zenodo RDF attachments, generic ontology documents, and Wikidata direct claims where applicable. URI values in resource pages link back into `/resolve?iri=...` so browsing stays inside the local app; if a browser request cannot be resolved locally, the app opens the original IRI in a new tab as a fallback. `h5tbx serve` accepts files and folders; folder discovery uses `.h5`, `.hdf`, and `.hdf5` by default, or repeated `--h5ext` values. `--local-iri-pattern` is optional and only limits which external IRIs get local resolver links in the graph view. If no filename is provided, `h5tbx serve` lists all matching HDF5 files in the current directory.
+
+The same graph metrics are available from Python:
 
-[//]: # (*reusing* data. Please visit the [documentation](https://h5rdmtoolbox.readthedocs.io/en/latest/) for detailed)
+```python
+import h5rdmtoolbox as h5tbx
 
-[//]: # (information of try the [quickstart using colab](#quickstart).)
+metrics = h5tbx.compute_metrics("example.h5")
 
+with h5tbx.File("example.h5") as h5:
+    metrics = h5.metrics()
+```
 
 ## 🚀 Key Features
 

{h5rdmtoolbox-2.7.3 → h5rdmtoolbox-2.8.0}/h5rdmtoolbox/__init__.py

@@ -2,7 +2,6 @@
 
 import logging
 import pathlib
-import warnings
 from logging.handlers import RotatingFileHandler
 from typing import Optional, Dict
 
@@ -20,7 +19,7 @@ _stream_handler = logging.StreamHandler()
 _stream_handler.setLevel(DEFAULT_LOGGING_LEVEL)
 _stream_handler.setFormatter(_formatter)
 
-_file_handler = RotatingFileHandler(USER_LOG_DIR / 'h5rdmtoolbox.log')
+_file_handler = RotatingFileHandler(USER_LOG_DIR / 'h5rdmtoolbox.log', delay=True)
 _file_handler.setLevel(logging.DEBUG)  # log everything to file!
 _file_handler.setFormatter(_formatter)
 
@@ -136,13 +135,46 @@ def get_ld(
         context: Optional[Dict] = None
 ) -> rdflib.Graph:
     """Return the HDF file content as a rdflib.Graph object."""
-    from h5rdmtoolbox.ld import get_ld
-    return get_ld(hdf_filename,
-                  structural=structural,
-                  contextual=contextual,
-                  skipND=skipND,
-                  file_uri=file_uri,
-                  context=context)
+    from . import ld
+    return ld.get_ld(
+        hdf_filename,
+        structural=structural,
+        contextual=contextual,
+        skipND=skipND,
+        file_uri=file_uri,
+        context=context,
+    )
+
+
+def compute_metrics(
+        hdf_filename: Union[str, pathlib.Path],
+        structural: bool = True,
+        contextual: bool = True,
+        skipND: int = 1,
+        file_uri: Optional[str] = None,
+        context: Optional[Dict] = None,
+        rdf_mappings: Dict[str, RDFMappingEntry] = None,
+) -> Dict[str, object]:
+    """Compute RDF knowledge graph metrics for an HDF5 file."""
+    from .ld.metrics import compute_metrics as _compute_metrics
+    return _compute_metrics(
+        hdf_filename,
+        structural=structural,
+        contextual=contextual,
+        skipND=skipND,
+        file_uri=file_uri,
+        context=context,
+        rdf_mappings=rdf_mappings,
+    )
+
+
+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)
 
 
 def dump_jsonld(
@@ -155,19 +187,16 @@ def dump_jsonld(
         file_uri: Optional[str] = None
 ):
     """Return the file content as a JSON-LD string."""
-    from .ld import optimize_context
-    context = context or {}
     graph = get_ld(hdf_filename,
                    structural=structural,
                    contextual=contextual,
                    file_uri=file_uri,
                    skipND=skipND)
-    context = optimize_context(graph, context)
     return graph.serialize(
         format="json-ld",
         indent=indent,
         auto_compact=True,
-        context=context
+        context=_optimize_ld_context(graph, context)
     )
 
 
@@ -286,7 +315,7 @@ def serialize(hdf_filename,
               rdf_mappings: Dict[str, RDFMappingEntry] = None,
               **kwargs):
     """Alternative to json-ld but allows multiple serialization options"""
-    fmt = kwargs.pop("format", fmt)
+    fmt = _resolve_serialize_format(fmt, kwargs)
     with File(hdf_filename) as h5:
         return h5.serialize(fmt=fmt,
                             skipND=skipND,
@@ -296,6 +325,32 @@ def serialize(hdf_filename,
                             rdf_mappings=rdf_mappings)
 
 
+def sparql(
+        hdf_filename: Union[str, pathlib.Path],
+        query: str,
+        structural: bool = True,
+        contextual: bool = True,
+        skipND: int = 1,
+        file_uri: Optional[Union[str, Dict[str, str]]] = None,
+        rdf_mappings: Dict[str, RDFMappingEntry] = None,
+        as_dataframe: bool = False,
+        **kwargs
+) -> rdflib.query.Result:
+    """Run a SPARQL query on the HDF5 file content. Returns a rdflib.query.Result object."""
+    from .ld import sparql
+    return sparql(
+        source=hdf_filename,
+        query=query,
+        structural=structural,
+        contextual=contextual,
+        skipND=skipND,
+        file_uri=file_uri,
+        rdf_mappings=rdf_mappings,
+        as_dataframe=as_dataframe,
+        **kwargs
+    )
+
+
 def build_pyvis_graph(hdf_filename, output_filename="kg-graph.html", notebook=False,
                       structural: bool = True,
                       contextual: bool = True,