cocotb 1.9.2__cp311-cp311-win32.whl → 2.0.0b1__cp311-cp311-win32.whl

cocotb/_outcomes.py

@@ -0,0 +1,54 @@
+"""
+Inspired by https://github.com/python-trio/outcome
+
+An outcome is similar to the built-in :any:`concurrent.futures.Future`
+or :any:`asyncio.Future`, but without being tied to a particular task model.
+"""
+
+import abc
+from typing import Callable, Generic, TypeVar
+
+from cocotb._py_compat import ParamSpec
+from cocotb._utils import remove_traceback_frames
+
+T = TypeVar("T")
+P = ParamSpec("P")
+
+
+def capture(
+    fn: "Callable[P, T]", *args: "P.args", **kwargs: "P.kwargs"
+) -> "Outcome[T]":
+    """Obtain an `Outcome` representing the result of a function call."""
+    try:
+        return Value(fn(*args, **kwargs))
+    except BaseException as e:
+        e = remove_traceback_frames(e, ["capture"])
+        return Error(e)
+
+
+class Outcome(Generic[T]):
+    @abc.abstractmethod
+    def get(self) -> T:
+        """Get the value of this outcome, or throw its exception."""
+
+
+class Value(Outcome[T]):
+    def __init__(self, value: T):
+        self.value = value
+
+    def get(self) -> T:
+        return self.value
+
+    def __repr__(self) -> str:
+        return f"Value({self.value!r})"
+
+
+class Error(Outcome[T]):
+    def __init__(self, error: BaseException) -> None:
+        self.error = error
+
+    def get(self) -> T:
+        raise self.error
+
+    def __repr__(self) -> str:
+        return f"Error({self.error!r})"

cocotb/_profiling.py

@@ -0,0 +1,46 @@
+# Copyright cocotb contributors
+# Licensed under the Revised BSD License, see LICENSE for details.
+# SPDX-License-Identifier: BSD-3-Clause
+
+
+# Debug mode controlled by environment variables
+import cProfile
+import os
+import pstats
+
+from cocotb._py_compat import AbstractContextManager, nullcontext
+
+profiling_context: AbstractContextManager[None, None]
+
+
+if "COCOTB_ENABLE_PROFILING" in os.environ:
+    _profile: cProfile.Profile
+
+    def initialize() -> None:
+        global _profile
+        _profile = cProfile.Profile()
+
+    def finalize() -> None:
+        ps = pstats.Stats(_profile).sort_stats("cumulative")
+        ps.dump_stats("cocotb.pstat")
+
+    class _profiling_context(AbstractContextManager[None, None]):
+        """Context manager that profiles its contents"""
+
+        def __enter__(self) -> None:
+            _profile.enable()
+
+        def __exit__(self, *excinfo: object) -> None:
+            _profile.disable()
+
+    profiling_context = _profiling_context()
+
+else:
+
+    def initialize() -> None:
+        pass
+
+    def finalize() -> None:
+        pass
+
+    profiling_context = nullcontext()

cocotb/_py_compat.py

@@ -1,38 +1,44 @@
-# Copyright (c) cocotb contributors
-# 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 the copyright holder 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.
+# Copyright cocotb contributors
+# Licensed under the Revised BSD License, see LICENSE for details.
+# SPDX-License-Identifier: BSD-3-Clause
 """
 Backports and compatibility shims for newer python features.
 
 These are for internal use - users should use a third party library like `six`
 if they want to use these shims in their own code
 """
+
 import sys
+from abc import ABC
+from contextlib import AbstractContextManager
+from typing import TypeVar, Union, overload
+
+__all__ = (
+    "AbstractContextManager",
+    "Final",
+    "Literal",
+    "ParamSpec",
+    "Protocol",
+    "Self",
+    "TypeAlias",
+    "cached_property",
+    "insertion_ordered_dict",
+    "nullcontext",
+)
+
+T = TypeVar("T")
+
+if sys.version_info < (3, 9):
+    from typing import Generic
+
+    T_co = TypeVar("T_co", covariant=True)
+    ExitT_co = TypeVar("ExitT_co", covariant=True)
+
+    class AbstractContextManager(AbstractContextManager, Generic[T_co, ExitT_co]): ...
 
 
 # backport of Python 3.7's contextlib.nullcontext
-class nullcontext:
+class nullcontext(AbstractContextManager[T, None]):
     """Context manager that does no additional processing.
     Used as a stand-in for a normal context manager, when a particular
     block of code is only sometimes used with a normal context manager:
@@ -42,22 +48,87 @@ class nullcontext:
         # Perform operation, using optional_cm if condition is True
     """
 
-    def __init__(self, enter_result=None):
+    enter_result: T
+
+    @overload
+    def __init__(self: "nullcontext[None]", enter_result: None = None) -> None: ...
+
+    @overload
+    def __init__(self: "nullcontext[T]", enter_result: T) -> None: ...
+
+    def __init__(
+        self: "nullcontext[Union[T, None]]", enter_result: Union[T, None] = None
+    ) -> None:
         self.enter_result = enter_result
 
-    def __enter__(self):
+    def __enter__(self) -> T:
         return self.enter_result
 
-    def __exit__(self, *excinfo):
+    def __exit__(self, *excinfo: object) -> None:
         pass
 
 
 # On python 3.7 onwards, `dict` is guaranteed to preserve insertion order.
 # Since `OrderedDict` is a little slower that `dict`, we prefer the latter
 # when possible.
-if sys.version_info[:2] >= (3, 7):
+if sys.version_info[:2] >= (3, 7):  # noqa: UP036 | bug in ruff
     insertion_ordered_dict = dict
 else:
     import collections
 
     insertion_ordered_dict = collections.OrderedDict
+
+
+# simple, but less than optimal backport of Python 3.8's cached_property
+if sys.version_info >= (3, 8):
+    from functools import cached_property
+else:
+    from functools import update_wrapper
+
+    class cached_property:
+        def __init__(self, method):
+            self._method = method
+            update_wrapper(self, method)
+
+        def __get__(self, instance, owner=None):
+            if instance is None:
+                return self
+            res = self._method(instance)
+            instance.__dict__[self._method.__name__] = res
+            return res
+
+
+class FakeGetItemType:
+    def __class_getitem__(self, a: object) -> str:
+        return ""
+
+
+if sys.version_info >= (3, 8):
+    from typing import Final, Literal, Protocol
+else:
+    Final = FakeGetItemType
+    Literal = FakeGetItemType
+    Protocol = ABC
+
+
+if sys.version_info >= (3, 10):
+    from typing import ParamSpec, TypeAlias
+else:
+    TypeAlias = ""
+
+    class FakeParamSpecType:
+        def __init__(self, name: str) -> None: ...
+
+        def kwargs(self) -> str:
+            return ""
+
+        def args(self) -> str:
+            return ""
+
+    ParamSpec = FakeParamSpecType
+
+
+if sys.version_info >= (3, 11):
+    from typing import Self
+else:
+    Self = ""