python-utils 3.8.2__py2.py3-none-any.whl → 3.9.1__py2.py3-none-any.whl

python_utils/containers.py

@@ -1,3 +1,59 @@
+"""
+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
@@ -35,6 +91,26 @@ OnDuplicate = types.Literal['ignore', 'raise']
 
 
 class CastedDictBase(types.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[types.Any, types.Any],
+            **kwargs: types.Any) -> None:
+            Updates the dictionary with the given arguments.
+        __setitem__(key: types.Any, value: types.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]
 
@@ -45,6 +121,20 @@ class CastedDictBase(types.Dict[KT, VT], abc.ABC):
         *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)
@@ -52,6 +142,14 @@ class CastedDictBase(types.Dict[KT, VT], abc.ABC):
     def update(
         self, *args: DictUpdateArgs[types.Any, types.Any], **kwargs: types.Any
     ) -> None:
+        """
+        Updates the dictionary with the given arguments.
+
+        Args:
+            *args (DictUpdateArgs[types.Any, types.Any]): Arguments to update
+                the dictionary.
+            **kwargs (types.Any): Keyword arguments to update the dictionary.
+        """
         if args:
             kwargs.update(*args)
 
@@ -60,6 +158,14 @@ class CastedDictBase(types.Dict[KT, VT], abc.ABC):
                 self[key] = value
 
     def __setitem__(self, key: types.Any, value: types.Any) -> None:
+        """
+        Sets the item in the dictionary, casting the key if a key cast
+        callable is provided.
+
+        Args:
+            key (types.Any): The key to set in the dictionary.
+            value (types.Any): The value to set in the dictionary.
+        """
         if self._key_cast is not None:
             key = self._key_cast(key)
 
@@ -67,7 +173,7 @@ class CastedDictBase(types.Dict[KT, VT], abc.ABC):
 
 
 class CastedDict(CastedDictBase[KT, VT]):
-    '''
+    """
     Custom dictionary that casts keys and values to the specified typing.
 
     Note that you can specify the types for mypy and type hinting with:
@@ -99,9 +205,10 @@ class CastedDict(CastedDictBase[KT, VT]):
     >>> d.update([('7', '8')])
     >>> d
     {1: 2, '3': '4', '5': '6', '7': '8'}
-    '''
+    """
 
     def __setitem__(self, key: typing.Any, value: typing.Any) -> None:
+        """Sets `key` to `cast(value)` in the dictionary."""
         if self._value_cast is not None:
             value = self._value_cast(value)
 
@@ -109,7 +216,7 @@ class CastedDict(CastedDictBase[KT, VT]):
 
 
 class LazyCastedDict(CastedDictBase[KT, VT]):
-    '''
+    """
     Custom dictionary that casts keys and lazily casts values to the specified
     typing. Note that the values are cast only when they are accessed and
     are not cached between executions.
@@ -152,15 +259,33 @@ class LazyCastedDict(CastedDictBase[KT, VT]):
     [(1, 2), ('3', '4'), ('5', '6'), ('7', '8')]
     >>> d['3']
     '4'
-    '''
+    """
 
-    def __setitem__(self, key: types.Any, value: types.Any):
+    def __setitem__(self, key: types.Any, value: types.Any) -> None:
+        """
+        Sets the item in the dictionary, casting the key if a key cast
+        callable is provided.
+
+        Args:
+            key (types.Any): The key to set in the dictionary.
+            value (types.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: types.Any) -> VT:
+        """
+        Gets the item from the dictionary, casting the value if a value cast
+        callable is provided.
+
+        Args:
+            key (types.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)
 
@@ -171,16 +296,32 @@ class LazyCastedDict(CastedDictBase[KT, VT]):
 
         return value
 
-    def items(  # type: ignore
+    def items(  # type: ignore[override]
         self,
     ) -> types.Generator[types.Tuple[KT, VT], None, None]:
+        """
+        Returns a generator of the dictionary's items, casting the values if a
+        value cast callable is provided.
+
+        Yields:
+            types.Generator[types.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) -> types.Generator[VT, None, None]:  # type: ignore
+    def values(self) -> types.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:
+            types.Generator[VT, None, None]: A generator of the dictionary's
+                values.
+        """
         if self._value_cast is None:
             yield from super().values()
         else:
@@ -189,7 +330,7 @@ class LazyCastedDict(CastedDictBase[KT, VT]):
 
 
 class UniqueList(types.List[HT]):
-    '''
+    """
     A list that only allows unique values. Duplicate values are ignored by
     default, but can be configured to raise an exception instead.
 
@@ -220,7 +361,7 @@ class UniqueList(types.List[HT]):
     Traceback (most recent call last):
     ...
     ValueError: Duplicate value: 4
-    '''
+    """
 
     _set: types.Set[HT]
 
@@ -229,6 +370,14 @@ class UniqueList(types.List[HT]):
         *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__()
@@ -236,6 +385,17 @@ class UniqueList(types.List[HT]):
             self.append(arg)
 
     def insert(self, index: types.SupportsIndex, value: HT) -> None:
+        """
+        Inserts a value at the specified index, ensuring uniqueness.
+
+        Args:
+            index (types.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}')
@@ -246,6 +406,16 @@ class UniqueList(types.List[HT]):
         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}')
