iframe-proxy | Sunbelt Computer Software

623 lines (522 loc) · 18.7 KB
This module provides custom container classes with enhanced functionality.
    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.
    - 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.
    >>> d = CastedDict(int, int)
    >>> d[1] = 2
    >>> d['3'] = '4'
    >>> d.update({'5': '6'})
    >>> d.update([('7', '8')])
    {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
    [5, 10, 2, 3, 4]
    >>> d = SliceableDeque([1, 2, 3, 4, 5])
    >>> d[1:4]
    SliceableDeque([2, 3, 4])
# pyright: reportIncompatibleMethodOverride=false
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')
# 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]',
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')])
    {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]
    # 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')])
    {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)
        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')])
    {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]
    # 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')])
    {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']
    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
    [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
    >>> l[0]
    >>> 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: ...
    @typing.overload
    def __setitem__(
        self, indices: slice, values: collections.abc.Iterable[HT]
    ) -> None: ...
    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: ...
    @typing.overload
    def __getitem__(self, index: slice) -> 'SliceableDeque[T]': ...
    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
        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)
            >>> d.pop()
        """
        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()
Sunbelt Computer Software

PL/B Language Development and Support

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Sunbelt Computer Software

PL/B Language Development and Support

FilesExpand file tree

containers.py

Latest commit

History

containers.py

File metadata and controls
