vt-commons 0.0.1__py3-none-any.whl

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

@@ -0,0 +1,827 @@
+#!/usr/bin/env python3
+# coding=utf-8
+
+"""
+Reusable utilities related to core python.
+"""
+
+from collections.abc import Callable, Sequence
+from typing import Any, cast, TypeGuard, overload, Literal
+
+from vt.utils.commons.commons.core_py.base import MISSING, Missing, UNSET, Unset
+
+
+def is_missing[T](obj: T) -> TypeGuard[Missing]:
+    """
+    Determine whether an ``obj`` is ``MISSING``, i.e. not supplied by the caller.
+
+    Examples:
+
+    * ``obj`` is ``MISSING``, i.e. not supplied by the caller:
+
+    >>> obj_to_test = MISSING
+    >>> is_missing(obj_to_test)
+    True
+
+    * ``obj`` is supplied but ``None``, i.e. it is supplied by the caller and hence, not missing:
+
+    >>> is_missing(None)
+    False
+
+    * ``obj`` is truthy primitive and supplied but non ``None``, i.e. it is supplied by the caller and
+      hence, not missing:
+
+    >>> is_missing(2) or is_missing('a') or is_missing(2.5) or is_missing(True) or is_missing(1+0j) or is_missing(b'y')
+    False
+
+    * ``obj`` is falsy primitive and supplied but non ``None``, i.e. it is supplied by the caller and
+      hence, not missing:
+
+    >>> is_missing(0) or is_missing('') or is_missing(0.0) or is_missing(False) or is_missing(0j) or is_missing(b'')
+    False
+
+    * ``obj`` is truthy non-primitive and supplied but non ``None``, i.e. it is supplied by the caller and
+      hence, not missing:
+
+    >>> is_missing([1, 2, 3]) or is_missing({1: 'a', 2: 'b'}) or is_missing({2.5, 2.0})
+    False
+
+    * ``obj`` is falsy non-primitive and supplied but non ``None``, i.e. it is supplied by the caller and
+      hence, not missing:
+
+    >>> is_missing([]) or is_missing({}) or is_missing(set())
+    False
+
+    :param obj: object to be tested whether it was supplied by caller or not.
+    :return: ``True`` if the ``obj`` is missing and not supplied by caller, ``False`` otherwise.
+    """
+    return obj is MISSING
+
+
+def is_unset[T](obj: T) -> TypeGuard[Unset]:
+    """
+    Determine whether an ``obj`` is ``UNSET``, i.e. deliberately unset an already set value by the caller.
+
+    Examples:
+
+    * ``obj`` is ``UNSET``, i.e. deliberately unset by the caller:
+
+    >>> obj_to_test = UNSET
+    >>> is_unset(obj_to_test)
+    True
+
+    * ``obj`` is supplied but ``None``, i.e. it is supplied by the caller and hence, not unset:
+
+    >>> is_unset(None)
+    False
+
+    * ``obj`` is truthy primitive and supplied but non ``None``, i.e. it is supplied by the caller and
+      hence, not unset:
+
+    >>> is_unset(2) or is_unset('a') or is_unset(2.5) or is_unset(True) or is_unset(1+0j) or is_unset(b'y')
+    False
+
+    * ``obj`` is falsy primitive and supplied but non ``None``, i.e. it is supplied by the caller and
+      hence, not unset:
+
+    >>> is_unset(0) or is_unset('') or is_unset(0.0) or is_unset(False) or is_unset(0j) or is_unset(b'')
+    False
+
+    * ``obj`` is truthy non-primitive and supplied but non ``None``, i.e. it is supplied by the caller and
+      hence, not unset:
+
+    >>> is_unset([1, 2, 3]) or is_unset({1: 'a', 2: 'b'}) or is_unset({2.5, 2.0})
+    False
+
+    * ``obj`` is falsy non-primitive and supplied but non ``None``, i.e. it is supplied by the caller and
+      hence, not unset:
+
+    >>> is_unset([]) or is_unset({}) or is_unset(set())
+    False
+
+    :param obj: object to be tested whether it was supplied by caller or not.
+    :return: ``True`` if the ``obj`` is deliberatley unset by the caller, ``False`` otherwise.
+    """
+    return obj is UNSET
+
+
+def not_none_not_sentinel[T, S](val: T | None, *, sentinel: S) -> TypeGuard[T]:
+    """
+    Returns True if ``val`` is not None and not the given sentinel.
+
+    Used to create specific type guards for `UNSET`, `MISSING`, or any custom sentinel.
+
+    >>> not_none_not_sentinel("x", sentinel=UNSET)
+    True
+    >>> not_none_not_sentinel(None, sentinel=UNSET)
+    False
+    >>> not_none_not_sentinel(UNSET, sentinel=UNSET)
+    False
+    """
+    return val is not None and val is not sentinel
+
+
+def not_none_not_unset[T](val: T | None | Unset) -> TypeGuard[T]:
+    """
+    Check if the value is neither None nor UNSET.
+
+    >>> not_none_not_unset("a")
+    True
+    >>> not_none_not_unset(None)
+    False
+    >>> not_none_not_unset(UNSET)
+    False
+
+    >>> not_none_not_unset(0)
+    True
+    >>> not_none_not_unset("")
+    True
+    >>> not_none_not_unset(False)
+    True
+    >>> not_none_not_unset([])
+    True
+    >>> not_none_not_unset({})
+    True
+    >>> not_none_not_unset(set())
+    True
+
+    >>> _val: int | None | Unset = 5
+    >>> if not_none_not_unset(_val):
+    ...     type(_val)  # Revealed type is "int"
+    <class 'int'>
+    """
+    return not_none_not_sentinel(val, sentinel=UNSET)
+
+
+def not_none_not_missing[T](val: T | None | Missing) -> TypeGuard[T]:
+    """
+    Check if the value is neither None nor MISSING.
+
+    >>> not_none_not_missing("b")
+    True
+    >>> not_none_not_missing(None)
+    False
+    >>> not_none_not_missing(MISSING)
+    False
+
+    >>> not_none_not_missing(0)
+    True
+    >>> not_none_not_missing("")
+    True
+    >>> not_none_not_missing(False)
+    True
+    >>> not_none_not_missing([])
+    True
+    >>> not_none_not_missing({})
+    True
+    >>> not_none_not_missing(set())
+    True
+
+    >>> _val: str | None | Missing = "hello"
+    >>> if not_none_not_missing(_val):
+    ...     type(_val)  # Revealed type is "str"
+    <class 'str'>
+    """
+    return not_none_not_sentinel(val, sentinel=MISSING)
+
+
+def _alt_if_predicate_true[T, U](
+    obj: Any | U, alt: T, predicate: Callable[[Any | U], bool]
+) -> T:
+    """
+    Get an alternate object ``alt`` if the queried object ``obj`` is ``MISSING``, i.e. it is not supplied by the caller.
+
+    Note::
+
+        Returned value is always of the type of alt object.
+
+    :param obj: object to be tested whether it was fulfills the ``predicate`` or not.
+    :param predicate: A predicate that ``obj`` needs to fulfill to be returned from this method.
+    :param alt: alternate object to be returned if ``obj`` does not fulfill the ``predicate``.
+    :return: ``obj`` if it fulfills the ``predicate`` else ``alt``.
+    """
+    if predicate(obj):
+        return alt
+    if type(obj) is not type(alt):
+        raise TypeError(
+            f"Unexpected type: `obj` and `alt` must be of the same type. type(obj): {type(obj)}, "
+            f"type(alt): {type(alt)}"
+        )
+    return alt if is_missing(obj) else cast(T, obj)
+
+
+def alt_if_missing[T](obj: Any | Missing, alt: T) -> T:
+    """
+    Get an alternate object ``alt`` if the queried object ``obj`` is ``MISSING``, i.e. it is not supplied by the caller.
+
+    Note::
+
+        Returned value is always of the type of alt object.
+
+    Examples:
+
+    * Main object ``obj`` is returned if it is not ``MISSING``, i.e. it was supplied by the caller. Also, the returned
+      object ``obj`` is of the type of alternative ``alt`` object, test for falsy ``obj`` objects:
+
+    >>> assert alt_if_missing(None, None) is None
+    >>> assert alt_if_missing(0, 2) == 0
+    >>> assert alt_if_missing(0.0, 1.3) == 0.0
+    >>> assert alt_if_missing('', 'z') == ''
+    >>> assert alt_if_missing([], [1, 2, 3]) == []
+    >>> assert alt_if_missing({}, {'a': 1, 'b': 2}) == {}
+    >>> assert alt_if_missing(set(), {1, 2, 3}) == set()
+    >>> assert alt_if_missing(0j, 1+2j) == 0j
+
+    * Main object ``obj`` is returned if it is not ``MISSING``, i.e. it was supplied by the caller. Also, the returned
+      object ``obj`` is of the type of alternative ``alt`` object, test for truthy ``obj`` objects:
+
+    >>> assert alt_if_missing('a', 'null') == 'a'
+    >>> assert alt_if_missing(-1, 2) == -1
+    >>> assert alt_if_missing(0.9, 1.3) == 0.9
+    >>> assert alt_if_missing('jo', 'z') == 'jo'
+    >>> assert alt_if_missing([9, 8, 7], [1, 2, 3]) == [9, 8, 7]
+    >>> assert alt_if_missing({'z': 10, 'y': 9, 'x': 8}, {'a': 1, 'b': 2}) == {'z': 10, 'y': 9, 'x': 8}
+    >>> assert alt_if_missing({0, 9, 8}, {1, 2, 3}) == {0, 9, 8}
+    >>> assert alt_if_missing(1+0j, 1+2j) == 1+0j
+
+    * Alternate object ``alt`` is returned when main object ``obj`` is ``MISSING``, i.e. it was not supplied by
+      the caller. Also, the returned object ``alt`` is of the type of alternative ``alt`` object:
+
+    >>> assert alt_if_missing(MISSING, None) is None
+    >>> assert alt_if_missing(MISSING, 0) == 0
+    >>> assert alt_if_missing(MISSING, 0.0) == 0,0
+    >>> assert alt_if_missing(MISSING, '') == ''
+    >>> assert alt_if_missing(MISSING, []) == []
+    >>> assert alt_if_missing(MISSING, {}) == {}
+    >>> assert alt_if_missing(MISSING, set()) == set()
+    >>> assert alt_if_missing(MISSING, 0j) == 0j
+
+    * Errs if main object ``obj`` is not ``MISSING`` and hence, is supplied by the caller, but its type is different
+      from the type of the alternative ``alt`` object:
+
+    >>> alt_if_missing('a', 2)
+    Traceback (most recent call last):
+    TypeError: Unexpected type: `obj` and `alt` must be of the same type. type(obj): <class 'str'>, type(alt): <class 'int'>
+
+    >>> alt_if_missing([], (2, 3, 4))
+    Traceback (most recent call last):
+    TypeError: Unexpected type: `obj` and `alt` must be of the same type. type(obj): <class 'list'>, type(alt): <class 'tuple'>
+
+    :param obj: object to be tested whether it was supplied by caller or not.
+    :param alt: alternate object to be returned if ``obj`` was not supplied by the caller.
+    :return: ``obj`` if it was supplied by the caller else ``alt``.
+    """
+    return _alt_if_predicate_true(obj, alt, is_missing)
+
+
+def alt_if_unset[T](obj: Any | Unset, alt: T) -> T:
+    """
+    Get an alternate object ``alt`` if the queried object ``obj`` is ``UNSET``, i.e. it is deliberately unset by
+    the caller.
+
+    Note::
+
+        Returned value is always of the type of alt object.
+
+    Examples:
+
+    * Main object ``obj`` is returned if it is not ``UNSET``, i.e. it was not deliberately unset by the caller. Also,
+      the returned object ``obj`` is of the type of alternative ``alt`` object, test for falsy ``obj`` objects:
+
+    >>> assert alt_if_unset(None, None) is None
+    >>> assert alt_if_unset(0, 2) == 0
+    >>> assert alt_if_unset(0.0, 1.3) == 0.0
+    >>> assert alt_if_unset('', 'z') == ''
+    >>> assert alt_if_unset([], [1, 2, 3]) == []
+    >>> assert alt_if_unset({}, {'a': 1, 'b': 2}) == {}
+    >>> assert alt_if_unset(set(), {1, 2, 3}) == set()
+    >>> assert alt_if_unset(0j, 1+2j) == 0j
+
+    * Main object ``obj`` is returned if it is not ``UNSET``, i.e. it was not deliberately unset by the caller. Also,
+      the returned object ``obj`` is of the type of alternative ``alt`` object, test for truthy ``obj`` objects:
+
+    >>> assert alt_if_unset('a', 'null') == 'a'
+    >>> assert alt_if_unset(-1, 2) == -1
+    >>> assert alt_if_unset(0.9, 1.3) == 0.9
+    >>> assert alt_if_unset('jo', 'z') == 'jo'
+    >>> assert alt_if_unset([9, 8, 7], [1, 2, 3]) == [9, 8, 7]
+    >>> assert alt_if_unset({'z': 10, 'y': 9, 'x': 8}, {'a': 1, 'b': 2}) == {'z': 10, 'y': 9, 'x': 8}
+    >>> assert alt_if_unset({0, 9, 8}, {1, 2, 3}) == {0, 9, 8}
+    >>> assert alt_if_unset(1+0j, 1+2j) == 1+0j
+
+    * Alternate object ``alt`` is returned when main object ``obj`` is ``UNSET``, i.e. it was deliberately unset by
+      the caller. Also, the returned object ``alt`` is of the type of alternative ``alt`` object:
+
+    >>> assert alt_if_unset(UNSET, None) is None
+    >>> assert alt_if_unset(UNSET, 0) == 0
+    >>> assert alt_if_unset(UNSET, 0.0) == 0,0
+    >>> assert alt_if_unset(UNSET, '') == ''
+    >>> assert alt_if_unset(UNSET, []) == []
+    >>> assert alt_if_unset(UNSET, {}) == {}
+    >>> assert alt_if_unset(UNSET, set()) == set()
+    >>> assert alt_if_unset(UNSET, 0j) == 0j
+
+    * Errs if main object ``obj`` is not ``UNSET`` and hence, is supplied by the caller, but its type is different
+      from the type of the alternative ``alt`` object:
+
+    >>> alt_if_unset('a', 2)
+    Traceback (most recent call last):
+    TypeError: Unexpected type: `obj` and `alt` must be of the same type. type(obj): <class 'str'>, type(alt): <class 'int'>
+
+    >>> alt_if_unset([], (2, 3, 4))
+    Traceback (most recent call last):
+    TypeError: Unexpected type: `obj` and `alt` must be of the same type. type(obj): <class 'list'>, type(alt): <class 'tuple'>
+
+    :param obj: object to be tested whether it was deliberately unset by the caller or not.
+    :param alt: alternate object to be returned if ``obj`` was not supplied by the caller.
+    :return: ``alt`` if ``obj`` was deliberately unset by the caller, else ``obj``.
+    """
+    return _alt_if_predicate_true(obj, alt, is_unset)
+
+
+def is_ellipses(obj: Any) -> bool:
+    """
+    :param obj: object to be tested whether it was supplied by caller or not.
+    :return: ``True`` if the ``obj`` is missing and not supplied by caller, ``False`` otherwise.
+    """
+    return obj is ...
+
+
+def alt_if_ellipses[T](obj, alt: T) -> T:
+    """
+    Get an alternate object ``alt`` if the queried object ``obj`` is ``...``, i.e. it is not supplied by the caller or
+    is deliberatey kept ``...`` by the caller.
+
+    Note::
+
+        Returned value is always of the type of alt object.
+
+    Examples:
+
+    * Main object ``obj`` is returned if it is not ``...``, i.e. it was supplied by the caller. Also, the returned
+      object ``obj`` is of the type of alternative ``alt`` object, test for falsy ``obj`` objects:
+
+    >>> assert alt_if_ellipses(None, None) is None
+    >>> assert alt_if_ellipses(0, 2) == 0
+    >>> assert alt_if_ellipses(0.0, 1.3) == 0.0
+    >>> assert alt_if_ellipses('', 'z') == ''
+    >>> assert alt_if_ellipses([], [1, 2, 3]) == []
+    >>> assert alt_if_ellipses({}, {'a': 1, 'b': 2}) == {}
+    >>> assert alt_if_ellipses(set(), {1, 2, 3}) == set()
+    >>> assert alt_if_ellipses(0j, 1+2j) == 0j
+
+    * Main object ``obj`` is returned if it is not ``...``, i.e. it was supplied by the caller. Also, the returned
+      object ``obj`` is of the type of alternative ``alt`` object, test for truthy ``obj`` objects:
+
+    >>> assert alt_if_ellipses('a', 'null') == 'a'
+    >>> assert alt_if_ellipses(-1, 2) == -1
+    >>> assert alt_if_ellipses(0.9, 1.3) == 0.9
+    >>> assert alt_if_ellipses('jo', 'z') == 'jo'
+    >>> assert alt_if_ellipses([9, 8, 7], [1, 2, 3]) == [9, 8, 7]
+    >>> assert alt_if_ellipses({'z': 10, 'y': 9, 'x': 8}, {'a': 1, 'b': 2}) == {'z': 10, 'y': 9, 'x': 8}
+    >>> assert alt_if_ellipses({0, 9, 8}, {1, 2, 3}) == {0, 9, 8}
+    >>> assert alt_if_ellipses(1+0j, 1+2j) == 1+0j
+
+    * Alternate object ``alt`` is returned when main object ``obj`` is ``...``, i.e. it was not supplied by
+      the caller or is deliberately kept ``...`` by the caller. Also, the returned object ``alt`` is of the type of
+      alternative ``alt`` object:
+
+    >>> assert alt_if_ellipses(..., None) is None
+    >>> assert alt_if_ellipses(..., 0) == 0
+    >>> assert alt_if_ellipses(..., 0.0) == 0,0
+    >>> assert alt_if_ellipses(..., '') == ''
+    >>> assert alt_if_ellipses(..., []) == []
+    >>> assert alt_if_ellipses(..., {}) == {}
+    >>> assert alt_if_ellipses(..., set()) == set()
+    >>> assert alt_if_ellipses(..., 0j) == 0j
+
+    * Errs if main object ``obj`` is not ``...`` and hence, is supplied by the caller, but its type is different
+      from the type of the alternative ``alt`` object:
+
+    >>> alt_if_ellipses('a', 2)
+    Traceback (most recent call last):
+    TypeError: Unexpected type: `obj` and `alt` must be of the same type. type(obj): <class 'str'>, type(alt): <class 'int'>
+
+    >>> alt_if_ellipses([], (2, 3, 4))
+    Traceback (most recent call last):
+    TypeError: Unexpected type: `obj` and `alt` must be of the same type. type(obj): <class 'list'>, type(alt): <class 'tuple'>
+
+    :param obj: object to be tested whether it was supplied as ellipses by caller or not.
+    :param alt: alternate object to be returned if ``obj`` is supplied as ellipses by the caller.
+    :return: ``obj`` if it was supplied as ellipses by the caller, else ``alt``.
+    """
+    return _alt_if_predicate_true(obj, alt, is_ellipses)
+
+
+def fallback_on_none[T](value: T | None, default_val: T | None) -> T | None:
+    """
+    Get ``value`` if it is non-``None`` else get ``default_val``.
+
+    Examples:
+
+    >>> fallback_on_none('a', 'b')
+    'a'
+
+    >>> fallback_on_none(None, 'b')
+    'b'
+
+    >>> fallback_on_none(None, True)
+    True
+
+    >>> fallback_on_none(True, False)
+    True
+
+    * on Falsy values:
+
+    >>> fallback_on_none([], [1, 2])
+    []
+
+    >>> fallback_on_none({}, {1: 2, 2: 3})
+    {}
+
+    >>> fallback_on_none(set(), {1, 2, 3})
+    set()
+
+    >>> fallback_on_none((),
+    ...                 (1, 2, 3)) # noqa: some tuple warning
+    ()
+
+    >>> fallback_on_none(False, True)
+    False
+
+    :param value: The main value to return if it is not ``None``.
+    :param default_val: returned if ``value`` is ``None``.
+    :return: ``default_val`` if ``value`` is ``None`` else ``value``.
+    """
+    return default_val if value is None else value
+
+
+def fallback_on_none_strict[T](value: T | None, default_val: T) -> T:
+    """
+    Same as ``fallback_on_non_strict()`` but has an assertion guarantee that ``default_val`` is non-``None``.
+
+    Examples:
+
+    >>> fallback_on_none_strict('a', 'b')
+    'a'
+
+    >>> fallback_on_none_strict('a',
+    ...                         None) # noqa: just for example
+    Traceback (most recent call last):
+    AssertionError: default_val must not be None.
+
+    :param value: The main value to return if it is not ``None``.
+    :param default_val: returned if ``value`` is ``None``.
+    :return: ``default_val`` if ``value`` is ``None`` else ``value``.
+    """
+    assert default_val is not None, "default_val must not be None."
+    return cast(T, fallback_on_none(value, default_val))
+
+
+def strictly_int(value: object) -> TypeGuard[int]:
+    """
+    Check if a value is strictly an integer but NOT a boolean.
+
+    This utility function is designed to distinguish between `int` and `bool` types
+    because in Python, `bool` is a subclass of `int` and would pass an `isinstance(value, int)`
+    check. This function returns `True` only if the value is a genuine integer
+    (excluding booleans).
+
+    Usage of this function is crucial in contexts where the semantic difference between
+    integers and booleans must be maintained, such as argument validation for functions
+    that accept integers but must reject boolean values.
+
+    :param value: The value to be checked.
+    :return: `True` if `value` is an `int` but not a `bool`; otherwise `False`.
+
+    :rtype: TypeGuard[int]
+
+    Examples::
+
+        >>> strictly_int(5)
+        True
+        >>> strictly_int(-10)
+        True
+        >>> strictly_int(0)
+        True
+        >>> strictly_int(True)
+        False
+        >>> strictly_int(False)
+        False
+        >>> strictly_int(5.0)
+        False
+        >>> strictly_int("5")
+        False
+        >>> strictly_int(None)
+        False
+        >>> strictly_int([1, 2, 3])
+        False
+        >>> strictly_int(object())
+        False
+
+    This function helps static type checkers like mypy to narrow types::
+
+        >>> from typing import reveal_type
+        >>> def test(x: int | bool | str) -> int:
+        ...     if strictly_int(x):
+        ...         reveal_type(x)  # Revealed type is 'int'
+        ...         return x + 1
+        ...     else:
+        ...         raise ValueError("Not strictly an int")
+        ...
+        >>> test(10)
+        11
+        >>> test(True)  # Raises ValueError
+        Traceback (most recent call last):
+        ValueError: Not strictly an int
+    """
+    return isinstance(value, int) and not isinstance(value, bool)
+
+
+# region positional args related utility methods
+
+# region ensure_atleast_one_arg() and overloads
+
+
+@overload
+def ensure_atleast_one_arg[T](
+    first: T | None, *rest: T, falsy: bool = False, enforce_type: None = None
+) -> Sequence[T]: ...
+
+
+@overload
+def ensure_atleast_one_arg[T](
+    first: object | None,
+    *rest: object,
+    falsy: bool = False,
+    enforce_type: Literal[False] = False,
+) -> Sequence[object]: ...
+
+
+@overload
+def ensure_atleast_one_arg[T](
+    first: T | None, *rest: T, falsy: bool = False, enforce_type: type[T]
+) -> Sequence[T]: ...
+
+
+def ensure_atleast_one_arg[T](
+    first: T | object | None,
+    *rest: T | object,
+    falsy: bool = False,
+    enforce_type: type | Literal[False] | None = None,
+) -> Sequence[T] | Sequence[object]:
+    """
+    Ensures that at least one argument is provided (truthy or non-None),
+    with optional type enforcement or inference.
+
+
+    ``enforce_type`` behavior:
+
+      * if not provided, defaults to ``None``. This defaults the method to type check all the arguments to have the same
+        type as the first valid argument. Invalidating this condition raises a ``TypeError``.
+
+      * if ``False`` then, no type-enforcement is performed.
+
+      * if a type is provided, like ``str``, ``int`` etc. then all the arguments are enforce to have this same type.
+        Invalidating this condition raises a ``TypeError``.
+
+    :param first: First argument (can be None).
+    :param rest: Additional arguments.
+    :param falsy: Whether to treat falsy values as invalid.
+    :param enforce_type: A specific type to enforce across all arguments.
+
+    :returns: A tuple of valid arguments.
+
+    :raises ValueError: If no valid argument is provided.
+    :raises TypeError: If enforce_type is given but a mismatch is found.
+
+
+    Examples::
+
+    >>> ensure_atleast_one_arg("foo", None)
+    ('foo',)
+
+    >>> ensure_atleast_one_arg("foo", "bar", enforce_type=str)
+    ('foo', 'bar')
+
+    >>> ensure_atleast_one_arg(1, "a", enforce_type=int) # type: ignore[arg-type] # expected int, provided str.
+    Traceback (most recent call last):
+    TypeError: Expected all arguments to be of type int.
+
+    >>> ensure_atleast_one_arg(1, "a")
+    Traceback (most recent call last):
+    TypeError: Expected all arguments to be of type int.
+
+    >>> ensure_atleast_one_arg(1, "a", enforce_type=False)
+    (1, 'a')
+
+    >>> ensure_atleast_one_arg(None, [], {}, falsy=True)
+    Traceback (most recent call last):
+    ValueError: At least one argument is required.
+
+    >>> ensure_atleast_one_arg(None, 0, "", enforce_type=False, falsy=True)
+    Traceback (most recent call last):
+    ValueError: At least one argument is required.
+
+    >>> ensure_atleast_one_arg(None, "hi", 2.3, enforce_type=False)
+    ('hi', 2.3)
+
+    >>> ensure_atleast_one_arg(None, "hi", 2.3)
+    Traceback (most recent call last):
+    TypeError: Expected all arguments to be of type str.
+
+    >>> ensure_atleast_one_arg(None, 123, enforce_type=int)
+    (123,)
+
+    >>> ensure_atleast_one_arg(None, 123, enforce_type=str)
+    Traceback (most recent call last):
+    TypeError: Expected all arguments to be of type str.
+
+    >>> ensure_atleast_one_arg("hi", None, 3.0, falsy=True)
+    Traceback (most recent call last):
+    TypeError: Expected all arguments to be of type str.
+
+    >>> ensure_atleast_one_arg(None, 'null', 3.0, None, set(), enforce_type=False)
+    ('null', 3.0, set())
+    """
+    values = _filter_args(first, *rest, falsy=falsy)
+
+    if not values:
+        raise ValueError("At least one argument is required.")
+
+    if enforce_type is not False:
+        expected_type = enforce_type or type(values[0])
+        for v in values:
+            if not isinstance(v, expected_type):
+                raise TypeError(
+                    f"Expected all arguments to be of type {expected_type.__name__}."
+                )
+
+    return values
+
+
+# endregion
+
+
+# region has_atleast_one_arg() and overloads
+@overload
+def has_atleast_one_arg[T](
+    first: T | None, *rest: T, falsy: bool = False, enforce_type: None = None
+) -> bool:
+    """
+    A ``has_atleast_one_arg()`` overload.
+
+    ``first`` and ``rest`` all args must be of the same type when ``enforce_type`` is not provided or is ``None``.
+    """
+    ...
+
+
+@overload
+def has_atleast_one_arg(
+    first: object | None,
+    *rest: object,
+    falsy: bool = False,
+    enforce_type: Literal[False] = False,
+) -> bool:
+    """
+    A ``has_atleast_one_arg()`` overload.
+
+    ``first`` and ``rest`` all args can be of any type when ``enforce_type=False``.
+    """
+    ...
+
+
+@overload
+def has_atleast_one_arg[T](
+    first: T | None, *rest: T, falsy: bool = False, enforce_type: type[T]
+) -> bool:
+    """
+    A ``has_atleast_one_arg()`` overload.
+
+    ``first`` and ``rest`` all args must be of the type provided as ``enforce_type``.
+
+    For example, ``first`` and ``rest`` all args must be ``int`` when ``enforce_type=int``.
+    """
+    ...
+
+
+def has_atleast_one_arg(
+    first: object | None,
+    *rest: object,
+    falsy: bool = False,
+    enforce_type: type | Literal[False] | None = None,
+) -> bool:
+    """
+    Returns True if there is at least one valid (non-None or truthy) argument,
+    optionally enforcing all values are of the same type.
+
+    :param first: First argument (can be None).
+    :param rest: Additional arguments.
+    :param falsy: Whether to treat falsy values as invalid.
+    :param enforce_type: Type to enforce across all arguments.
+    :returns: True if valid arguments are found and type checks pass.
+
+    >>> has_atleast_one_arg(None, [])
+    True
+
+    >>> has_atleast_one_arg(None, [], falsy=True)
+    False
+
+    >>> has_atleast_one_arg("a", "b", enforce_type=str)
+    True
+
+    >>> has_atleast_one_arg("a", 1, enforce_type=str) # type: ignore[arg-type] # expected str, provided int.
+    False
+
+    >>> has_atleast_one_arg("foo")
+    True
+
+    >>> has_atleast_one_arg(None, "bar")
+    True
+
+    >>> has_atleast_one_arg(None, None)
+    False
+
+    >>> has_atleast_one_arg("", [], 0)
+    False
+
+    >>> has_atleast_one_arg("", [], 0, enforce_type=False)
+    True
+
+    >>> has_atleast_one_arg("", [], 0, falsy=True)
+    False
+
+    >>> has_atleast_one_arg(1, 2, 3, enforce_type=int)
+    True
+
+    >>> has_atleast_one_arg(1, "2", enforce_type=int) # type: ignore[arg-type] # expected int, provided str.
+    False
+
+    >>> has_atleast_one_arg(1, "2", enforce_type=False)
+    True
+
+    >>> has_atleast_one_arg(None, 2.0, enforce_type=int)
+    False
+
+    >>> has_atleast_one_arg(None, 2.0, enforce_type=float)
+    True
+
+    >>> has_atleast_one_arg(None, "", 0, False, enforce_type=False, falsy=True)
+    False
+
+    >>> has_atleast_one_arg("abc", 123)
+    False
+
+    >>> has_atleast_one_arg("abc", 123, enforce_type=False)
+    True
+
+    >>> has_atleast_one_arg("abc", 123, enforce_type=str) # type: ignore[arg-type] # expected str, provided int.
+    False
+
+    >>> has_atleast_one_arg(None, None, None, falsy=True)
+    False
+
+    >>> has_atleast_one_arg("a", None, falsy=True)
+    True
+
+    >>> has_atleast_one_arg("a", None, enforce_type=str) # type: ignore[arg-type] # expected str, provided None.
+    True
+
+    >>> has_atleast_one_arg(None, [1, 2, 3], enforce_type=list)
+    True
+
+    >>> has_atleast_one_arg(None, [1, 2, 3], enforce_type=dict)
+    False
+    """
+    return bool(
+        _collect_valid_args(first, *rest, falsy=falsy, enforce_type=enforce_type)
+    )
+
+
+# endregion
+
+
+# region Internal utility functions to handle positional variadic args.
+def _filter_args(first, *rest, falsy):
+    args = (first, *rest)
+    if falsy:
+        return tuple(arg for arg in args if arg)
+    else:
+        return tuple(arg for arg in args if arg is not None)
+
+
+def _collect_valid_args(first, *rest, falsy, enforce_type):
+    values = _filter_args(first, *rest, falsy=falsy)
+    if enforce_type is False:
+        return values
+
+    if values:
+        expected_type = enforce_type or type(values[0])
+        if all(isinstance(v, expected_type) for v in values):
+            return values
+    return ()
+
+
+# endregion
+
+# endregion