cocotb 2.0.0b1__cp313-cp313-win_amd64.whl → 2.0.0rc2__cp313-cp313-win_amd64.whl

cocotb/_test_factory.py

@@ -7,8 +7,8 @@ import inspect
 import logging
 import warnings
 from itertools import product
-from types import FrameType, FunctionType
 from typing import (
+    TYPE_CHECKING,
     Callable,
     Coroutine,
     Dict,
@@ -25,6 +25,9 @@ from cocotb._base_triggers import Trigger
 from cocotb._decorators import Test
 from cocotb._typing import TimeUnit
 
+if TYPE_CHECKING:
+    from types import FrameType, FunctionType
+
 
 class TestFactory:
     """Factory to automatically generate tests.

cocotb/_utils.py

@@ -6,12 +6,10 @@
 
 """Utilities for implementors."""
 
-import os
-import sys
 import traceback
 import types
 from enum import Enum, IntEnum
-from functools import lru_cache, update_wrapper, wraps
+from functools import update_wrapper, wraps
 from types import TracebackType
 from typing import (
     TYPE_CHECKING,
@@ -27,26 +25,6 @@ from typing import (
     overload,
 )
 
-
-@lru_cache(maxsize=None)
-def want_color_output() -> bool:
-    """Return ``True`` if colored output is possible/requested and not running in GUI.
-
-    Colored output can be explicitly requested in a cocotb-specific way
-    by setting :envvar:`COCOTB_ANSI_OUTPUT` to  ``1``.
-
-    Returns: Whether color output is wanted and supported.
-    """
-    want_color = sys.stdout.isatty()  # default to color for TTYs
-    if os.getenv("NO_COLOR") is not None:
-        want_color = False
-    if os.getenv("COCOTB_ANSI_OUTPUT", default="0") == "1":
-        want_color = True
-    if os.getenv("GUI", default="0") == "1":
-        want_color = False
-    return want_color
-
-
 ExceptionTuple = Tuple[
     Type[BaseException], BaseException, TracebackType
 ]  # TypeAlias in Python 3.10

cocotb/_version.py

@@ -1,4 +1,4 @@
 # Package version
 # Generated by setup.py -- do not modify directly
 
-__version__ = "2.0.0b1"
+__version__ = "2.0.0rc2"

cocotb/clock.py

@@ -31,9 +31,9 @@ from cocotb.handle import (
 from cocotb.simulator import clock_create
 from cocotb.task import Task
 from cocotb.triggers import (
-    ClockCycles,
     Event,
     FallingEdge,
+    NullTrigger,
     RisingEdge,
     Timer,
     ValueChange,
@@ -58,10 +58,10 @@ class Clock:
 
     Args:
         signal: The clock pin/signal to be driven.
-        period: The clock period.
+        period:
+            The clock period.
+            Must be a multiple of the time precision of the simulator.
 
-            .. note::
-                Must convert to an even number of timesteps.
         unit:
             One of ``'step'``, ``'fs'``, ``'ps'``, ``'ns'``, ``'us'``, ``'ms'``, ``'sec'``.
             When *unit* is ``'step'``,
@@ -84,6 +84,13 @@ class Clock:
 
             .. versionadded:: 2.0
 
+        period_high:
+            The period of time when the clock is driven to ``1``.
+            Defaults to half of the *period*.
+            Must be a multiple of the time precision of the simulator and less than *period*.
+
+            .. versionadded:: 2.0
+
     When *impl* is ``'auto'``, if :envvar:`COCOTB_TRUST_INERTIAL_WRITES` is defined,
     the :class:`~cocotb.simulator.GpiClock` implementation will be used.
     Otherwise, the Python coroutine implementation will be used.
@@ -158,9 +165,10 @@ class Clock:
         *,
         units: None = None,
         set_action: Union[Type[Immediate], Type[Deposit], Type[Force], None] = None,
+        period_high: Union[float, Fraction, Decimal, None] = None,
     ) -> None:
         self._signal = signal
-        self._period = period
+
         if units is not None:
             warnings.warn(
                 "The 'units' argument has been renamed to 'unit'.",
@@ -169,11 +177,18 @@ class Clock:
             )
             unit = units
         self._unit: TimeUnit = unit
+
+        self._period = period
+        try:
+            self._period_steps = get_sim_steps(self._period, self._unit)
+        except ValueError as e:
+            raise ValueError(f"Bad `period`: {e}") from None
+
         if set_action is None:
             set_action = type(self).default_set_action
         if set_action not in (Immediate, Deposit, Force):
             raise TypeError(
-                "Invalid value for *set_action*. *set_action* must be one of Immediate, Deposit, or Force"
+                "Invalid value for `set_action`. `set_action` must be one of Immediate, Deposit, or Force"
             )
         self._set_action = set_action
 
@@ -187,6 +202,23 @@ class Clock:
                 f"Invalid clock impl {impl!r}, must be one of: {valid_impls_str}"
             )
 
+        self._period_high: Union[float, Fraction, Decimal]
+        if period_high is not None:
+            if period_high >= self._period:
+                raise ValueError("`period_high` must be strictly less than `period`.")
+            self._period_high = period_high
+            try:
+                self._period_high_steps = get_sim_steps(self._period_high, self._unit)
+            except ValueError as e:
+                raise ValueError(f"Bad `period_high`: {e}") from None
+        else:
+            if self._period_steps % 2 != 0:
+                raise ValueError(
+                    "Bad `period`: Must be divisible by 2 if `period_high` is not given."
+                )
+            self._period_high = period / 2
+            self._period_high_steps = self._period_steps // 2
+
         self._task: Union[Task[None], None] = None
 
     @property
@@ -196,9 +228,22 @@ class Clock:
 
     @property
     def period(self) -> Union[float, Fraction, Decimal]:
-        """The clock period (unit-less)."""
+        """The clock period.
+
+        The unit is :attr:`unit`.
+        """
         return self._period
 
+    @property
+    def period_high(self) -> Union[float, Fraction, Decimal]:
+        """The period of time when the clock is driven to ``1``.
+
+        The unit is :attr:`unit`.
+
+        .. versionadded:: 2.0
+        """
+        return self._period_high
+
     @property
     def unit(self) -> TimeUnit:
         """The unit of the clock period.
@@ -256,9 +301,6 @@ class Clock:
         if self._task is not None:
             raise RuntimeError("Starting clock that has already been started.")
 
-        period = get_sim_steps(self._period, self._unit)
-        t_high = period // 2
-
         if self._impl == "gpi":
             clkobj = clock_create(self._signal._handle)
             set_action = {
@@ -266,7 +308,12 @@ class Clock:
                 Immediate: _GPISetAction.NO_DELAY,
                 Force: _GPISetAction.FORCE,
             }[self._set_action]
-            clkobj.start(period, t_high, start_high, set_action)
+            clkobj.start(
+                self._period_steps,
+                self._period_high_steps,
+                start_high,
+                set_action.value,
+            )
 
             async def drive() -> None:
                 # The clock is meant to toggle forever, so awaiting this should
@@ -280,8 +327,8 @@ class Clock:
         else:
 
             async def drive() -> None:
-                timer_high = Timer(t_high)
-                timer_low = Timer(period - t_high)
+                timer_high = Timer(self._period_high_steps)
+                timer_low = Timer(self._period_steps - self._period_high_steps)
                 if start_high:
                     self._signal.set(self._set_action(1))
                     await timer_high
@@ -316,9 +363,44 @@ class Clock:
             Type[RisingEdge], Type[FallingEdge], Type[ValueChange]
         ] = RisingEdge,
     ) -> None:
