vt-commons 0.0.1__py3-none-any.whl

vt/utils/commons/commons/__init__.py

@@ -0,0 +1,6 @@
+#!/usr/bin/env python3
+# coding=utf-8
+
+"""
+Reusable common utilities, interfaces and implementations for python projects.
+"""

vt/utils/commons/commons/collections/__init__.py

@@ -0,0 +1,9 @@
+#!/usr/bin/env python3
+# coding=utf-8
+
+"""
+Reusable common utilities, interfaces and implementations for python projects related to collections.
+"""
+
+from vt.utils.commons.commons.collections.utils import get_first_true as get_first_true
+from vt.utils.commons.commons.collections.utils import get_last_true as get_last_true

vt/utils/commons/commons/collections/utils.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+# coding=utf-8
+
+"""
+Reusable common utilities for python projects related to collections.
+"""
+
+from collections.abc import Sequence, Callable, Iterator
+
+
+def get_first_true[T](
+    ids: Sequence[T],
+    default_val: T,
+    predicate: Callable[[T], bool],
+    iter_provider: Callable[[Sequence[T]], Iterator[T]] = iter,
+) -> T:
+    """
+    Get the first id which returns ``True`` from the supplied ``predicate`` else get the ``default_val``.
+
+    Examples:
+
+    * First id is returned if all ``ids`` are inferred as ``True``::
+
+        >>> get_first_true([1, 2, 3], -1, lambda x: True)
+        1
+
+    * Default id is returned if no ``ids`` are inferred as ``True``::
+
+        >>> get_first_true([1, 2, 3], -1, lambda x: False)
+        -1
+
+    Error scenarios:
+
+    * supplied predicate is not a callable::
+
+        >>> get_first_true([1, 2, 3], -1,
+        ...                     object()) # noqa: to avoid typecheck warnings, expects (x)->bool Callable
+        Traceback (most recent call last):
+        TypeError: predicate must be a (x) -> bool Callable. Supplied <class 'object'>.
+
+    * suppplied predicate is a non-conforming callable::
+
+        >>> get_first_true([1, 2, 3], -1,
+        ...                     lambda x, y: True) # noqa: to avoid typecheck warnings, expects (x)->bool Callable.
+        Traceback (most recent call last):
+        TypeError: <lambda>() missing 1 required positional argument: 'y'
+
+    :param ids: sequence of id(s) from which the first ever ``predicate`` determined truthy id is to be found.
+    :param default_val: value returned if no id is found as truthy from the ``ids`` list according to the supplied
+        ``predicate``.
+    :param predicate: predicate to determine whether an id is inferred as satisfying and hence returning ``True`` for
+        that id.
+    :param iter_provider: iterator provider for the ``ids`` sequence.
+    :return: the first id from the list of ``ids`` which returns ``True`` by the ``predicate`` or ``default_val`` if
+        the ``predicate`` returns ``True`` for no id(s).
+    """
+    if not callable(predicate):
+        raise TypeError(
+            f"predicate must be a (x) -> bool Callable. Supplied {type(predicate)}."
+        )
+
+    for _id in iter_provider(ids):
+        if predicate(_id):
+            return _id
+    return default_val
+
+
+def get_last_true[T](
+    ids: Sequence[T], default_val: T, predicate: Callable[[T], bool]
+) -> T:
+    """
+    Get the last id which returns ``True`` from the supplied ``predicate`` else get the ``default_val``.
+
+    Examples:
+
+    * Last id is returned if all ``ids`` are inferred as ``True``::
+
+        >>> get_last_true([1, 2, 3], -1, lambda x: True)
+        3
+
+    * Default id is returned if no ``ids`` are inferred as ``True``::
+
+        >>> get_last_true([1, 2, 3], -1, lambda x: False)
+        -1
+
+    Error scenarios:
+
+    * supplied predicate is not a callable::
+
+        >>> get_last_true([1, 2, 3], -1,
+        ...                     object()) # noqa: to avoid typecheck warnings, expects (x)->bool Callable
+        Traceback (most recent call last):
+        TypeError: predicate must be a (x) -> bool Callable. Supplied <class 'object'>.
+
+    * suppplied predicate is a non-conforming callable::
+
+        >>> get_last_true([1, 2, 3], -1,
+        ...                     lambda x, y: True) # noqa: to avoid typecheck warnings, expects (x)->bool Callable.
+        Traceback (most recent call last):
+        TypeError: <lambda>() missing 1 required positional argument: 'y'
+
+    :param ids: sequence of id(s) from which the last ``predicate`` determined truthy id is to be found.
+    :param default_val: value returned if no id is found as truthy from the ``ids`` list according to the supplied
+        ``predicate``.
+    :param predicate: predicate to determine whether an id is inferred as satisfying and hence returning ``True`` for
+        that id.
+    :return: the last id from the list of ``ids`` which returns ``True`` by the ``predicate`` or ``default_val`` if
+        the ``predicate`` returns ``True`` for no id(s).
+    """
+    return get_first_true(ids, default_val, predicate, reversed)

