ENH: add `ax` kwarg to every pyplot function by tacaswell · Pull Request #9111 · matplotlib/matplotlib · GitHub

This allows passing ax=some_ax into all of the pyplot plotting
functions.

PR Checklist

Has Pytest style unit tests
Code is PEP 8 compliant
New features are documented, with examples if plot related
Documentation is sphinx and numpydoc compliant
Added an entry to doc/users/next_whats_new/ if major new feature (follow instructions in README.rst there)

What's the benefit as opposed to just using the OO API, if you really want to specify the figure/axis?

This is the opening pass at something I have been thinking about for a while.

The very short version is that there is currently a major difference between 'built in' plotting (ax.foo(data, style)) and user / third-party plotting (foo(data, style, ax=ax)) and it would be better to reduce. As we do not want third-party tools to be monkey-patching methods on to Axes, we should rotate the main API to look more like functions to put everything on the same footing. The suggested API would then be

def my_plotter(*data, ax, **style):
   ...

This is bread-crumbs leading that direction.

This actually looks like a reasonable argument (as much as I would like not to admit it...)

Yeah, this is pretty much the same proposal from a few years ago that got sidelined to focus on getting the data kwarg into the v1.5 release, isn't it? I totally get the argument, I just don't know how well I like that coding style. Feels very basemap-ish. Whatever happened to the idea of plotting objects?

…

On Mon, Aug 28, 2017 at 11:37 AM, Antony Lee ***@***.***> wrote: This actually looks like a reasonable argument (as much as I would like not to admit it...) — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#9111 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AARy-N7mVbidz89QregvZ__Vt6Tz1ch1ks5sct6mgaJpZM4PEATz> .

In general I'm ok with the idea. I do think we should think about the idea of plotting objects in this context before proceeding, though.

Also what's wrong with just using sca() in that case?
Or even

with plt.sca(ax): ...

which is probably going to be less repetitive that having to pass ax again and again.

If for no other reason than that this allows using the pyplot interface with an explicit axes, I'm 💯 on this.

I think that this and more complex objects are orthogonal. The objects are about making more complex plots easier to update and work with (ex errorbars) and this is about letting third-party code, or code that takes in not-arrays as input feel like first class citizens next to the 'official'.

I expect there to be plotting functions that take in very non-array things (like a partial sql query!).

It also provides a smoother path to leaving the fully implicit world to the full OO world.

This is actually pass 2 at this, see #4488

I would just test that len(ax1.lines) == 2 instead of doing an image comp.

test name has typo ("explicit")

There should be one line per axes (gca() is surprising! ax2 was created last so it is 'current')

you got me :-)
but still you should be able to just test how many lines there are on each axis.

Done

the comment above needs to be updated
side point: I think we should just throw an exception in this case -- the parameter name is part of the API so renaming it seems silly

I was suggesting to do the same for washold and ret below.

Even if this turns out to be the way to go, bringing in such a major strategic change with so little discussion and review is not good. Suggestion: leave this out of 2.1, and make it the proposed centerpiece of 2.2, with a very short release cycle--say, Nov. 1 as the target.

It was worth a shot!

I am taking @efiring 's comment as a veto of this going in for 2.1.

Delaying to 2.2 in Nov would give us time to write some collateral around this change, flesh out some of the other implications, and retroactively write a MEP which is probably for the best

Having though a bit about this, right now I belive my preferred take on such an API ("to make pyplot and external functions more symmetrical") would be

with plt.sca(ax): # or a new function
    plt.plot(...)
    seaborn.somemethod(...)
# when sca() is *exited* there is *no* current axes,
# so plt.gca() would return None and plt.plot would error

which seems better than having to pass the same ax again and again.

