cocotb 1.9.2__cp313-cp313-win_amd64.whl → 2.0.0rc2__cp313-cp313-win_amd64.whl

cocotb/types/array.py

@@ -1,309 +0,0 @@
-# Copyright cocotb contributors
-# Licensed under the Revised BSD License, see LICENSE for details.
-# SPDX-License-Identifier: BSD-3-Clause
-import typing
-from itertools import chain
-
-from cocotb.types.range import Range
-
-T = typing.TypeVar("T")
-S = typing.TypeVar("S")
-Self = typing.TypeVar("Self", bound="Array[typing.Any]")
-
-
-class Array(typing.Reversible[T], typing.Collection[T]):
-    r"""
-    Fixed-size, arbitrarily-indexed, homogeneous collection type.
-
-    Arrays are similar to, but different from Python :class:`list`\ s.
-    An array can store values of any type or values of multiple types at a time, just like a :class:`list`.
-    Unlike :class:`list`\ s, an array's size cannot change.
-
-    The indexes of an array can start or end at any integer value, they are not limited to 0-based indexing.
-    Indexing schemes can be either ascending or descending in value.
-    An array's indexes are described using a :class:`~cocotb.types.Range` object.
-    Initial values are treated as iterables, which are copied into an internal buffer.
-
-    .. code-block:: python3
-
-        >>> Array("1234")  # the 0-based range `(0, len(value)-1)` is inferred
-        Array(['1', '2', '3', '4'], Range(0, 'to', 3))
-
-        >>> Array([1, True, None, "example"], Range(-2, 1))  # initial value and range lengths must be equal
-        Array([1, True, None, 'example'], Range(-2, 'to', 1))
-
-    Arrays also support "null" ranges; "null" arrays have zero length and cannot be indexed.
-
-    .. code-block:: python3
-
-        >>> Array([], range=Range(1, "to", 0))
-        Array([], Range(1, 'to', 0))
-
-    Indexing and slicing is very similar to :class:`list`\ s, but it uses the indexing scheme specified.
-    Slicing, just like the :class:`~cocotb.types.Range` object uses an inclusive right bound,
-    which is commonly seen in HDLs.
-    Like :class:`list`\ s, if a start or stop index is not specified, it is inferred as the start or end of the array.
-    Slicing an array returns a new :class:`~cocotb.types.Array` object, whose bounds are the slice indexes.
-
-    .. code-block:: python3
-
-        >>> a = Array("1234abcd")
-        >>> a[7]
-        'd'
-        >>> a[2:5]
-        Array(['3', '4', 'a', 'b'], Range(2, 'to', 5))
-        >>> a[2:5] = reversed(a[2:5])
-        >>> "".join(a)
-        '12ba43cd'
-
-        >>> b = Array("1234", Range(0, -3))
-        >>> b[-2]
-        '3'
-        >>> b[-1:]
-        Array(['2', '3', '4'], Range(-1, 'downto', -3))
-        >>> b[:] = reversed(b)
-        >>> b
-        Array(['4', '3', '2', '1'], Range(0, 'downto', -3))
-
-    .. warning::
-        Arrays behave differently in certain situations than Python's builtin sequence types (:class:`list`, :class:`tuple`, etc.).
-
-        - Arrays are not necessarily 0-based and slices use inclusive right bounds,
-          so many functions that work on Python sequences by index (like :mod:`bisect`) may not work on arrays.
-        - Slice indexes must be specified in the same direction as the array and do not support specifying a "step".
-        - When setting a slice, the new value must be an iterable of the same size as the slice.
-        - Negative indexes are *not* treated as an offset from the end of the array, but are treated literally.
-
-    Arrays are equal to other arrays of the same length with the same values (structural equality).
-    Bounds do not matter for equality.
-
-    .. code-block:: python3
-
-        >>> a = Array([1, 1, 2, 3, 5], Range(4, "downto", 0))
-        >>> b = Array([1, 1, 2, 3, 5], Range(-2, "to", 2))
-        >>> a == b
-        True
-
-    You can change the bounds of an array by setting the :attr:`range` to a new value.
-    The new bounds must be the same length of the array.
-
-    .. code-block:: python3
-
-        >>> a = Array("1234")
-        >>> a.range
-        Range(0, 'to', 3)
-        >>> a.range = Range(3, 'downto', 0)
-        >>> a.range
-        Range(3, 'downto', 0)
-
-    Arrays support the methods and semantics defined by :class:`collections.abc.Sequence`.
-
-    .. code-block:: python
-
-        >>> a = Array("stuff", Range(2, "downto", -2))
-        >>> len(a)
-        5
-        >>> "t" in a
-        True
-        >>> a.index("u")
-        0
-        >>> for c in a:
-        ...     print(c)
-        s
-        t
-        u
-        f
-        f
-
-    Args:
-        value: Initial value for the array.
-        range: Indexing scheme of the array.
-
-    Raises:
-        ValueError: When argument values cannot be used to construct an array.
-        TypeError: When invalid argument types are used.
-    """
-
-    __slots__ = (
-        "_value",
-        "_range",
-    )
-
-    def __init__(self, value: typing.Iterable[T], range: typing.Optional[Range] = None):
-        self._value = list(value)
-        if range is None:
-            self._range = Range(0, "to", len(self._value) - 1)
-        else:
-            self._range = range
-            if len(self._value) != len(self._range):
-                raise ValueError(
-                    "init value of length {!r} does not fit in {!r}".format(
-                        len(self._value), self._range
-                    )
-                )
-
-    @property
-    def left(self) -> int:
-        """Leftmost index of the array."""
-        return self.range.left
-
-    @property
-    def direction(self) -> str:
-        """``"to"`` if indexes are ascending, ``"downto"`` otherwise."""
-        return self.range.direction
-
-    @property
-    def right(self) -> int:
-        """Rightmost index of the array."""
-        return self.range.right
-
-    @property
-    def range(self) -> Range:
-        """:class:`Range` of the indexes of the array."""
-        return self._range
-
-    @range.setter
-    def range(self, new_range: Range) -> None:
-        """Sets a new indexing scheme on the array, must be the same size"""
-        if not isinstance(new_range, Range):
-            raise TypeError("range argument must be of type 'Range'")
-        if len(new_range) != len(self):
-            raise ValueError(
-                f"{new_range!r} not the same length as old range ({self._range!r})."
-            )
-        self._range = new_range
-
-    def __len__(self) -> int:
-        return len(self.range)
-
-    def __iter__(self) -> typing.Iterator[T]:
-        return iter(self._value)
-
-    def __reversed__(self) -> typing.Iterator[T]:
-        return reversed(self._value)
-
-    def __contains__(self, item: object) -> bool:
-        return item in self._value
-
-    def __eq__(self, other: object) -> bool:
-        if isinstance(other, type(self)):
-            return self._value == other._value
-        return NotImplemented
-
-    @typing.overload
-    def __getitem__(self, item: int) -> T:
-        ...
-
-    @typing.overload
-    def __getitem__(self, item: slice) -> "Array[T]":
-        ...
-
-    def __getitem__(
-        self, item: typing.Union[int, slice]
-    ) -> typing.Union[T, "Array[T]"]:
-        if isinstance(item, int):
-            idx = self._translate_index(item)
-            return self._value[idx]
-        elif isinstance(item, slice):
-            start = item.start if item.start is not None else self.left
-            stop = item.stop if item.stop is not None else self.right
-            if item.step is not None:
-                raise IndexError("do not specify step")
-            start_i = self._translate_index(start)
-            stop_i = self._translate_index(stop)
-            if start_i > stop_i:
-                raise IndexError(
-                    "slice [{}:{}] direction does not match array direction [{}:{}]".format(
-                        start, stop, self.left, self.right
-                    )
-                )
-            value = self._value[start_i : stop_i + 1]
-            range = Range(start, self.direction, stop)
-            return type(self)(value=value, range=range)
-        raise TypeError(
-            "indexes must be ints or slices, not {}".format(type(item).__name__)
-        )
-
-    @typing.overload
-    def __setitem__(self, item: int, value: T) -> None:
-        ...
-
-    @typing.overload
-    def __setitem__(self, item: slice, value: typing.Iterable[T]) -> None:
-        ...
-
-    def __setitem__(
-        self, item: typing.Union[int, slice], value: typing.Union[T, typing.Iterable[T]]
-    ) -> None:
-        if isinstance(item, int):
-            idx = self._translate_index(item)
-            self._value[idx] = typing.cast(T, value)
-        elif isinstance(item, slice):
-            start = item.start if item.start is not None else self.left
-            stop = item.stop if item.stop is not None else self.right
-            if item.step is not None:
-                raise IndexError("do not specify step")
-            start_i = self._translate_index(start)
-            stop_i = self._translate_index(stop)
-            if start_i > stop_i:
-                raise IndexError(
-                    "slice [{}:{}] direction does not match array direction [{}:{}]".format(
-                        start, stop, self.left, self.right
-                    )
-                )
-            value = list(typing.cast(typing.Iterable[T], value))
-            if len(value) != (stop_i - start_i + 1):
-                raise ValueError(
-                    "value of length {!r} will not fit in slice [{}:{}]".format(
-                        len(value), start, stop
-                    )
-                )
-            self._value[start_i : stop_i + 1] = value
-        else:
-            raise TypeError(
-                "indexes must be ints or slices, not {}".format(type(item).__name__)
-            )
-
-    def __repr__(self) -> str:
-        return "{}({!r}, {!r})".format(type(self).__name__, self._value, self._range)
-
-    def __concat__(self: Self, other: Self) -> Self:
-        if isinstance(other, type(self)):
-            return type(self)(chain(self, other))
-        return NotImplemented
-
-    def __rconcat__(self: Self, other: Self) -> Self:
-        if isinstance(other, type(self)):
-            return type(self)(chain(other, self))
-        return NotImplemented
-
-    def index(
-        self,
-        value: T,
-        start: typing.Optional[int] = None,
-        stop: typing.Optional[int] = None,
-    ) -> int:
-        """
-        Return index of first occurrence of *value*.
-
-        Raises :exc:`IndexError` if the value is not found.
-        Search only within *start* and *stop* if given.
-        """
-        if start is None:
-            start = self.left
-        if stop is None:
-            stop = self.right
-        for i in Range(start, self.direction, stop):
-            if self[i] == value:
-                return i
-        raise IndexError(f"{value!r} not in array")
-
-    def count(self, value: T) -> int:
-        """Return number of occurrences of *value*."""
-        return self._value.count(value)
-
-    def _translate_index(self, item: int) -> int:
-        try:
-            return self._range.index(item)
-        except ValueError:
-            raise IndexError(f"index {item} out of range") from None

