coco-framework 0.1.0__py3-none-any.whl

coco_core/_api/deprecation.py

@@ -0,0 +1,637 @@
+"""Helper functions for deprecating parts of the Coco API.
+
+This module was adapted from matplotlib's [`_api/deprecation.py`](https://github.com/matplotlib/matplotlib/blob/main/lib/matplotlib/_api/deprecation.py)
+module.
+
+!!! warning
+
+    This module is for internal use only. Do not use it in your own code. We may change
+    the API at any time with no warning.
+"""
+
+import contextlib
+import functools
+import inspect
+import sys
+import warnings
+from collections.abc import Callable, Generator
+from contextvars import ContextVar
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    ParamSpec,
+    TypeGuard,
+    TypeVar,
+    cast,
+)
+
+from pydantic.fields import FieldInfo
+
+from coco_core._api.internal import is_caller_internal
+
+if TYPE_CHECKING:
+    from pydantic.v1.fields import FieldInfo as FieldInfoV1
+
+
+def _is_pydantic_v1_field_info(obj: Any) -> TypeGuard["FieldInfoV1"]:
+    """Check if `obj` is a `pydantic.v1.fields.FieldInfo` without forcing import.
+
+    Importing `pydantic.v1` emits a `UserWarning` on Python 3.14+. Skipping the
+    import entirely when no caller has constructed a v1 `FieldInfo` keeps that
+    warning out of `coco_core`'s import path. If a caller did construct one,
+    `pydantic.v1.fields` is already in `sys.modules` and isinstance is safe.
+    """
+    mod = sys.modules.get("pydantic.v1.fields")
+    if mod is None:
+        return False
+    return isinstance(obj, mod.FieldInfo)
+
+
+def _build_deprecation_message(
+    *,
+    alternative: str = "",
+    alternative_import: str = "",
+) -> str:
+    """Build a simple deprecation message for `__deprecated__` attribute.
+
+    Args:
+        alternative: An alternative API name.
+        alternative_import: A fully qualified import path for the alternative.
+
+    Returns:
+        A deprecation message string for IDE/type checker display.
+    """
+    if alternative_import:
+        return f"Use {alternative_import} instead."
+    if alternative:
+        return f"Use {alternative} instead."
+    return "Deprecated."
+
+
+class CocoDeprecationWarning(DeprecationWarning):
+    """A class for issuing deprecation warnings for Coco users."""
+
+
+class CocoPendingDeprecationWarning(PendingDeprecationWarning):
+    """A class for issuing deprecation warnings for Coco users."""
+
+
+# Tracks when callers intentionally silence Coco deprecation warnings.
+# Suppressed warnings should not consume a deprecated callable's one-time
+# warning state; otherwise an internal compatibility path can prevent the first
+# user-visible call from warning.
+_SUPPRESSING_COCO_DEPRECATION_WARNING = ContextVar(
+    "_SUPPRESSING_COCO_DEPRECATION_WARNING", default=False
+)
+
+
+# PUBLIC API
+
+
+# Bound is `Any` (not `FieldInfoV1`) because importing `pydantic.v1` at module
+# scope emits a `UserWarning` on Python 3.14+; v1 `FieldInfo` support is handled
+# at runtime via `_is_pydantic_v1_field_info`.
+T = TypeVar("T", bound=type | Callable[..., Any] | Any)
+
+
+def _validate_deprecation_params(
+    removal: str,
+    alternative: str,
+    alternative_import: str,
+    *,
+    pending: bool,
+) -> None:
+    """Validate the deprecation parameters."""
+    if pending and removal:
+        msg = "A pending deprecation cannot have a scheduled removal"
+        raise ValueError(msg)
+    if alternative and alternative_import:
+        msg = "Cannot specify both alternative and alternative_import"
+        raise ValueError(msg)
+
+    if alternative_import and "." not in alternative_import:
+        msg = (
+            "alternative_import must be a fully qualified module path. Got "
+            f" {alternative_import}"
+        )
+        raise ValueError(msg)
+
+
+def deprecated(
+    since: str,
+    *,
+    message: str = "",
+    name: str = "",
+    alternative: str = "",
+    alternative_import: str = "",
+    pending: bool = False,
+    obj_type: str = "",
+    addendum: str = "",
+    removal: str = "",
+    package: str = "",
+) -> Callable[[T], T]:
+    """Decorator to mark a function, a class, or a property as deprecated.
+
+    When deprecating a classmethod, a staticmethod, or a property, the `@deprecated`
+    decorator should go *under* `@classmethod` and `@staticmethod` (i.e., `deprecated`
+    should directly decorate the underlying callable), but *over* `@property`.
+
+    When deprecating a class `C` intended to be used as a base class in a multiple
+    inheritance hierarchy, `C` *must* define an `__init__` method (if `C` instead
+    inherited its `__init__` from its own base class, then `@deprecated` would mess up
+    `__init__` inheritance when installing its own (deprecation-emitting) `C.__init__`).
+
+    Parameters are the same as for `warn_deprecated`, except that *obj_type* defaults to
+    'class' if decorating a class, 'attribute' if decorating a property, and 'function'
+    otherwise.
+
+    Args:
+        since: The release at which this API became deprecated.
+        message: Override the default deprecation message.
+
+            The `%(since)s`, `%(name)s`, `%(alternative)s`, `%(obj_type)s`,
+            `%(addendum)s`, and `%(removal)s` format specifiers will be replaced by the
+            values of the respective arguments passed to this function.
+        name: The name of the deprecated object.
+        alternative: An alternative API that the user may use in place of the deprecated
+            API.
+
+            The deprecation warning will tell the user about this alternative if
+            provided.
+        alternative_import: An alternative import that the user may use instead.
+        pending: If `True`, uses a `PendingDeprecationWarning` instead of a
+            `DeprecationWarning`.
+
+            Cannot be used together with removal.
+        obj_type: The object type being deprecated.
+        addendum: Additional text appended directly to the final message.
+        removal: The expected removal version.
+
+            With the default (an empty string), no removal version is shown in the
+            warning message.
+
+            Cannot be used together with pending.
+        package: The package of the deprecated object.
+
+    Returns:
+        A decorator to mark a function or class as deprecated.
+
+    Example:
+        ```python
+        @deprecated("1.4.0")
+        def the_function_to_deprecate():
+            pass
+        ```
+    """
+    _validate_deprecation_params(
+        removal, alternative, alternative_import, pending=pending
+    )
+
+    def deprecate(
+        obj: T,
+        *,
+        _obj_type: str = obj_type,
+        _name: str = name,
+        _message: str = message,
+        _alternative: str = alternative,
+        _alternative_import: str = alternative_import,
+        _pending: bool = pending,
+        _addendum: str = addendum,
+        _package: str = package,
+    ) -> T:
+        """Implementation of the decorator returned by `deprecated`."""
+
+        def emit_warning() -> None:
+            """Emit the warning."""
+            warn_deprecated(
+                since,
+                message=_message,
+                name=_name,
+                alternative=_alternative,
+                alternative_import=_alternative_import,
+                pending=_pending,
+                obj_type=_obj_type,
+                addendum=_addendum,
+                removal=removal,
+                package=_package,
+            )
+
+        warned = False
+
+        def warning_emitting_wrapper(*args: Any, **kwargs: Any) -> Any:
+            """Wrapper for the original wrapped callable that emits a warning.
+
+            Args:
+                *args: The positional arguments to the function.
+                **kwargs: The keyword arguments to the function.
+
+            Returns:
+                The return value of the function being wrapped.
+            """
+            nonlocal warned
+            if not warned and not is_caller_internal():
+                emit_warning()
+                # Only mark the warning as emitted if it was not intentionally
+                # suppressed by `suppress_coco_deprecation_warning()`.
+                warned = not _SUPPRESSING_COCO_DEPRECATION_WARNING.get()
+            return wrapped(*args, **kwargs)
+
+        async def awarning_emitting_wrapper(*args: Any, **kwargs: Any) -> Any:
+            """Same as warning_emitting_wrapper, but for async functions."""
+            nonlocal warned
+            if not warned and not is_caller_internal():
+                emit_warning()
+                # Only mark the warning as emitted if it was not intentionally
+                # suppressed by `suppress_coco_deprecation_warning()`.
+                warned = not _SUPPRESSING_COCO_DEPRECATION_WARNING.get()
+            return await wrapped(*args, **kwargs)
+
+        _package = _package or obj.__module__.split(".")[0].replace("_", "-")
+
+        if isinstance(obj, type):
+            if not _obj_type:
+                _obj_type = "class"
+            wrapped = obj.__init__  # type: ignore[misc]
+            _name = _name or obj.__qualname__
+            old_doc = obj.__doc__
+
+            def finalize(_: Callable[..., Any], new_doc: str, /) -> T:
+                """Finalize the deprecation of a class."""
+                # Can't set new_doc on some extension objects.
+                with contextlib.suppress(AttributeError):
+                    obj.__doc__ = new_doc
+
+                def warn_if_direct_instance(
+                    self: Any, *args: Any, **kwargs: Any
+                ) -> Any:
+                    """Warn that the class is in beta."""
+                    nonlocal warned
+                    if not warned and type(self) is obj and not is_caller_internal():
+                        emit_warning()
+                        # Only mark the warning as emitted if it was not intentionally
+                        # suppressed by `suppress_coco_deprecation_warning()`.
+                        warned = not _SUPPRESSING_COCO_DEPRECATION_WARNING.get()
+                    return wrapped(self, *args, **kwargs)
+
+                obj.__init__ = functools.wraps(obj.__init__)(  # type: ignore[misc]
+                    warn_if_direct_instance
+                )
+                # Set __deprecated__ for PEP 702 (IDE/type checker support)
+                obj.__deprecated__ = _build_deprecation_message(  # type: ignore[attr-defined]
+                    alternative=alternative,
+                    alternative_import=alternative_import,
+                )
+                return obj
+
+        elif _is_pydantic_v1_field_info(obj):
+            wrapped = None
+            if not _obj_type:
+                _obj_type = "attribute"
+            if not _name:
+                msg = f"Field {obj} must have a name to be deprecated."
+                raise ValueError(msg)
+            old_doc = obj.description
+
+            def finalize(_: Callable[..., Any], new_doc: str, /) -> T:
+                from pydantic.v1.fields import FieldInfo as FieldInfoV1  # noqa: PLC0415
+
+                return cast(
+                    "T",
+                    FieldInfoV1(
+                        default=obj.default,
+                        default_factory=obj.default_factory,
+                        description=new_doc,
+                        alias=obj.alias,
+                        exclude=obj.exclude,
+                    ),
+                )
+
+        elif isinstance(obj, FieldInfo):
+            wrapped = None
+            if not _obj_type:
+                _obj_type = "attribute"
+            if not _name:
+                msg = f"Field {obj} must have a name to be deprecated."
+                raise ValueError(msg)
+            old_doc = obj.description
+
+            def finalize(_: Callable[..., Any], new_doc: str, /) -> T:
+                return cast(
+                    "T",
+                    FieldInfo(
+                        default=obj.default,
+                        default_factory=obj.default_factory,
+                        description=new_doc,
+                        alias=obj.alias,
+                        exclude=obj.exclude,
+                    ),
+                )
+
+        elif isinstance(obj, property):
+            if not _obj_type:
+                _obj_type = "attribute"
+            wrapped = None
+            _name = _name or cast("type", obj.fget).__qualname__
+            old_doc = obj.__doc__
+
+            class _DeprecatedProperty(property):
+                """A deprecated property."""
+
+                def __init__(
+                    self,
+                    fget: Callable[[Any], Any] | None = None,
+                    fset: Callable[[Any, Any], None] | None = None,
+                    fdel: Callable[[Any], None] | None = None,
+                    doc: str | None = None,
+                ) -> None:
+                    super().__init__(fget, fset, fdel, doc)
+                    self.__orig_fget = fget
+                    self.__orig_fset = fset
+                    self.__orig_fdel = fdel
+
+                def __get__(self, instance: Any, owner: type | None = None) -> Any:
+                    if instance is not None or owner is not None:
+                        emit_warning()
+                    if self.fget is None:
+                        return None
+                    return self.fget(instance)
+
+                def __set__(self, instance: Any, value: Any) -> None:
+                    if instance is not None:
+                        emit_warning()
+                    if self.fset is not None:
+                        self.fset(instance, value)
+
+                def __delete__(self, instance: Any) -> None:
+                    if instance is not None:
+                        emit_warning()
+                    if self.fdel is not None:
+                        self.fdel(instance)
+
+                def __set_name__(self, owner: type | None, set_name: str) -> None:
+                    nonlocal _name
+                    if _name == "<lambda>":
+                        _name = set_name
+
+            def finalize(_: Callable[..., Any], new_doc: str, /) -> T:
+                """Finalize the property."""
+                prop = _DeprecatedProperty(
+                    fget=obj.fget, fset=obj.fset, fdel=obj.fdel, doc=new_doc
+                )
+                # Set __deprecated__ for PEP 702 (IDE/type checker support)
+                prop.__deprecated__ = _build_deprecation_message(  # type: ignore[attr-defined]
+                    alternative=alternative,
+                    alternative_import=alternative_import,
+                )
+                return cast("T", prop)
+
+        else:
+            _name = _name or cast("type", obj).__qualname__
+            if not _obj_type:
+                # edge case: when a function is within another function
+                # within a test, this will call it a "method" not a "function"
+                _obj_type = "function" if "." not in _name else "method"
+            wrapped = obj
+            old_doc = wrapped.__doc__
+
+            def finalize(wrapper: Callable[..., Any], new_doc: str, /) -> T:
+                """Wrap the wrapped function using the wrapper and update the docstring.
+
+                Args:
+                    wrapper: The wrapper function.
+                    new_doc: The new docstring.
+
+                Returns:
+                    The wrapped function.
+                """
+                wrapper = functools.wraps(wrapped)(wrapper)
+                wrapper.__doc__ = new_doc
+                # Set __deprecated__ for PEP 702 (IDE/type checker support)
+                wrapper.__deprecated__ = _build_deprecation_message(  # type: ignore[attr-defined]
+                    alternative=alternative,
+                    alternative_import=alternative_import,
+                )
+                return cast("T", wrapper)
+
+        old_doc = inspect.cleandoc(old_doc or "").strip("\n")
+
+        # old_doc can be None
+        if not old_doc:
+            old_doc = ""
+
+        # Modify the docstring to include a deprecation notice.
+        if (
+            _alternative
+            and _alternative.rsplit(".", maxsplit=1)[-1].lower()
+            == _alternative.rsplit(".", maxsplit=1)[-1]
+        ) or _alternative:
+            _alternative = f"`{_alternative}`"
+
+        if (
+            _alternative_import
+            and _alternative_import.rsplit(".", maxsplit=1)[-1].lower()
+            == _alternative_import.rsplit(".", maxsplit=1)[-1]
+        ) or _alternative_import:
+            _alternative_import = f"`{_alternative_import}`"
+
+        components = [
+            _message,
+            f"Use {_alternative} instead." if _alternative else "",
+            f"Use {_alternative_import} instead." if _alternative_import else "",
+            _addendum,
+        ]
+        details = " ".join([component.strip() for component in components if component])
+        package = _package or (
+            _name.split(".")[0].replace("_", "-") if "." in _name else None
+        )
+        if removal:
+            if removal.startswith("1.") and package and package.startswith("coco"):
+                removal_str = f"It will not be removed until {package}=={removal}."
+            else:
+                removal_str = f"It will be removed in {package}=={removal}."
+        else:
+            removal_str = ""
+        new_doc = f"""\
+!!! deprecated "{since} {details} {removal_str}"
+
+{old_doc}\
+"""
+
+        if inspect.iscoroutinefunction(obj):
+            return finalize(awarning_emitting_wrapper, new_doc)
+        return finalize(warning_emitting_wrapper, new_doc)
+
+    return deprecate
+
+
+@contextlib.contextmanager
+def suppress_coco_deprecation_warning() -> Generator[None, None, None]:
+    """Context manager to suppress `CocoDeprecationWarning`."""
+    token = _SUPPRESSING_COCO_DEPRECATION_WARNING.set(True)
+    try:
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", CocoDeprecationWarning)
+            warnings.simplefilter("ignore", CocoPendingDeprecationWarning)
+            yield
+    finally:
+        _SUPPRESSING_COCO_DEPRECATION_WARNING.reset(token)
+
+
+def warn_deprecated(
+    since: str,
+    *,
+    message: str = "",
+    name: str = "",
+    alternative: str = "",
+    alternative_import: str = "",
+    pending: bool = False,
+    obj_type: str = "",
+    addendum: str = "",
+    removal: str = "",
+    package: str = "",
+) -> None:
+    """Display a standardized deprecation.
+
+    Args:
+        since: The release at which this API became deprecated.
+        message: Override the default deprecation message.
+
+            The `%(since)s`, `%(name)s`, `%(alternative)s`, `%(obj_type)s`,
+            `%(addendum)s`, and `%(removal)s` format specifiers will be replaced by the
+            values of the respective arguments passed to this function.
+        name: The name of the deprecated object.
+        alternative: An alternative API that the user may use in place of the
+            deprecated API.
+
+            The deprecation warning will tell the user about this alternative if
+            provided.
+        alternative_import: An alternative import that the user may use instead.
+        pending: If `True`, uses a `PendingDeprecationWarning` instead of a
+            `DeprecationWarning`.
+
+            Cannot be used together with removal.
+        obj_type: The object type being deprecated.
+        addendum: Additional text appended directly to the final message.
+        removal: The expected removal version.
+
+            With the default (an empty string), no removal version is shown in the
+            warning message.
+
+            Cannot be used together with pending.
+        package: The package of the deprecated object.
+    """
+    if not pending and removal:
+        removal = f"in {removal}"
+
+    if not message:
+        message = ""
+        package_ = (
+            package or name.split(".", maxsplit=1)[0].replace("_", "-")
+            if "." in name
+            else "Coco"
+        )
+
+        if obj_type:
+            message += f"The {obj_type} `{name}`"
+        else:
+            message += f"`{name}`"
+
+        if pending:
+            message += " will be deprecated in a future version"
+        else:
+            message += f" was deprecated in {package_} {since}"
+
+            if removal:
+                message += f" and will be removed {removal}"
+
+        if alternative_import:
+            alt_package = alternative_import.split(".", maxsplit=1)[0].replace("_", "-")
+            if alt_package == package_:
+                message += f". Use {alternative_import} instead."
+            else:
+                alt_module, alt_name = alternative_import.rsplit(".", 1)
+                message += (
+                    f". An updated version of the {obj_type} exists in the "
+                    f"{alt_package} package and should be used instead. To use it run "
+                    f"`pip install -U {alt_package}` and import as "
+                    f"`from {alt_module} import {alt_name}`."
+                )
+        elif alternative:
+            message += f". Use {alternative} instead."
+
+        if addendum:
+            message += f" {addendum}"
+
+    warning_cls = (
+        CocoPendingDeprecationWarning if pending else CocoDeprecationWarning
+    )
+    warning = warning_cls(message)
+    warnings.warn(warning, category=CocoDeprecationWarning, stacklevel=4)
+
+
+def surface_coco_deprecation_warnings() -> None:
+    """Unmute Coco deprecation warnings."""
+    warnings.filterwarnings(
+        "default",
+        category=CocoPendingDeprecationWarning,
+    )
+
+    warnings.filterwarnings(
+        "default",
+        category=CocoDeprecationWarning,
+    )
+
+
+_P = ParamSpec("_P")
+_R = TypeVar("_R")
+
+
+def rename_parameter(
+    *,
+    since: str,
+    removal: str,
+    old: str,
+    new: str,
+) -> Callable[[Callable[_P, _R]], Callable[_P, _R]]:
+    """Decorator indicating that parameter *old* of *func* is renamed to *new*.
+
+    The actual implementation of *func* should use *new*, not *old*. If *old* is passed
+    to *func*, a `DeprecationWarning` is emitted, and its value is used, even if *new*
+    is also passed by keyword.
+
+    Args:
+        since: The version in which the parameter was renamed.
+        removal: The version in which the old parameter will be removed.
+        old: The old parameter name.
+        new: The new parameter name.
+
+    Returns:
+        A decorator indicating that a parameter was renamed.
+
+    Example:
+        ```python
+        @_api.rename_parameter("3.1", "bad_name", "good_name")
+        def func(good_name): ...
+        ```
+    """
+
+    def decorator(f: Callable[_P, _R]) -> Callable[_P, _R]:
+        @functools.wraps(f)
+        def wrapper(*args: _P.args, **kwargs: _P.kwargs) -> _R:
+            if new in kwargs and old in kwargs:
+                msg = f"{f.__name__}() got multiple values for argument {new!r}"
+                raise TypeError(msg)
+            if old in kwargs:
+                warn_deprecated(
+                    since,
+                    removal=removal,
+                    message=f"The parameter `{old}` of `{f.__name__}` was "
+                    f"deprecated in {since} and will be removed "
+                    f"in {removal} Use `{new}` instead.",
+                )
+                kwargs[new] = kwargs.pop(old)
+            return f(*args, **kwargs)
+
+        return wrapper
+
+    return decorator

coco_core/_api/internal.py

@@ -0,0 +1,23 @@
+import inspect
+from typing import cast
+
+
+def is_caller_internal(depth: int = 2) -> bool:
+    """Return whether the caller at `depth` of this function is internal."""
+    try:
+        frame = inspect.currentframe()
+    except AttributeError:
+        return False
+    if frame is None:
+        return False
+    try:
+        for _ in range(depth):
+            frame = frame.f_back
+            if frame is None:
+                return False
+        # Directly access the module name from the frame's global variables
+        module_globals = frame.f_globals
+        caller_module_name = cast("str", module_globals.get("__name__", ""))
+        return caller_module_name.startswith("coco")
+    finally:
+        del frame