iker-python-common 1.0.62__py3-none-any.whl → 1.0.64__py3-none-any.whl

iker/common/utils/{sequtils.py → iterutils.py}

@@ -27,6 +27,15 @@ __all__ = [
     "chunk_between",
     "chunk_with_key",
     "merge_chunks",
+    "dicttree",
+    "dicttree_value",
+    "dicttree_subtree",
+    "dicttree_children",
+    "dicttree_lineage",
+    "dicttree_make",
+    "dicttree_add",
+    "dicttree_remove",
+    "dicttree_purge",
     "Seq",
     "seq",
 ]
@@ -539,6 +548,165 @@ def merge_chunks[T](
                    chunk_between(chunks, lambda a, b: not merge_func(a, b)))
 
 
+# Dicttree, a tree structure implemented using nested dictionaries,
+# where each node can have an optional value and child nodes.
+type dicttree[K, V] = dict[K, tuple[V | None, dicttree[K, V]]]
+
+
+def dicttree_value[K, V](tree: dicttree[K, V], path: list[K]) -> V | None:
+    """
+    Gets the value stored at the specified path in the dicttree.
+
+    :param tree: the dicttree to retrieve the value from.
+    :param path: the list of keys representing the path to the desired value.
+    :return: the value at the specified path, or ``None`` if the path does not exist.
+    """
+    value = None
+    for key in path:
+        if key not in tree:
+            return None
+        value, tree = tree[key]
+    return value
+
+
+def dicttree_subtree[K, V](tree: dicttree[K, V], path: list[K]) -> dicttree[K, V] | None:
+    """
+    Gets the subtree located at the specified path in the dicttree.
+
+    :param tree: the dicttree to retrieve the subtree from.
+    :param path: the list of keys representing the path to the desired subtree.
+    :return: the subtree at the specified path, or ``None`` if the path does not exist.
+    """
+    for key in path:
+        if key not in tree:
+            return None
+        _, tree = tree[key]
+    return tree
+
+
+def dicttree_children[K, V](tree: dicttree[K, V], *, leaves_only: bool = False) -> Generator[V, None, None]:
+    """
+    Yields all values in the dicttree. If ``leaves_only`` is ``True``, only yields values at leaf nodes.
+
+    :param tree: the dicttree to traverse.
+    :param leaves_only: whether to yield only values at leaf nodes.
+    :return: a generator yielding all values in the dicttree.
+    """
+    for value, subtree in tree.values():
+        if value is not None and (not leaves_only or not subtree):
+            yield value
+        yield from dicttree_children(subtree, leaves_only=leaves_only)
+
+
+def dicttree_lineage[K, V](tree: dicttree[K, V], path: list[K]) -> Generator[V, None, None]:
+    """
+    Yields all values along the specified path in the dicttree.
+
+    :param tree: the dicttree to traverse.
+    :param path: the list of keys representing the path to follow.
+    :return: a generator yielding all values along the specified path.
+    """
+    for key in path:
+        if key not in tree:
+            return
+        value, tree = tree[key]
+        if value is not None:
+            yield value
+
+
+def dicttree_make[K, V](tree: dicttree[K, V], path: list[K]) -> dicttree[K, V]:
+    """
+    Ensures that the specified path exists in the dicttree, creating any missing nodes along the way.
+
+    :param tree: the dicttree to modify.
+    :param path: the list of keys representing the path to create.
+    :return: the subtree at the end of the created path.
+    """
+    for key in path:
+        tree.setdefault(key, (None, {}))
+        _, tree = tree[key]
+    return tree
+
+
+def dicttree_add[K, V](
+    tree: dicttree[K, V],
+    path: list[K],
+    value: V,
+    *,
+    create_prefix: bool = True,
+    overwrite: bool = False,
+) -> dicttree[K, V]:
+    """
+    Adds a value at the specified path in the dicttree. If ``create_prefix`` is ``True``, any missing nodes along the
+    path are created. If ``overwrite`` is ``False``, raises an error if the path already exists.
+
+    :param tree: the dicttree to modify.
+    :param path: the list of keys representing the path to add the value to.
+    :param value: the value to add at the specified path.
+    :param create_prefix: whether to create missing nodes along the path.
+    :param overwrite: whether to overwrite an existing value at the path.
+    :return: the modified dicttree.
+    """
+    if len(path) == 0:
+        raise ValueError("path cannot be empty")
+    *prefix, key = path
+    if create_prefix:
+        subtree = dicttree_make(tree, prefix)
+    else:
+        subtree = dicttree_subtree(tree, prefix)
+        if subtree is None:
+            raise ValueError("prefix path does not exist in dicttree")
+    if not overwrite and dicttree_value(subtree, [key]) is not None:
+        raise ValueError("path already exists in dicttree")
+    else:
+        subtree[key] = (value, dicttree_subtree(subtree, [key]) or {})
+    return tree
+
+
+def dicttree_remove[K, V](
+    tree: dicttree[K, V],
+    path: list[K],
+    *,
+    recursive: bool = False,
+) -> dicttree[K, V]:
+    """
+    Removes the value at the specified path in the dicttree. If ``recursive`` is ``True``, removes the entire subtree
+    at that path; otherwise, only removes the value, leaving any child nodes intact.
+
+    :param tree: the dicttree to modify.
+    :param path: the list of keys representing the path to remove the value from.
+    :param recursive: whether to remove the entire subtree at the path.
+    :return: the modified dicttree.
+    """
+    if len(path) == 0:
+        raise ValueError("path cannot be empty")
+    *prefix, key = path
+    subtree = dicttree_subtree(tree, prefix)
+    if subtree is None:
+        raise ValueError("prefix path does not exist in dicttree")
+    if dicttree_value(subtree, [key]) is None:
+        raise ValueError("path does not exist in dicttree")
+    else:
+        subtree[key] = (None, {} if recursive else dicttree_subtree(subtree, [key]) or {})
+    return tree
+
+
+def dicttree_purge[K, V](tree: dicttree[K, V]) -> dicttree[K, V]:
+    """
+    Recursively removes all nodes in the dicttree that have no value and no children.
+
+    :param tree: the dicttree to purge.
+    :return: the purged dicttree.
+    """
+    for key in list(tree.keys()):
+        value, subtree = tree[key]
+        dicttree_purge(subtree)
+        if subtree or value is not None:
+            continue
+        del tree[key]
+    return tree
+
+
 class Seq[T](Sequence[T], Sized):
     def __init__(self, data: Iterable[T]):
         if isinstance(data, Seq):

