cocotb 1.9.2__cp311-cp311-win_amd64.whl → 2.0.0rc2__cp311-cp311-win_amd64.whl

cocotb/_ANSI.py

@@ -0,0 +1,65 @@
+# Copyright cocotb contributors
+# Copyright (c) 2013, 2018 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
+
+from cocotb._py_compat import StrEnum
+
+_ESCAPE = "\033["
+
+
+class ANSI(StrEnum):
+    """ANSI escape codes for coloring output.
+
+    The color names supported are ``[BRIGHT_]{BLACK|RED|GREEN|YELLOW|BLUE|MAGENTA|CYAN|WHITE}{_FG|_BG}``.
+
+    Variables that end in ``_FG`` will color the character or symbol ("foreground")
+    and variables that end in ``_BG`` will color the background.
+
+    Foreground and background colors can be combined together with a ``+``.
+    Setting a new foreground color will override the previous foreground, likewise with background colors.
+
+    Use ``DEFAULT_FG`` and ``DEFAULT_BG`` to reset the coloring to the default colors for the foreground and background, respectively.
+    Or use ``DEFAULT`` to reset both.
+    """
+
+    DEFAULT_FG = _ESCAPE + "39m"
+    DEFAULT_BG = _ESCAPE + "49m"
+    DEFAULT = DEFAULT_BG + DEFAULT_FG
+
+    BLACK_FG = _ESCAPE + "30m"
+    RED_FG = _ESCAPE + "31m"
+    GREEN_FG = _ESCAPE + "32m"
+    YELLOW_FG = _ESCAPE + "33m"
+    BLUE_FG = _ESCAPE + "34m"
+    MAGENTA_FG = _ESCAPE + "35m"
+    CYAN_FG = _ESCAPE + "36m"
+    WHITE_FG = _ESCAPE + "37m"
+
+    BLACK_BG = _ESCAPE + "40m"
+    RED_BG = _ESCAPE + "41m"
+    GREEN_BG = _ESCAPE + "42m"
+    YELLOW_BG = _ESCAPE + "43m"
+    BLUE_BG = _ESCAPE + "44m"
+    MAGENTA_BG = _ESCAPE + "45m"
+    CYAN_BG = _ESCAPE + "46m"
+    WHITE_BG = _ESCAPE + "47m"
+
+    BRIGHT_BLACK_FG = _ESCAPE + "90m"
+    BRIGHT_RED_FG = _ESCAPE + "91m"
+    BRIGHT_GREEN_FG = _ESCAPE + "92m"
+    BRIGHT_YELLOW_FG = _ESCAPE + "93m"
+    BRIGHT_BLUE_FG = _ESCAPE + "94m"
+    BRIGHT_MAGENTA_FG = _ESCAPE + "95m"
+    BRIGHT_CYAN_FG = _ESCAPE + "96m"
+    BRIGHT_WHITE_FG = _ESCAPE + "97m"
+
+    BRIGHT_BLACK_BG = _ESCAPE + "100m"
+    BRIGHT_RED_BG = _ESCAPE + "101m"
+    BRIGHT_GREEN_BG = _ESCAPE + "102m"
+    BRIGHT_YELLOW_BG = _ESCAPE + "103m"
+    BRIGHT_BLUE_BG = _ESCAPE + "104m"
+    BRIGHT_MAGENTA_BG = _ESCAPE + "105m"
+    BRIGHT_CYAN_BG = _ESCAPE + "106m"
+    BRIGHT_WHITE_BG = _ESCAPE + "107m"

cocotb/__init__.py

@@ -1,371 +1,125 @@
+# Copyright cocotb contributors
 # Copyright (c) 2013 Potential Ventures Ltd
 # Copyright (c) 2013 SolarFlare Communications Inc
-# All rights reserved.
-
-# Redistribution and use in source and binary forms, with or without
-# modification, are permitted provided that the following conditions are met:
-#     * Redistributions of source code must retain the above copyright
-#       notice, this list of conditions and the following disclaimer.
-#     * Redistributions in binary form must reproduce the above copyright
-#       notice, this list of conditions and the following disclaimer in the
-#       documentation and/or other materials provided with the distribution.
-#     * Neither the name of Potential Ventures Ltd,
-#       SolarFlare Communications Inc nor the
-#       names of its contributors may be used to endorse or promote products
-#       derived from this software without specific prior written permission.
-
-# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
-# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
-# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-# DISCLAIMED. IN NO EVENT SHALL POTENTIAL VENTURES LTD BE LIABLE FOR ANY
-# DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
-# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
-# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
-# ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
-# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-
-"""
-Cocotb is a coroutine, cosimulation framework for writing testbenches in Python.
-
-See https://docs.cocotb.org for full documentation
-"""
-import logging
-import os
-import random
+# Licensed under the Revised BSD License, see LICENSE for details.
+# SPDX-License-Identifier: BSD-3-Clause
 import sys