vt/utils/commons/commons/core_py/__init__.py

@@ -0,0 +1,42 @@
+#!/usr/bin/env python3
+# coding=utf-8
+
+"""
+Reusable interfaces related to core python.
+"""
+
+# region Base interfaces
+from vt.utils.commons.commons.core_py.base import MISSING as MISSING
+from vt.utils.commons.commons.core_py.base import Missing as Missing
+from vt.utils.commons.commons.core_py.base import UNSET as UNSET
+from vt.utils.commons.commons.core_py.base import Unset as Unset
+# endregion
+
+# region utility functions
+from vt.utils.commons.commons.core_py.utils import (
+    has_atleast_one_arg as has_atleast_one_arg,
+)
+from vt.utils.commons.commons.core_py.utils import (
+    ensure_atleast_one_arg as ensure_atleast_one_arg,
+)
+from vt.utils.commons.commons.core_py.utils import (
+    not_none_not_unset as not_none_not_unset,
+)
+from vt.utils.commons.commons.core_py.utils import is_unset as is_unset
+from vt.utils.commons.commons.core_py.utils import alt_if_unset as alt_if_unset
+from vt.utils.commons.commons.core_py.utils import alt_if_missing as alt_if_missing
+from vt.utils.commons.commons.core_py.utils import is_missing as is_missing
+from vt.utils.commons.commons.core_py.utils import alt_if_ellipses as alt_if_ellipses
+from vt.utils.commons.commons.core_py.utils import is_ellipses as is_ellipses
+from vt.utils.commons.commons.core_py.utils import fallback_on_none as fallback_on_none
+from vt.utils.commons.commons.core_py.utils import (
+    fallback_on_none_strict as fallback_on_none_strict,
+)
+from vt.utils.commons.commons.core_py.utils import (
+    not_none_not_missing as not_none_not_missing,
+)
+from vt.utils.commons.commons.core_py.utils import (
+    not_none_not_sentinel as not_none_not_sentinel,
+)
+from vt.utils.commons.commons.core_py.utils import strictly_int as strictly_int
+# endregion

vt/utils/commons/commons/core_py/base.py

@@ -0,0 +1,47 @@
+#!/usr/bin/env python3
+# coding=utf-8
+
+"""
+Reusable interfaces and sentinel objects related to core python.
+"""
+
+from typing import Final
+
+
+class Sentinel:
+    """
+    Class denoting sentinel values.
+    """
+
+    pass
+
+
+class Missing(Sentinel):
+    """
+    A Sentinel type to represent a missing value. Can be used:
+
+    * as default value for a parameter which has ``None`` as a valid value.
+    """
+
+    pass
+
+
+class Unset(Sentinel):
+    """
+    Sentinel type that can be used to unset a previously set value.
+    """
+
+    pass
+
+
+MISSING: Final[Missing] = Missing()
+"""
+Sentinel to represent a missing value. Can be used:
+
+* as default value for a parameter which has ``None`` as a valid value.
+"""
+
+UNSET: Final[Unset] = Unset()
+"""
+Sentinel that can be used to unset a previously set value.
+"""