add number of children limit, typing and docstring

src/silx/io/tiledh5.py

@@ -1,4 +1,30 @@
-"""Provides a wrapper to expose `Tiled <https://blueskyproject.io/tiled/>`_"""
+# /*##########################################################################
+# Copyright (C) 2024 European Synchrotron Radiation Facility
+#
+# 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.
+#
+# ############################################################################*/
+"""
+Provides a wrapper to expose `Tiled <https://blueskyproject.io/tiled/>`_
+
+This is a preview feature.
+"""
 from __future__ import annotations
 
 
@@ -13,9 +39,26 @@
 _logger = logging.getLogger(__name__)
 
 
-def _get_children(parent, container):
+def _get_children(
+    parent: TiledH5 | TiledGroup,
+    container: tiled.client.container.Container,
+    max_children: int | None = None,
+):
+    """Return first max_children items of given container as commonh5 wrappers.
+
+    :param parent: The commonh5 wrapper for which to retrieve children.
+    :param container: The corresponding tiled container.
+    :param max_children: The maximum number of childre to retrieve.
+    """
+    items = container.items()
+
+    if max_children is not None and len(items) > max_children:
+        _logger.warning(
+            f"{container.uri} contains too many entries: Only loading first {max_children}."
+        )
+
     children = {}
-    for key, client in container.items():
+    for key, client in items.head(max_children):
         if isinstance(client, tiled.client.container.Container):
             children[key] = TiledGroup(client, name=key, parent=parent)
         elif isinstance(client, tiled.client.array.ArrayClient):
@@ -31,12 +74,25 @@ def _get_children(parent, container):
 
 
 class TiledH5(commonh5.File):
-    def __init__(self, name=None, mode=None, attrs=None):
+    """tiled client wrapper"""
+
+    MAX_CHILDREN: int | None = None
+    """Maximum number of group children to instantiate for each group.
+
+    Set to None for allowing an unbound number of children per group.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        mode: str | None = None,
+        attrs: dict | None = None,
+    ):
         assert mode in ("r", None)
         super().__init__(name, mode, attrs)
-        self.__container = tiled.client.from_uri(
-            name[6:] if name.startswith("tiled:") else name
-        )
+        if name.startswith("tiled:"):
+            name = name[6:]
+        self.__container = tiled.client.from_uri(name)
         assert isinstance(self.__container, tiled.client.container.Container)
 
     def close(self):
@@ -45,25 +101,37 @@ def close(self):
 
     @lru_cache
     def _get_items(self):
-        return _get_children(self, self.__container)
+        return _get_children(self, self.__container, self.MAX_CHILDREN)
 
 
 class TiledGroup(commonh5.Group):
     """tiled Container wrapper"""
 
-    def __init__(self, container, name, parent=None, attrs=None):
+    def __init__(
+        self,
+        container: tiled.client.container.Container,
+        name: str,
+        parent: TiledH5 | TiledGroup | None = None,
+        attrs: dict | None = None,
+    ):
         super().__init__(name, parent, attrs)
         self.__container = container
 
     @lru_cache
     def _get_items(self):
-        return _get_children(self, self.__container)
+        return _get_children(self, self.__container, self.file.MAX_CHILDREN)
 
 
 class TiledDataset(commonh5.LazyLoadableDataset):
     """tiled ArrayClient wrapper"""
 
-    def __init__(self, client, name, parent=None, attrs=None):
+    def __init__(
+        self,
+        client: tiled.client.array.ArrayClient,
+        name: str,
+        parent: TiledH5 | TiledGroup | None = None,
+        attrs: dict | None = None,
+    ):
         super().__init__(name, parent, attrs)
         self.__client = client