-import threading
-import time
-import warnings
-from collections.abc import Coroutine
-from typing import Dict, List, Optional, Union
+from typing import TYPE_CHECKING, Dict, List, Union
 
-import cocotb.handle
-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
-    coroutine,
-    external,
-    function,
+from cocotb._decorators import (
+    parametrize,
     test,
 )
-from cocotb.log import _filter_from_c, _log_from_c  # isort: skip # noqa: F401
+from cocotb._test import create_task, start, start_soon
+from cocotb._test_functions import pass_test
+
+from ._version import __version__ as _version
+
+if TYPE_CHECKING:
+    from logging import Logger
+    from types import SimpleNamespace
+
+    from cocotb._scheduler import Scheduler
+    from cocotb.handle import SimHandleBase
+    from cocotb.regression import RegressionManager
+
+__all__ = (
+    "RANDOM_SEED",
+    "SIM_NAME",
+    "SIM_VERSION",
+    "__version__",
+    "argv",
+    "create_task",
+    "is_simulation",
+    "log",
+    "packages",
+    "parametrize",
+    "pass_test",
+    "plusargs",
+    "start",
+    "start_soon",
+    "test",
+    "top",
+)
 
+# Set __module__ on re-exports
+test.__module__ = __name__
+start_soon.__module__ = __name__
+start.__module__ = __name__
+create_task.__module__ = __name__
+parametrize.__module__ = __name__
+pass_test.__module__ = __name__
 
-def _setup_logging() -> None:
-    default_config()
-    global log
-    log = logging.getLogger(__name__)
 
+__version__: str = _version
+"""The version of cocotb."""
 
-# Singleton scheduler instance
-# NB this cheekily ensures a singleton since we're replacing the reference
-# so that cocotb.scheduler gives you the singleton instance and not the
-# scheduler package
 
-scheduler: Optional[Scheduler] = None
-"""The global scheduler instance.
+log: "Logger"
+"""An easily accessible :class:`~logging.Logger` for the user.
 
-This is guaranteed to hold a value at test time.
-"""
+This logger defaults to the :data:`logging.INFO` log level.
 
-regression_manager: Optional[RegressionManager] = None
-"""The global regression manager instance.
-
-This is guaranteed to hold a value at test time.
+.. versionchanged:: 2.0
+    This was previously the ``"cocotb"`` Logger.
+    It is now a Logger under the ``"test"`` namespace.
 """
 
-argv: Optional[List[str]] = None
-"""The argument list as seen by the simulator.
-
-This is guaranteed to hold a value at test time.
-"""
+_scheduler_inst: "Scheduler"
+"""The global scheduler instance."""
 
-argc: Optional[int] = None
-"""The length of :data:`cocotb.argv`.
+_regression_manager: "RegressionManager"
+"""The global regression manager instance."""
 
-This is guaranteed to hold a value at test time.
-"""
+argv: List[str]
+"""The argument list as seen by the simulator."""
 
-plusargs: Optional[Dict[str, Union[bool, str]]] = None
+plusargs: Dict[str, Union[bool, str]]
 """A dictionary of "plusargs" handed to the simulation.
 
-See :make:var:`PLUSARGS` for details.
-This is guaranteed to hold a value at test time.
+See :envvar:`COCOTB_PLUSARGS` for details.
 """
 
-LANGUAGE: Optional[str] = os.getenv("TOPLEVEL_LANG")
-"""The value of :make:var:`TOPLEVEL_LANG`.
-
-This is guaranteed to hold a value at test time.
-"""
+packages: "SimpleNamespace"
+"""A :class:`python:types.SimpleNamespace` of package handles.
 
-SIM_NAME: Optional[str] = None
-"""The running simulator product information.
+This will be populated with handles at test time if packages can be discovered
+via the GPI.
 
-``None`` if :mod:`cocotb` was not loaded from a simulator.
+.. versionadded:: 2.0
 """
 
