From dcae8f114ea7555a3597a1e0a7ee96bd99ed1023 Mon Sep 17 00:00:00 2001 From: Vyron Vasileiadis Date: Sat, 18 Jul 2026 04:04:26 +0300 Subject: [PATCH 1/3] gh-150076: Document the public attributes of warnings.deprecated The documentation described only the ``__deprecated__`` attribute set on the decorated object, and did not mention that ``deprecated`` is a class whose instances expose the constructor arguments (``message``, ``category`` and ``stacklevel``) as attributes of the same names -- a part of the API that downstream projects rely on. Document these attributes, and rename the first parameter in the signature from ``msg`` to ``message`` to match the implementation and the attribute. --- Doc/library/warnings.rst | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/Doc/library/warnings.rst b/Doc/library/warnings.rst index 9063bea96ccb0a..42a60f8bc93da5 100644 --- a/Doc/library/warnings.rst +++ b/Doc/library/warnings.rst @@ -566,7 +566,7 @@ Available Functions and calls to :func:`simplefilter`. -.. decorator:: deprecated(msg, *, category=DeprecationWarning, stacklevel=1) +.. decorator:: deprecated(message, *, category=DeprecationWarning, stacklevel=1) Decorator to indicate that a class, function or overload is deprecated. @@ -612,6 +612,18 @@ Available Functions for the attribute to exist on the overload as returned by :func:`typing.get_overloads`. + ``deprecated`` is implemented as a class, so applying it (for example, + ``deprecated("Use B instead")``) returns an instance that acts as the + decorator. The arguments passed to it are available as attributes of the + same names on that instance: + + * ``message``: the deprecation message (a :class:`str`; a + :exc:`TypeError` is raised if it is not). + * ``category``: the warning category, or ``None`` if no runtime warning + should be emitted. + * ``stacklevel``: the number of stack frames to skip when emitting the + warning (an :class:`int`). + .. versionadded:: 3.13 See :pep:`702`. From 292000f25ec5f25daa2b749be62e89f8a3873d29 Mon Sep 17 00:00:00 2001 From: Vyron Vasileiadis Date: Sun, 19 Jul 2026 16:30:20 +0300 Subject: [PATCH 2/3] gh-150076: Don't document warnings.deprecated internals as public API The paragraph described deprecated as a class exposing its constructor arguments as message, category and stacklevel attributes. Neither PEP 702 nor the typing spec guarantees this, so documenting it would turn an implementation detail into a permanent API commitment. Drop it and keep only the msg -> message signature fix, which matches the actual positional-only parameter. --- Doc/library/warnings.rst | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/Doc/library/warnings.rst b/Doc/library/warnings.rst index 42a60f8bc93da5..a8741245ec5d43 100644 --- a/Doc/library/warnings.rst +++ b/Doc/library/warnings.rst @@ -612,18 +612,6 @@ Available Functions for the attribute to exist on the overload as returned by :func:`typing.get_overloads`. - ``deprecated`` is implemented as a class, so applying it (for example, - ``deprecated("Use B instead")``) returns an instance that acts as the - decorator. The arguments passed to it are available as attributes of the - same names on that instance: - - * ``message``: the deprecation message (a :class:`str`; a - :exc:`TypeError` is raised if it is not). - * ``category``: the warning category, or ``None`` if no runtime warning - should be emitted. - * ``stacklevel``: the number of stack frames to skip when emitting the - warning (an :class:`int`). - .. versionadded:: 3.13 See :pep:`702`. From a64f941ba78a0dc8eed7781e8c5e87a943cd1f57 Mon Sep 17 00:00:00 2001 From: Vyron Vasileiadis Date: Sun, 19 Jul 2026 17:19:31 +0300 Subject: [PATCH 3/3] Update Doc/library/warnings.rst Co-authored-by: Jelle Zijlstra --- Doc/library/warnings.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/warnings.rst b/Doc/library/warnings.rst index a8741245ec5d43..d5f89102d5853b 100644 --- a/Doc/library/warnings.rst +++ b/Doc/library/warnings.rst @@ -566,7 +566,7 @@ Available Functions and calls to :func:`simplefilter`. -.. decorator:: deprecated(message, *, category=DeprecationWarning, stacklevel=1) +.. decorator:: deprecated(message, /, *, category=DeprecationWarning, stacklevel=1) Decorator to indicate that a class, function or overload is deprecated.