cocotb 1.9.1__cp311-cp311-win_amd64.whl → 2.0.0__cp311-cp311-win_amd64.whl

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}

cocotb/types/logic_array.py

@@ -1,298 +0,0 @@
-# Copyright cocotb contributors
-# Licensed under the Revised BSD License, see LICENSE for details.
-# SPDX-License-Identifier: BSD-3-Clause
-import typing
-
-from cocotb.binary import BinaryRepresentation, BinaryValue
-from cocotb.types.array import Array
-from cocotb.types.logic import Logic, LogicConstructibleT
-from cocotb.types.range import Range
-
-LogicT = typing.TypeVar("LogicT", bound=Logic)
-S = typing.TypeVar("S")
-Self = typing.TypeVar("Self", bound="LogicArray")
-
-
-class LogicArray(Array[Logic]):
-    r"""
-    Fixed-sized, arbitrarily-indexed, array of :class:`cocotb.types.Logic`.
-
-    .. currentmodule:: cocotb.types
-
-    :class:`LogicArray`\ s can be constructed from either iterables of values
-    constructible into :class:`Logic`: like :class:`bool`, :class:`str`, :class:`int`;
-    or from integers.
-    If constructed from a positive integer, an unsigned bit representation is used to
-    construct the :class:`LogicArray`.
-    If constructed from a negative integer, a two's complement bit representation is
-    used.
-    Like :class:`Array`, if no *range* argument is given, it is deduced from the length
-    of the iterable or bit string used to initialize the variable.
-    If a *range* argument is given, but no value,
-    the array is filled with the default value of Logic().
-
-    .. code-block:: python3
-
-        >>> LogicArray("01XZ")
-        LogicArray('01XZ', Range(3, 'downto', 0))
-
-        >>> LogicArray([0, True, "X"])
-        LogicArray('01X', Range(2, 'downto', 0))
-
-        >>> LogicArray(0xA)  # picks smallest range that can fit the value
-        LogicArray('1010', Range(3, 'downto', 0))
-
-        >>> LogicArray(-4, Range(0, "to", 3))  # will sign-extend
-        LogicArray('1100', Range(0, 'to', 3))
-
-        >>> LogicArray(range=Range(0, "to", 3))  # default values
-        LogicArray('XXXX', Range(0, 'to', 3))
-
-    :class:`LogicArray`\ s support the same operations as :class:`Array`;
-    however, it enforces the condition that all elements must be a :class:`Logic`.
-
-    .. code-block:: python3
-
-        >>> la = LogicArray("1010")
-        >>> la[0]                               # is indexable
-        Logic('0')
-
-        >>> la[1:]                              # is slice-able
-        LogicArray('10', Range(1, 'downto', 0))
-
-        >>> Logic("0") in la                    # is a collection
-        True
-
-        >>> list(la)                            # is an iterable
-        [Logic('1'), Logic('0'), Logic('1'), Logic('0')]
-
-    When setting an element or slice, the *value* is first constructed into a
-    :class:`Logic`.
-
-    .. code-block:: python3
-
-        >>> la = LogicArray("1010")
-        >>> la[3] = "Z"
-        >>> la[3]
-        Logic('Z')
-
-        >>> la[2:] = ['X', True, 0]
-        >>> la
-        LogicArray('ZX10', Range(3, 'downto', 0))
-
-    :class:`LogicArray`\ s can be converted into :class:`str`\ s or :class:`int`\ s.
-
-    .. code-block:: python3
-
-        >>> la = LogicArray("1010")
-        >>> la.binstr
-        '1010'
-
-        >>> la.integer          # uses unsigned representation
-        10
-
-        >>> la.signed_integer   # uses two's complement representation
-        -6
-
-    :class:`LogicArray`\ s also support element-wise logical operations: ``&``, ``|``,
-    ``^``, and ``~``.
-
-    .. code-block:: python3
-
-        >>> def big_mux(a: LogicArray, b: LogicArray, sel: Logic) -> LogicArray:
-        ...     s = LogicArray([sel] * len(a))
-        ...     return (a & ~s) | (b & s)
-
-        >>> la = LogicArray("0110")
-        >>> p = LogicArray("1110")
-        >>> sel = Logic('1')        # choose second option
-        >>> big_mux(la, p, sel)
-        LogicArray('1110', Range(3, 'downto', 0))
-
-    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__ = ()
-
-    @typing.overload
-    def __init__(
-        self,
-        value: typing.Union[int, typing.Iterable[LogicConstructibleT], BinaryValue],
-        range: typing.Optional[Range],
-    ):
-        ...
-
-    @typing.overload
-    def __init__(
-        self,
-        value: typing.Union[
-            int, typing.Iterable[LogicConstructibleT], BinaryValue, None
-        ],
-        range: Range,
-    ):
-        ...
-
-    def __init__(
-        self,
-        value: typing.Union[
-            int, typing.Iterable[LogicConstructibleT], BinaryValue, None
-        ] = None,
-        range: typing.Optional[Range] = None,
-    ) -> None:
-        if value is None and range is None:
-            raise ValueError(
-                "at least one of the value and range input parameters must be given"
-            )
-        if value is None:
-            self._value = [Logic() for _ in range]
-        elif isinstance(value, int):
-            if value < 0:
-                bitlen = int.bit_length(value + 1) + 1
-            else:
-                bitlen = max(1, int.bit_length(value))
-            if range is None:
-                self._value = [Logic(v) for v in _int_to_bitstr(value, bitlen)]
-            else:
-                if bitlen > len(range):
-                    raise ValueError(f"{value} will not fit in {range}")
-                self._value = [Logic(v) for v in _int_to_bitstr(value, len(range))]
-        elif isinstance(value, typing.Iterable):
-            self._value = [Logic(v) for v in value]
-        elif isinstance(value, BinaryValue):
-            self._value = [Logic(v) for v in value.binstr]
-        else:
-            raise TypeError(
-                f"cannot construct {type(self).__qualname__} from value of type {type(value).__qualname__}"
-            )
-        if range is None:
-            self._range = Range(len(self._value) - 1, "downto", 0)
-        else:
-            self._range = range
-        if len(self._value) != len(self._range):
-            raise ValueError(
-                f"value of length {len(self._value)} will not fit in {self._range}"
-            )
-
-    @property
-    def binstr(self) -> str:
-        return "".join(str(bit) for bit in self)
-
-    @property
-    def is_resolvable(self) -> bool:
-        return all(bit in (Logic(0), Logic(1)) for bit in self)
-
-    @property
-    def integer(self) -> int:
-        value = 0
-        for bit in self:
-            value = value << 1 | int(bit)
-        return value
-
-    @property
-    def signed_integer(self) -> int:
-        value = self.integer
-        if value >= (1 << (len(self) - 1)):
-            value -= 1 << len(self)
-        return value
-
-    @typing.overload
-    def __setitem__(self, item: int, value: LogicConstructibleT) -> None:
-        ...
-
-    @typing.overload
-    def __setitem__(
-        self, item: slice, value: typing.Iterable[LogicConstructibleT]
-    ) -> None:
-        ...
-
-    def __setitem__(
-        self,
-        item: typing.Union[int, slice],
-        value: typing.Union[LogicConstructibleT, typing.Iterable[LogicConstructibleT]],
-    ) -> None:
-        if isinstance(item, int):
-            super().__setitem__(item, Logic(typing.cast(LogicConstructibleT, value)))
-        elif isinstance(item, slice):
-            super().__setitem__(
-                item,
-                (
-                    Logic(v)
-                    for v in typing.cast(typing.Iterable[LogicConstructibleT], value)
-                ),
-            )
-        else:
-            raise TypeError(
-                f"indexes must be ints or slices, not {type(item).__name__}"
-            )
-
-    def __repr__(self) -> str:
-        return "{}({!r}, {!r})".format(type(self).__qualname__, self.binstr, self.range)
-
-    def __and__(self: Self, other: Self) -> Self:
-        if isinstance(other, type(self)):
-            if len(self) != len(other):
-                raise ValueError(
-                    f"cannot perform bitwise & "
-                    f"between {type(self).__qualname__} of length {len(self)} "
-                    f"and {type(other).__qualname__} of length {len(other)}"
-                )
-            return type(self)(a & b for a, b in zip(self, other))  # type: ignore
-        return NotImplemented
-
-    def __rand__(self: Self, other: Self) -> Self:
-        return self & other
-
-    def __or__(self: Self, other: Self) -> Self:
-        if isinstance(other, type(self)):
-            if len(self) != len(other):
-                raise ValueError(
-                    f"cannot perform bitwise | "
-                    f"between {type(self).__qualname__} of length {len(self)} "
-                    f"and {type(other).__qualname__} of length {len(other)}"
-                )
-            return type(self)(a | b for a, b in zip(self, other))  # type: ignore
-        return NotImplemented
-
-    def __ror__(self: Self, other: Self) -> Self:
-        return self | other
-
-    def __xor__(self: Self, other: Self) -> Self:
-        if isinstance(other, type(self)):
-            if len(self) != len(other):
-                raise ValueError(
-                    f"cannot perform bitwise ^ "
-                    f"between {type(self).__qualname__} of length {len(self)} "
-                    f"and {type(other).__qualname__} of length {len(other)}"
-                )
-            return type(self)(a ^ b for a, b in zip(self, other))  # type: ignore
-        return NotImplemented
-
-    def __rxor__(self: Self, other: Self) -> Self:
-        return self ^ other
-
-    def __invert__(self: Self) -> Self:
-        return type(self)(~v for v in self)
-
-    def to_BinaryValue(
-        self,
-        bigEndian: bool = True,
-        binaryRepresentation: BinaryRepresentation = BinaryRepresentation.UNSIGNED,
-    ) -> BinaryValue:
-        return BinaryValue(
-            value=self.binstr,
-            n_bits=len(self),
-            bigEndian=bigEndian,
-            binaryRepresentation=binaryRepresentation,
-        )
-
-
-def _int_to_bitstr(value: int, n_bits: int) -> str:
-    if value < 0:
-        value += 1 << n_bits
-    return format(value, f"0{n_bits}b")