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.