diff --git a/qiskit/utils/deprecation.py b/qiskit/utils/deprecation.py index 0262542a800b..93468a01d0be 100644 --- a/qiskit/utils/deprecation.py +++ b/qiskit/utils/deprecation.py @@ -27,7 +27,7 @@ def deprecate_func( additional_msg: str | None = None, pending: bool = False, package_name: str = "Qiskit", - removal_timeline: str = "no earlier than 3 months after the release date", + removal_timeline: str | None = None, is_property: bool = False, stacklevel: int = 2, ): @@ -47,7 +47,8 @@ def deprecate_func( pending: Set to ``True`` if the deprecation is still pending. package_name: The package name shown in the deprecation message (e.g. the PyPI package name). removal_timeline: How soon can this deprecation be removed? Expects a value - like "no sooner than 6 months after the latest release" or "in release 9.99". + like "in two major releases" or "in release 9.99". Default: + "in the next major release {since_major + 1}". is_property: If the deprecated function is a `@property`, set this to True so that the generated message correctly describes it as such. (This isn't necessary for property setters, as their docstring is ignored by Python.) @@ -112,7 +113,7 @@ def deprecate_arg( package_name: str = "Qiskit", new_alias: str | None = None, predicate: Callable[[Any], bool] | None = None, - removal_timeline: str = "no earlier than 3 months after the release date", + removal_timeline: str | None = None, ): """Decorator to indicate an argument has been deprecated in some way. @@ -139,7 +140,8 @@ def deprecate_arg( `lambda my_arg: isinstance(my_arg, dict)`. Regardless of if a predicate is set, the runtime warning will only log when the user specifies the argument. removal_timeline: How soon can this deprecation be removed? Expects a value - like "no sooner than 6 months after the latest release" or "in release 9.99". + like "in two major releases" or "in release 9.99". Default: + "in the next major release {since_major + 1}". Returns: Callable: The decorated callable. @@ -246,8 +248,12 @@ def _write_deprecation_msg( since: str, pending: bool, additional_msg: str, - removal_timeline: str, + removal_timeline: str | None, ) -> tuple[str, Type[DeprecationWarning] | Type[PendingDeprecationWarning]]: + if not removal_timeline: + removal_major = int(str(since).split(".", maxsplit=1)[0]) + 1 + removal_timeline = f"in the next major release {removal_major}.0" + if pending: category: Type[DeprecationWarning] | Type[PendingDeprecationWarning] = ( PendingDeprecationWarning diff --git a/releasenotes/notes/semver_deprecation-6b0f07db27dfc638.yaml b/releasenotes/notes/semver_deprecation-6b0f07db27dfc638.yaml new file mode 100644 index 000000000000..881d700fc635 --- /dev/null +++ b/releasenotes/notes/semver_deprecation-6b0f07db27dfc638.yaml @@ -0,0 +1,7 @@ +--- +upgrade_misc: + - | + The decorators :func:`deprecate_func` and :func:`deprecate_arg` changed their default behaivor to adapt to the + Qiskit SemVer versioning (`RFC0020` `__). As a consequence, + the parameter ``removal_timeline`` default changed: from "no earlier than 3 months after the release date" to "in the next major + release {``since`` major + 1}". If you would like to preserve the previous messaging, you should set ``removal_timeline`` explicitly. diff --git a/test/python/utils/test_deprecation.py b/test/python/utils/test_deprecation.py index 7af97711c243..c0ba5375d2cd 100644 --- a/test/python/utils/test_deprecation.py +++ b/test/python/utils/test_deprecation.py @@ -83,8 +83,7 @@ def test_deprecate_func_docstring(self) -> None: .. deprecated:: 9.99_pending The class ``{__name__}._Foo`` is pending deprecation as of Qiskit 9.99. It \ -will be marked deprecated in a future release, and then removed no earlier than 3 months after \ -the release date. +will be marked deprecated in a future release, and then removed in the next major release 10.0. """ ), ) @@ -96,7 +95,7 @@ def test_deprecate_func_docstring(self) -> None: .. deprecated:: 9.99 The method ``{__name__}._Foo.my_method()`` is deprecated as of Qiskit \ -9.99. It will be removed no earlier than 3 months after the release date. Stop using this! +9.99. It will be removed in the next major release 10.0. Stop using this! """ ), ) @@ -108,7 +107,7 @@ def test_deprecate_func_docstring(self) -> None: .. deprecated:: 9.99 The property ``{__name__}._Foo.my_property`` is deprecated as of Qiskit \ -9.99. It will be removed no earlier than 3 months after the release date. +9.99. It will be removed in the next major release 10.0. """ ), ) @@ -152,18 +151,18 @@ def my_func() -> None: .. deprecated:: 9.99 ``{__name__}.{my_func.__qualname__}()``'s argument ``arg4`` is deprecated as of \ -Qiskit 9.99. It will be removed no earlier than 3 months after the release date. Instead, \ +Qiskit 9.99. It will be removed in the next major release 10.0. Instead, \ use foo. .. deprecated:: 9.99 Using the argument arg3 is deprecated as of Qiskit 9.99. It will be \ -removed no earlier than 3 months after the release date. Instead, use the argument ``new_arg3``, \ +removed in the next major release 10.0. Instead, use the argument ``new_arg3``, \ which behaves identically. .. deprecated:: 9.99_pending ``{__name__}.{my_func.__qualname__}()``'s argument ``arg2`` is pending \ deprecation as of Qiskit 9.99. It will be marked deprecated in a future release, and then \ -removed no earlier than 3 months after the release date. +removed in the next major release 10.0. .. deprecated:: 9.99 ``{__name__}.{my_func.__qualname__}()``'s argument ``arg1`` is deprecated as of \