The great API cleanup

[timhoffm]

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:

  1. Move the exising module git mv my_module.py _my_module.py and put this into a commit.
  2. Create a new my_module.py with 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.py and modified my_module.py. Then, we could not go back in history for the moved code.

• [DONE] Move all the internal cbook functions 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 camelCase to camel_case (when not too public; e.g. rcParams must stay).

• Internally use import mpl and mpl.rcParams instead of from matplotlib import rcParams and rcParams. - 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.

[anntzer]

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]

IMO, font_manager and legend_handler should stay public. Both provide classes/functions that is quite useful.

• Any text accepts fontproperties, which the user probably wants to instantiate via matplotlib.font_manager.FontProperties; there are also many usecases for matplotlib.font_manager.FontManager, matplotlib.font_manager.findSystemFonts and matplotlib.font_manager.get_font`. The matplotlib logo uses some of them.

• The classes in legend_handler are meant to be used with the legend's handler_map argument as shown in the legend guide.

[anntzer]

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]

Many things are private now, but I don't think this, as a whole, will be done for 3.3.

[timhoffm]

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.

Many things are private now, but I don't think this, as a whole, will be done for 3.3.

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]

edited the list of modules: blocking_input has been deprecated.

[oscargus]

Not allowed to edit, but mathtext can probably be considered done now (at least after #22107 ).

[timhoffm]

Thanks, I've marked mathtext as done.

[oscargus]

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.hatch is imported in non-mpl projects. As opposed to e..g type1font, which is the next I'm deprecating.)

[dopplershift]

@oscargus See #20690 for more on custom hatches.

[timhoffm]

@oscargus we had a discussion on this in the dev call and decided that hatch should stay public for now.

[oscargus]

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!(?)