-SIM_VERSION: Optional[str] = None
-"""The version of the running simulator.
+SIM_NAME: str
+"""The product information of the running simulator."""
 
-``None`` if :mod:`cocotb` was not loaded from a simulator."""
+SIM_VERSION: str
+"""The version of the running simulator."""
 
-RANDOM_SEED: Optional[int] = None
+RANDOM_SEED: int
 """
-The value passed to the Python default random number generator.
+The value passed to the Python global random number generator.
 
-See :envvar:`RANDOM_SEED` for details on how the value is computed.
+See :envvar:`COCOTB_RANDOM_SEED` for details on how the value is computed.
 This is guaranteed to hold a value at test time.
 """
 
-_library_coverage = None
-""" used for cocotb library coverage """
-
-top: Optional[cocotb.handle.SimHandleBase] = None
+top: "SimHandleBase"
 r"""
-A handle to the :envvar:`TOPLEVEL` entity/module.
+A handle to the :envvar:`COCOTB_TOPLEVEL` entity/module.
 
 This is equivalent to the :term:`DUT` parameter given to cocotb tests, so it can be used wherever that variable can be used.
 It is particularly useful for extracting information about the :term:`DUT` in module-level class and function definitions;
 and in parameters to :class:`.TestFactory`\ s.
-``None`` if :mod:`cocotb` was not loaded from a simulator.
 """
 
+is_simulation: bool = False
+"""``True`` if cocotb was loaded in a simulation."""
 
-def fork(coro: Union[Task, Coroutine]) -> Task:
-    """
-    Schedule a coroutine to be run concurrently. See :ref:`coroutines` for details on its use.
-
-    .. deprecated:: 1.7.0
-        This function has been deprecated in favor of :func:`cocotb.start_soon` and :func:`cocotb.start`.
-        In most cases you can simply substitute ``cocotb.fork`` with ``cocotb.start_soon``.
-        For more information on when to use ``start_soon`` vs ``start`` see :ref:`coroutines`.
-    """
-    warnings.warn(
-        "cocotb.fork has been deprecated in favor of cocotb.start_soon and cocotb.start.\n"
-        "In most cases you can simply substitute cocotb.fork with cocotb.start_soon.\n"
-        "For more information about when you would want to use cocotb.start see the docs,\n"
-        "https://docs.cocotb.org/en/latest/coroutines.html#concurrent-execution",
-        DeprecationWarning,
-        stacklevel=2,
-    )
-    return scheduler._add(coro)
-
-
-def start_soon(coro: Union[Task, Coroutine]) -> Task:
-    """
-    Schedule a coroutine to be run concurrently.
-
-    Note that this is not an async function,
-    and the new task will not execute until the calling task yields control.
-
-    .. versionadded:: 1.6.0
-    """
-    return scheduler.start_soon(coro)
-
-
-async def start(coro: Union[Task, Coroutine]) -> Task:
-    """
-    Schedule a 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.
-
-    .. versionadded:: 1.6.0
-    """
-    task = scheduler.start_soon(coro)
-    await cocotb.triggers.NullTrigger()
-    return task
-
-
-def create_task(coro: Union[Task, Coroutine]) -> Task:
-    """
-    Construct a coroutine into a Task without scheduling the Task.
-
-    The Task can later be scheduled with :func:`cocotb.fork`, :func:`cocotb.start`, or
-    :func:`cocotb.start_soon`.
-
-    .. versionadded:: 1.6.0
-    """
-    return cocotb.scheduler.create_task(coro)
-
-
-# FIXME is this really required?
-_rlock = threading.RLock()
-
-
-def mem_debug(port):
-    import cocotb.memdebug
 
-    cocotb.memdebug.start(port)
+if sys.version_info < (3, 8):
+    import warnings
 
