Vendor the Deprecated library

Author: mdboom

.pre-commit-config.yaml

@@ -32,7 +32,7 @@ repos:
         language: python
         additional_dependencies:
           - https://files.pythonhosted.org/packages/cc/20/ff623b09d963f88bfde16306a54e12ee5ea43e9b597108672ff3a408aad6/pathspec-0.12.1-py3-none-any.whl
-        exclude: '(.*pixi\.lock)|(\.git_archival\.txt)|(.*\.patch$)'
+        exclude: '(.*pixi\.lock)|(\.git_archival\.txt)|(.*\.patch$)|(^cuda_core/cuda/core/_vendored/)'
         args: ["--fix"]
 
       - id: no-markdown-in-docs-source
@@ -111,11 +111,11 @@ repos:
         alias: mypy-cuda-core
         name: mypy-cuda-core
         files: ^cuda_core/cuda/.*\.(py|pyi)$
+        exclude: ^cuda_core/cuda/core/_vendored/
         pass_filenames: false
         args: [--config-file=cuda_core/pyproject.toml, cuda_core/cuda/core]
         additional_dependencies:
           - numpy
-          - types-Deprecated
 
   - repo: https://github.com/rhysd/actionlint
     rev: "914e7df21a07ef503a81201c76d2b11c789d3fca"  # frozen: v1.7.12

cuda_core/AGENTS.md

@@ -157,11 +157,12 @@ Reviews should point out where existing public APIs are broken.
 - Changes should be notated in the code and also in the release notes in the
   "Deprecated APIs" section.
 
-**Annotating a new API** — Use the `deprecated.sphinx.versionadded` decorator:
+**Annotating a new API** — Use the `versionadded` decorator from the vendored
+`cuda.core._vendored.deprecated.sphinx` module:
 
 ```python
 
-from deprecated.sphinx import versionadded
+from cuda.core._vendored.deprecated.sphinx import versionadded
 
 @versionadded("1.2.0")
 def new_feature(...):
@@ -180,11 +181,12 @@ def new_feature(...):
     """
 ```
 
-**Annotating a changed API** — Use the `deprecated.sphinx.versionchanged` decorator:
+**Annotating a changed API** — Use the `versionchanged` decorator from the
+vendored `cuda.core._vendored.deprecated.sphinx` module:
 
 ```python
 
-from deprecated.sphinx import versionchanged
+from cuda.core._vendored.deprecated.sphinx import versionchanged
 
 @versionchanged("1.2.0", reason="The old version was broken because...")
 def new_feature(...):
@@ -205,13 +207,13 @@ def new_feature(...):
 ```
 
 **Deprecating an existing API** — use the `@deprecated` decorator from the
