cocotb 2.0.0rc2__cp310-cp310-macosx_11_0_arm64.whl

cocotb/_test.py

@@ -0,0 +1,248 @@
+# Copyright cocotb contributors
+# Licensed under the Revised BSD License, see LICENSE for details.
+# SPDX-License-Identifier: BSD-3-Clause
+import inspect
+import os
+import pdb
+from typing import (
+    Any,
+    Callable,
+    Coroutine,
+    List,
+    Optional,
+    Union,
+)
+
+import cocotb
+from cocotb._base_triggers import NullTrigger, Trigger
+from cocotb._deprecation import deprecated
+from cocotb._exceptions import InternalError
+from cocotb._outcomes import Error, Outcome, Value
+from cocotb._test_functions import TestSuccess
+from cocotb.task import ResultType, Task
+
+_pdb_on_exception = "COCOTB_PDB_ON_EXCEPTION" in os.environ
+
+
+class RunningTest:
+    """State of the currently executing Test."""
+
+    # TODO
+    # Make the tasks list a TaskManager.
+    # Make shutdown errors and outcome be an ExceptionGroup from that TaskManager.
+    # Replace result() with passing the outcome to the done callback.
+    # Make this and Task the same object which is a Coroutine.
+    # Reimplement the logic in the body of an async function.
+    # Make RunningTest a normal Task that the RegressionManager runs and registers a
+    #  done callback with.
+
+    def __init__(
+        self, test_complete_cb: Callable[[], None], main_task: Task[None]
+    ) -> None:
+        self._test_complete_cb: Callable[[], None] = test_complete_cb
+        self._main_task: Task[None] = main_task
+        self._main_task._add_done_callback(self._test_done_callback)
+
+        self.tasks: List[Task[Any]] = [main_task]
+
+        self._outcome: Union[None, Outcome[None]] = None
+        self._shutdown_errors: list[Outcome[None]] = []
+
+    def _test_done_callback(self, task: Task[None]) -> None:
+        self.tasks.remove(task)
+        # If cancelled, end the Test without additional error. This case would only
+        # occur if a child threw a CancelledError or if the Test was forced to shutdown.
+        if task.cancelled():
+            self.abort(Value(None))
+            return
+        # Handle outcome appropriately and shut down the Test.
+        e = task.exception()
+        if e is None:
+            self.abort(Value(task.result()))
+        elif isinstance(e, TestSuccess):
+            task._log.info("Test stopped early by this task")
+            self.abort(Value(None))
+        else:
+            task._log.warning(e, exc_info=e)
+            self.abort(Error(e))
+
+    def start(self) -> None:
+        cocotb._scheduler_inst._schedule_task_internal(self._main_task)
+        cocotb._scheduler_inst._event_loop()
+
+    def result(self) -> Outcome[None]:
+        if self._outcome is None:  # pragma: no cover
+            raise InternalError("Getting result before test is completed")
+
+        if not isinstance(self._outcome, Error) and self._shutdown_errors:
+            return self._shutdown_errors[0]
+        return self._outcome
+
+    def abort(self, outcome: Outcome[None]) -> None:
+        """Force this test to end early."""
+
+        # If we are shutting down, save any errors
+        if self._outcome is not None:
+            if isinstance(outcome, Error):
+                self._shutdown_errors.append(outcome)
+            return
+
+        # Break into pdb on test end before all Tasks are killed.
+        if _pdb_on_exception and isinstance(outcome, Error):
+            try:
+                pdb.post_mortem(outcome.error.__traceback__)
+            except BaseException:
+                pdb.set_trace()
+
+        # Set outcome and cancel Tasks.
+        self._outcome = outcome
+        for task in self.tasks[:]:
+            task._cancel_now()
+
+        self._test_complete_cb()
+
+    def add_task(self, task: Task[Any]) -> None:
+        self.tasks.append(task)
+        task._add_done_callback(self._task_done_callback)
+
+    def _task_done_callback(self, task: Task[Any]) -> None:
+        self.tasks.remove(task)
+        # if cancelled, do nothing
+        if task.cancelled():
+            return
+        # if there's a Task awaiting this one, don't fail
+        if task.complete in cocotb._scheduler_inst._trigger2tasks:
+            return
+        # if no failure, do nothing
+        e = task.exception()
+        if e is None:
+            return
+        # there was a failure and no one is watching, fail test
+        elif isinstance(e, TestSuccess):
+            task._log.info("Test stopped early by this task")
+            self.abort(Value(None))
+        else:
+            task._log.warning(e, exc_info=e)
+            self.abort(Error(e))
+
+
+def start_soon(
+    coro: Union[Task[ResultType], Coroutine[Trigger, None, ResultType]],
+    *,
+    name: Optional[str] = None,
+) -> Task[ResultType]:
+    """
+    Schedule a :term:`coroutine` to be run concurrently in a :class:`~cocotb.task.Task`.
+
+    Note that this is not an :keyword:`async` function,
+    and the new task will not execute until the calling task yields control.
+
+    Args:
+        coro: A :class:`!Task` or :term:`!coroutine` to be run concurrently.
+        name:
+            The task's name.
+
+            .. versionadded:: 2.0
+
+    Returns:
+        The :class:`~cocotb.task.Task` that is scheduled to be run.
+
+    .. versionadded:: 1.6
+    """
+    task = create_task(coro, name=name)
+    cocotb._scheduler_inst._schedule_task(task)
+    return task
+
+
+@deprecated("Use ``cocotb.start_soon`` instead.")
+async def start(
+    coro: Union[Task[ResultType], Coroutine[Trigger, None, ResultType]],
+    *,
+    name: Optional[str] = None,
+) -> Task[ResultType]:
+    """
+    Schedule a :term:`coroutine` to be run concurrently, then yield control to allow pending tasks to execute.
+
+    The calling task will resume execution before control is returned to the simulator.
+
+    When the calling task resumes, the newly scheduled task may have completed,
+    raised an Exception, or be pending on a :class:`~cocotb.triggers.Trigger`.
+
+    Args:
+        coro: A :class:`!Task` or :term:`!coroutine` to be run concurrently.
+        name:
+            The task's name.
+
+            .. versionadded:: 2.0
+
+    Returns:
+        The :class:`~cocotb.task.Task` that has been scheduled and allowed to execute.
+
+    .. versionadded:: 1.6
+
+    .. deprecated:: 2.0
+        Use :func:`cocotb.start_soon` instead.
+        If you need the scheduled Task to start before continuing the current Task,
+        use an :class:`.Event` to block the current Task until the scheduled Task starts,
+        like so:
+
+        .. code-block:: python
+
+            async def coro(started: Event) -> None:
+                started.set()
+                # Do stuff...
+
+
+            task_started = Event()
+            task = cocotb.start_soon(coro(task_started))
+            await task_started.wait()
+    """
+    task = start_soon(coro, name=name)
+    await NullTrigger()
+    return task
+
+
+def create_task(
+    coro: Union[Task[ResultType], Coroutine[Trigger, None, ResultType]],
+    *,
+    name: Optional[str] = None,
+) -> Task[ResultType]:
+    """
+    Construct a :term:`!coroutine` into a :class:`~cocotb.task.Task` without scheduling the task.
+
+    The task can later be scheduled with :func:`cocotb.start` or :func:`cocotb.start_soon`.
+
+    Args:
+        coro: A :class:`!Task` or a :term:`!coroutine` to be turned into a :class:`!Task`.
+        name:
+            The task's name.
+
+            .. versionadded:: 2.0
+
+    Returns:
+        Either the provided :class:`~cocotb.task.Task` or a new Task wrapping the coroutine.
+
+    .. versionadded:: 1.6
+    """
+    if isinstance(coro, Task):
+        if name is not None:
+            coro.set_name(name)
+        return coro
+    elif isinstance(coro, Coroutine):
+        task = Task[ResultType](coro, name=name)
+        cocotb._regression_manager._running_test.add_task(task)
+        return task
+    elif inspect.iscoroutinefunction(coro):
+        raise TypeError(
+            f"Coroutine function {coro} should be called prior to being scheduled."
+        )
+    elif inspect.isasyncgen(coro):
+        raise TypeError(
+            f"{coro.__qualname__} is an async generator, not a coroutine. "
+            "You likely used the yield keyword instead of await."
+        )
+    else:
+        raise TypeError(
+            f"Attempt to add an object of type {type(coro)} to the scheduler, "
+            f"which isn't a coroutine: {coro!r}\n"
+        )

