cocotb 1.7.2__cp39-cp39-win_amd64.whl → 1.8.0rc1__cp39-cp39-win_amd64.whl

cocotb/__init__.py

@@ -45,12 +45,12 @@ from cocotb._deprecation import deprecated
 from cocotb.log import default_config
 from cocotb.regression import RegressionManager
 from cocotb.scheduler import Scheduler
+from cocotb.task import Task
 
 from ._version import __version__
 
 # Things we want in the cocotb namespace
 from cocotb.decorators import (  # isort: skip # noqa: F401
-    Task,
     coroutine,
     external,
     function,
@@ -322,26 +322,15 @@ def _initialise_testbench_(argv_):
     regression_manager._execute()
 
 
-def _sim_event(level, message):
+def _sim_event(message):
     """Function that can be called externally to signal an event."""
-    # SIM_INFO = 0
-    SIM_TEST_FAIL = 1
-    SIM_FAIL = 2
     from cocotb.result import SimFailure
 
-    if level is SIM_TEST_FAIL:
-        scheduler.log.error("Failing test at simulator request")
-        scheduler._finish_test(
-            AssertionError(f"Failure from external source: {message}")
-        )
-    elif level is SIM_FAIL:
-        # We simply return here as the simulator will exit
-        # so no cleanup is needed
-        msg = f"Failing test at simulator request before test run completion: {message}"
-        scheduler.log.error(msg)
-        scheduler._finish_scheduler(SimFailure(msg))
-    else:
-        scheduler.log.error("Unsupported sim event")
+    # We simply return here as the simulator will exit
+    # so no cleanup is needed
+    msg = f"Failing test at simulator request before test run completion: {message}"
+    scheduler.log.error(msg)
+    scheduler._finish_scheduler(SimFailure(msg))
 
 
 @deprecated("This function is now private")

cocotb/_sim_versions.py

@@ -68,9 +68,24 @@ class QuestaVersion(LooseVersion):
         True
         >>> QuestaVersion("2020.1 2020.01") > QuestaVersion("10.7c 2018.08")
         True
+        >>> QuestaVersion("2020.1 2020.01") == QuestaVersion("2020.1")
+        True
+        >>> QuestaVersion("2023.1_2 2023.03") > QuestaVersion("2023.1_1")
+        True
     """
 
-    pass
+    def parse(self, vstring):
+        # A Questa version string, as returned by the simulator, consists of two
+        # space-separated parts. The first part is the actual version number,
+        # the second part seems to be the year and month of the initial release.
+        # We only need the first part, which is also used in public
+        # communication by Siemens.
+        try:
+            first_component = vstring.split(" ", 1)[0]
+        except IndexError:
+            first_component = vstring
+
+        super().parse(first_component)
 
 
 class RivieraVersion(LooseVersion):

cocotb/_version.py

@@ -5,4 +5,4 @@
 # 1) we don't load dependencies by storing it in __init__.py
 # 2) we can import it in setup.py for the same reason
 # 3) we can import it into your module
-__version__ = "1.7.2"
+__version__ = "1.8.0rc1"

cocotb/clock.py

@@ -29,6 +29,9 @@
 
 import itertools
 import warnings
+from decimal import Decimal
+from numbers import Real
+from typing import Union
 
 from cocotb.log import SimLog
 from cocotb.triggers import Timer
@@ -114,7 +117,9 @@ class Clock(BaseClock):
         Using ``None`` as the *units* argument is deprecated, use ``'step'`` instead.
     """
 
-    def __init__(self, signal, period, units="step"):
+    def __init__(
+        self, signal, period: Union[float, Real, Decimal], units: str = "step"
+    ):
         BaseClock.__init__(self, signal)
         if units is None:
             warnings.warn(
@@ -124,8 +129,8 @@ class Clock(BaseClock):
             )
             units = "step"  # don't propagate deprecated value
         self.period = get_sim_steps(period, units)
-        self.half_period = get_sim_steps(period / 2.0, units)
-        self.frequency = 1.0 / get_time_from_sim_steps(self.period, units="us")
+        self.half_period = get_sim_steps(period / 2, units)
+        self.frequency = 1 / get_time_from_sim_steps(self.period, units="us")
         self.hdl = None
         self.signal = signal
         self.coro = None

cocotb/decorators.py

@@ -25,31 +25,17 @@
 # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 # SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
-import collections.abc
 import functools
-import inspect
-import os
 import sys
 import typing
 import warnings
-from asyncio import CancelledError, InvalidStateError
 
 import cocotb
 import cocotb.triggers
-from cocotb import outcomes
 from cocotb.log import SimLog
-from cocotb.result import ReturnValue
-from cocotb.utils import extract_coro_stack, lazy_property, remove_traceback_frames
-
-T = typing.TypeVar("T")
-Self = typing.TypeVar("Self")
-
-# Sadly the Python standard logging module is very slow so it's better not to
-# make any calls by testing a boolean flag first
-if "COCOTB_SCHEDULER_DEBUG" in os.environ:
-    _debug = True
-else:
-    _debug = False
+from cocotb.task import Task as _Task  # noqa: F401
+from cocotb.task import _RunningCoroutine, _RunningTest
+from cocotb.utils import lazy_property
 
 
 def public(f):
@@ -69,308 +55,12 @@ def public(f):
 public(public)  # Emulate decorating ourself
 
 
-class Task(typing.Coroutine[typing.Any, typing.Any, T]):
-    """Concurrently executing task.
-
-    This class is not intended for users to directly instantiate.
-    Use :func:`cocotb.create_task` to create a Task object,
-    or use :func:`cocotb.start_soon` or :func:`cocotb.start` to
-    create a Task and schedule it to run.
-    """
-
-    _name: str = "Task"  # class name of schedulable task
-    _id_count = 0  # used by the scheduler for debug
-
-    def __init__(self, inst):
-
-        if isinstance(inst, collections.abc.Coroutine):
-            self._natively_awaitable = True
-        elif inspect.isgenerator(inst):
-            self._natively_awaitable = False
-        elif inspect.iscoroutinefunction(inst):
-            raise TypeError(
-                "Coroutine function {} should be called prior to being "
-                "scheduled.".format(inst)
-            )
-        elif inspect.isasyncgen(inst):
-            raise TypeError(
-                "{} is an async generator, not a coroutine. "
-                "You likely used the yield keyword instead of await.".format(
-                    inst.__qualname__
-                )
-            )
-        else:
-            raise TypeError(
-                f"{inst} isn't a valid coroutine! Did you forget to use the yield keyword?"
-            )
-        self._coro = inst
-        self._started = False
-        self._outcome: outcomes.Outcome = None
-        self._trigger: typing.Optional[cocotb.triggers.Trigger] = None
-        self._cancelled: typing.Optional[CancelledError] = None
-
-        self._task_id = self._id_count
-        type(self)._id_count += 1
-        self.__name__ = f"{type(self)._name} {self._task_id}"
-        self.__qualname__ = self.__name__
-
-    @lazy_property
-    def log(self) -> SimLog:
-        # Creating a logger is expensive, only do it if we actually plan to
-        # log anything
-        return SimLog(f"cocotb.{self.__qualname__}.{self._coro.__qualname__}")
-
-    @property
-    def retval(self) -> T:
-        """Return the result of the Task.
-
-        If the Task ran to completion, the result is returned.
-        If the Task failed with an exception, the exception is re-raised.
-        If the Task is not yet complete, a :exc:`RuntimeError` is raised.
-
-        .. deprecated:: 1.7.0
-        """
-        warnings.warn(
-            "Deprecated in favor of the result() method. "
-            "Replace `task.retval` with `task.result()`.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        if self._outcome is None:
-            raise RuntimeError("coroutine is not complete")
-        return self._outcome.get()
-
-    @property
-    def _finished(self) -> bool:
-        """``True`` if the Task is finished executing.
-
-        .. deprecated:: 1.7.0
-        """
-        warnings.warn(
-            "Deprecated in favor of the done() method. "
-            "Replace `task._finished` with `task.done()`.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        return self._outcome is not None
-
-    def __iter__(self: Self) -> Self:
-        # for use in "yield from" statements
-        return self
-
-    def __str__(self) -> str:
-        return f"<{self.__name__}>"
-
-    def _get_coro_stack(self) -> typing.Any:
-        """Get the coroutine callstack of this Task."""
-        coro_stack = extract_coro_stack(self._coro)
-
-        # Remove Trigger.__await__() from the stack, as it's not really useful
-        if self._natively_awaitable and len(coro_stack):
-            if coro_stack[-1].name == "__await__":
-                coro_stack.pop()
-
-        return coro_stack
-
-    def __repr__(self) -> str:
-        coro_stack = self._get_coro_stack()
-
-        if cocotb.scheduler._current_task is self:
-            fmt = "<{name} running coro={coro}()>"
-        elif self.done():
-            fmt = "<{name} finished coro={coro}() outcome={outcome}>"
-        elif self._trigger is not None:
-            fmt = "<{name} pending coro={coro}() trigger={trigger}>"
-        elif not self._started:
-            fmt = "<{name} created coro={coro}()>"
-        else:
-            fmt = "<{name} adding coro={coro}()>"
-
-        try:
-            coro_name = coro_stack[-1].name
-        # coro_stack may be empty if:
-        # - exhausted generator
-        # - finished coroutine
-        except IndexError:
-            coro_name = self._coro.__name__
-
-        repr_string = fmt.format(
-            name=self.__name__,
-            coro=coro_name,
-            trigger=self._trigger,
-            outcome=self._outcome,
-        )
-        return repr_string
-
-    def _advance(self, outcome: outcomes.Outcome) -> typing.Any:
-        """Advance to the next yield in this coroutine.
-
-        Args:
-            outcome: The :any:`outcomes.Outcome` object to resume with.
-
-        Returns:
-            The object yielded from the coroutine or None if coroutine finished
-
-        """
-        try:
-            self._started = True
-            return outcome.send(self._coro)
-        except ReturnValue as e:
-            self._outcome = outcomes.Value(e.retval)
-        except StopIteration as e:
-            self._outcome = outcomes.Value(e.value)
-        except BaseException as e:
-            self._outcome = outcomes.Error(
-                remove_traceback_frames(e, ["_advance", "send"])
-            )
-
-    def send(self, value: typing.Any) -> typing.Any:
-        return self._coro.send(value)
-
-    def throw(self, exc: BaseException) -> typing.Any:
-        return self._coro.throw(exc)
-
-    def close(self) -> None:
-        return self._coro.close()
-
-    def kill(self) -> None:
-        """Kill a coroutine."""
-        if self._outcome is not None:
-            # already finished, nothing to kill
-            return
-
-        if _debug:
-            self.log.debug("kill() called on coroutine")
-        # todo: probably better to throw an exception for anyone waiting on the coroutine
-        self._outcome = outcomes.Value(None)
-        cocotb.scheduler._unschedule(self)
-
-    def join(self) -> cocotb.triggers.Join:
-        """Return a trigger that will fire when the wrapped coroutine exits."""
-        return cocotb.triggers.Join(self)
-
-    def has_started(self) -> bool:
-        """Return ``True`` if the Task has started executing."""
-        return self._started
-
-    def cancel(self, msg: typing.Optional[str] = None) -> None:
-        """Cancel a Task's further execution.
-
-        When a Task is cancelled, a :exc:`asyncio.CancelledError` is thrown into the Task.
-        """
-        self._cancelled = CancelledError(msg)
-        warnings.warn(
-            "Calling this method will cause a CancelledError to be thrown in the "
-            "Task sometime in the future.",
-            FutureWarning,
-            stacklevel=2,
-        )
-        self.kill()
-
-    def cancelled(self) -> bool:
-        """Return ``True`` if the Task was cancelled."""
-        return self._cancelled is not None
-
-    def done(self) -> bool:
-        """Return ``True`` if the Task has finished executing."""
-        return self._outcome is not None or self.cancelled()
-
-    def result(self) -> T:
-        """Return the result of the Task.
-
-        If the Task ran to completion, the result is returned.
-        If the Task failed with an exception, the exception is re-raised.
-        If the Task was cancelled, the CancelledError is re-raised.
-        If the coroutine is not yet complete, a :exc:`asyncio.InvalidStateError` is raised.
-        """
-        if not self.done():
-            raise InvalidStateError("result is not yet available")
-        elif self.cancelled():
-            raise self._cancelled
-        else:
-            return self._outcome.get()
-
-    def exception(self) -> typing.Optional[BaseException]:
-        """Return the exception of the Task.
-
-        If the Task ran to completion, ``None`` is returned.
-        If the Task failed with an exception, the exception is returned.
-        If the Task was cancelled, the CancelledError is re-raised.
-        If the coroutine is not yet complete, a :exc:`asyncio.InvalidStateError` is raised.
-        """
-        if not self.done():
-            raise InvalidStateError("result is not yet available")
-        elif self.cancelled():
-            raise self._cancelled
-        elif isinstance(self._outcome, outcomes.Error):
-            return self._outcome.error
-        else:
-            return None
-
-    def __bool__(self) -> bool:
-        """``True`` if Task is not done.
-
-        .. deprecated:: 1.7.0
-        """
-        warnings.warn(
-            "Deprecated in favor of the done() method. "
-            "Replace with `not task.done()`.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        return not self.done()
-
-    def __await__(self) -> typing.Generator[typing.Any, typing.Any, T]:
-        # It's tempting to use `return (yield from self._coro)` here,
-        # which bypasses the scheduler. Unfortunately, this means that
-        # we can't keep track of the result or state of the coroutine,
-        # things which we expose in our public API. If you want the
-        # efficiency of bypassing the scheduler, remove the `@coroutine`
-        # decorator from your `async` functions.
-
-        # Hand the coroutine back to the scheduler trampoline.
-        return (yield self)
-
-
-RunningTask = Task
-
-
-class RunningCoroutine(Task[T]):
-    """
-    The result of calling a :any:`cocotb.coroutine` decorated coroutine.
-
-    All this class does is provide some extra attributes.
-    """
-
-    def __init__(self, inst, parent):
-        super().__init__(inst)
-        self._parent = parent
-        self.__doc__ = parent._func.__doc__
-        self.module = parent._func.__module__
-        self.funcname = parent._func.__name__
-
-
-class RunningTest(RunningCoroutine[T]):
-    """
-    The result of calling a :class:`cocotb.test` decorated object.
-
-    All this class does is change ``__name__`` to show "Test" instead of "Task".
-    """
-
-    _name: str = "Test"
-
-    def __init__(self, inst, parent):
-        super().__init__(inst, parent)
-        self.__name__ = f"{type(self)._name} {self.funcname}"
-        self.__qualname__ = self.__name__
-
-
 class coroutine:
     """Decorator class that allows us to provide common coroutine mechanisms:
 
     ``log`` methods will log to ``cocotb.coroutine.name``.
 
-    :meth:`~cocotb.decorators.Task.join` method returns an event which will fire when the coroutine exits.
+    :meth:`~cocotb.task.Task.join` method returns an event which will fire when the coroutine exits.
 
     Used as ``@cocotb.coroutine``.
     """
@@ -384,7 +74,7 @@ class coroutine:
         return SimLog(f"cocotb.coroutine.{self._func.__qualname__}.{id(self)}")
 
     def __call__(self, *args, **kwargs):
-        return RunningCoroutine(self._func(*args, **kwargs), self)
+        return _RunningCoroutine(self._func(*args, **kwargs), self)
 
     def __get__(self, obj, owner=None):
         """Permit the decorator to be used on class methods
@@ -503,7 +193,9 @@ class test(coroutine, metaclass=_decorator_helper):
                 Using ``None`` as the *timeout_unit* argument is deprecated, use ``'step'`` instead.
 
         expect_fail (bool, optional):
-            Don't mark the result as a failure if the test fails.
+            If ``True`` and the test fails a functional check via an ``assert`` statement, :class:`pytest.raises`,
+            :class:`pytest.warns`, or :class:`pytest.deprecated_call` the test is considered to have passed.
+            If ``True`` and the test passes successfully, the test is considered to have failed.
 
         expect_error (exception type or tuple of exception types, optional):
             Mark the result as a pass only if one of the exception types is raised in the test.
@@ -589,7 +281,7 @@ class test(coroutine, metaclass=_decorator_helper):
                 stacklevel=2,
             )
         if expect_error is True:
-            expect_error = (Exception,)
+            expect_error = (BaseException,)
         elif expect_error is False:
             expect_error = ()
         self.expect_error = expect_error
@@ -600,5 +292,35 @@ class test(coroutine, metaclass=_decorator_helper):
 
     def __call__(self, *args, **kwargs):
         inst = self._func(*args, **kwargs)
-        coro = RunningTest(inst, self)
+        coro = _RunningTest(inst, self)
         return coro
+
+
+if sys.version_info < (3, 7):
+    Task = _Task
+    RunningTask = _Task
+    RunningCoroutine = _RunningCoroutine
+    RunningTest = _RunningTest
+else:
+
+    def __getattr__(attr: str) -> typing.Any:
+        if attr in ("Task", "RunningTask"):
+            warnings.warn(
+                f"The class {attr} has been renamed to cocotb.task.Task.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            attr = "_Task"
+        elif attr in ("RunningCoroutine", "RunningTest"):
+            warnings.warn(
+                f"The class {attr} is now private. Update all uses to the parent class cocotb.task.Task.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            attr = f"_{attr}"
+        try:
+            return globals()[attr]
+        except KeyError:
+            raise AttributeError(
+                f"module {__name__!r} has no attribute {attr!r}"
+            ) from None

cocotb/ipython_support.py

@@ -61,7 +61,9 @@ async def embed(user_ns: dict = {}):
     c = load_default_config()
     c.TerminalInteractiveShell.loop_runner = lambda x: _runner(shell, x)
     c.TerminalInteractiveShell.autoawait = True
-
+    # Python3 checks SQLite DB accesses to ensure process ID matches the one that opened the DB and is not propogated
+    # because we launch IPython in a different process, this will cause unnecessary warnings, so disable the PID check
+    c.HistoryAccessor.connection_options = {"check_same_thread": False}
     # create a shell with access to the dut, and cocotb pre-imported
     shell = IPython.terminal.embed.InteractiveShellEmbed(
         user_ns=default_ns,