-`Deprecated` PyPI package (`deprecated.sphinx` import name) and add a
+vendored `cuda.core._vendored.deprecated.sphinx` module and add a
 `.. deprecated::` directive in the docstring.  The decorator emits a
 `DeprecationWarning` at call time; the docstring directive surfaces it in the
 generated docs.
 
 ```python
-from deprecated.sphinx import deprecated
+from cuda.core._vendored.deprecated.sphinx import deprecated
 
 @deprecated(version="1.2.0", reason="Use `new_feature` instead.")
 def old_feature(...):

cuda_core/cuda/core/_vendored/__init__.py

@@ -0,0 +1,6 @@
+# Vendored from the Deprecated package (https://pypi.org/project/Deprecated/),
+# version 1.3.1, (c) Laurent LAPORTE, MIT License.
+# Modified to remove the dependency on the `wrapt` package.
+
+from cuda.core._vendored.deprecated.classic import deprecated
+from cuda.core._vendored.deprecated.params import deprecated_params

cuda_core/cuda/core/_vendored/deprecated/__init__.py

@@ -0,0 +1,111 @@
+# Vendored from the Deprecated package (https://pypi.org/project/Deprecated/),
+# version 1.3.1, (c) Laurent LAPORTE, MIT License.
+# Modified to remove the dependency on the `wrapt` package.
+
+import functools
+import inspect
+import warnings
+
+# stacklevel=2 points past the wrapper to the actual call site
+_routine_stacklevel = 2
+_class_stacklevel = 2
+
+string_types = (bytes, str)
+
+
+class ClassicAdapter:
+    """
+    Classic adapter -- *for advanced usage only*
+
+    This adapter is used to get the deprecation message according to the wrapped
+    object type: class, function, standard method, static method, or class method.
+
+    This is the base class of the :class:`~deprecated.sphinx.SphinxAdapter` class
+    which is used to update the wrapped object docstring.
+    """
+
+    def __init__(self, reason="", version="", action=None, category=DeprecationWarning, extra_stacklevel=0):
+        self.reason = reason or ""
+        self.version = version or ""
+        self.action = action
+        self.category = category
+        self.extra_stacklevel = extra_stacklevel
+
+    def get_deprecated_msg(self, wrapped, instance):
+        if instance is None:
+            if inspect.isclass(wrapped):
+                fmt = "Call to deprecated class {name}."
+            else:
+                fmt = "Call to deprecated function (or staticmethod) {name}."
+        else:
+            if inspect.isclass(instance):
+                fmt = "Call to deprecated class method {name}."
+            else:
+                fmt = "Call to deprecated method {name}."
+        if self.reason:
+            fmt += " ({reason})"
+        if self.version:
+            fmt += " -- Deprecated since version {version}."
+        return fmt.format(name=wrapped.__name__, reason=self.reason or "", version=self.version or "")
+
+    def __call__(self, wrapped):
+        if inspect.isclass(wrapped):
+            old_new1 = wrapped.__new__
+
+            def wrapped_cls(cls, *args, **kwargs):
+                msg = self.get_deprecated_msg(wrapped, None)
+                stacklevel = _class_stacklevel + self.extra_stacklevel
+                if self.action:
+                    with warnings.catch_warnings():
+                        warnings.simplefilter(self.action, self.category)
+                        warnings.warn(msg, category=self.category, stacklevel=stacklevel)
+                else:
+                    warnings.warn(msg, category=self.category, stacklevel=stacklevel)
+                if old_new1 is object.__new__:
+                    return old_new1(cls)
+                return old_new1(cls, *args, **kwargs)
+
+            wrapped.__new__ = staticmethod(wrapped_cls)
+            return wrapped
+
+        elif inspect.isroutine(wrapped):
+            adapter = self
+
+            @functools.wraps(wrapped)
+            def wrapper(*args, **kwargs):
+                msg = adapter.get_deprecated_msg(wrapped, None)
+                stacklevel = _routine_stacklevel + adapter.extra_stacklevel
+                if adapter.action:
+                    with warnings.catch_warnings():
+                        warnings.simplefilter(adapter.action, adapter.category)
+                        warnings.warn(msg, category=adapter.category, stacklevel=stacklevel)
+                else:
+                    warnings.warn(msg, category=adapter.category, stacklevel=stacklevel)
+                return wrapped(*args, **kwargs)
+
+            return wrapper
+
+        else:
+            raise TypeError(repr(type(wrapped)))
+
+
+def deprecated(*args, **kwargs):
+    """
+    Decorator which can be used to mark functions as deprecated.
+
+    It will result in a warning being emitted when the function is used.
+    """
+    if args and isinstance(args[0], string_types):
+        kwargs["reason"] = args[0]
+        args = args[1:]
+
+    if args and not callable(args[0]):
+        raise TypeError(repr(type(args[0])))
+
+    if args:
+        adapter_cls = kwargs.pop("adapter_cls", ClassicAdapter)
+        adapter = adapter_cls(**kwargs)
+        wrapped = args[0]
+        return adapter(wrapped)
+
+    return functools.partial(deprecated, **kwargs)

cuda_core/cuda/core/_vendored/deprecated/classic.py

@@ -0,0 +1,52 @@
+# Vendored from the Deprecated package (https://pypi.org/project/Deprecated/),
+# version 1.3.1, (c) Laurent LAPORTE, MIT License.
+# Modified to remove the dependency on the `wrapt` package.
+
+import collections
+import functools
+import inspect
+import warnings
+
+
+class DeprecatedParams:
+    """
+    Decorator for functions where one or more parameters are deprecated.
+    """
+
+    def __init__(self, param, reason="", category=DeprecationWarning):
+        self.messages = {}
+        self.category = category
+        self.populate_messages(param, reason=reason)
+
+    def populate_messages(self, param, reason=""):
+        if isinstance(param, dict):
+            self.messages.update(param)
+        elif isinstance(param, str):
+            fmt = "'{param}' parameter is deprecated"
+            reason = reason or fmt.format(param=param)
+            self.messages[param] = reason
+        else:
+            raise TypeError(param)
+
+    def check_params(self, signature, *args, **kwargs):
+        binding = signature.bind(*args, **kwargs)
+        bound = collections.OrderedDict(binding.arguments, **binding.kwargs)
+        return [param for param in bound if param in self.messages]
+
+    def warn_messages(self, messages):
+        for message in messages:
+            warnings.warn(message, category=self.category, stacklevel=3)
+
+    def __call__(self, f):
+        signature = inspect.signature(f)
+
+        @functools.wraps(f)
+        def wrapper(*args, **kwargs):
+            invalid_params = self.check_params(signature, *args, **kwargs)
+            self.warn_messages([self.messages[param] for param in invalid_params])
+            return f(*args, **kwargs)
+
+        return wrapper
+
+
+deprecated_params = DeprecatedParams

cuda_core/cuda/core/_vendored/deprecated/params.py

@@ -0,0 +1,113 @@
+# Vendored from the Deprecated package (https://pypi.org/project/Deprecated/),
+# version 1.3.1, (c) Laurent LAPORTE, MIT License.
+# Modified to remove the dependency on the `wrapt` package.
+
+import re
+import textwrap
+
+from cuda.core._vendored.deprecated.classic import ClassicAdapter
+from cuda.core._vendored.deprecated.classic import deprecated as _classic_deprecated
+
+
+class SphinxAdapter(ClassicAdapter):
+    """
+    Sphinx adapter -- *for advanced usage only*
+
+    This adapter overrides :class:`~deprecated.classic.ClassicAdapter` to add
+    Sphinx directives ("versionadded", "versionchanged", "deprecated") to the
+    end of the decorated function or class docstring.
+    """
+
+    def __init__(
+        self,
+        directive,
+        reason="",
+        version="",
+        action=None,
+        category=DeprecationWarning,
+        extra_stacklevel=0,
+        line_length=70,
+    ):
+        if not version:
+            raise ValueError("'version' argument is required in Sphinx directives")
+        self.directive = directive
+        self.line_length = line_length
+        super().__init__(
+            reason=reason, version=version, action=action, category=category, extra_stacklevel=extra_stacklevel
+        )
+
+    def __call__(self, wrapped):
+        fmt = ".. {directive}:: {version}" if self.version else ".. {directive}::"
+        div_lines = [fmt.format(directive=self.directive, version=self.version)]
+        width = self.line_length - 3 if self.line_length > 3 else 2**16
+        reason = textwrap.dedent(self.reason).strip()
+        for paragraph in reason.splitlines():
+            if paragraph:
+                div_lines.extend(
+                    textwrap.fill(
+                        paragraph,
+                        width=width,
+                        initial_indent="   ",
+                        subsequent_indent="   ",
+                    ).splitlines()
+                )
+            else:
+                div_lines.append("")
+
+        docstring = wrapped.__doc__ or ""
+        lines = docstring.splitlines(True) or [""]
+        docstring = textwrap.dedent("".join(lines[1:])) if len(lines) > 1 else ""
+        docstring = lines[0] + docstring
+        if docstring:
+            docstring = re.sub(r"\n+$", "", docstring, flags=re.DOTALL) + "\n\n"
+        else:
+            docstring = "\n"
+
+        docstring += "".join(f"{line}\n" for line in div_lines)
+
+        wrapped.__doc__ = docstring
+        if self.directive in {"versionadded", "versionchanged"}:
+            return wrapped
+        return super().__call__(wrapped)
+
+    def get_deprecated_msg(self, wrapped, instance):
+        msg = super().get_deprecated_msg(wrapped, instance)
+        msg = re.sub(r"(?: : [a-zA-Z]+ )? : [a-zA-Z]+ : (`[^`]*`)", r"\1", msg, flags=re.X)
+        return msg
+
+
+def versionadded(reason="", version="", line_length=70):
+    """
+    Decorator that inserts a "versionadded" Sphinx directive into the docstring.
+    """
+    return SphinxAdapter(
+        "versionadded",
+        reason=reason,
+        version=version,
+        line_length=line_length,
+    )
+
+
+def versionchanged(reason="", version="", line_length=70):
+    """
+    Decorator that inserts a "versionchanged" Sphinx directive into the docstring.
+    """
+    return SphinxAdapter(
+        "versionchanged",
+        reason=reason,
+        version=version,
+        line_length=line_length,
+    )
+
+
+def deprecated(reason="", version="", line_length=70, **kwargs):
+    """
+    Decorator that inserts a "deprecated" Sphinx directive into the docstring
+    and emits a :exc:`DeprecationWarning` when the decorated object is called.
+    """
+    directive = kwargs.pop("directive", "deprecated")
+    adapter_cls = kwargs.pop("adapter_cls", SphinxAdapter)
+    kwargs["reason"] = reason
+    kwargs["version"] = version
+    kwargs["line_length"] = line_length
+    return _classic_deprecated(directive=directive, adapter_cls=adapter_cls, **kwargs)

