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 approachesAdd decorator to inherit keyword-only deprecations #14130 orPropagate 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 modulegit mv my_module.py _my_module.py and put this into a commit.
  2. Create a newmy_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 modifiedmy_module.py. Then, we could not go back in history for the moved code.

• [DONE] Move all the internalcbook 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.

• RenamecamelCase tocamel_case (when not too public; e.g.rcParams must stay).

• Internally useimport mpl andmpl.rcParams instead offrom matplotlib import rcParams andrcParams. - Partially addressed inDon't import rcParams but rather use mpl.rcParams. #16406.

• remove the obscure functionpyplot.plotting(), which is used as a container for the pyplot docstring.