-
-def _initialise_testbench(argv_):  # pragma: no cover
-    """Initialize testbench.
-
-    This function is called after the simulator has elaborated all
-    entities and is ready to run the test.
-
-    The test must be defined by the environment variables
-    :envvar:`MODULE` and :envvar:`TESTCASE`.
-    """
-    with _rlock:
-
-        if "COCOTB_LIBRARY_COVERAGE" in os.environ:
-            import coverage
-
-            global _library_coverage
-            _library_coverage = coverage.coverage(
-                data_file=".coverage.cocotb",
-                config_file=False,
-                branch=True,
-                include=["{}/*".format(os.path.dirname(__file__))],
-            )
-            _library_coverage.start()
-
-        _initialise_testbench_(argv_)
-
-
-def _initialise_testbench_(argv_):
-    # The body of this function is split in two because no coverage is collected on
-    # the function that starts the coverage. By splitting it in two we get coverage
-    # on most of the function.
-
-    global argc, argv
-    argv = argv_
-    argc = len(argv)
-
-    root_name = os.getenv("TOPLEVEL")
-    if root_name is not None:
-        root_name = root_name.strip()
-        if root_name == "":
-            root_name = None
-        elif "." in root_name:
-            # Skip any library component of the toplevel
-            root_name = root_name.split(".", 1)[1]
-
-    # sys.path normally includes "" (the current directory), but does not appear to when python is embedded.
-    # Add it back because users expect to be able to import files in their test directory.
-    # TODO: move this to gpi_embed.cpp
-    sys.path.insert(0, "")
-
-    _setup_logging()
-
-    # From https://www.python.org/dev/peps/pep-0565/#recommended-filter-settings-for-test-runners
-    # If the user doesn't want to see these, they can always change the global
-    # warning settings in their test module.
-    if not sys.warnoptions:
-        warnings.simplefilter("default")
-
-    from cocotb import simulator
-
-    global SIM_NAME, SIM_VERSION
-    SIM_NAME = simulator.get_simulator_product().strip()
-    SIM_VERSION = simulator.get_simulator_version().strip()
-
-    cocotb.log.info(f"Running on {SIM_NAME} version {SIM_VERSION}")
-
-    memcheck_port = os.getenv("MEMCHECK")
-    if memcheck_port is not None:
-        mem_debug(int(memcheck_port))
-
-    log.info(
-        "Running tests with cocotb v%s from %s"
-        % (__version__, os.path.dirname(__file__))
+    warnings.warn(
+        "Support for Python versions < 3.8 will be dropped in version 2.1",
+        FutureWarning,
     )
-
-    # Create the base handle type
-
-    _process_plusargs()
-
-    # Seed the Python random number generator to make this repeatable
-    global RANDOM_SEED
-    RANDOM_SEED = os.getenv("RANDOM_SEED")
-
-    if RANDOM_SEED is None:
-        if "ntb_random_seed" in plusargs:
-            RANDOM_SEED = eval(plusargs["ntb_random_seed"])
-        elif "seed" in plusargs:
-            RANDOM_SEED = eval(plusargs["seed"])
-        else:
-            RANDOM_SEED = int(time.time())
-        log.info("Seeding Python random module with %d" % (RANDOM_SEED))
-    else:
-        RANDOM_SEED = int(RANDOM_SEED)
-        log.info("Seeding Python random module with supplied seed %d" % (RANDOM_SEED))
-    random.seed(RANDOM_SEED)
-
-    # Setup DUT object
-    from cocotb import simulator
-
-    handle = simulator.get_root_handle(root_name)
-    if not handle:
-        raise RuntimeError(f"Can not find root handle ({root_name})")
-
-    global top
-    top = cocotb.handle.SimHandle(handle)
-
-    global regression_manager
-    try:
-        regression_manager = RegressionManager.from_discovery(top)
-    except BaseException as e:
-        log.error(e)
-        simulator.stop_simulator()
-        _stop_library_coverage()
-        return  # pragma: no cover
-
-    global scheduler
-    scheduler = Scheduler(handle_result=regression_manager._handle_result)
-
-    # start Regression Manager
-    regression_manager._execute()
-
-
-def _stop_library_coverage() -> None:
-    if _library_coverage is not None:
-        # TODO: move this once we have normal shutdown behavior to _sim_event
-        _library_coverage.stop()
-        _library_coverage.save()  # pragma: no cover
-
-
-def _sim_event(message):
-    """Function that can be called externally to signal an event."""
-    from cocotb.result import SimFailure
-
-    # 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}"
-    if scheduler is not None:
-        scheduler.log.error(msg)
-        scheduler._finish_scheduler(SimFailure(msg))
-    else:
-        log.error(msg)
-        _stop_library_coverage()
-
-
-@deprecated("This function is now private")
-def process_plusargs() -> None:
-
-    _process_plusargs()
-
-
-def _process_plusargs() -> None:
-
-    global plusargs
-
-    plusargs = {}
-
-    for option in cocotb.argv:
-        if option.startswith("+"):
-            if option.find("=") != -1:
-                (name, value) = option[1:].split("=", 1)
-                plusargs[name] = value
-            else:
-                plusargs[option[1:]] = True