Thanks to visit codestin.com
Credit goes to github.com

Skip to content

The great API cleanup #16181

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
8 of 13 tasks
timhoffm opened this issue Jan 11, 2020 · 12 comments
Closed
8 of 13 tasks

The great API cleanup #16181

timhoffm opened this issue Jan 11, 2020 · 12 comments
Labels
API: changes Maintenance
Milestone
v3.6.0

Comments

@timhoffm
Copy link
Member

timhoffm commented Jan 11, 2020 •
edited by oscargus
Loading

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.
@timhoffm timhoffm added this to the v3.3.0 milestone Jan 11, 2020
@anntzer
Copy link
Contributor

anntzer commented 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
Copy link
Member

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
Copy link
Contributor

anntzer commented 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.

This was referenced Feb 15, 2020
Merged
Merged
@timhoffm timhoffm mentioned this issue Mar 15, 2020
Merged
@timhoffm timhoffm mentioned this issue Apr 7, 2020
Merged
6 tasks
@SidharthBansal SidharthBansal mentioned this issue Apr 7, 2020
Closed
6 tasks
@QuLogic
Copy link
Member

QuLogic commented May 23, 2020

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

@QuLogic QuLogic modified the milestones: v3.3.0, v3.4.0 May 23, 2020
@timhoffm
Copy link
Member Author

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 anntzer mentioned this issue Aug 30, 2020
Merged
7 tasks
This was referenced Sep 16, 2020
Merged
Merged
@QuLogic QuLogic modified the milestones: v3.4.0, v3.5.0 Jan 27, 2021
@QuLogic QuLogic modified the milestones: v3.5.0, v3.6.0 Aug 18, 2021
@anntzer
Copy link
Contributor

anntzer commented Aug 18, 2021

edited the list of modules: blocking_input has been deprecated.

@oscargus
Copy link
Member

oscargus commented Jan 6, 2022

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

@oscargus oscargus mentioned this issue Jan 6, 2022
Closed
4 tasks
@timhoffm
Copy link
Member Author

timhoffm commented Jan 6, 2022

Thanks, I've marked mathtext as done.

@oscargus
Copy link
Member

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

This was referenced Jan 6, 2022
Merged
Merged
@dopplershift
Copy link
Contributor

@oscargus See #20690 for more on custom hatches.

@timhoffm
Copy link
Member Author

timhoffm commented Jan 6, 2022

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

@oscargus oscargus mentioned this issue Jan 7, 2022
Merged
3 tasks
@oscargus
Copy link
Member

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

@timhoffm timhoffm mentioned this issue Aug 19, 2022
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
API: changes Maintenance
Projects
None yet
Milestone
v3.6.0
Development

No branches or pull requests
6 participants
@dopplershift @QuLogic @anntzer @timhoffm @oscargus @ImportanceOfBeingErnest