Skip to content

Commit 2808916

Browse files
timhoffmtimhoffm
authored
Merge pull request #18657 from timhoffm/move-deprecation
Move cbook.deprecation to _api.deprecation
2 parents 868504e + aec6841 commit 2808916

File tree

17 files changed

+615
-568
lines changed

17 files changed

+615
-568
lines changed

‎.flake8

+1
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,7 @@ per-file-ignores =
5858
lib/matplotlib/backends/backend_*.py: F401
5959
lib/matplotlib/backends/qt_editor/formlayout.py: F401, F403
6060
lib/matplotlib/cbook/__init__.py: F401
61+
lib/matplotlib/cbook/deprecation.py: F401
6162
lib/matplotlib/font_manager.py: E221, E251, E501
6263
lib/matplotlib/image.py: F401, F403
6364
lib/matplotlib/lines.py: F401

‎doc/api/_api_api.rst

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
*******************
2+
``matplotlib._api``
3+
*******************
4+
5+
.. automodule:: matplotlib._api
6+
:members:
7+
:undoc-members:
8+
:show-inheritance:
9+
10+
.. automodule:: matplotlib._api.deprecation
11+
:members:
12+
:undoc-members:
13+
:show-inheritance:

‎doc/api/cbook_api.rst

-5
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,3 @@
66
:members:
77
:undoc-members:
88
:show-inheritance:
9-
10-
.. automodule:: matplotlib.cbook.deprecation
11-
:members:
12-
:undoc-members:
13-
:show-inheritance:

‎doc/api/index.rst

+1
Original file line numberDiff line numberDiff line change
@@ -126,6 +126,7 @@ Matplotlib consists of the following submodules:
126126
type1font.rst
127127
units_api.rst
128128
widgets_api.rst
129+
_api_api.rst
129130

130131
Toolkits
131132
--------

‎doc/api/next_api_changes/deprecations/18657-TH.rst

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
``matplotlib.cbook.deprecation`` is deprecated
2+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3+
The module is considered internal and will be removed from the public API.

‎doc/api/prev_api_changes/api_changes_3.0.0.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -405,7 +405,7 @@ The following classes, methods, functions, and attributes are deprecated:
405405
- ``textpath.TextToPath.tex_font_map``
406406
- ``matplotlib.cbook.deprecation.mplDeprecation`` will be removed
407407
in future versions. It is just an alias for
408-
:class:`matplotlib.cbook.deprecation.MatplotlibDeprecationWarning`. Please
408+
``matplotlib.cbook.deprecation.MatplotlibDeprecationWarning``. Please
409409
use ``matplotlib.cbook.MatplotlibDeprecationWarning`` directly if necessary.
410410
- The ``matplotlib.cbook.Bunch`` class has been deprecated. Instead, use
411411
`types.SimpleNamespace` from the standard library which provides the same

‎doc/api/prev_api_changes/api_changes_3.1.0.rst

+8-8
Original file line numberDiff line numberDiff line change
@@ -767,12 +767,12 @@ The following signature related behaviours are deprecated:
767767
keyword.
768768
- The *interp_at_native* parameter to `.BboxImage`, which has had no effect
769769
since Matplotlib 2.0, is deprecated.
770-
- All arguments to the `~.cbook.deprecation.deprecated` decorator and
771-
`~.cbook.deprecation.warn_deprecated` function, except the first one (the
772-
version where the deprecation occurred), are now keyword-only. The goal is
773-
to avoid accidentally setting the "message" argument when the "name" (or
774-
"alternative") argument was intended, as this has repeatedly occurred in the
775-
past.
770+
- All arguments to the ``matplotlib.cbook.deprecation.deprecated`` decorator
771+
and ``matplotlib.cbook.deprecation.warn_deprecated`` function, except the
772+
first one (the version where the deprecation occurred), are now keyword-only.
773+
The goal is to avoid accidentally setting the "message" argument when the
774+
"name" (or "alternative") argument was intended, as this has repeatedly
775+
occurred in the past.
776776
- The arguments of `matplotlib.testing.compare.calculate_rms` have been renamed
777777
from ``expectedImage, actualImage``, to ``expected_image, actual_image``.
778778
- Passing positional arguments to `.Axis.set_ticklabels` beyond *ticklabels*
@@ -1076,8 +1076,8 @@ Undeprecations
10761076
--------------
10771077
The following API elements have been un-deprecated:
10781078