-        """Wait for a number of clock cycles."""
-        # TODO Improve implementation to use a Timer to skip most of the cycles
-        await ClockCycles(self._signal, num_cycles, edge_type)
+        """Wait for a number of clock cycles.
+
+        Args:
+            num_cycles: The number of clock cycles to wait.
+            edge_type:
+                The edge of the clock to wait on.
+                Must be one of :class:`.RisingEdge`, :class:`.FallingEdge`, or :class:`.ValueChange`.
+
+        Raises:
+            ValueError: if *num_cycles* is negative.
+        """
+        if num_cycles == 0:
+            await NullTrigger()
+            return
+        elif num_cycles < 0:
+            raise ValueError("`num_cycles` cannot be negative")
+
+        # Synchronize first.
+        await edge_type(self._signal)
+        num_cycles -= 1
+
+        # Use Timer as an optimization if we are waiting long enough.
+        if num_cycles >= 2:
+            # NOTE: num_cycles must end 1 higher than expected because all edge_types occur
+            # strictly after beginning of time steps, so the last edge_type will jump within
+            # the same time step.
+            if edge_type is ValueChange:
+                # Make cycles_skipped the nearest even number so division by 2 doesn't cause issues.
+                cycles_skipped = (num_cycles // 2) * 2
+                await Timer(self._period_steps * cycles_skipped / 2, "step")
+                num_cycles = num_cycles - cycles_skipped + 1
+            else:
+                await Timer(self._period_steps * num_cycles, "step")
+                num_cycles = 1
+
+        # Run N edge_type trigger.
+        for _ in range(num_cycles):
+            await edge_type(self._signal)
 
     def __repr__(self) -> str:
         return self._repr

cocotb/debug.py

@@ -0,0 +1,24 @@
+# Copyright cocotb contributors
+# Licensed under the Revised BSD License, see LICENSE for details.
+# SPDX-License-Identifier: BSD-3-Clause
+
+import os
+
+debug: bool = bool(os.getenv("COCOTB_SCHEDULER_DEBUG"))
+"""Global flag to enable additional debugging functionality.
+
+Defaults to ``True`` if the :envvar:`COCOTB_SCHEDULER_DEBUG` environment variable is set,
+but can be programmatically set by the user afterwards.
+
+The ``"cocotb"`` logger should have its logging level set to :data:`logging.DEBUG`
+to see additional debugging information in the test log.
+This can be accomplished by setting the :envvar:`COCOTB_LOG_LEVEL` environment variable
+to ``DEBUG``,
+or using the following code.
+
+.. code-block:: python
+
+    import logging
+    logging.getLogger("cocotb").setLevel(logging.DEBUG)
+
+"""

cocotb/handle.py

@@ -45,6 +45,7 @@ from cocotb._py_compat import cached_property, insertion_ordered_dict
 from cocotb._utils import DocIntEnum
 from cocotb.task import Task
 from cocotb.types import Array, Logic, LogicArray, Range
+from cocotb.types._indexing import do_indexing_changed_warning, indexing_changed
 
 __all__ = (
     "ArrayObject",
@@ -214,6 +215,9 @@ class _RangeableObjectMixin(SimHandleBase):
 #: Type of keys (name or index) in HierarchyObjectBase.
 KeyType = TypeVar("KeyType")
 
+#: Subtype of :class:`SimHandleBase` returned when iterating or indexing a :class:`HierarchyArrayObject`.
+HierarchyChildObjectT = TypeVar("HierarchyChildObjectT", bound=SimHandleBase)
+
 
 class GPIDiscovery(DocIntEnum):
     """Simulator object discovery strategy."""
@@ -417,7 +421,7 @@ class HierarchyObject(_HierarchyObjectBase[str]):
 
     - the name cannot start with a number
     - the name cannot start with a ``_`` character
-    - the name can only contain ASCII letters, numbers, and the ``_`` character
+    - the name can only contain ASCII letters, numbers, and the ``_`` character.
 
     Any possible name of an object is supported with the index syntax,
     but it can be more verbose.
@@ -460,7 +464,16 @@ class HierarchyObject(_HierarchyObjectBase[str]):
         if name.startswith("_"):
             return object.__setattr__(self, name, value)
 
-        raise AttributeError(f"{self._name} contains no object named {name}")
+        try:
+            getattr(self, name)
+        except AttributeError:
+            raise AttributeError(
+                f"Cannot set attribute {name!r} on simulation object {self._path}. No such object exists."
+            ) from None
+        else:
+            raise AttributeError(
+                f"Cannot set attribute {name!r} on simulation object {self._path}. Did you forget to add `.value`?"
+            )
 
     def __getattr__(self, name: str) -> SimHandleBase:
         if name.startswith("_"):
@@ -524,7 +537,9 @@ class HierarchyObject(_HierarchyObjectBase[str]):
         return self._handle.get_handle_by_name(key, discovery_method)
 
 
-class HierarchyArrayObject(_HierarchyObjectBase[int], _RangeableObjectMixin):
+class HierarchyArrayObject(
+    _HierarchyObjectBase[int], _RangeableObjectMixin, Generic[HierarchyChildObjectT]
+):
     """A simulation object that is an array of hierarchical simulation objects.
 
     Inherits from :class:`SimHandleBase`.
@@ -597,35 +612,36 @@ class HierarchyArrayObject(_HierarchyObjectBase[int], _RangeableObjectMixin):
             )
         return self._handle.get_handle_by_index(key)
 
-    def __getitem__(self, key: int) -> SimHandleBase:
+    def __getitem__(self, key: int) -> HierarchyChildObjectT:
         if isinstance(key, slice):
             raise TypeError("Slice indexing is not supported")
 
         handle = self._get(key)
         if handle is None:
             raise IndexError(f"{self._path} contains no child object at index {key}")
-        return handle
+        return cast("HierarchyChildObjectT", handle)
 
     # ideally `__len__` could be implemented in terms of `range`, but `range` doesn't work universally.
 
-    def __iter__(self) -> Iterator[SimHandleBase]:
+    def __iter__(self) -> Iterator[HierarchyChildObjectT]:
         # must use `sorted(self._keys())` instead of the range because `range` doesn't work universally.
         for i in sorted(self._keys()):
             yield self[i]
 
 
-class _GPISetAction(enum.IntEnum):
+class _GPISetAction(enum.Enum):
     DEPOSIT = 0
     FORCE = 1
     RELEASE = 2
     NO_DELAY = 3
+    OLD_IMMEDIATE = 0
 
 
 _ValueT = TypeVar("_ValueT")
 
 
 class Deposit(Generic[_ValueT]):
-    r""":term:`Inertially deposits <inertial deposit>` the given value on a simulator object.
+    r""":term:`Inertially deposit <inertial deposit>` the given value on a simulator object.
 
     If another :term:`deposit` comes after this deposit, the newer deposit overwrites the old value.
     If an HDL process is :term:`driving` the signal/net/register where a deposit from cocotb is made,
@@ -655,12 +671,12 @@ class Force(Generic[_ValueT]):
         while ``variable`` writes are set immediately, regardless of using this class.
 
     .. note::
-        Verilog Forces are always immediate.
+        Verilog :class:`!Force`\ s are always immediate.
         This also means that if there are multiple cocotb Tasks or multiple ``always`` blocks writing to the same object,
         the resulting value is non-deterministic.
 
     .. note::
-        Issuing a Force and Release in the same evaluation cycle in VHDL will result in the Force "winning".
+        Issuing a :class:`!Force` and :class:`Release` in the same evaluation cycle in VHDL will result in the :class:`!Force` "winning".
     """
 
     def __init__(self, value: _ValueT) -> None:
@@ -680,17 +696,17 @@ class Freeze:
         while ``variable`` writes are set immediately, regardless of using this class.
 
     .. note::
-        Verilog Forces are always immediate.
+        Verilog :class:`Force`\ s are always immediate.
         This also means that if there are multiple cocotb Tasks or multiple ``always`` blocks writing to the same object,
         the resulting value is non-deterministic.
 
     .. note::
-        Issuing a Force and Release in the same evaluation cycle in VHDL will result in the Force "winning".
+        Issuing a :class:`!Force` and :class:`Release` in the same evaluation cycle in VHDL will result in the :class:`!Force` "winning".
     """
 
 
 class Release:
-    """:term:`Release <release>` a :term:`forced <force>` simulation object.
+    r""":term:`Release <release>` a :term:`forced <force>` simulation object.
 
     Does not change the current value of the simulation object.
     See :class:`Deposit` for information on behavior after this write completes.
@@ -701,18 +717,18 @@ class Release:
         while ``variable`` writes are set immediately, regardless of using this class.
 
     .. note::
-        Verilog Releases are always immediate.
+        Verilog :class:`!Release`\ s are always immediate.
         This also means that if there are multiple cocotb Tasks or multiple ``always`` blocks writing to the same object,
         the resulting value is non-deterministic.
 
     .. note::
-        Issuing a Force and Release in the same evaluation cycle in VHDL will result in the Force "winning".
+        Issuing a :class:`Force` and :class:`!Release` in the same evaluation cycle in VHDL will result in the :class:`!Force` "winning".
 
     .. note::
-        Releasing a ``reg`` or `logic` in Verilog will leave the current value.
+        Releasing a ``reg`` or ``logic`` in Verilog will leave the current value.
         Releasing a ``wire`` in Verilog will cause the value to be recomputed from the wire's drivers current values.
         Releasing a ``signal`` in VHDL will cause the value to be recomputed from the signal's drivers current value.
-        Unconnected ``in`` ports and unconnected internal signals have no drivers and their value after Release will be ``U`` in VHDL and ``X`` in Verilog.
+        Unconnected ``in`` ports and unconnected internal signals have no drivers and their value after :class:`!Release` will be ``U`` in VHDL and ``X`` in Verilog.
     """
 
 
@@ -738,6 +754,11 @@ class Immediate(Generic[_ValueT]):
         self.value = value
 
 
+class _OldImmediate(Generic[_ValueT]):
+    def __init__(self, value: _ValueT) -> None:
+        self.value = value
+
+
 _trust_inertial = bool(int(os.environ.get("COCOTB_TRUST_INERTIAL_WRITES", "0")))
 
 # A dictionary of pending (write_func, args), keyed by handle.
@@ -801,7 +822,7 @@ else:
         if isinstance(current_gpi_trigger(), ReadWrite):
             # If we are already in the ReadWrite phase, apply writes immediately as an optimization.
             write_func(action.value, value)
-        elif action == _GPISetAction.DEPOSIT:
+        elif action is _GPISetAction.DEPOSIT:
             # Queue write for the beginning of the next ReadWrite phase because we can't trust the simulator. =(
             if handle in _write_calls:
                 del _write_calls[handle]
@@ -876,7 +897,6 @@ class ValueObjectBase(SimHandleBase, Generic[ValueGetT, ValueSetT]):
 
         Args:
             value: The value to set the simulation object to. This may include type conversion.
-            action: How to set the value. See :class:`Action` for more details.
 
         Raises:
             TypeError: If the *value* is of a type that cannot be converted to a simulation value,
@@ -899,6 +919,8 @@ class ValueObjectBase(SimHandleBase, Generic[ValueGetT, ValueSetT]):
             self._set_value(cast("ValueSetT", self.get()), _GPISetAction.RELEASE)
         elif isinstance(value, Immediate):
             self._set_value(value.value, _GPISetAction.NO_DELAY)
+        elif isinstance(value, _OldImmediate):
+            self._set_value(value.value, _GPISetAction.OLD_IMMEDIATE)
         else:
             self._set_value(value, _GPISetAction.DEPOSIT)
 
@@ -924,12 +946,13 @@ class ValueObjectBase(SimHandleBase, Generic[ValueGetT, ValueSetT]):
         Passing :class:`Deposit`\ s and unwrapped values is equivalent to passing an :class:`Immediate` to :meth:`set`.
 
         .. deprecated:: 2.0
-            "Use `handle.set(Immediate(...))` or `handle.value = Immediate(...)` instead.
+            Use ``handle.set(Immediate(...))`` or ``handle.value = Immediate(...)`` instead.
+            This could result in a change in behavior because prior to version 2.0 this function did not set values immediately.
         """
         if isinstance(value, Deposit):
-            value = Immediate(value.value)
+            value = _OldImmediate(value.value)  # type: ignore
         elif not isinstance(value, (Force, Freeze, Release, Immediate)):
-            value = Immediate(value)
+            value = _OldImmediate(value)  # type: ignore
         self.set(value)
 
     @cached_property
@@ -1013,7 +1036,12 @@ class ArrayObject(
         | ``arr[7:4]`` | ``arr(7 downto 4)`` | ``Array([arr[7].value, arr[6].value, arr[5].value, arr[4].value], range=Range(7, 'downto', 4))`` |
         +--------------+---------------------+--------------------------------------------------------------------------------------------------+
         """
-        return Array._from_handle([self[i].value for i in self.range], self.range)
+        r = self.range
+        return Array._from_handle(
+            value=[self[i].value for i in r],
+            range=r,
+            warn_indexing=indexing_changed(r) if do_indexing_changed_warning else False,
+        )
 
     def set(
         self,
@@ -1043,9 +1071,9 @@ class ArrayObject(
         Raises:
             TypeError: If *value* is of a type that can't be assigned to the simulation object.
 
-            .. warning::
-                Exceptions from array element :meth:`.ValueObjectBase.set` calls will be propagated up,
-                so the actual set of exceptions possible is greater than this list.
+        .. warning::
+            Exceptions from array element :meth:`.ValueObjectBase.set` calls will be propagated up,
+            so the actual set of exceptions possible is greater than this list.
         """
         super().set(value)
 
@@ -1187,9 +1215,6 @@ class LogicObject(_NonIndexableValueObjectBase[Logic, Union[Logic, int, str]]):
             raise TypeError("Can't get FallingEdge on immutable signal")
         return FallingEdge._make(self)
 
-    @deprecated(
-        '`len(logic_scalar_handle)` has been deprecated. A scalar handle\'s "length" is always 1.'
-    )
     def __len__(self) -> int:
         return 1
 
@@ -1295,7 +1320,12 @@ class LogicArrayObject(
     def get(self) -> LogicArray:
         """Return the current value of the simulation object as a :class:`.LogicArray`."""
         binstr = self._handle.get_signal_val_binstr()
-        return LogicArray._from_handle(binstr)
+        return LogicArray._from_handle(
+            value=binstr,
+            warn_indexing=indexing_changed(self.range)
+            if do_indexing_changed_warning
+            else False,
+        )
 
     def set(
         self,
@@ -1657,7 +1687,7 @@ class StringObject(
 
 _ConcreteHandleTypes = Union[
     HierarchyObject,
-    HierarchyArrayObject,
+    HierarchyArrayObject[SimHandleBase],
     LogicObject,
     LogicArrayObject,
     ArrayObject[Any, ValueObjectBase[Any, Any]],
@@ -1684,7 +1714,7 @@ _type2cls: Dict[int, Type[_ConcreteHandleTypes]] = {
     simulator.INTEGER: IntegerObject,
     simulator.ENUM: EnumObject,
     simulator.STRING: StringObject,
-    simulator.GENARRAY: HierarchyArrayObject,
+    simulator.GENARRAY: HierarchyArrayObject[SimHandleBase],
     simulator.PACKAGE: HierarchyObject,
 }