@matplotlib/developers Thoughts on this?

I would like to present some version of this in my scipy talk so would like feed back as soon as possible.

I haven't tested it yet, but it looks good.
Maybe the decorators could also add some boilerplate documentation to cover the change in signature options? I don't know how hard this would be.

@efiring Thoughts on docstring changes?

@tacaswell, the docstring change looks good.

@tacaswell Does this need an example? At least I feel a bit confused by it as I don't see it used anywhere (and I haven't learnt about decorators yet)...

Looks good. I doubt this is the case, but just to anticipate a question from the peanut gallery: does this add significant overhead vs. the current approach?

One other question, what does ENH stand for? (Also I have seen MNT and the likes in PR titles).

ENH -- Enhancement
MNT -- Maintenance
WIP -- Work In Progress

On Wed, Jul 8, 2015 at 11:33 AM, OceanWolf notifications@github.com wrote:

One other question, what does ENH stand for? (Also I have seen MNT and the
likes in PR titles).

—
Reply to this email directly or view it on GitHub
#4488 (comment)
.

I'm assuming it's
MNT: maintenance, cleanups, refactoring
FIX: bugfix
ENH: enhancement, new feature
I don't know if it's official policy, but I imagine it can be useful when dealing with large numbers of pull requests.
On 8 Jul 2015 6:33 pm, OceanWolf notifications@github.com wrote:One other question, what does ENH stand for? (Also I have seen MNT and the likes in PR titles).

—Reply to this email directly or view it on GitHub.

This is shameless stolen from numpy, there is a key in their development
docs (probably should copy to ours).

On Wed, Jul 8, 2015, 11:24 AM Jouni K. Seppänen notifications@github.com
wrote:

I'm assuming it's
MNT: maintenance, cleanups, refactoring
FIX: bugfix
ENH: enhancement, new feature
I don't know if it's official policy, but I imagine it can be useful when
dealing with large numbers of pull requests.
On 8 Jul 2015 6:33 pm, OceanWolf notifications@github.com wrote:One
other question, what does ENH stand for? (Also I have seen MNT and the
likes in PR titles).

—Reply to this email directly or view it on GitHub.

—
Reply to this email directly or view it on GitHub
#4488 (comment)
.

that key is a little below this link.

@njsmith expressed grave concern about the registration function, please don't merge this until that gets sorted (I think I am leaning towards agreeing with him that this is a bad idea).

@ericdill Added one of the decorators you wanted 🍺

I think this is ready to merge.

The addition of quick_axes should probably get some more eyes on it.

rebased to fix import conflict in pyplot

I owe the mailing list several MEPs.

👍 - you've much more time thinking about improvements to a very old codebase than anybody else, and you've got some great ideas - I think for the sake of the community it is well worth writing small MEPs which we can all buy-in to.

For that reason, I don't believe this is a release critical PR, and I wouldn't want to see a release held up for it. Maybe we need a "a core dev is advocating this for the next release, and we should do our best to make sure it gets in" milestone 😄

I see a lot of these "Release critical" things as extra features that might help a few people... I don't understand what makes something "Release critical". In debian, they have a strict set of goals (MEPs) that they want to achieve for the next release, like ensuring everything supports utf8...

👍 to needing more MEPs, but I don't mind them large, or at least overarching... we can always split up MEPs into smaller sub MEPs and those into even smaller PRs... for instance we have a large backend refactor now and that got divided into two sub-MEPs, MEP22 and MEP27, and those get broken down into smaller PRs.

One thing we do need before that though, a way of sorting out the MEPs, I like that we now submit MEPs through PRs, but... we now have a problem with numbering, if we have multiple MEPs sitting in PRs not yet merged, it becomes a nightmare to keep track of numbers, and we will have merge conflicts, etcetera, so we need to sort that out...

Okay, I have just started writing an MEP on an axes refactor/overhaul, written from the ground up. Depending on whether we achieve full Backwards Compatibility with the MEP looks by the end I guess will determine whether this will go out in 2.x or 3.0.

But first to figure out how to do MEPs based on my points above...

I expected this to be a relatively non-controversial PR.