cuda_core/cuda/core/_vendored/deprecated/sphinx.py

@@ -6,6 +6,8 @@ from typing import Iterable
 
 import cuda.core
 from cuda.bindings import nvml
+from cuda.core._vendored.deprecated.sphinx import (deprecated, versionadded,
+                                                   versionchanged)
 from cuda.core.system.typing import (AddressingMode, AffinityScope, ClockId,
                                      ClocksEventReasons, ClockType,
                                      CoolerControl, CoolerTarget, DeviceArch,
@@ -14,7 +16,6 @@ from cuda.core.system.typing import (AddressingMode, AffinityScope, ClockId,
                                      GpuTopologyLevel, InforomObject,
                                      TemperatureThresholds, ThermalController,
                                      ThermalTarget)
-from deprecated.sphinx import deprecated, versionadded, versionchanged
 
 
 class ClockOffsets:

cuda_core/cuda/core/system/_device.pyi

@@ -9,8 +9,6 @@ from multiprocessing import cpu_count
 from typing import Iterable, TYPE_CHECKING
 import warnings
 
-from deprecated.sphinx import deprecated, versionadded, versionchanged
-
 from cuda.bindings import nvml
 
 from ._nvml_context cimport initialize
@@ -35,6 +33,7 @@ from cuda.core.system.typing import (
     ThermalController,
     ThermalTarget,
 )
+from cuda.core._vendored.deprecated.sphinx import deprecated, versionadded, versionchanged
 
 if TYPE_CHECKING:
     import cuda.core  # no-cython-lint