However this means inside of every function there must be a call to plt.gca(). The other long term goal is to get away from the shared global state of pyplot (so everything GC's reasonable, etc).

Having no current figure/ax is a non-starter. pyplot (and all of it's shared global state) exists as convince methods for people sitting in an interactive shell and I do not think we will ever be able to remove it, just make it possible for people to use without it.

Having a context manager that resets the current axes to what it was before would be a reasonable thing though.

XXX(..., ax=ax) is not that much more onerous than ax.XXX(...)

In terms of code, this looks good, but the PR introduces a backward incompatible change.

On the documentation front, a lot of the docstrings need to be updated to reflect the addition of an optional keyword argument. I'm happy to push the missing documentation.

I'm also concerned about the unit tests. While indeed, this has been tested on one of the pyplot function, I think we should maybe write smoke tests coverage all pyplot functions concerned by this change.

This will fail if args has more arguments than one. If args is can only be one optional argument, why not change *args into an actual optional keyword argument? That would make the code more readible, and more easily documentable than currently.

Note that because of this line we are currently introducing a backward compatible change with this PR.

The docstring needs to be update to reflect the addition of an optional keyword argument.

👍

The docstring needs to be update to reflect the addition of an optional keyword argument.

rebased to keep the dream alive.

Since this Pull Request has not been updated in 60 days, it has been marked "inactive." This does not mean that it will be closed, though it may be moved to a "Draft" state. This helps maintainers prioritize their reviewing efforts. You can pick the PR back up anytime - please ping us if you need a review or guidance to move the PR forward! If you do not plan on continuing the work, please let us know so that we can either find someone to take the PR over, or close it.

As a side-note: The place where the ax keyword is most present is the pandas plot API. Unfortunately, they have a different semantic (“if not given, create a new axes” vs. pyplot: “if not given, use the current axes - only if there is no current axes, create a new one).
Not necessarily a blocker, but we have to be aware that this will be a source of confusion.

I've marked this as keep and needs comment/discussion because it really something to investigate, but the correct approach is not yet clear.

This allows passing `ax=some_ax` or `fig=some_fig` into all of the pyplot plotting functions.

I could not quickly figure out how to convince the generated annotations to not use the fully qualified class names.

Bit confused why it was not hitting these before.

mypy is still also a bit unhappy (it does not like forwarding returns through unconditionally...I guess the fix would be to make the generating code smart enough to drop the return if the wrapped function claims to only ever return None.

This has significantly bit-rotted. I still think this is a good idea, but will close for now.

Thanks for contributing this improvement! Adding ax as an implicit input to pyplot functions looks useful for making the API more consistent. I’ll be interested to see how this behaves across different plotting functions and whether the tests cover the expected behavior. Great work!

@gargcodes2006 please not that this is not implemented right now.

tacaswell added this to the 2.1 (next point release) milestone Aug 28, 2017

tacaswell force-pushed the ENH_ax_into_pyplot branch from e95b2b8 to 4d4662e Compare August 28, 2017 02:17

dopplershift approved these changes Aug 28, 2017

View reviewed changes

tacaswell added the Release critical For bugs that make the library unusable (segfaults, incorrect plots, etc) and major regressions. label Aug 28, 2017

tacaswell force-pushed the ENH_ax_into_pyplot branch from 54215b7 to 1bbbed8 Compare August 31, 2017 02:17

tacaswell force-pushed the ENH_ax_into_pyplot branch 2 times, most recently from b08714c to f26efd9 Compare August 31, 2017 03:06

anntzer reviewed Aug 31, 2017

View reviewed changes

tacaswell force-pushed the ENH_ax_into_pyplot branch from 198eb48 to ccabef7 Compare August 31, 2017 03:56

anntzer reviewed Aug 31, 2017

View reviewed changes

tacaswell modified the milestones: 2.2 (next next feature release), 2.1 (next point release) Aug 31, 2017

dstansby removed the Release critical For bugs that make the library unusable (segfaults, incorrect plots, etc) and major regressions. label Oct 14, 2017

tacaswell modified the milestones: needs sorting, v3.1 Jul 7, 2018

tacaswell added the Release critical For bugs that make the library unusable (segfaults, incorrect plots, etc) and major regressions. label Jul 7, 2018

NelleV reviewed Jul 12, 2018

View reviewed changes

tacaswell modified the milestones: v3.5.0, 3.6.0 Jul 8, 2021

timhoffm modified the milestones: v3.6.0, unassigned Apr 30, 2022

story645 modified the milestones: unassigned, needs sorting Oct 6, 2022

github-actions Bot added the status: needs rebase label Oct 18, 2022

tacaswell force-pushed the ENH_ax_into_pyplot branch from 98c8f53 to 2cb8655 Compare December 4, 2022 18:46

github-actions Bot removed the status: needs rebase label Dec 4, 2022

github-actions Bot added the status: needs rebase label Dec 23, 2022

github-actions Bot added the status: inactive Marked by the “Stale” Github Action label Apr 16, 2023

timhoffm added status: needs comment/discussion needs consensus on next step keep Items to be ignored by the “Stale” Github Action and removed status: inactive Marked by the “Stale” Github Action labels Apr 16, 2023

ENH: add ax or fig kwarg to every pyplot function

e0178fb

This allows passing `ax=some_ax` or `fig=some_fig` into all of the pyplot plotting functions.

tacaswell force-pushed the ENH_ax_into_pyplot branch from 2fc6e64 to e0178fb Compare July 3, 2023 20:20

github-actions Bot removed the status: needs rebase label Jul 3, 2023

tacaswell mentioned this pull request Jul 3, 2023

Idea: unite xlim and set_xlim to same function #15938

Closed

STY: attempt to placate mypy

2c7f076

Bit confused why it was not hitting these before.

github-actions Bot added the status: needs rebase label Jul 27, 2023

tacaswell closed this Oct 9, 2025

tacaswell removed this from the future releases milestone Oct 9, 2025

gargcodes2006 reviewed Oct 18, 2026

View reviewed changes

+              def test_explict_ax():
+                  fig, (ax1, ax2) = plt.subplots(2)
+                  plt.plot(range(5))
+                  plt.plot(range(5)[::-1], ax=ax1)

                           # A gensym-like facility in case some function takes an
                           # argument named washold, ax, or ret
-                          washold, ret, ax = 'washold', 'ret', 'ax'
+                          washold, ret = 'washold', 'ret'

+                          washold, ret = 'washold', 'ret'
                           bad = set(args) | {varargs, varkw}
-                          while washold in bad or ret in bad or ax in bad:
+                          if 'ax' is set(args):

                       ax = gca()
                   else:
-                      ax = args[0]
+                      ax, = args

                   """
-                  fig = gcf()
+                  if fig is None:

                   loc : {'center', 'left', 'right'}, str, optional
                       Which title to set, defaults to 'center'
+                  ax : matplotlib.axes.Axes, optional

                   """
-                  return gca().set_title(s, *args, **kwargs)
+                  return _pop_or_gca(kwargs).set_title(s, *args, **kwargs)



		def box(on=None):
		def box(on=None, ax=None):

ENH: add `ax` kwarg to every pyplot function by tacaswell · Pull Request #9111 · matplotlib/matplotlib · GitHub

Repository navigation

ENH: add ax kwarg to every pyplot function - #9111

ENH: add ax kwarg to every pyplot function#9111tacaswell wants to merge 2 commits intomatplotlib:mainmatplotlib/matplotlib:mainfrom tacaswell:ENH_ax_into_pyplottacaswell/matplotlib:ENH_ax_into_pyplotCopy head branch name to clipboard

Conversation

tacaswell commented Aug 28, 2017

PR Checklist

Uh oh!

anntzer commented Aug 28, 2017

Uh oh!

tacaswell commented Aug 28, 2017

Uh oh!

anntzer commented Aug 28, 2017

Uh oh!

WeatherGod commented Aug 28, 2017 via email

Uh oh!

dopplershift commented Aug 28, 2017

Uh oh!

anntzer commented Aug 28, 2017

Uh oh!

dopplershift left a comment

Choose a reason for hiding this comment

Uh oh!

tacaswell commented Aug 28, 2017

Uh oh!

tacaswell commented Aug 31, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

anntzer Aug 31, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

efiring commented Aug 31, 2017

Uh oh!

tacaswell commented Aug 31, 2017

Uh oh!

anntzer commented Aug 31, 2017

Uh oh!

tacaswell commented Sep 1, 2017

Uh oh!

NelleV left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tacaswell commented Dec 4, 2022

Uh oh!

github-actions Bot commented Apr 16, 2023

Uh oh!

timhoffm commented Apr 16, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tacaswell commented Jul 3, 2023

Uh oh!

tacaswell commented Jul 3, 2023

Uh oh!

tacaswell commented Oct 9, 2025

Uh oh!

gargcodes2006 left a comment

Choose a reason for hiding this comment

Uh oh!

timhoffm commented Oct 19, 2026

Uh oh!

ENH: add ax kwarg to every pyplot function#9111
tacaswell wants to merge 2 commits into
matplotlib:mainfrom
tacaswell:ENH_ax_into_pyplot

anntzer Aug 31, 2017 •
edited
Loading

timhoffm commented Apr 16, 2023 •
edited
Loading