gh-150076: Fix the documented signature of warnings.deprecated#153879
gh-150076: Fix the documented signature of warnings.deprecated#153879fedonman wants to merge 5 commits into
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
29 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>
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