cocotb 1.9.2__cp312-cp312-win32.whl → 2.0.0rc2__cp312-cp312-win32.whl

cocotb/types/{range.py → _range.py}

@@ -1,12 +1,14 @@
 # Copyright cocotb contributors
 # Licensed under the Revised BSD License, see LICENSE for details.
 # SPDX-License-Identifier: BSD-3-Clause
-import typing
+import copy
+from functools import lru_cache
+from typing import Any, Dict, Iterator, Sequence, Union, overload
 
-T = typing.TypeVar("T")
+from cocotb._utils import cached_method
 
 
-class Range(typing.Sequence[int]):
+class Range(Sequence[int]):
     r"""
     Variant of :class:`range` with inclusive right bound.
 
@@ -19,19 +21,19 @@ class Range(typing.Sequence[int]):
     left and right bounds.
     Not specifying directionality will cause the directionality to be inferred.
 
-    .. code-block:: python3
+    .. code-block:: pycon3
 
         >>> r = Range(-2, 3)
         >>> r.left, r.right, len(r)
         (-2, 3, 6)
 
-        >>> s = Range(8, 'downto', 1)
+        >>> s = Range(8, "downto", 1)
         >>> s.left, s.right, len(s)
         (8, 1, 8)
 
     :meth:`from_range` and :meth:`to_range` can be used to convert from and to :class:`range`.
 
-    .. code-block:: python3
+    .. code-block:: pycon3
 
         >>> r = Range(-2, 3)
         >>> r.to_range()
@@ -39,11 +41,11 @@ class Range(typing.Sequence[int]):
 
     :class:`Range` supports "null" ranges as seen in VHDL.
     "null" ranges occur when a left bound cannot reach a right bound with the given direction.
-    They have a length of 0, but the :attr:`left`, :attr:`right`, and :attr:`direction` values remain as given.
+    They have a length of ``0``, but the :attr:`left`, :attr:`right`, and :attr:`direction` values remain as given.
 
-    .. code-block:: python3
+    .. code-block:: pycon3
 
-        >>> r = Range(1, 'to', 0)  # no way to count from 1 'to' 0
+        >>> r = Range(1, "to", 0)  # no way to count from 1 'to' 0
         >>> r.left, r.direction, r.right
         (1, 'to', 0)
         >>> len(r)
@@ -60,30 +62,25 @@ class Range(typing.Sequence[int]):
     The typical use case of this type is in conjunction with :class:`~cocotb.types.Array`.
 
     Args:
-        left: leftmost bound of range
-        direction: ``'to'`` if values are ascending, ``'downto'`` if descending
-        right: rightmost bound of range (inclusive)
+        left: Leftmost bound of range.
+        direction: ``'to'`` if values are ascending, ``'downto'`` if descending.
+        right: Rightmost bound of range (inclusive).
     """
 
-    __slots__ = ("_range",)
+    @overload
+    def __init__(self, left: int, direction: int) -> None: ...
 
-    @typing.overload
-    def __init__(self, left: int, direction: int) -> None:
-        pass  # pragma: no cover
+    @overload
+    def __init__(self, left: int, direction: str, right: int) -> None: ...
 
-    @typing.overload
-    def __init__(self, left: int, direction: str, right: int) -> None:
-        pass  # pragma: no cover
-
-    @typing.overload
-    def __init__(self, left: int, *, right: int) -> None:
-        pass  # pragma: no cover
+    @overload
+    def __init__(self, left: int, *, right: int) -> None: ...
 
     def __init__(
         self,
         left: int,
-        direction: typing.Union[int, str, None] = None,
-        right: typing.Union[int, None] = None,
+        direction: Union[int, str, None] = None,
+        right: Union[int, None] = None,
     ) -> None:
         start = left
         stop: int
@@ -91,12 +88,12 @@ class Range(typing.Sequence[int]):
         if isinstance(direction, int) and right is None:
             step = _guess_step(left, direction)
             stop = direction + step
-        elif direction is None and isinstance(right, int):
-            step = _guess_step(left, right)
-            stop = right + step
         elif isinstance(direction, str) and isinstance(right, int):
             step = _direction_to_step(direction)
             stop = right + step
+        elif direction is None and isinstance(right, int):
+            step = _guess_step(left, right)
+            stop = right + step
         else:
             raise TypeError("invalid arguments")
         self._range = range(start, stop, step)
@@ -111,51 +108,49 @@ class Range(typing.Sequence[int]):
         )
 
     def to_range(self) -> range:
-        """Convert :class:`Range` to :class:`range`."""
+        """Convert Range to :class:`range`."""
         return self._range
 
     @property
     def left(self) -> int:
-        """Leftmost value in a range."""
+        """Leftmost value in a Range."""
         return self._range.start
 
     @property
     def direction(self) -> str:
-        """``'to'`` if values are meant to be ascending, ``'downto'`` otherwise."""
+        """``'to'`` if Range is ascending, ``'downto'`` otherwise."""
         return _step_to_direction(self._range.step)
 
     @property
     def right(self) -> int:
-        """Rightmost value in a range."""
+        """Rightmost value in a Range."""
         return self._range.stop - self._range.step
 
     def __len__(self) -> int:
         return len(self._range)
 