cocotb/_test_factory.py

@@ -0,0 +1,312 @@
+# Copyright cocotb contributors
+# Licensed under the Revised BSD License, see LICENSE for details.
+# SPDX-License-Identifier: BSD-3-Clause
+
+import functools
+import inspect
+import logging
+import warnings
+from itertools import product
+from typing import (
+    TYPE_CHECKING,
+    Callable,
+    Coroutine,
+    Dict,
+    Optional,
+    Sequence,
+    Tuple,
+    Type,
+    Union,
+    cast,
+    overload,
+)
+
+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.
+
+    Args:
+        test_function: A Callable that returns the test Coroutine.
+            Must take *dut* as the first argument.
+        *args: Remaining arguments are passed directly to the test function.
+            Note that these arguments are not varied. An argument that
+            varies with each test must be a keyword argument to the
+            test function.
+        **kwargs: Remaining keyword arguments are passed directly to the test function.
+            Note that these arguments are not varied. An argument that
+            varies with each test must be a keyword argument to the
+            test function.
+
+    Assuming we have a common test function that will run a test. This test
+    function will take keyword arguments (for example generators for each of
+    the input interfaces) and generate tests that call the supplied function.
+
+    This Factory allows us to generate sets of tests based on the different
+    permutations of the possible arguments to the test function.
+
+    For example, if we have a module that takes backpressure, has two configurable
+    features where enabling ``feature_b`` requires ``feature_a`` to be active, and
+    need to test against data generation routines ``gen_a`` and ``gen_b``:
+
+    >>> tf = TestFactory(test_function=run_test)
+    >>> tf.add_option(name="data_in", optionlist=[gen_a, gen_b])
+    >>> tf.add_option("backpressure", [None, random_backpressure])
+    >>> tf.add_option(
+    ...     ("feature_a", "feature_b"), [(False, False), (True, False), (True, True)]
+    ... )
+    >>> tf.generate_tests()
+
+    We would get the following tests:
+
+        * ``gen_a`` with no backpressure and both features disabled
+        * ``gen_a`` with no backpressure and only ``feature_a`` enabled
+        * ``gen_a`` with no backpressure and both features enabled
+        * ``gen_a`` with ``random_backpressure`` and both features disabled
+        * ``gen_a`` with ``random_backpressure`` and only ``feature_a`` enabled
+        * ``gen_a`` with ``random_backpressure`` and both features enabled
+        * ``gen_b`` with no backpressure and both features disabled
+        * ``gen_b`` with no backpressure and only ``feature_a`` enabled
+        * ``gen_b`` with no backpressure and both features enabled
+        * ``gen_b`` with ``random_backpressure`` and both features disabled
+        * ``gen_b`` with ``random_backpressure`` and only ``feature_a`` enabled
+        * ``gen_b`` with ``random_backpressure`` and both features enabled
+
+    The tests are appended to the calling module for auto-discovery.
+
+    Tests are simply named ``test_function_N``. The docstring for the test (hence
+    the test description) includes the name and description of each generator.
+
+    .. versionchanged:: 1.5
+        Groups of options are now supported
+
+    .. versionchanged:: 2.0
+        You can now pass :func:`cocotb.test` decorator arguments when generating tests.
+
+    .. deprecated:: 2.0
+        Use :func:`cocotb.parametrize` instead.
+    """
+
+    def __init__(
+        self,
+        test_function: Callable[..., Coroutine[Trigger, None, None]],
+        *args: object,
+        **kwargs: object,
+    ) -> None:
+        warnings.warn(
+            "TestFactory is deprecated, use `@cocotb.parametrize` instead",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        self.test_function = test_function
+        self.args = args
+        self.kwargs_constant = kwargs
+        self.kwargs: Dict[
+            Union[str, Sequence[str]],
+            Union[Sequence[object], Sequence[Sequence[object]]],
+        ] = {}
+        self._log = logging.getLogger(f"TestFactory({self.test_function.__name__})")
+
+    @overload
+    def add_option(self, name: str, optionlist: Sequence[object]) -> None: ...
+
+    @overload
+    def add_option(
+        self, name: Sequence[str], optionlist: Sequence[Sequence[object]]
+    ) -> None: ...
+
+    def add_option(
+        self,
+        name: Union[str, Sequence[str]],
+        optionlist: Union[Sequence[object], Sequence[Sequence[object]]],
+    ) -> None:
+        """Add a named option to the test.
+
+        Args:
+            name:
+                An option name, or an iterable of several option names. Passed to test as keyword arguments.
+
+            optionlist:
+                A list of possible options for this test knob.
+                If N names were specified, this must be a list of N-tuples or
+                lists, where each element specifies a value for its respective
+                option.
+
+        .. versionchanged:: 1.5
+            Groups of options are now supported
+        """
+        if not isinstance(name, str):
+            optionlist = cast("Sequence[Sequence[object]]", optionlist)
+            for opt in optionlist:
+                if len(name) != len(opt):
+                    raise ValueError(
+                        "Mismatch between number of options and number of option values in group"
+                    )
+        self.kwargs[name] = optionlist
+
+    def generate_tests(
+        self,
+        *,
+        prefix: Optional[str] = None,
+        postfix: Optional[str] = None,
+        stacklevel: int = 0,
+        name: Optional[str] = None,
+        timeout_time: Optional[float] = None,
+        timeout_unit: TimeUnit = "step",
+        expect_fail: bool = False,
+        expect_error: Union[Type[BaseException], Tuple[Type[BaseException], ...]] = (),
+        skip: bool = False,
+        stage: int = 0,
+    ) -> None:
+        """
+        Generate an exhaustive set of tests using the cartesian product of the
+        possible keyword arguments.
+
+        The generated tests are appended to the namespace of the calling
+        module.
+
+        Args:
+            prefix:
+                Text string to append to start of ``test_function`` name when naming generated test cases.
+                This allows reuse of a single ``test_function`` with multiple :class:`TestFactories <.TestFactory>` without name clashes.
+
+                .. deprecated:: 2.0
+                    Use the more flexible ``name`` field instead.
+
+            postfix:
+                Text string to append to end of ``test_function`` name when naming generated test cases.
+                This allows reuse of a single ``test_function`` with multiple :class:`TestFactories <.TestFactory>` without name clashes.
+
+                .. deprecated:: 2.0
+                    Use the more flexible ``name`` field instead.
+            stacklevel:
+                Which stack level to add the generated tests to. This can be used to make a custom TestFactory wrapper.
+
+            name:
+                Passed as ``name`` argument to :func:`cocotb.test`.
+
+                .. versionadded:: 2.0
+
+            timeout_time:
+                Passed as ``timeout_time`` argument to :func:`cocotb.test`.
+
+                .. versionadded:: 2.0
+
+            timeout_unit:
+                Passed as ``timeout_unit`` argument to :func:`cocotb.test`.
+
+                .. versionadded:: 2.0
+
+            expect_fail:
+                Passed as ``expect_fail`` argument to :func:`cocotb.test`.
+
+                .. versionadded:: 2.0
+
+            expect_error:
+                Passed as ``expect_error`` argument to :func:`cocotb.test`.
+
+                .. versionadded:: 2.0
+
+            skip:
+                Passed as ``skip`` argument to :func:`cocotb.test`.
+
+                .. versionadded:: 2.0
+
+            stage:
+                Passed as ``stage`` argument to :func:`cocotb.test`.
+
+                .. versionadded:: 2.0
+        """
+
+        if prefix is not None:
+            warnings.warn(
+                "``prefix`` argument is deprecated. Use the more flexible ``name`` field instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        else:
+            prefix = ""
+
+        if postfix is not None:
+            warnings.warn(
+                "``postfix`` argument is deprecated. Use the more flexible ``name`` field instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        else:
+            postfix = ""
+
+        # trust the user puts a reasonable stacklevel in
+        glbs = cast("FrameType", inspect.stack()[stacklevel][0].f_back).f_globals
+
+        test_func_name = self.test_function.__qualname__ if name is None else name
+
+        for index, testoptions in enumerate(
+            dict(zip(self.kwargs, v)) for v in product(*self.kwargs.values())
+        ):
+            name = f"{prefix}{test_func_name}{postfix}_{(index + 1):03d}"
+            doc: str = "Automatically generated test\n\n"
+
+            # preprocess testoptions to split tuples
+            testoptions_split: Dict[str, Sequence[object]] = {}
+            for optname, optvalue in testoptions.items():
+                if isinstance(optname, str):
+                    optvalue = cast("Sequence[object]", optvalue)
+                    testoptions_split[optname] = optvalue
+                else:
+                    # previously checked in add_option; ensure nothing has changed
+                    optvalue = cast("Sequence[Sequence[object]]", optvalue)
+                    assert len(optname) == len(optvalue)
+                    for n, v in zip(optname, optvalue):
+                        testoptions_split[n] = v
+
+            for optname, optvalue in testoptions_split.items():
+                if callable(optvalue):
+                    optvalue = cast("FunctionType", optvalue)
+                    if optvalue.__doc__ is None:
+                        desc = "No docstring supplied"
+                    else:
+                        desc = optvalue.__doc__.split("\n")[0]
+                    doc += f"\t{optname}: {optvalue.__qualname__} ({desc})\n"
+                else:
+                    doc += f"\t{optname}: {optvalue!r}\n"
+
+            kwargs = self.kwargs_constant.copy()
+            kwargs.update(testoptions_split)
+
+            @functools.wraps(self.test_function)
+            async def _my_test(dut: object, kwargs: Dict[str, object] = kwargs) -> None:
+                await self.test_function(dut, *self.args, **kwargs)
+
+            _my_test.__doc__ = doc
+            _my_test.__name__ = name
+            _my_test.__qualname__ = name
+
+            if name in glbs:
+                self._log.error(
+                    "Overwriting %s in module %s. "
+                    "This causes a previously defined testcase not to be run. "
+                    "Consider using the `name`, `prefix`, or `postfix` arguments to augment the name.",
+                    name,
+                    glbs["__name__"],
+                )
+
+            test = Test(
+                func=_my_test,
+                name=name,
+                module=glbs["__name__"],
+                timeout_time=timeout_time,
+                timeout_unit=timeout_unit,
+                expect_fail=expect_fail,
+                expect_error=expect_error,
+                skip=skip,
+                stage=stage,
+            )
+
+            glbs[test.name] = test

cocotb/_test_functions.py

@@ -0,0 +1,42 @@
+# Copyright cocotb contributors
+# Licensed under the Revised BSD License, see LICENSE for details.
+# SPDX-License-Identifier: BSD-3-Clause
+"""Collection of functions to control a running test and related exceptions."""
+
+from typing import NoReturn, Type, Union
+
+Failed: Type[BaseException]
+try:
+    import pytest
+except ModuleNotFoundError:
+    Failed = AssertionError
+else:
+    try:
+        with pytest.raises(Exception):
+            pass
+    except BaseException as _raises_e:
+        Failed = type(_raises_e)
+    else:
+        assert False, "pytest.raises doesn't raise an exception when it fails"
+
+
+class TestSuccess(BaseException):
+    """Implementation of :func:`pass_test`.
+
+    Users are *not* intended to catch this exception type.
+    """
+
+    def __init__(self, msg: Union[str, None]) -> None:
+        super().__init__(msg)
+        self.msg = msg
+
+
+def pass_test(msg: Union[str, None] = None) -> NoReturn:
+    """Force a test to pass.
+
+    The test will end and enter termination phase when this is called.
+
+    Args:
+        msg: The message to display when the test passes.
+    """
+    raise TestSuccess(msg)

cocotb/_typing.py

@@ -0,0 +1,7 @@
+# Copyright cocotb contributors
+# Licensed under the Revised BSD License, see LICENSE for details.
+# SPDX-License-Identifier: BSD-3-Clause
+from cocotb._py_compat import Literal, TypeAlias
+
+RoundMode: TypeAlias = Literal["error", "round", "ceil", "floor"]
+TimeUnit: TypeAlias = Literal["step", "fs", "ps", "ns", "us", "ms", "sec"]