gh-150076: Fix the documented signature of warnings.deprecated#153879
Conversation
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.
Documentation build overview
45 files changed ·
|
|
Documenting this like that makes it an implementation-detail IMO. For context, can you look at the related PEP (there seems to be one) please? and check for past discussions. Exposing an implementation details opens cans of worms that we usually want to keep closed. |
|
@zware part of EuroPython sprint. |
…ic 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.
Thanks, I looked into it. You're right that PEP 702 only guarantees the deprecated attribute on the decorated object. It doesn't require deprecated to be a class and doesn't mention the message, category or stacklevel attributes, and the typing spec even says the runtime category/stacklevel behaviour is out of scope. So documenting those attributes would turn an implementation detail into a permanent API commitment, which isn't what this PR should do. I've dropped that paragraph. The PR is now just the msg -> message signature fix, so the documented parameter matches the actual positional-only parameter in the implementation. That part is a straightforward correctness fix with no API implications, so I think it's good to merge as is. The separate question of whether the class and its attributes should become guaranteed public API (typeshed and Pydantic already rely on them) really belongs in the typing spec, so I'm happy to take that up there rather than hold this fix. |
|
Please update the PR title and description then. I don't think we want to document the implementation being a class, but we can do it in a separate PR. But we can ask @JelleZijlstra |
fedonman
changed the title
warnings.deprecated
|
done |
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
JelleZijlstra
added
needs backport to 3.13
|
Thanks @fedonman for the PR, and @JelleZijlstra for merging it 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14, 3.15. |
|
GH-154487 is a backport of this pull request to the 3.15 branch. |
bedevere-app
Bot
removed
the
needs backport to 3.15
|
GH-154488 is a backport of this pull request to the 3.14 branch. |
|
GH-154489 is a backport of this pull request to the 3.13 branch. |
…GH-153879) (#154489) gh-150076: Fix the documented signature of warnings.deprecated (GH-153879) (cherry picked from commit 56ad3bc) Co-authored-by: Vyron Vasileiadis <hi@fedonman.com> Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
…GH-153879) (#154488) gh-150076: Fix the documented signature of warnings.deprecated (GH-153879) (cherry picked from commit 56ad3bc) Co-authored-by: Vyron Vasileiadis <hi@fedonman.com> Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
…GH-153879) (#154487) gh-150076: Fix the documented signature of warnings.deprecated (GH-153879) (cherry picked from commit 56ad3bc) Co-authored-by: Vyron Vasileiadis <hi@fedonman.com> Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
4 participants
The documented signature for warnings.deprecated used msg as the first parameter, but the implementation names it message and it is positional-only. This updates the documented signature to match.
An earlier version of this PR also documented that deprecated is a class whose instances expose message, category and stacklevel attributes. As discussed in review, that is not guaranteed by PEP 702 or the typing spec, so documenting it would turn an implementation detail into a permanent API commitment. I dropped that part. Whether those attributes should become guaranteed public API is a separate question that belongs in the typing spec.
warnings.deprecatedpublic API #150076