@@ -255,22 +425,46 @@ class UniqueList(types.List[HT]):
         self._set.add(value)
         super().append(value)
 
-    def __contains__(self, item: HT) -> bool:  # type: ignore
+    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: types.SupportsIndex, values: HT) -> None:
-        ...
+    def __setitem__(
+        self, indices: types.SupportsIndex, values: HT
+    ) -> None: ...
 
     @typing.overload
-    def __setitem__(self, indices: slice, values: types.Iterable[HT]) -> None:
-        ...
+    def __setitem__(
+        self, indices: slice, values: types.Iterable[HT]
+    ) -> None: ...
 
     def __setitem__(
         self,
         indices: types.Union[slice, types.SupportsIndex],
         values: types.Union[types.Iterable[HT], HT],
     ) -> None:
+        """
+        Sets the item(s) at the specified index/indices, ensuring uniqueness.
+
+        Args:
+            indices (types.Union[slice, types.SupportsIndex]): The index or
+                slice to set the value(s) at.
+            values (types.Union[types.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 = types.cast(types.Iterable[HT], values)
             if self.on_duplicate == 'ignore':
@@ -301,6 +495,13 @@ class UniqueList(types.List[HT]):
     def __delitem__(
         self, index: types.Union[types.SupportsIndex, slice]
     ) -> None:
+        """
+        Deletes the item(s) at the specified index/indices.
+
+        Args:
+            index (types.Union[types.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)
@@ -312,38 +513,68 @@ class UniqueList(types.List[HT]):
 
 # Type hinting `collections.deque` does not work consistently between Python
 # runtime, mypy and pyright currently so we have to ignore the errors
-class SliceableDeque(types.Generic[T], collections.deque):  # type: ignore
+class SliceableDeque(types.Generic[T], collections.deque[T]):
+    """
+    A deque that supports slicing and enhanced equality checks.
+
+    Methods:
+        __getitem__(index: types.Union[types.SupportsIndex, slice]) ->
+            types.Union[T, 'SliceableDeque[T]']:
+            Returns the item or slice at the given index.
+        __eq__(other: types.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: types.SupportsIndex) -> T:
-        ...
+    def __getitem__(self, index: types.SupportsIndex) -> T: ...
 
     @typing.overload
-    def __getitem__(self, index: slice) -> 'SliceableDeque[T]':
-        ...
+    def __getitem__(self, index: slice) -> 'SliceableDeque[T]': ...
 
     def __getitem__(
         self, index: types.Union[types.SupportsIndex, slice]
     ) -> types.Union[T, 'SliceableDeque[T]']:
-        '''
+        """
         Return the item or slice at the given index.
 
-        >>> d = SliceableDeque[int]([1, 2, 3, 4, 5])
-        >>> d[1:4]
-        SliceableDeque([2, 3, 4])
+        Args:
+            index (types.Union[types.SupportsIndex, slice]): The index or
+             slice to retrieve.
+
+        Returns:
+            types.Union[T, 'SliceableDeque[T]']: The item or slice at the
+            given index.
 
-        >>> d = SliceableDeque[str](['a', 'b', 'c'])
-        >>> d[-2:]
-        SliceableDeque(['b', 'c'])
+        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 types.cast(T, super().__getitem__(index))
+            return super().__getitem__(index)
 
     def __eq__(self, other: types.Any) -> bool:
-        # Allow for comparison with a list or tuple
+        """
+        Checks equality with another object, allowing for comparison with
+        lists, tuples, and sets.
+
+        Args:
+            other (types.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):
@@ -354,12 +585,31 @@ class SliceableDeque(types.Generic[T], collections.deque):  # type: ignore
             return super().__eq__(other)
 
     def pop(self, index: int = -1) -> T:
-        # We need to allow for an index but a deque only allows the removal of
-        # the first or last item.
+        """
+        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 typing.cast(T, super().popleft())
+            return super().popleft()
         elif index in {-1, len(self) - 1}:
-            return typing.cast(T, super().pop())
+            return super().pop()
         else:
             raise IndexError(
                 'Only index 0 and the last index (`N-1` or `-1`) '