python-utils 2.5.6__py3-none-any.whl → 4.0.0__py3-none-any.whl

python_utils/containers.py

@@ -0,0 +1,637 @@
+"""
+This module provides custom container classes with enhanced functionality.
+
+Classes::
+
+    CastedDictBase: Abstract base class for dictionaries that cast keys and
+        values.
+    CastedDict: Dictionary that casts keys and values to specified types.
+    LazyCastedDict: Dictionary that lazily casts values to specified types upon
+        access.
+    UniqueList: List that only allows unique values, with configurable behavior
+        on duplicates.
+    SliceableDeque: Deque that supports slicing and enhanced equality checks.
+
+Type Aliases::
+
+    KT: Type variable for dictionary keys.
+    VT: Type variable for dictionary values.
+    DT: Type alias for a dictionary with keys of type KT and values of type VT.
+    KT_cast: Type alias for a callable that casts dictionary keys.
+    VT_cast: Type alias for a callable that casts dictionary values.
+    HT: Type variable for hashable values in UniqueList.
+    T: Type variable for generic types.
+    DictUpdateArgs: Union type for arguments that can be used to update a
+        dictionary.
+    OnDuplicate: Literal type for handling duplicate values in UniqueList.
+
+Usage::
+
+    - CastedDict and LazyCastedDict can be used to create dictionaries with
+        automatic type casting.
+    - UniqueList ensures all elements are unique and can raise an error on
+        duplicates.
+    - SliceableDeque extends deque with slicing support and enhanced equality
+        checks.
+
+Examples:
+    >>> d = CastedDict(int, int)
+    >>> d[1] = 2
+    >>> d['3'] = '4'
+    >>> d.update({'5': '6'})
+    >>> d.update([('7', '8')])
+    >>> d
+    {1: 2, 3: 4, 5: 6, 7: 8}
+
+    >>> l = UniqueList(1, 2, 3)
+    >>> l.append(4)
+    >>> l.append(4)
+    >>> l.insert(0, 4)
+    >>> l.insert(0, 5)
+    >>> l[1] = 10
+    >>> l
+    [5, 10, 2, 3, 4]
+
+    >>> d = SliceableDeque([1, 2, 3, 4, 5])
+    >>> d[1:4]
+    SliceableDeque([2, 3, 4])
+"""
+
+# pyright: reportIncompatibleMethodOverride=false
+import abc
+import collections
+import collections.abc
+import typing
+
+if typing.TYPE_CHECKING:
+    import _typeshed  # noqa: F401
+
+#: A type alias for a type that can be used as a key in a dictionary.
+KT = typing.TypeVar('KT')
+#: A type alias for a type that can be used as a value in a dictionary.
+VT = typing.TypeVar('VT')
+#: A type alias for a dictionary with keys of type KT and values of type VT.
+DT = dict[KT, VT]
+#: A type alias for the casted type of a dictionary key.
+KT_cast = collections.abc.Callable[..., KT] | None
+#: A type alias for the casted type of a dictionary value.
+VT_cast = collections.abc.Callable[..., VT] | None
+#: A type alias for the hashable values of the `UniqueList`
+HT = typing.TypeVar('HT', bound=collections.abc.Hashable)
+#: A type alias for a regular generic type
+T = typing.TypeVar('T')
+
+#: Argument shapes accepted when updating a casted dict: a mapping, an iterable
+#: of key/value pairs, an iterable of mappings, or a keys-and-getitem object.
+# Kept as `typing.Union` (not PEP 604 `|`): one member is a string forward
+# reference, and `|` evaluates its operands eagerly, raising `TypeError` on a
+# `str` operand at runtime. `typing.Union` accepts it as a lazy `ForwardRef`.
+DictUpdateArgs = typing.Union[
+    collections.abc.Mapping[KT, VT],
+    collections.abc.Iterable[tuple[KT, VT]],
+    collections.abc.Iterable[collections.abc.Mapping[KT, VT]],
+    '_typeshed.SupportsKeysAndGetItem[KT, VT]',
+]
+
+#: Policy for ``UniqueList`` duplicates: silently ``'ignore'`` or ``'raise'``.
+OnDuplicate = typing.Literal['ignore', 'raise']
+
+
+class CastedDictBase(dict[KT, VT], abc.ABC):
+    """
+    Abstract base class for dictionaries that cast keys and values.
+
+    Attributes:
+        _key_cast (KT_cast[KT]): Callable to cast dictionary keys.
+        _value_cast (VT_cast[VT]): Callable to cast dictionary values.
+
+    Methods::
+
+        __init__(key_cast: KT_cast[KT] = None, value_cast: VT_cast[VT] = None,
+            *args: DictUpdateArgs[KT, VT], **kwargs: VT) -> None:
+            Initializes the dictionary with optional key and value casting
+            callables.
+        update(*args: DictUpdateArgs[typing.Any, typing.Any],
+            **kwargs: typing.Any) -> None:
+            Updates the dictionary with the given arguments.
+        __setitem__(key: typing.Any, value: typing.Any) -> None:
+            Sets the item in the dictionary, casting the key if a key cast
+            callable is provided.
+    """
+
+    _key_cast: KT_cast[KT]
+    _value_cast: VT_cast[VT]
+
+    def __init__(
+        self,
+        key_cast: KT_cast[KT] = None,
+        value_cast: VT_cast[VT] = None,
+        *args: DictUpdateArgs[KT, VT],
+        **kwargs: VT,
+    ) -> None:
+        """
+        Initializes the CastedDictBase with optional key and value
+        casting callables.
+
+        Args:
+            key_cast (KT_cast[KT], optional): Callable to cast
+                dictionary keys. Defaults to None.
+            value_cast (VT_cast[VT], optional): Callable to cast
+                dictionary values. Defaults to None.
+            *args (DictUpdateArgs[KT, VT]): Arguments to initialize
+                the dictionary.
+            **kwargs (VT): Keyword arguments to initialize the
+                dictionary.
+        """
+        self._value_cast = value_cast
+        self._key_cast = key_cast
+        self.update(*args, **kwargs)
+
+    def update(
+        self,
+        *args: DictUpdateArgs[typing.Any, typing.Any],
+        **kwargs: typing.Any,
+    ) -> None:
+        """
+        Updates the dictionary with the given arguments.
+
+        Args:
+            *args (DictUpdateArgs[typing.Any, typing.Any]): Arguments to update
+                the dictionary.
+            **kwargs (typing.Any): Keyword arguments to update the dictionary.
+        """
+        if args:
+            kwargs.update(*args)
+
+        if kwargs:
+            for key, value in kwargs.items():
+                self[key] = value
+
+    def __setitem__(self, key: typing.Any, value: typing.Any) -> None:
+        """
+        Sets the item in the dictionary, casting the key if a key cast
+        callable is provided.
+
+        Args:
+            key (typing.Any): The key to set in the dictionary.
+            value (typing.Any): The value to set in the dictionary.
+        """
+        if self._key_cast is not None:
+            key = self._key_cast(key)
+
+        return super().__setitem__(key, value)
+
+
+class CastedDict(CastedDictBase[KT, VT]):
+    """
+    Custom dictionary that casts keys and values to the specified types.
+
+    Note that you can specify the types for mypy and type hinting with:
+    CastedDict[int, int](int, int)
+
+    >>> d: CastedDict[int, int] = CastedDict(int, int)
+    >>> d[1] = 2
+    >>> d['3'] = '4'
+    >>> d.update({'5': '6'})
+    >>> d.update([('7', '8')])
+    >>> d
+    {1: 2, 3: 4, 5: 6, 7: 8}
+    >>> list(d.keys())
+    [1, 3, 5, 7]
+    >>> list(d)
+    [1, 3, 5, 7]
+    >>> list(d.values())
+    [2, 4, 6, 8]
+    >>> list(d.items())
+    [(1, 2), (3, 4), (5, 6), (7, 8)]
+    >>> d[3]
+    4
+
+    # Casts are optional and can be disabled by passing None as the cast
+    >>> d = CastedDict()
+    >>> d[1] = 2
+    >>> d['3'] = '4'
+    >>> d.update({'5': '6'})
+    >>> d.update([('7', '8')])
+    >>> d
+    {1: 2, '3': '4', '5': '6', '7': '8'}
+    """
+
+    def __setitem__(self, key: typing.Any, value: typing.Any) -> None:
+        """Cast ``value`` (if a value cast is set) and store it under ``key``.
+
+        The key itself is cast by ``CastedDictBase.__setitem__`` when a key
+        cast is configured.
+        """
+        if self._value_cast is not None:
+            value = self._value_cast(value)
+
+        super().__setitem__(key, value)
+
+
+class LazyCastedDict(CastedDictBase[KT, VT]):
+    """
+    Custom dictionary that casts keys and lazily casts values to the specified
+    types. Note that the values are cast only when they are accessed and
+    are not cached between executions.
+
+    Note that you can specify the types for mypy and type hinting with:
+    LazyCastedDict[int, int](int, int)
+
+    >>> d: LazyCastedDict[int, int] = LazyCastedDict(int, int)
+    >>> d[1] = 2
+    >>> d['3'] = '4'
+    >>> d.update({'5': '6'})
+    >>> d.update([('7', '8')])
+    >>> d
+    {1: 2, 3: '4', 5: '6', 7: '8'}
+    >>> list(d.keys())
+    [1, 3, 5, 7]
+    >>> list(d)
+    [1, 3, 5, 7]
+    >>> list(d.values())
+    [2, 4, 6, 8]
+    >>> list(d.items())
+    [(1, 2), (3, 4), (5, 6), (7, 8)]
+    >>> d[3]
+    4
+
+    # Casts are optional and can be disabled by passing None as the cast
+    >>> d = LazyCastedDict()
+    >>> d[1] = 2
+    >>> d['3'] = '4'
+    >>> d.update({'5': '6'})
+    >>> d.update([('7', '8')])
+    >>> d
+    {1: 2, '3': '4', '5': '6', '7': '8'}
+    >>> list(d.keys())
+    [1, '3', '5', '7']
+    >>> list(d.values())
+    [2, '4', '6', '8']
+
+    >>> list(d.items())
+    [(1, 2), ('3', '4'), ('5', '6'), ('7', '8')]
+    >>> d['3']
+    '4'
+    """
+
+    def __setitem__(self, key: typing.Any, value: typing.Any) -> None:
+        """
+        Sets the item in the dictionary, casting the key if a key cast
+        callable is provided.
+
+        Args:
+            key (typing.Any): The key to set in the dictionary.
+            value (typing.Any): The value to set in the dictionary.
+        """
+        if self._key_cast is not None:
+            key = self._key_cast(key)
+
+        super().__setitem__(key, value)
+
+    def __getitem__(self, key: typing.Any) -> VT:
+        """
+        Gets the item from the dictionary, casting the value if a value cast
+        callable is provided.
+
+        Args:
+            key (typing.Any): The key to get from the dictionary.
+
+        Returns:
+            VT: The value from the dictionary.
+        """
+        if self._key_cast is not None:
+            key = self._key_cast(key)
+
+        value = super().__getitem__(key)
+
+        if self._value_cast is not None:
+            value = self._value_cast(value)
+
+        return value
+
+    def items(  # type: ignore[override]
+        self,
+    ) -> collections.abc.Generator[tuple[KT, VT], None, None]:
+        """
+        Returns a generator of the dictionary's items, casting the values if a
+        value cast callable is provided.
+
+        Yields:
+            Generator[tuple[KT, VT], None, None]: A generator of
+                the dictionary's items.
+        """
+        if self._value_cast is None:
+            yield from super().items()
+        else:
+            for key, value in super().items():
+                yield key, self._value_cast(value)
+
+    def values(self) -> collections.abc.Generator[VT, None, None]:  # type: ignore[override]
+        """
+        Returns a generator of the dictionary's values, casting the values if a
+        value cast callable is provided.
+
+        Yields:
+            Generator[VT, None, None]: A generator of the dictionary's
+                values.
+        """
+        if self._value_cast is None:
+            yield from super().values()
+        else:
+            for value in super().values():
+                yield self._value_cast(value)
+
+
+class UniqueList(list[HT]):
+    """
+    A list that only allows unique values. Duplicate values are ignored by
+    default, but can be configured to raise an exception instead.
+
+    >>> l = UniqueList(1, 2, 3)
+    >>> l.append(4)
+    >>> l.append(4)
+    >>> l.insert(0, 4)
+    >>> l.insert(0, 5)
+    >>> l[1] = 10
+    >>> l
+    [5, 10, 2, 3, 4]
+
+    >>> l = UniqueList(1, 2, 3, on_duplicate='raise')
+    >>> l.append(4)
+    >>> l.append(4)
+    Traceback (most recent call last):
+    ...
+    ValueError: Duplicate value: 4
+    >>> l.insert(0, 4)
+    Traceback (most recent call last):
+    ...
+    ValueError: Duplicate value: 4
+    >>> 4 in l
+    True
+    >>> l[0]
+    1
+    >>> l[1] = 4
+    Traceback (most recent call last):
+    ...
+    ValueError: Duplicate value: 4
+    """
+
+    _set: set[HT]
+
+    def __init__(
+        self,
+        *args: HT,
+        on_duplicate: OnDuplicate = 'ignore',
+    ):
+        """
+        Initializes the UniqueList with optional duplicate handling behavior.
+
+        Args:
+            *args (HT): Initial values for the list.
+            on_duplicate (OnDuplicate, optional): Behavior on duplicates.
+                Defaults to 'ignore'.
+        """
+        self.on_duplicate = on_duplicate
+        self._set = set()
+        super().__init__()
+        for arg in args:
+            self.append(arg)
+
+    def insert(self, index: typing.SupportsIndex, value: HT) -> None:
+        """
+        Inserts a value at the specified index, ensuring uniqueness.
+
+        Args:
+            index (typing.SupportsIndex): The index to insert the value at.
+            value (HT): The value to insert.
+
+        Raises:
+            ValueError: If the value is a duplicate and `on_duplicate` is set
+                to 'raise'.
+        """
+        if value in self._set:
+            if self.on_duplicate == 'raise':
+                raise ValueError(f'Duplicate value: {value}')
+            else:
+                return
+
+        self._set.add(value)
+        super().insert(index, value)
+
+    def append(self, value: HT) -> None:
+        """
+        Appends a value to the list, ensuring uniqueness.
+
+        Args:
+            value (HT): The value to append.
+
+        Raises:
+            ValueError: If the value is a duplicate and `on_duplicate` is set
+                to 'raise'.
+        """
+        if value in self._set:
+            if self.on_duplicate == 'raise':
+                raise ValueError(f'Duplicate value: {value}')
+            else:
+                return
+
+        self._set.add(value)
+        super().append(value)
+
+    def __contains__(self, item: HT) -> bool:  # type: ignore[override]
+        """
+        Checks if the list contains the specified item.
+
+        Args:
+            item (HT): The item to check for.
+
+        Returns:
+            bool: True if the item is in the list, False otherwise.
+        """
+        return item in self._set
+
+    @typing.overload
+    def __setitem__(self, indices: typing.SupportsIndex, values: HT) -> None:
+        """Overload: assign a single value at an integer index."""
+
+    @typing.overload
+    def __setitem__(
+        self, indices: slice, values: collections.abc.Iterable[HT]
+    ) -> None:
+        """Overload: assign an iterable of values to a slice."""
+
+    def __setitem__(
+        self,
+        indices: slice | typing.SupportsIndex,
+        values: collections.abc.Iterable[HT] | HT,
+    ) -> None:
+        """
+        Sets the item(s) at the specified index/indices, ensuring uniqueness.
+
+        Args:
+            indices (slice | typing.SupportsIndex): The index or
+                slice to set the value(s) at.
+            values (Iterable[HT] | HT): The value(s) to set.
+
+        Raises:
+            RuntimeError: If `on_duplicate` is 'ignore' and setting slices.
+            ValueError: If the value(s) are duplicates and `on_duplicate` is
+                set to 'raise'.
+        """
+        if isinstance(indices, slice):
+            values = typing.cast(collections.abc.Iterable[HT], values)
+            if self.on_duplicate == 'ignore':
+                raise RuntimeError(
+                    'ignore mode while setting slices introduces ambiguous '
+                    'behaviour and is therefore not supported'
+                )
+
+            duplicates: set[HT] = set(values) & self._set
+            if duplicates and values != list(self[indices]):
+                raise ValueError(f'Duplicate values: {duplicates}')
+
+            self._set.update(values)
+        else:
+            values = typing.cast(HT, values)
+            if values in self._set and values != self[indices]:
+                if self.on_duplicate == 'raise':
+                    raise ValueError(f'Duplicate value: {values}')
+                else:
+                    return
+
+            self._set.add(values)
+
+        super().__setitem__(
+            typing.cast(slice, indices), typing.cast(list[HT], values)
+        )
+
+    def __delitem__(self, index: typing.SupportsIndex | slice) -> None:
+        """
+        Deletes the item(s) at the specified index/indices.
+
+        Args:
+            index (typing.SupportsIndex | slice): The index or slice
+                to delete the item(s) at.
+        """
+        if isinstance(index, slice):
+            for value in self[index]:
+                self._set.remove(value)
+        else:
+            self._set.remove(self[index])
+
+        super().__delitem__(index)
+
+
+# Type hinting `collections.deque` does not work consistently between Python
+# runtime, mypy and pyright currently so we have to ignore the errors
+class SliceableDeque(typing.Generic[T], collections.deque[T]):
+    """
+    A deque that supports slicing and enhanced equality checks.
+
+    Methods::
+
+        __getitem__(index: typing.SupportsIndex | slice) ->
+            T | 'SliceableDeque[T]':
+            Returns the item or slice at the given index.
+        __eq__(other: typing.Any) -> bool:
+            Checks equality with another object, allowing for comparison with
+             lists, tuples, and sets.
+        pop(index: int = -1) -> T:
+            Removes and returns the item at the given index. Only supports
+            index 0 and the last index.
+    """
+
+    @typing.overload
+    def __getitem__(self, index: typing.SupportsIndex) -> T:
+        """Overload: an integer index returns a single item."""
+
+    @typing.overload
+    def __getitem__(self, index: slice) -> 'SliceableDeque[T]':
+        """Overload: a slice returns a new ``SliceableDeque``."""
+
+    def __getitem__(
+        self, index: typing.SupportsIndex | slice
+    ) -> T | 'SliceableDeque[T]':
+        """
+        Return the item or slice at the given index.
+
+        Args:
+            index (typing.SupportsIndex | slice): The index or
+             slice to retrieve.
+
+        Returns:
+            T | 'SliceableDeque[T]': The item or slice at the
+            given index.
+
+        Examples:
+            >>> d = SliceableDeque[int]([1, 2, 3, 4, 5])
+            >>> d[1:4]
+            SliceableDeque([2, 3, 4])
+
+            >>> d = SliceableDeque[str](['a', 'b', 'c'])
+            >>> d[-2:]
+            SliceableDeque(['b', 'c'])
+        """
+        if isinstance(index, slice):
+            start, stop, step = index.indices(len(self))
+            return self.__class__(self[i] for i in range(start, stop, step))
+        else:
+            return super().__getitem__(index)
+
+    def __eq__(self, other: typing.Any) -> bool:
+        """
+        Checks equality with another object, allowing for comparison with
+        lists, tuples, and sets.
+
+        Args:
+            other (typing.Any): The object to compare with.
+
+        Returns:
+            bool: True if the objects are equal, False otherwise.
+        """
+        if isinstance(other, list):
+            return list(self) == other
+        elif isinstance(other, tuple):
+            return tuple(self) == other
+        elif isinstance(other, set):
+            return set(self) == other
+        else:
+            return super().__eq__(other)
+
+    def pop(self, index: int = -1) -> T:
+        """
+        Removes and returns the item at the given index. Only supports index 0
+        and the last index.
+
+        Args:
+            index (int, optional): The index of the item to remove. Defaults to
+            -1.
+
+        Returns:
+            T: The removed item.
+
+        Raises:
+            IndexError: If the index is not 0 or the last index.
+
+        Examples:
+            >>> d = SliceableDeque([1, 2, 3])
+            >>> d.pop(0)
+            1
+            >>> d.pop()
+            3
+        """
+        if index == 0:
+            return super().popleft()
+        elif index in {-1, len(self) - 1}:
+            return super().pop()
+        else:
+            raise IndexError(
+                'Only index 0 and the last index (`N-1` or `-1`) are supported'
+            )
+
+
+if __name__ == '__main__':
+    import doctest
+
+    doctest.testmod()