iker/common/utils/randutils.py

@@ -8,8 +8,8 @@ from typing import overload
 
 from iker.common.utils.dtutils import dt_utc_max, dt_utc_min
 from iker.common.utils.funcutils import memorized, singleton
+from iker.common.utils.iterutils import head_or_none
 from iker.common.utils.jsonutils import JsonType
-from iker.common.utils.sequtils import head_or_none
 
 __all__ = [
     "max_int",

iker/common/utils/shutils.py

@@ -4,7 +4,7 @@ import shutil
 from typing import Protocol
 
 from iker.common.utils import logger
-from iker.common.utils.sequtils import last, last_or_none, tail_iter
+from iker.common.utils.iterutils import last, last_or_none, tail_iter
 from iker.common.utils.strutils import is_empty
 
 __all__ = [

{iker_python_common-1.0.62.dist-info → iker_python_common-1.0.64.dist-info}/METADATA

@@ -1,13 +1,12 @@
 Metadata-Version: 2.4
 Name: iker-python-common
-Version: 1.0.62
+Version: 1.0.64
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Requires-Python: <3.15,>=3.12
 Requires-Dist: asyncpg>=0.30
-Requires-Dist: docker>=7.1
 Requires-Dist: numpy>=2.3
 Requires-Dist: psycopg>=3.2
 Requires-Dist: pymysql>=1.1

{iker_python_common-1.0.62.dist-info → iker_python_common-1.0.64.dist-info}/RECORD

@@ -4,21 +4,20 @@ iker/common/utils/argutils.py,sha256=hMLNqdZs_Kjc2hw4Npm6N47RivP6JRNzCKIbJr1jYy8
 iker/common/utils/config.py,sha256=z8rLqli961A-qAV9EaELp-pKuhNUNaq1Btdv-uwG7_I,4690
 iker/common/utils/csv.py,sha256=_V9OUrKcojec2L-hWagEIVnL2uvGjyJAFTrD7tHNr48,7573
 iker/common/utils/dbutils.py,sha256=09DgvfPVDCPXwOAO_FTynLXhSq--ZzRz2fCQ6vJ5qqk,16151
-iker/common/utils/dockerutils.py,sha256=n2WuzXaZB6_WocSljvPOnfExSIjIHRUbuWp2oBbaPKQ,8004
 iker/common/utils/dtutils.py,sha256=86vbaa4pgcBWERZvTfJ92PKB3IimxP6tf0O11ho2Ffk,12554
 iker/common/utils/funcutils.py,sha256=4AkkvK9_Z2tgk1-Sp6-vLLVhI15cIgN9xW58QqL5QL4,7780
+iker/common/utils/iterutils.py,sha256=l-FqaVUiL7WVkei7hYqWJqO5Ptcwe1T5CZ6nuIVNi4w,30884
 iker/common/utils/jsonutils.py,sha256=AkziMAYVQDODHRqZC-c1x7VqI2hHY3Kxrw7gmoss8mU,18527
 iker/common/utils/logger.py,sha256=FJaai6Sbchy4wKHcUMUCrrkBcXvIxq4qByERZ_TJBps,3881
 iker/common/utils/numutils.py,sha256=p6Rz1qyCcUru3v1zDy2PM-nds2NWJdL5A_vLmG-kswk,4294
-iker/common/utils/randutils.py,sha256=Sxf852B18CJ-MfrEDsv1ROO_brmz79dRZ4jpJiH65v4,12843
+iker/common/utils/randutils.py,sha256=D9bVAeHnLNkG8aZ2piWJgixTjXe0jl-GCVe4QgeFmsk,12844
 iker/common/utils/retry.py,sha256=H9lR6pp_jzgOwKTM-dOWIddjTlQbK-ijcwuDmVvurZM,8938
-iker/common/utils/sequtils.py,sha256=Wc8RcbNjVYSJYZv_07SOKWfYjhmGWz9_RXWbG2-tE1o,25060
-iker/common/utils/shutils.py,sha256=dUm1Y7m8u1Ri_R5598oQJsxwgQaBnVzhtpcsL7_Vzp0,7916
+iker/common/utils/shutils.py,sha256=DFwWdnGdAZEuwx6GDjFzPkMtNCFURjslOFUNs9FhrpA,7917
 iker/common/utils/span.py,sha256=u_KuWi2U7QDMUotl4AeW2_57ItL3YhVDSeCwaOiFDvs,5963
 iker/common/utils/strutils.py,sha256=Tu_qFeH3K-SfwvMxdrZAc9iLPV8ZmtX4ntyyFGNslf8,5094
 iker/common/utils/testutils.py,sha256=2VieV5yeCDntSKQSpIeyqRT8BZmZYE_ArMeQz3g7fXY,5568
 iker/common/utils/typeutils.py,sha256=RVkYkFRgDrx77OHFH7PavMV0AIB0S8ly40rs4g7JWE4,8220
-iker_python_common-1.0.62.dist-info/METADATA,sha256=0xFB0M0zbyGoFcUy9Y-lfZGzNDbAhtW0574bl8XS7XU,894
-iker_python_common-1.0.62.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-iker_python_common-1.0.62.dist-info/top_level.txt,sha256=4_B8Prfc_lxFafFYTQThIU1ZqOYQ4pHHHnJ_fQ_oHs8,5
-iker_python_common-1.0.62.dist-info/RECORD,,
+iker_python_common-1.0.64.dist-info/METADATA,sha256=mNIZFNquL8xwu6PutfTV3WRrxBzx4-crFq6Lz7r-Kx8,867
+iker_python_common-1.0.64.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+iker_python_common-1.0.64.dist-info/top_level.txt,sha256=4_B8Prfc_lxFafFYTQThIU1ZqOYQ4pHHHnJ_fQ_oHs8,5
+iker_python_common-1.0.64.dist-info/RECORD,,

{iker_python_common-1.0.62.dist-info → iker_python_common-1.0.64.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: setuptools (80.10.2)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

iker/common/utils/dockerutils.py

@@ -1,236 +0,0 @@
-import contextlib
-import dataclasses
-import re
-from collections.abc import Generator, Iterator
-from typing import Any
-
-import docker
-import docker.errors
-import docker.models.containers
-import docker.models.images
-import requests.exceptions
-
-from iker.common.utils import logger
-from iker.common.utils.strutils import parse_int_or, trim_to_empty
-
-__all__ = [
-    "ImageName",
-    "docker_create_client",
-    "docker_build_image",
-    "docker_get_image",
-    "docker_pull_image",
-    "docker_fetch_image",
-    "docker_run_detached",
-]
-
-
-@dataclasses.dataclass
-class ImageName(object):
-    registry_host: str | None
-    registry_port: int | None
-    components: list[str]
-    tag: str | None
-
-    @property
-    def registry(self) -> str:
-        if self.registry_host is None and self.registry_port is None:
-            return ""
-        if self.registry_port is None:
-            return self.registry_host
-        return f"{self.registry_host}:{self.registry_port}"
-
-    @property
-    def repository(self) -> str:
-        return "/".join(self.components)
-
-    @staticmethod
-    def parse(s: str):
-
-        # Registry absent version
-        matcher = re.compile(
-            r"^(?P<components>[a-z0-9]+((__?|-+)[a-z0-9]+)*(/[a-z0-9]+((__?|-+)[a-z0-9]+)*)*)(:(?P<tag>\w[\w.-]{0,127}))?$")
-        match = matcher.match(s)
-        if match:
-            return ImageName(registry_host=None,
-                             registry_port=None,
-                             components=trim_to_empty(match.group("components")).split("/"),
-                             tag=match.group("tag"))
-
-        # Registry present version
-        matcher = re.compile(
-            r"^((?P<host>[a-zA-Z0-9.-]+)(:(?P<port>\d+))?/)?(?P<components>[a-z0-9]+((__?|-+)[a-z0-9]+)*(/[a-z0-9]+((__?|-+)[a-z0-9]+)*)*)(:(?P<tag>\w[\w.-]{0,127}))?$")
-        match = matcher.match(s)
-        if match:
-            return ImageName(registry_host=match.group("host"),
-                             registry_port=parse_int_or(match.group("port"), None),
-                             components=trim_to_empty(match.group("components")).split("/"),
-                             tag=match.group("tag"))
-
-        return None
-
-
-def docker_create_client(
-    registry: str,
-    username: str,
-    password: str,
-) -> contextlib.AbstractContextManager[docker.DockerClient]:
-    try:
-        client = docker.DockerClient()
-        client.login(registry=registry, username=username, password=password, reauth=True)
-        return contextlib.closing(client)
-    except docker.errors.APIError:
-        logger.exception("Failed to login Docker server <%s>", registry)
-        raise
-
-
-def docker_build_image(
-    client: docker.DockerClient,
-    tag: str,
-    path: str,
-    dockerfile: str,
-    build_args: dict[str, str],
-) -> tuple[docker.models.images.Image, Iterator[dict[str, str]]]:
-    try:
-        return client.images.build(tag=tag,
-                                   path=path,
-                                   dockerfile=dockerfile,
-                                   buildargs=build_args,
-                                   rm=True,
-                                   forcerm=True,
-                                   nocache=True)
-
-    except docker.errors.BuildError:
-        logger.exception("Failed to build image <%s>", tag)
-        raise
-    except docker.errors.APIError:
-        logger.exception("Docker server returns an error while building image <%s>", tag)
-        raise
-    except Exception:
-        logger.exception("Unexpected error occurred while building image <%s>", tag)
-        raise
-
-
-def docker_get_image(
-    client: docker.DockerClient,
-    image: str,
-) -> docker.models.images.Image:
-    try:
-        return client.images.get(image)
-    except docker.errors.ImageNotFound:
-        logger.exception("Image <%s> is not found from local repository", image)
-        raise
-    except docker.errors.APIError:
-        logger.exception("Docker server returns an error while getting image <%s>", image)
-        raise
-    except Exception:
-        logger.exception("Unexpected error occurred while getting image <%s>", image)
-        raise
-
-
-def docker_pull_image(
-    client: docker.DockerClient,
-    image: str,
-    fallback_local: bool = False,
-) -> docker.models.images.Image:
-    try:
-        return client.images.pull(image)
-    except docker.errors.ImageNotFound:
-        if not fallback_local:
-            logger.exception("Image <%s> is not found from remote repository", image)
-            raise
-        logger.warning("Image <%s> is not found from remote repository, try local repository instead", image)
-    except docker.errors.APIError:
-        if not fallback_local:
-            logger.exception("Docker server returns an error while pulling image <%s>", image)
-            raise
-        logger.warning("Docker server returns an error while pulling image <%s>, try local repository instead", image)
-    except Exception:
-        logger.exception("Unexpected error occurred while pulling image <%s>", image)
-        raise
-
-    return docker_get_image(client, image)
-
-
-def docker_fetch_image(
-    client: docker.DockerClient,
-    image: str,
-    force_pull: bool = False,
-) -> docker.models.images.Image:
-    if force_pull:
-        return docker_pull_image(client, image, fallback_local=True)
-    else:
-        try:
-            return docker_get_image(client, image)
-        except Exception:
-            return docker_pull_image(client, image, fallback_local=False)
-
-
-def docker_run_detached(
-    client: docker.DockerClient,
-    image: str,
-    name: str,
-    command: str | list[str],
-    volumes: dict[str, dict[str, str]],
-    environment: dict[str, str],
-    extra_hosts: dict[str, str],
-    timeout: int,
-    **kwargs,
-) -> tuple[dict[str, Any], Any]:
-    @contextlib.contextmanager
-    def managed_docker_run(
-        client: docker.DockerClient,
-        **kwargs,
-    ) -> Generator[docker.models.containers.Container, None, None]:
-        container_model = None
-        try:
-            container_model = client.containers.run(**kwargs)
-            yield container_model
-        except docker.errors.DockerException:
-            raise
-        finally:
-            if container_model is not None:
-                try:
-                    if container_model.status != "exited":
-                        try:
-                            container_model.stop()
-                        except docker.errors.DockerException:
-                            pass
-                    container_model.wait()
-                    try:
-                        container_model.remove()
-                    except docker.errors.DockerException:
-                        pass
-                except Exception:
-                    raise
-
-    try:
-        run_args = kwargs.copy()
-        run_args.update(dict(image=image,
-                             name=name,
-                             command=command,
-                             volumes=volumes,
-                             environment=environment,
-                             extra_hosts=extra_hosts,
-                             detach=True))
-
-        with managed_docker_run(client, **run_args) as container_model:
-            result = container_model.wait(timeout=timeout)
-            logs = container_model.logs()
-
-            return result, logs
-
-    except requests.exceptions.ReadTimeout:
-        logger.exception("Running container <%s> of image <%s> exceed the timeout", name, image)
-        raise
-    except docker.errors.ImageNotFound:
-        logger.exception("Image <%s> is not found", image)
-        raise
-    except docker.errors.ContainerError:
-        logger.exception("Failed to run container <%s> of image <%s>", name, image)
-        raise
-    except docker.errors.APIError:
-        logger.exception("Docker server returns an error while running container <%s> of image <%s>", name, image)
-        raise
-    except Exception:
-        logger.exception("Unexpected error occurred while running container <%s> of image <%s>", image)
-        raise