hopefully py2 won't really be a thing anymore by the time this is implemented :p

indeed! If you dig into the commits on this, I started writing this in 2016...

Personally I find passing the axes as first argument muuuuuuch, much nicer (well, that may be because I essentially never use the pyplot layer which I understand may not be representative of most users).
Either we could use the "magic" decorator, or alternatively we could just have parallel namespaces plt.somefunc(..., ax=None) (None=gca()) & someothernamespace.somefunc(ax, ...) which would at least have the advantage of keeping reasonable signatures for all functions (with the "magic" decorator, inspect.signature can't represent the signature; which is not nice). Note that one namespace could be autogenerated from the other, e.g. in mod.py

@gen_pyplotlike  # registers to module_level registry
def func(ax, ...): ...

@gen_pyplotlike
def otherfunc(ax, ...): ...

pyplotlike = collect_pyplotlike()

and then one can do import mod; mod.func(ax, ...) or from mod import pyplotlike as mod; mod.func(..., ax=ax).

#4488 I tried something similar and it got rejected (and I sadly never followed up on making it its own package).

I find all three calling patterns valid approaches:

plt.plot([1, 2, 3])
plt.plot(ax, [1, 2, 3])
plt.plot([1, 2, 3], ax=ax)

and I welcome supporting all of them. Each one has it's use:

• simple interactive use
• interactive use with multiple axes (less to type than ax=ax)
• programmatic use, where the data should be the first arguments for better readability.

I'm against creating multiple namespaces just for the sake of different calling patterns. For one, it's conceptually more difficult to tell people: "Use pyplot.plot() if, or use posax.plot(ax, ...) or use kwargs.plot(..., ax=ax)". Also you would have to create multiple variants of the documentation. While that could be automated, you still have the problem which one to link. It's much easier to once state "axes can be automatically determined, or passed as the first positional arguement, or passed as kwarg."

As @tacaswell has demonstrated that can all be resolved with a decorator.

I'm not quite sure if the actual function definition should be

@ensure_ax
def func(ax, *data_args, **style_kwargs)

or

def func(*data_args, ax=ax, **style_kwargs)

I tend towards the latter because it's the syntactically correct signature for two out of the three cases. And it puts more emphasis on the data_args rather than on the axes. Also it has the big advantage, that it could be build into pyplot in a backward-compatible way. That way, we wouldn't need any new namespace.

Note also, that an axes context could be a valuable addition:

with plt.sca(ax):
    plt.plot([1, 2, 3])
    plt.xlabel('The x')
    plt.ylabel('The y')

(maybe using a more telling name than sca()).

I'm not sure if I understand the goal here.
Is the goal to have libraries add plt.my_new_plotting_thing(...) and ax.my_new_plotting_thing(...)?
That's all about entry points, right? Also: what exactly is the benefit of doing that?

Right now, my pattern is having an axes kwarg and if it's None I do plt.gca().
That's basically a single line, which might be slightly longer than adding the ensure_ax decorator in terms of characters but not by much, and seems much easier to understand.

Right now I'm reasonably happy to do some_plotting(ax=ax). Doing ax.some_plotting instead might be nice, but I'm not entirely sure if that is the main goal of this proposal? Doing plt.some_plotting(...) instead of just some_plotting(...) is just more characters, right? I guess it tells you by convention that if it starts with plt it'll modify the current axes? Though that's not even really true: plt.matshow creates a new figure.

Generally I prefer thinking about what code looks like when I use it first instead of thinking about the implementation first. Usually implementing whatever API we settle on is possible so it's more a question of what we want user code to look like.

I think the main goal is for matplotlib have plotting libraries that do

import matplotlib.basic as mbasic
import matplotlib.2d as m2d

fig, ax = plt.subplots()
mbasic.scatter(x, y, ax=ax)
m2d.pcolormesh(x, y, z, ax=ax)

so the matplotlib library looks more like what user and third party libraries look like.

I think the goal would then be for ax.scatter to just be a wrapper around mbasic.scatter.

But maybe I've completely misunderstood.

@jklymak Xo you're saying you want to change the matplotlib api to no longer do ax.scatter and plt.scatter but do scatter(ax=ax).
That is very different from what I understood, but I'm also very confused ;)

I think its meant to be a third way. Ahem, I don't particularly want this, but I think the point is to make third-party libraries more plug-and-play with the main library. It also would allow us to have more domain-specific sub libraries without polluting the ax.do_something name space. But maybe it has some deeper advantages as well?

Ok yeah I follow your interpretation. Let's see if that's what the others meant ;)