1079-
- The *obj_type* keyword argument to the `~.cbook.deprecation.deprecated`
1080-
decorator.
1079+
- The *obj_type* keyword argument to the
1080+
``matplotlib.cbook.deprecation.deprecated`` decorator.
10811081
- *xmin*, *xmax* keyword arguments to `.Axes.set_xlim` and *ymin*, *ymax*
10821082
keyword arguments to `.Axes.set_ylim`
10831083

‎doc/devel/contributing.rst

+8-8
Original file line numberDiff line numberDiff line change
@@ -511,7 +511,7 @@ There are five levels at which you can emit messages.
511511

512512
- `logging.critical` and `logging.error` are really only there for errors that
513513
will end the use of the library but not kill the interpreter.
514-
- `logging.warning` and `.cbook._warn_external` are used to warn the user,
514+
- `logging.warning` and `._api.warn_external` are used to warn the user,
515515
see below.
516516
- `logging.info` is for information that the user may want to know if the
517517
program behaves oddly. They are not displayed by default. For instance, if
@@ -527,16 +527,16 @@ By default, `logging` displays all log messages at levels higher than
527527
``logging.WARNING`` to `sys.stderr`.
528528

529529
The `logging tutorial`_ suggests that the difference between `logging.warning`
530-
and `.cbook._warn_external` (which uses `warnings.warn`) is that
531-
`.cbook._warn_external` should be used for things the user must change to stop
530+
and `._api.warn_external` (which uses `warnings.warn`) is that
531+
`._api.warn_external` should be used for things the user must change to stop
532532
the warning (typically in the source), whereas `logging.warning` can be more
533-
persistent. Moreover, note that `.cbook._warn_external` will by default only
533+
persistent. Moreover, note that `._api.warn_external` will by default only
534534
emit a given warning *once* for each line of user code, whereas
535535
`logging.warning` will display the message every time it is called.
536536

537537
By default, `warnings.warn` displays the line of code that has the ``warn``
538538
call. This usually isn't more informative than the warning message itself.
539-
Therefore, Matplotlib uses `.cbook._warn_external` which uses `warnings.warn`,
539+
Therefore, Matplotlib uses `._api.warn_external` which uses `warnings.warn`,
540540
but goes up the stack and displays the first line of code outside of
541541
Matplotlib. For example, for the module::
542542

@@ -559,13 +559,13 @@ will display::
559559
UserWarning: Attempting to set identical bottom==top
560560
warnings.warn('Attempting to set identical bottom==top')
561561

562-
Modifying the module to use `.cbook._warn_external`::
562+
Modifying the module to use `._api.warn_external`::
563563

564-
from matplotlib import cbook
564+
from matplotlib import _api
565565

566566
def set_range(bottom, top):
567567
if bottom == top:
568-
cbook._warn_external('Attempting to set identical bottom==top')
568+
_api.warn_external('Attempting to set identical bottom==top')
569569

570570
and running the same script will display::
571571

‎lib/matplotlib/_api.py renamed to ‎lib/matplotlib/_api/__init__.py

+37
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,19 @@
1+
"""
2+
Helper functions for managing the Matplotlib API.
3+
4+
This documentation is only relevant for Matplotlib developers, not for users.
5+
6+
.. warning:
7+
8+
This module and its submodules are for internal use only. Do not use them
9+
in your own code. We may change the API at any time with no warning.
10+
11+
"""
12+
113
import itertools
14+
import re
15+
import sys
16+
import warnings
217

318

419
def check_in_list(_values, *, _print_supported_values=True, **kwargs):
@@ -93,3 +108,25 @@ def check_getitem(_mapping, **kwargs):
93108
raise ValueError(
94109
"{!r} is not a valid value for {}; supported values are {}"
95110
.format(v, k, ', '.join(map(repr, mapping)))) from None
111+
112+
113+
def warn_external(message, category=None):
114+
"""
115+
`warnings.warn` wrapper that sets *stacklevel* to "outside Matplotlib".
116+
117+
The original emitter of the warning can be obtained by patching this
118+
function back to `warnings.warn`, i.e. ``_api.warn_external =
119+
warnings.warn`` (or ``functools.partial(warnings.warn, stacklevel=2)``,
120+
etc.).
121+
"""
122+
frame = sys._getframe()
123+
for stacklevel in itertools.count(1): # lgtm[py/unused-loop-variable]
124+
if frame is None:
125+
# when called in embedded context may hit frame is None
126+
break
127+
if not re.match(r"\A(matplotlib|mpl_toolkits)(\Z|\.(?!tests\.))",
128+
# Work around sphinx-gallery not setting __name__.
129+
frame.f_globals.get("__name__", "")):
130+
break
131+
frame = frame.f_back
132+
warnings.warn(message, category, stacklevel)

0 commit comments

Comments
 (0)