cocotb 1.9.2__cp313-cp313-win32.whl → 2.0.0rc2__cp313-cp313-win32.whl

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"]

cocotb/_utils.py

@@ -0,0 +1,274 @@
+# Copyright cocotb contributors
+# Copyright (c) 2013 Potential Ventures Ltd
+# Copyright (c) 2013 SolarFlare Communications Inc
+# Licensed under the Revised BSD License, see LICENSE for details.
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Utilities for implementors."""
+
+import traceback
+import types
+from enum import Enum, IntEnum
+from functools import update_wrapper, wraps
+from types import TracebackType
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Iterable,
+    List,
+    Optional,
+    Tuple,
+    Type,
+    TypeVar,
+    Union,
+    cast,
+    overload,
+)
+
+ExceptionTuple = Tuple[
+    Type[BaseException], BaseException, TracebackType
+]  # TypeAlias in Python 3.10
+
+
+@overload
+def remove_traceback_frames(
+    tb_or_exc: ExceptionTuple, frame_names: List[str]
+) -> ExceptionTuple: ...
+
+
+@overload
+def remove_traceback_frames(
+    tb_or_exc: BaseException, frame_names: List[str]
+) -> BaseException: ...
+
+
+@overload
+def remove_traceback_frames(
+    tb_or_exc: TracebackType, frame_names: List[str]
+) -> TracebackType: ...
+
+
+def remove_traceback_frames(
+    tb_or_exc: Union[ExceptionTuple, BaseException, TracebackType],
+    frame_names: List[str],
+) -> Union[ExceptionTuple, BaseException, TracebackType]:
+    """
+    Strip leading frames from a traceback
+
+    Args:
+        tb_or_exc:
+            Object to strip frames from. If an exception is passed, creates
+            a copy of the exception with a new shorter traceback. If a tuple
+            from `sys.exc_info` is passed, returns the same tuple with the
+            traceback shortened
+        frame_names:
+            Names of the frames to strip, which must be present at the top of the Traceback or Exception.
+
+    Returns:
+        Traceback or Exception passed to the function with the *frame_names* stripped out.
+    """
+    # self-invoking overloads
+    if isinstance(tb_or_exc, BaseException):
+        exc: BaseException = tb_or_exc
+        return exc.with_traceback(
+            remove_traceback_frames(
+                cast("TracebackType", exc.__traceback__), frame_names
+            )
+        )
+    elif isinstance(tb_or_exc, tuple):
+        exc_type, exc_value, exc_tb = tb_or_exc
+        exc_tb = remove_traceback_frames(exc_tb, frame_names)
+        return exc_type, exc_value, exc_tb
+    # base case
+    else:
+        tb: TracebackType = tb_or_exc
+        for frame_name in frame_names:
+            # the assert and cast are there assuming the frame_names being removed are correct
+            assert tb.tb_frame.f_code.co_name == frame_name
+            tb = cast("TracebackType", tb.tb_next)
+        return tb
+
+
+def walk_coro_stack(
+    coro: "types.CoroutineType[Any, Any, Any]",
+) -> Iterable[Tuple[types.FrameType, int]]:
+    """Walk down the coroutine stack, starting at *coro*.
+
+    Args:
+        coro: The :class:`coroutine` object to traverse.
+
+    Yields:
+        Frame and line number of each frame in the coroutine.
+    """
+    c: Optional[types.CoroutineType[Any, Any, Any]] = coro
+    while c is not None:
+        try:
+            f = c.cr_frame
+        except AttributeError:
+            break
+        else:
+            c = c.cr_await
+        if f is not None:
+            yield (f, f.f_lineno)
+
+
+def extract_coro_stack(
+    coro: "types.CoroutineType[Any, Any, Any]", limit: Optional[int] = None
+) -> traceback.StackSummary:
+    r"""Create a list of pre-processed entries from the coroutine stack.
+
+    This is based on :func:`traceback.extract_tb`.
+
+    If *limit* is omitted or ``None``, all entries are extracted.
+    The list is a :class:`traceback.StackSummary` object, and
+    each entry in the list is a :class:`traceback.FrameSummary` object
+    containing attributes ``filename``, ``lineno``, ``name``, and ``line``
+    representing the information that is usually printed for a stack
+    trace. The line is a string with leading and trailing
+    whitespace stripped; if the source is not available it is ``None``.
+
+    Args:
+        coro: The :class:`coroutine` object from which to extract a stack.
+        level: The maximum number of frames from *coro*\ s stack to extract.
+
+    Returns:
+        The stack of *coro*.
+    """
+    return traceback.StackSummary.extract(walk_coro_stack(coro), limit=limit)
+
+
+EnumT = TypeVar("EnumT", bound=Enum)
+
+
+class DocEnum(Enum):
+    """Like :class:`enum.Enum`, but allows documenting enum values.
+
+    Documentation for enum members can be optionally added by setting enum values to a tuple of the intended value and the docstring.
+    This adds the provided docstring to the ``__doc__`` field of the enum value.
+
+    .. code-block:: python
+
+        class MyEnum(DocEnum):
+            \"\"\"Class documentation\"\"\"
+
+            VALUE1 = 1, "Value documentation"
+            VALUE2 = 2  # no documentation
+
+    Taken from :ref:`this StackOverflow answer <https://stackoverflow.com/questions/50473951/how-can-i-attach-documentation-to-members-of-a-python-enum/50473952#50473952>`
+    by :ref:`Eric Wieser <https://stackoverflow.com/users/102441/eric>`,
+    as recommended by the ``enum_tools`` documentation.
+    """
+
+    def __new__(cls: Type[EnumT], value: object, doc: Optional[str] = None) -> EnumT:
+        # super().__new__() assumes the value is already an enum value
+        # so we side step that and create a raw object and fill in _value_
+        self = object.__new__(cls)
+        self._value_ = value
+        if doc is not None:
+            self.__doc__ = doc
+        return self
+
+
+IntEnumT = TypeVar("IntEnumT", bound=IntEnum)
+
+
+class DocIntEnum(IntEnum):
+    """Like DocEnum but for :class:`IntEnum` enum types."""
+
+    def __new__(cls: Type[IntEnumT], value: int, doc: Optional[str] = None) -> IntEnumT:
+        self = int.__new__(cls, value)
+        self._value_ = value
+        if doc is not None:
+            self.__doc__ = doc
+        return self
+
+
+if TYPE_CHECKING:
+    F = TypeVar("F")
+
+    def cached_method(f: F) -> F: ...
+
+else:
+
+    class cached_method:
+        def __init__(self, method):
+            self._method = method
+            update_wrapper(self, method)
+
+        def __get__(self, instance, objtype=None):
+            if instance is None:
+                return self
+
+            cache = {}
+
+            @wraps(self._method)
+            def lookup(*args, **kwargs):
+                key = (args, tuple(kwargs.items()))
+                try:
+                    return cache[key]
+                except KeyError:
+                    res = self._method(instance, *args, **kwargs)
+                    cache[key] = res
+                    return res
+
+            lookup.cache = cache
+
+            setattr(instance, self._method.__name__, lookup)
+            return lookup
+
+        def __call__(self, instance, *args, **kwargs):
+            func = getattr(instance, self._method.__name__)
+            return func(*args, **kwargs)
+
+
+T = TypeVar("T")
+
+
+if TYPE_CHECKING:
+
+    def singleton(orig_cls: T) -> T: ...
+
+else:
+
+    def singleton(orig_cls):
+        """Class decorator which turns a type into a Singleton type."""
+        orig_new = orig_cls.__new__
+        orig_init = orig_cls.__init__
+        instance = None
+
+        @wraps(orig_cls.__new__)
+        def __new__(cls, *args, **kwargs):
+            nonlocal instance
+            if instance is None:
+                instance = orig_new(cls, *args, **kwargs)
+                orig_init(instance, *args, **kwargs)
+            return instance
+
+        @wraps(orig_cls.__init__)
+        def __init__(self, *args, **kwargs):
+            pass
+
+        orig_cls.__new__ = __new__
+        orig_cls.__init__ = __init__
+        return orig_cls
+
+
+def pointer_str(obj: object) -> str:
+    """Get the memory address of *obj* as used in :meth:`object.__repr__`.
+
+    This is equivalent to ``sprintf("%p", id(obj))``, but Python does not
+    support ``%p``.
+    """
+    full_repr = object.__repr__(obj)  # gives "<{type} object at {address}>"
+    return full_repr.rsplit(" ", 1)[1][:-1]
+
+
+def safe_divide(a: float, b: float) -> float:
+    """Used when computing time ratios to ensure no exception is raised if either time is 0."""
+    try:
+        return a / b
+    except ZeroDivisionError:
+        if a == 0:
+            return float("nan")
+        else:
+            return float("inf")

cocotb/_version.py

@@ -1,8 +1,4 @@
-# Package versioning solution originally found here:
-# http://stackoverflow.com/q/458550
+# Package version
+# Generated by setup.py -- do not modify directly
 
-# Store the version here so:
-# 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.9.2"
+__version__ = "2.0.0rc2"