cocotb/types/logic.py

@@ -1,292 +0,0 @@
-# Copyright cocotb contributors
-# Licensed under the Revised BSD License, see LICENSE for details.
-# SPDX-License-Identifier: BSD-3-Clause
-import typing
-from functools import lru_cache
-
-LogicT = typing.TypeVar("LogicT", bound="Logic")
-LogicLiteralT = typing.Union[str, int, bool]
-LogicConstructibleT = typing.Union[LogicLiteralT, "Logic"]
-
-
-_0 = 0
-_1 = 1
-_X = 2
-_Z = 3
-
-_literal_repr: typing.Dict[LogicLiteralT, int] = {
-    # 0 and weak 0
-    False: _0,
-    0: _0,
-    "0": _0,
-    "L": _0,
-    "l": _0,
-    # 1 and weak 1
-    True: _1,
-    1: _1,
-    "1": _1,
-    "H": _1,
-    "h": _1,
-    # unknown, unassigned, and weak unknown
-    "X": _X,
-    "x": _X,
-    "U": _X,
-    "u": _X,
-    "W": _X,
-    "w": _X,
-    "-": _X,
-    # high impedance
-    "Z": _Z,
-    "z": _Z,
-}
-
-
-class Logic:
-    r"""
-    Model of a 4-value (``0``, ``1``, ``X``, ``Z``) datatype commonly seen in HDLs.
-
-    .. currentmodule:: cocotb.types
-
-    This is modeled after (System)Verilog's 4-value ``logic`` type.
-    VHDL's 9-value ``std_ulogic`` type maps to this type by treating weak values as full strength values
-    and treating "uninitialized" (``U``) and "don't care" (``-``) as "unknown" (``X``).
-
-    :class:`Logic` can be converted to and from :class:`int`, :class:`str`, :class:`bool`, and :class:`Bit`
-    by using the appropriate constructor syntax.
-    The list of values convertable to :class:`Logic` includes
-    ``0``, ``1``, ``True``, ``False``, ``"0"``, ``"1"``, ``"X"``, ``"Z"``, ``Bit('0')``, and ``Bit('1')``.
-    For a comprehensive list of values that can be converted into :class:`Logic` see :file:`tests/pytest/test_logic.py`.
-
-    .. code-block:: python3
-
-        >>> Logic("X")
-        Logic('X')
-        >>> Logic(True)
-        Logic('1')
-        >>> Logic(1)
-        Logic('1')
-        >>> Logic(Bit(0))
-        Logic('0')
-
-        >>> Logic()  # default value
-        Logic('X')
-
-        >>> str(Logic("Z"))
-        'Z'
-        >>> bool(Logic(0))
-        False
-        >>> int(Logic(1))
-        1
-        >>> Bit(Logic("1"))
-        Bit('1')
-
-    .. note::
-
-        The :class:`int` and :class:`bool` conversions will raise :exc:`ValueError` if the value is not ``0`` or ``1``.
-
-    :class:`Logic` values are immutable and therefore hashable and can be placed in :class:`set`\ s and used as keys in :class:`dict`\ s.
-
-    :class:`Logic` supports the common logic operations ``&``, ``|``, ``^``, and ``~``.
-
-    .. code-block:: python3
-
-        >>> def full_adder(a: Logic, b: Logic, carry: Logic) -> typing.Tuple[Logic, Logic]:
-        ...     res = a ^ b ^ carry
-        ...     carry_out = (a & b) | (b & carry) | (a & carry)
-        ...     return res, carry_out
-
-        >>> full_adder(a=Logic('0'), b=Logic('1'), carry=Logic('1'))
-        (Logic('0'), Logic('1'))
-
-    Args:
-        value: value to construct into a :class:`Logic`.
-
-    Raises:
-        ValueError: if the value cannot be constructed into a :class:`Logic`.
-    """
-    __slots__ = ("_repr",)
-    _repr: int
-
-    _default = _X
-    _valid = {_X, _0, _1, _Z}
-
-    @classmethod
-    @lru_cache(maxsize=None)
-    def _make(cls: typing.Type[LogicT], _repr: int) -> LogicT:
-        """enforce singleton"""
-        self = object.__new__(cls)
-        self._repr = _repr
-        return typing.cast(LogicT, self)
-
-    def __new__(
-        cls: typing.Type[LogicT],
-        value: typing.Optional[LogicConstructibleT] = None,
-    ) -> LogicT:
-        if isinstance(value, Logic):
-            # convert Logic
-            _repr = value._repr
-        elif value is None:
-            _repr = cls._default
-        else:
-            # convert literal
-            try:
-                _repr = _literal_repr[value]
-            except KeyError:
-                raise ValueError(
-                    "{!r} is not convertible to a {}".format(value, cls.__qualname__)
-                ) from None
-        if _repr not in cls._valid:
-            raise ValueError("{!r} is not a valid {}".format(value, cls.__qualname__))
-        obj = cls._make(_repr)
-        return obj
-
-    if not typing.TYPE_CHECKING:  # pragma: no cover
-        # mypy currently does not support lru_cache on __new__
-        __new__ = lru_cache(maxsize=None)(__new__)
-
-    def __and__(self: LogicT, other: LogicT) -> LogicT:
-        if not isinstance(other, type(self)):
-            return NotImplemented
-        return type(self)(
-            (
-                ("0", "0", "0", "0"),
-                ("0", "1", "X", "X"),
-                ("0", "X", "X", "X"),
-                ("0", "X", "X", "X"),
-            )[self._repr][other._repr]
-        )
-
-    def __rand__(self: LogicT, other: LogicT) -> LogicT:
-        return self & other
-
-    def __or__(self: LogicT, other: LogicT) -> LogicT:
-        if not isinstance(other, type(self)):
-            return NotImplemented
-        return type(self)(
-            (
-                ("0", "1", "X", "X"),
-                ("1", "1", "1", "1"),
-                ("X", "1", "X", "X"),
-                ("X", "1", "X", "X"),
-            )[self._repr][other._repr]
-        )
-
-    def __ror__(self: LogicT, other: LogicT) -> LogicT:
-        return self | other
-
-    def __xor__(self: LogicT, other: LogicT) -> LogicT:
-        if not isinstance(other, type(self)):
-            return NotImplemented
-        return type(self)(
-            (
-                ("0", "1", "X", "X"),
-                ("1", "0", "X", "X"),
-                ("X", "X", "X", "X"),
-                ("X", "X", "X", "X"),
-            )[self._repr][other._repr]
-        )
-
-    def __rxor__(self: LogicT, other: LogicT) -> LogicT:
-        return self ^ other
-
-    def __invert__(self: LogicT) -> LogicT:
-        return type(self)(("1", "0", "X", "X")[self._repr])
-
-    def __eq__(self, other: object) -> bool:
-        if not isinstance(other, type(self)):
-            return NotImplemented
-        return self._repr == other._repr
-
-    def __hash__(self) -> int:
-        return self._repr
-
-    def __repr__(self) -> str:
-        return "{}({!r})".format(type(self).__qualname__, str(self))
-
-    def __str__(self) -> str:
-        return ("0", "1", "X", "Z")[self._repr]
-
-    def __bool__(self) -> bool:
-        if self._repr in {_0, _1}:
-            return bool(self._repr)
-        raise ValueError(f"Cannot convert {self!r} to bool")
-
-    def __int__(self) -> int:
-        if self._repr in {_0, _1}:
-            return int(self._repr)
-        raise ValueError(f"Cannot convert {self!r} to int")
-
-
-class Bit(Logic):
-    r"""
-    Model of a 2-value (``0``, ``1``) datatype commonly seen in HDLs.
-
-    .. currentmodule:: cocotb.types
-
-    This is modeled after (System)Verilog's 2-value ``bit`` type.
-    VHDL's ``bit`` type maps to this type perfectly.
-
-    :class:`Bit` is a proper subtype of :class:`Logic`, meaning a use of :class:`Logic` can be substituted with a :class:`Bit`.
-    Some behavior may surprise you if you do not expect it.
-
-    .. code-block:: python3
-
-        >>> Bit(0) == Logic(0)
-        True
-        >>> Bit(0) in {Logic(0)}
-        True
-
-    :class:`Bit` can be converted to and from :class:`int`, :class:`str`, :class:`bool`, and :class:`Logic`
-    by using the appropriate constructor syntax.
-    The list of values convertable to :class:`Bit` includes
-    ``0``, ``1``, ``True``, ``False``, ``"0"``, ``"1"``, ``Logic('0')``, and ``Logic('1')``.
-    For a comprehensive list of values that can be converted into :class:`Bit` see :file:`tests/pytest/test_logic.py`.
-
-    .. code-block:: python3
-
-        >>> Bit("0")
-        Bit('0')
-        >>> Bit(True)
-        Bit('1')
-        >>> Bit(1)
-        Bit('1')
-        >>> Bit(Logic(0))
-        Bit('0')
-
-        >>> Bit()  # default value
-        Bit('0')
-
-        >>> str(Bit("0"))
-        '0'
-        >>> bool(Bit(False))
-        False
-        >>> int(Bit(1))
-        1
-        >>> Logic(Bit("1"))
-        Logic('1')
-
-    :class:`Bit` values are hashable and can be placed in :class:`set`\ s and used as keys in :class:`dict`\ s.
-
-    :class:`Bit` supports the common logic operations ``&``, ``|``, ``^``, and ``~``.
-
-    .. code-block:: py3
-
-        >>> def mux(a: Bit, b: Bit, s: Bit) -> Bit:
-        ...     return (a & ~s) | (b & s)
-
-        >>> a = Bit(0)
-        >>> b = Bit(1)
-        >>> sel = Bit(1)  # choose second argument
-        >>> mux(a, b, sel)
-        Bit('1')
-
-    Args:
-        value: value to construct into a :class:`Bit`.
-
-    Raises:
-        ValueError: if the value cannot be constructed into a :class:`Bit`.
-    """
-    __slots__ = ()
-
-    _default = _0
-    _valid = {_0, _1}