-    @typing.overload
-    def __getitem__(self, item: int) -> int:
-        pass  # pragma: no cover
+    @overload
+    def __getitem__(self, item: int) -> int: ...
 
-    @typing.overload
-    def __getitem__(self, item: slice) -> "Range":
-        pass  # pragma: no cover
+    @overload
+    def __getitem__(self, item: slice) -> "Range": ...
 
-    def __getitem__(self, item: typing.Union[int, slice]) -> typing.Union[int, "Range"]:
+    def __getitem__(self, item: Union[int, slice]) -> Union[int, "Range"]:
         if isinstance(item, int):
             return self._range[item]
         elif isinstance(item, slice):
             return type(self).from_range(self._range[item])
         raise TypeError(
-            "indices must be integers or slices, not {}".format(type(item).__name__)
+            f"indices must be integers or slices, not {type(item).__name__}"
         )
 
     def __contains__(self, item: object) -> bool:
         return item in self._range
 
-    def __iter__(self) -> typing.Iterator[int]:
+    def __iter__(self) -> Iterator[int]:
         return iter(self._range)
 
-    def __reversed__(self) -> typing.Iterator[int]:
+    def __reversed__(self) -> Iterator[int]:
         return reversed(self._range)
 
     def __eq__(self, other: object) -> bool:
@@ -166,13 +161,16 @@ class Range(typing.Sequence[int]):
     def __hash__(self) -> int:
         return hash(self._range)
 
-    def count(self, item: int) -> int:
-        return self._range.count(item)
-
     def __repr__(self) -> str:
-        return "{}({!r}, {!r}, {!r})".format(
-            type(self).__qualname__, self.left, self.direction, self.right
-        )
+        return f"{type(self).__qualname__}({self.left!r}, {self.direction!r}, {self.right!r})"
+
+    index = cached_method(Sequence.index)
+
+    def __copy__(self) -> "Range":
+        return Range.from_range(self._range)
+
+    def __deepcopy__(self, memo: Dict[int, Any]) -> "Range":
+        return Range.from_range(copy.deepcopy(self._range, memo=memo))
 
 
 def _guess_step(left: int, right: int) -> int:
@@ -181,6 +179,7 @@ def _guess_step(left: int, right: int) -> int:
     return -1
 
 
+@lru_cache(maxsize=None)
 def _direction_to_step(direction: str) -> int:
     direction = direction.lower()
     if direction == "to":

cocotb/types/_resolve.py

@@ -0,0 +1,76 @@
+# Copyright cocotb contributors
+# Licensed under the Revised BSD License, see LICENSE for details.
+# SPDX-License-Identifier: BSD-3-Clause
+import os
+from functools import lru_cache
+from random import getrandbits
+from typing import Callable, Dict, Union
+
+from cocotb._py_compat import Final, Literal, TypeAlias
+
+ResolverLiteral: TypeAlias = Literal["weak", "zeros", "ones", "random"]
+
+
+_ord_0 = ord("0")
+
+
+class _random_resolve_table(Dict[int, int]):
+    def __init__(self) -> None:
+        self[ord("0")] = ord("0")
+        self[ord("1")] = ord("1")
+        self[ord("L")] = ord("0")
+        self[ord("H")] = ord("1")
+
+    def __missing__(self, _: str) -> int:
+        return getrandbits(1) + _ord_0
+
+
+_resolve_tables: Dict[str, Dict[int, int]] = {
+    "error": {},
+    "weak": str.maketrans("LHW", "01X"),
+    "zeros": str.maketrans("LHUXZW-", "0100000"),
+    "ones": str.maketrans("LHUXZW-", "0111111"),
+    "random": _random_resolve_table(),
+}
+
+_VALID_RESOLVERS = ("error", "weak", "zeros", "ones", "random")
+_VALID_RESOLVERS_ERR_MSG = (
+    "Valid values are 'error', 'weak', 'zeros', 'ones', or 'random'"
+)
+
+
+@lru_cache(maxsize=None)
+def get_str_resolver(resolver: ResolverLiteral) -> Callable[[str], str]:
+    if resolver not in _VALID_RESOLVERS:
+        raise ValueError(f"Invalid resolver: {resolver!r}. {_VALID_RESOLVERS_ERR_MSG}")
+
+    resolve_table = _resolve_tables[resolver]
+
+    def resolve_func(value: str) -> str:
+        return value.translate(resolve_table)
+
+    return resolve_func
+
+
+def _init() -> Union[Callable[[str], str], None]:
+    _envvar = os.getenv("COCOTB_RESOLVE_X", None)
+
+    # no resolver
+    if _envvar is None:
+        return None
+
+    # backwards compatibility
+    resolver = _envvar.strip().lower()
+    if resolver == "value_error":
+        resolver = "error"
+
+    # get resolver
+    try:
+        return get_str_resolver(resolver)
+    except ValueError:
+        raise ValueError(
+            f"Invalid COCOTB_RESOLVE_X value: {_envvar!r}. {_VALID_RESOLVERS_ERR_MSG}"
+        ) from None
+
+
+RESOLVE_X: Final = _init()