@OceanWolf With the exception of the labeled data unpacking (which is a release critical feature, we need to address the reality of labeled data being wide-spread) all of these feature have been in the milestone for several months. To be fair, they are there because I put them there, but no one argued at the time and as I am running the release I am going to claim that as my prerogative 😉. The main thing that makes these 'critical' is that they are new features (which can't be merged once we have an RC), not bug fixes (which can be).

@pelson I am not sure what your hesitation about the decorators. I am happy to mark these as experimental if that makes you more comfortable. The logic on how I got to them was basically

1. I want people to write functions like def plotter(ax, data, style) which can assert that it gets an explicit axes (and does not need to even know that pyplot exists). This is good for re-usability / composability etc. We also have a large number of functions with this signature (the Axes methods) that we can work with internally. I think that many people should be writing many more of these functions that can take in rich data objects for domain-specific plotting tools.
2. people complain about having to use explicit axes (I don't find these complaints particularly compelling, but enough people have independently said this that I believe our users about it) so if we don't want to have every user write their own (slightly different!) way of handling the axes, we should provide a decorator to do that. A obvious thing to do would be to have the decorated function just take an ax kwarg, but then the resulting function no longer has the same signature (which is bad from a consistency point of view, arts = fun(ax, data, style) should always work, from switching between interactive/non-interactive work (as implicit axes should only really be used at the repl)). Hence the crazy first arg introspection to sort out if it is an axes or not.
3. a bunch of down-stream libraries already use the ax as a kwarg pattern so we should support that too

The weakest point that I see in there is my dislike of breaking ax as first arg always working.

Long term I think the list of figure/axes creation methods in pyplot should go down to:

• gcf / gnf (get current / new figure)
• gca / gna (get current / new axes)
• subplots(...) (make a grid of axes)

and everything else should be deprecated.

I share Tom's surprise that this PR is arousing discomfort. But evidently it is, so we need some clear discussion as to why, and what to do about it. I think that Tom's rationale for it is quite clear. I am open to arguments against it, or to suggested modifications or alternatives.

On 2015/09/03 7:51 PM, Thomas A Caswell wrote:

The weakest point that I see in there is my dislike of breaking |ax| as
first |arg| always working.

Sorry, I haven't been able to figure out what you mean here. Are some
words missing?

The suggested signature for the non implicit calls is func(ax, data,
style). We could have the decorated function have the signature func(data,
style, ax=ax) vs allowing the decorated function to also be used as
func(ax, data, style). The logic to use the wrapped function with both
signature is where most of the ugly code comes from.

The trade off is partially consistent api between interactive/non
interactive vs code complexity in the decorator.

On Fri, Sep 4, 2015, 02:22 Eric Firing notifications@github.com wrote:

On 2015/09/03 7:51 PM, Thomas A Caswell wrote:

The weakest point that I see in there is my dislike of breaking |ax| as
first |arg| always working.

Sorry, I haven't been able to figure out what you mean here. Are some
words missing?

—
Reply to this email directly or view it on GitHub
#4488 (comment)
.

I share Tom's surprise that this PR is arousing discomfort.

I guess the concern comes down to the fact that right now this PR doesn't make the mpl codebase more succinct and it represents 4 new functions in the pyplot namespace which need consideration.

If we want to iterate on this in this PR, rather than as a MEP, I'm happy to do that, but I suspect there will be several threads to the discussion which doesn't read well in a linear GH style...

I'll outline some of my concerns, and we can go from there:

ensure_ax.* decorators

It is unclear to me that a decorator is the way to go here:

• It isn't until py3.4 that functools.wraps preserves the wrapped fn's signature, so we end up with even more *args, **kwargs style documentation.
• Whilst it is technically possible to do, it is plain weird (and therefore unexpected) to define a positional argument which is optional. There is no reconciliation of this which puts axes as the first argument of a plotting function at the same time as making it optional.

Assuming the weird thing is a deal breaker, the problem is hugely simplified, and a function would do:

def my_plotting_function(arg1, arg2, ax=None):
    ax = plt.ensure_axes(ax)

Truthfully though, the backwards compatible way is just as good:

def my_plotting_function(arg1, arg2, ax=None):
    ax = ax if ax is not None else plt.gca(ax)

The question about whether axes should be the first argument for all plotting functions needs to be also addressed. I completely understand the recommendation, but doing so means that you cannot then call the argument optional (without breaking the expected Python definition of positional). So I think we need to look at the motivation again - is the recommendation that axes be the first argument related to the fact that our current Axes methods are implicitly doing this (through self)? Or is there another reason why accepting ax as an optional argument is an unhealthy recommendation? The idea that developers wouldn't need pyplot (specifically gca) in their functions is hampered by the fact that these wrappers themselves live in pyplot.

Finally, if there are to be this many repetitively named items in pyplot, I'd consider giving them a namespace (via a class) - it would also allow for some of the duplicated code to be shared between functions.

gna.* function

I'm all in favour of improving the interface - plt.figure().gca() is hardly a pleasant alternative. It has irked me for a long time that gca actually returns a subplot object though - I have never seen the downside of a Axes (rather than a Subplot), and so quite happily use plt.axes rather than plt.subplots (which obviously do very different things). My point being that gna continues this trend of using a single Subplot, rather than an Axes.

I appreciate we are where we are, but the gc* family of functions have never been appealingly named, and given we are talking seriously about making improved interfaces I think this is an opportunity to think about how we want modern matplotlib to look.

Incidentally, I was surprised that only those two kwargs were added to the gna implementation, and that gna is making a new figure (I would have expected it to use an existing figure, but then where would it put that axes).

I hope this isn't coming across as negative - that is not my intention. I think there is room for debate here about the best course for us to be setting for matplotlib, and I'm very comfortable with @tacaswell leading that discussion; I just want to ensure we have it rather than take ad-hoc changes without an overarching strategy.

On 2015/09/04 8:08 AM, Phil Elson wrote:

I share Tom's surprise that this PR is arousing discomfort.

I guess the concern comes down to the fact that right now this PR
doesn't make the mpl codebase more succinct and it represents 4 new
functions in the pyplot namespace which need consideration.

If we want to iterate on this in this PR, rather than as a MEP, I'm
happy to do that, but I suspect there will be several threads to the
discussion which doesn't read well in a linear GH style...

MEPs via GH have the same problem, don't they? Should we move this to
the mailing list?

I'll outline some of my concerns, and we can go from there:

Very helpful, thank you.

@tacaswell I understand that we can't merge these features between RC and 1.5, but that doesn't prevent us from releasing this in 2.1? I would rather see us get this right, than rush it.

👍 to what @pelson says regarding an overarching strategy and about the naming, I really dislike gcf, etcetera. it took me ages to realise what this meant having seen it many times sprawled throughout the code I saw it sprawled throughout the code... lets keep it readable.

@efiring I think MEPs allow us to more easily discuss logic, by commenting on specific ideas/lines. Coincidently I have just pushed an MEP (#5029) to begin a conversation around the future of the axes class. Quite wide-ranging, but I don't think it will cover this area specifically, but it may pick up on a few of the points said here and add to the list of questions pertaining to this PR...

Block quoting to make it clear what I am responding to, the gna discussion is simpler.

gna.* function

I'm all in favour of improving the interface - plt.figure().gca() is hardly a pleasant alternative. It has irked me for a long time that gca actually returns a subplot object though - I have never seen the downside of a Axes (rather than a Subplot), and so quite happily use plt.axes rather than plt.subplots (which obviously do very different things). My point being that gna continues this trend of using a single Subplot, rather than an Axes.

I appreciate we are where we are, but the gc* family of functions have never been appealingly named, and given we are talking seriously about making improved interfaces I think this is an opportunity to think about how we want modern matplotlib to look.

Incidentally, I was surprised that only those two kwargs were added to the gna implementation, and that gna is making a new figure (I would have expected it to use an existing figure, but then where would it put that axes).

I didn't know the plt.axes existed (so my list way up thread should be at least one longer) and it can return either an Axes or a AxesSubplot depending on how you call it.

The point of gna is to safely (that is without messing up any existing figures) get a new axes that can be passed into plotting functions. The two kwargs I implemented are based on SO questions I have seen go by, my sense is that those two are the most frequently used. gna was implemented as a stand-alone function to support ensure_new_ax which implements the logic we discussed with Luke the last night of scipy.

Throwing it in as a top-level function seemed like a useful thing to do but I have no problem nuking it if we want to hold off on adding it for a more comprehensive simplification of this class of things (but I think it adds a useful functionality and does not make things that much worse).

As excited as I am about this, I am leaning towards giving up on it for now 😞

I really want this to go in, but not over @pelson 's protests and I want to get 1.5rc1 tagged (maybe tomorrow night?)

After phone call with @pelson we have decided to spin this off into it's own project. This lets us:

• iterate faster
• not pollute the pyplot namespace with possible ill-considered / thrashy API
• allows us to retro-fit existing 1.3 / 1.4 installations with this functionality

👍

Thanks to @tacaswell for being very gracious on this. I think the distinct package approach gives us some great opportunities, with very little cost (an extra installation). The big selling point for me was the ability for package developers to use these wrappers for older versions of matplotlib.

👍 to @tacaswell. 👏