Repository navigation
The great API cleanup #16181
Description
As discussed in the last call, technically public (i.e. not flagged as private with an underscore), but semantically internal API makes it hard to change anything in Matplotlib.
I propose to set a focus on reducing the API footprint for 3.3. With our current deprecation policy, we could remove that stuff from master once 3.4 is out, which should be towards the end of this year.
In particular:
-
Turn most parameters into keyword-only arguments. Depending on the function 0 to maybe 4 positional parameters should stay. Deprecations will be handled via
@cbook._make_keyword_only(). This needs one of the approaches Add decorator to inherit keyword-only deprecations #14130 or Propagate signature-modifying decorators to pyplot wrappers. #15254 to go in so that deprecations on Axes methods are also warned about in the pyplot wrappers. -
Make more functions and methods private
-
Make more modules private. e.g. (not necessary complete):
-
afm -
blocking_input -
docstring -
dviread -
font_manager -
fontconfig_pattern -
hatch -
legend_handler -
mathtext -
texmanager -
tight_bbox -
tight_layout -
type1font
-
-
Mechanism to deprecate whole modules:
- Move the exising module
git mv my_module.py _my_module.pyand put this into a commit. - Create a new
my_module.pywith the content:
from matplotlib._my_module import * from matplotlib import _api _api.warn_deprecated("3.3", f"The module {__name__} is deprecated")and add this in a second commit.
It is important to have the move in a separate commit to maintain the history of that code. If put together in one commit, git thinks we added
_my_module.pyand modifiedmy_module.py. Then, we could not go back in history for the moved code. - Move the exising module
-
[DONE] Move all the internal
cbookfunctions to (a/multiple) private module(s).from matplotlib import _api @_api.deprecated("3.2") def compare_versions(a, b):reads better than the current
from matplotlib import cbook @cbook._deprecated("3.2") def compare_versions(a, b):and it does not pollute the namespace with the public package name.
-
Rename
camelCasetocamel_case(when not too public; e.g.rcParamsmust stay). -
Internally use
import mplandmpl.rcParamsinstead offrom matplotlib import rcParamsandrcParams. - Partially addressed in Don't import rcParams but rather use mpl.rcParams. #16406. -
remove the obscure function
pyplot.plotting(), which is used as a container for the pyplot docstring.
Activity
anntzer commentedon Jan 11, 2020
Also privatize ft2font, our freetype2 bindings (there's freetype-py that's installable from PyPI for third-party users, though it's not usable for us as it's ctypes-based). The tricky part here is not so much making it private, but making sure that there's no public API that leak a FT2Font (or FT2Image) object to the user.
ImportanceOfBeingErnest commentedon Jan 11, 2020
IMO,
font_managerandlegend_handlershould stay public. Both provide classes/functions that is quite useful.Any text accepts
fontproperties, which the user probably wants to instantiate viamatplotlib.font_manager.FontProperties; there are also many usecases formatplotlib.font_manager.FontManager,matplotlib.font_manager.findSystemFontsand matplotlib.font_manager.get_font`. The matplotlib logo uses some of them.The classes in
legend_handlerare meant to be used with the legend'shandler_mapargument as shown in the legend guide.anntzer commentedon Jan 11, 2020
The fontproperties API is quite clunky; even if some of it stays public we should try to make it so that most users don't have to instantiate a FontProperties explicitly, see e.g. the proposed "end-result" in #10249.
QuLogic commentedon May 23, 2020
Many things are private now, but I don't think this, as a whole, will be done for 3.3.
timhoffm commentedon May 23, 2020
This issue is rather thought to be a strategic suggestion how to evolve the existing API. I originally intended to address it in a coordinated series of PR so that we have one release with more API changes instead of continuously changing parts over various releases.
As far as I have an overview, the "many things" are mainly methods and attributes. This is only bullet point 2 (and only parts thereof) of the list above. Most is still to be done. I have no problem moving this to 3.4.
anntzer commentedon Aug 18, 2021
edited the list of modules: blocking_input has been deprecated.
oscargus commentedon Jan 6, 2022
Not allowed to edit, but
mathtextcan probably be considered done now (at least after #22107 ).timhoffm commentedon Jan 6, 2022
Thanks, I've marked
mathtextas done.oscargus commentedon Jan 6, 2022
I checked around a bit and it seems like there are packages using
hatch. Also, isn't it the case that it is needed for doing custom hatches? I saw some usage of it.(I'm sure you've had a thorough discussion, but just searching the whole of github gave quite a few examples of where
matplotlib.hatchis imported in non-mpl projects. As opposed to e..gtype1font, which is the next I'm deprecating.)dopplershift commentedon Jan 6, 2022
@oscargus See #20690 for more on custom hatches.
timhoffm commentedon Jan 6, 2022
@oscargus we had a discussion on this in the dev call and decided that
hatchshould stay public for now.oscargus commentedon Mar 21, 2022
As discussed in #22127 it is not obvious which parts of dviread and texmanager that should be deprecated, if any.
With the recent merging of #22148 it means that everything on the list is deprecated and that this can be closed!(?)