Skip to content

Add explicit signatures for pyplot.{polar,savefig,set_loglevel} #30200

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.

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

Merged
merged 13 commits into from
Jun 30, 2025

Conversation

ZPyrolink
Copy link
Contributor

@ZPyrolink ZPyrolink commented Jun 21, 2025

PR summary

This PR update lib/matplotlib/pyplot.pyto replace *args, **kwargs with the real signature for the following methods:

  • savefig
  • set_loglevel
  • polar

PR checklist

@ZPyrolink ZPyrolink changed the title Pyplot signatures Pyplot explicit signature Jun 21, 2025
Copy link
Member

@timhoffm timhoffm left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor suggestions, but I'm fine either way.

@melissawm melissawm moved this to Waiting for author in First Time Contributors Jun 23, 2025
@QuLogic QuLogic changed the title Pyplot explicit signature Add explicit signatures for pyplot.{polar,savefig,set_loglevel} Jun 23, 2025
@ZPyrolink
Copy link
Contributor Author

You are right, however, changing the signature would break the added test that was created (because it's tied to the plot signature for consistency). That's why I chose to implement it this way.

@timhoffm
Copy link
Member

timhoffm commented Jun 24, 2025

Looking at the polar code agian, we should rather modify the signature to become plt.polar(r, theta, fmt=None, /, **kwargs), as the call signature in the docstring already describes. The polar() function is conceptually not really a straight forwarding function. It generally does not make sense to specify polar(r), which technically is possible, resulting in a non-meaningful interger-range theta. Also the matlab inspired syntax polar(r, thetha, r2, theta2) is luckily almost never used.
polar() is not a wrapper, but rather a function that uses plot() internally as an implementation detail. Therefore, no signature consistency check is needed.

This will be for a separate PR, so please revert the polar change here. Technically, we first need to deprecate other signatures by checking that *args has two or three elements and if not warn_deprecated(). When the deprecation expires, we can write out the signature.

Copy link
Member

@timhoffm timhoffm left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please revert the polar part as discussed above.

@ZPyrolink
Copy link
Contributor Author

Reverted as requested 👍

Co-authored-by: Elliott Sales de Andrade <quantum.analyst@gmail.com>
@@ -484,3 +486,71 @@ def test_matshow():

# Smoke test that matshow does not ask for a new figsize on the existing figure
plt.matshow(arr, fignum=fig.number)


def assert_signatures_identical(plt_meth, original_meth, remove_self_param=False):
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don’t have time to check the details, but this functions seems quite heavy-weight now that we only check the really simple function set_loglevel. Do we really bread/want that complexity?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is a bit complex; we could extend the test to cover additional things in a later PR like plt.rc, plt.getp, plt.figlegend, plt.imread, plt.imsave, and maybe some others, but that does hit some limitations; I think the test as written doesn't handle overloads, and making it do that also might be more trouble than it's worth.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, I see. The complexity arises from ensuring identical typing.

As long as it's only about set_loglevel(), it would be sufficient for me to check identical names and numbers of arguments. That ensures identical runtime behavior. At the same time, this is probably the biggest risk: We modify the signature (renaming, adding arguments) and don't sync that. It's rather unlikely that we change the declared types - and even if that'd happen it's only a type-checking issue not a runtime issue.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have replaced with a low cost check. In addition to the names and numbers, I also check the kinds.

… parameters) with assert_same_signature (only check len(parameters), names and kinds)
Copy link
Member

@timhoffm timhoffm left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, this looks much better in terms of matching simplicity with the test goals. Only a minor naming suggestion remains.

@QuLogic QuLogic added this to the v3.11.0 milestone Jun 27, 2025
@QuLogic QuLogic moved this from Waiting for author to Needs review in First Time Contributors Jun 27, 2025
@QuLogic QuLogic merged commit 0e430b9 into matplotlib:main Jun 30, 2025
40 checks passed
@github-project-automation github-project-automation bot moved this from Needs review to Waiting for author in First Time Contributors Jun 30, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
Status: Waiting for author
Development

Successfully merging this pull request may close these issues.

[MNT]: pyplot type hints
4 participants