Thanks to visit codestin.com
Credit goes to github.com

Skip to content

[Doc]: add examples of what each type deprecation means #27456

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
story645 opened this issue Dec 6, 2023 · 3 comments
Open

[Doc]: add examples of what each type deprecation means #27456

story645 opened this issue Dec 6, 2023 · 3 comments
Labels
Documentation: devdocs files in doc/devel

Comments

@story645
Copy link
Member

story645 commented Dec 6, 2023 •
edited
Loading

Documentation Link

https://matplotlib.org/devdocs/devel/api_changes.html#deprecation

Problem

The deprecation docs are fairly terse in terms of which decorator gets applied where/how.

Suggested improvement

@QuLogic had a really nice write up with examples of how to do deprecation in #26865 and I think it'd be great to fold that into our deprecation guide.

Especially if deprecation is gonna be a standing sprint/good first issue, it's nice to be able to point to a page in docs and not have it mixed up w/ issue information;.
@story645 story645 added the Documentation: devdocs files in doc/devel label Dec 6, 2023
@anntzer
Copy link
Contributor

anntzer commented Dec 7, 2023

Especially if deprecation is gonna be a standing sprint/good first issue

Hopefully only expiring deprecations can be made a standing sprint/good first issue.

@tacaswell
Copy link
Member

To be clear, the examples in #26865 are about expiring not adding deprecations. Having done it once, I am not sure I would want to use expiring deprecations as a sprint issue again.

The helpers mentioned are well documented in the source (e.g.

matplotlib/lib/matplotlib/_api/deprecation.py

Lines 50 to 91 in 7ba90fe

def warn_deprecated(
since, *, message='', name='', alternative='', pending=False,
obj_type='', addendum='', removal=''):
"""
Display a standardized deprecation.
Parameters
----------
since : str
The release at which this API became deprecated.
message : str, optional
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 : str, optional
The name of the deprecated object.
alternative : str, optional
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.
pending : bool, optional
If True, uses a PendingDeprecationWarning instead of a
DeprecationWarning. Cannot be used together with *removal*.
obj_type : str, optional
The object type being deprecated.
addendum : str, optional
Additional text appended directly to the final message.
removal : str, optional
The expected removal version. With the default (an empty string), a
removal version is automatically computed from *since*. Set to other
Falsy values to not schedule a removal date. Cannot be used together
with *pending*.
Examples
--------
::
# To warn of the deprecation of "matplotlib.name_of_module"
warn_deprecated('1.4.0', name='matplotlib.name_of_module',
obj_type='module')
"""
) but we do not put them in the html docs (which I think is a reasonable choice, we really do not want people outside of our code base to use these). I also do not think it is too big of a lift to expect someone who is adding a deprecation to find an existing use in the code base / git history if they want to find an example usage.

On net I think this is sufficiently documented for its audience.

@story645
Copy link
Member Author

story645 commented Dec 7, 2023 •
edited
Loading

but we do not put them in the html docs

https://matplotlib.org/stable/devel/contribute.html#expire-deprecation

Though I would argue to document them in the docs if you don't want to expand this section of the docs.

also do not think it is too big of a lift to expect someone who is adding a deprecation to find an existing use in the code base / git history if they want to find an example usage.

The advantage of @QuLogic's write up, and integrating it into the docs, is that it's got framing/context + example. What is the benefit of making them chase down an example that they may not be sure is a good example?

ETA: also my thinking on this is that this is already written to serve a need & not having it is more likely to either mean folks bounce cause they're not sure where to start or they ask us these questions and we ad-hoc write this guide.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Documentation: devdocs files in doc/devel
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
3 participants
@tacaswell @story645 @anntzer