A novel idea for future: have a globalMATPLOTLIB_WARN_ALIASES environment variable, and when set emit warnings when aliases are used. Follow up: ensure that internally matplotlib never uses the aliases, but always the full names.

Alright, here's the solution that preserves__signature__ in python 3:

classAliasedMethod(object):def__init__(self,base_name):self.base_name=base_namedef__get__(self,instance,cls):base_method=getattr(cls,self.base_name)@functools.wraps(base_method)defmethod(obj,*args,**kwargs):returnbase_method(obj,*args,**kwargs)method.__doc__="alias of `{}`".format(self.base_name)returnmethod.__get__(instance,cls)

More expensive though since it constructs a function upon attribute lookup

I think that's a reasonable option, but will let other reviewers chime in first.

To be clear, I think what you have now is fine, and am just exploring alternatives out of curiosity :)

In general I like this. The clutter-reduction is great, and I agree with favoring the singular forms. My only discomfort with the PR is that in ipython, the single-question-mark works perfectly but the double-question-mark returns the wrapper-method code (and no docstring) instead of the relevant code:

In [5]: l.get_mec?Signature: l.get_mec(*args, **kwargs)Docstring: alias for `get_markeredgecolor`File:      ~/work/programs/py/mpl/matplotlib/lib/matplotlib/cbook/__init__.pyType:      methodIn [6]: l.get_mec??Signature: l.get_mec(*args, **kwargs)Source:        def method(self, *args, **kwargs):            return getattr(self, name)(*args, **kwargs)File:      ~/work/programs/py/mpl/matplotlib/lib/matplotlib/cbook/__init__.pyType:      method

That's not a blocker, but it's not ideal, either.

fwiw the relevant code in IPython is in IPython.core.oinspect (_info); specificallyhttps://github.com/ipython/ipython/blob/3c53804581bd51347eca577950752e1eac1d5e9b/IPython/core/oinspect.py#L823: "Add docstring only if no source is to be shown (avoid repetitions)."

@Carreau any hooks in IPython that we could rely on for this? thanks :-)

Could this be done as a class decorator? I think that would be clearer than hacking onlocals() in the class body.

A class decorator will be slower, since it would invoke the descriptor protocol on each attribute lookup. (Rather than the direct dict lookup that is happening here).

I suppose it could usecls.__dict__[name] instead ofgetattr(cls, name) to avoid that though.

I don't think it even needs to be a decorator - just a free function with signatureadd_aliases(cls: Type, aliases: Dict) -> None

@Carreau any hooks in IPython that we could rely on for this? thanks :-)

Not that I can think of from the top of my head. This is some old code that would highly need refactor, and I am thinking about an ability to make that more configurable with a way for a package to provide a custom object->doc mapping for?/?? but that will take time.

@tacaswell It could be a decorator or a free function but I think it would actually make things less clear. A decorator would either need to declare the aliases at the beginning of the class definition, before the properties themselves are defined (or read the alias table from a table defined in the body of the function, but that doesn't play well with inheritance). A free function would modify the class definition post-hoc, which is not a model of clarity either.

@Carreau Perhaps the line athttps://github.com/ipython/ipython/blob/3c53804581bd51347eca577950752e1eac1d5e9b/IPython/core/oinspect.py#L823 ("Add docstring only if no source is to be shown (avoid repetitions).") could try to parse the source tree and see whether the docstring is textually present in the source, and decide accordingly whether to display the docstring? This would be a fairly generic solution for dynamically generated functions. It sounds a bit scary but I don't think it's that hard to write (happy to push the item somewhere on my todo list if that sounds good to you).

@Carreau Perhaps the line at ipython/ipython:IPython/core/oinspect.py@3c53804#L823 ("Add docstring only if no source is to be shown (avoid repetitions).") could try to parse the source tree and see whether the docstring is textually present in the source, and decide accordingly whether to display the docstring? This would be a fairly generic solution for dynamically generated functions. It sounds a bit scary but I don't think it's that hard to write (happy to push the item somewhere on my todo list if that sounds good to you).

I have to think about it and like feedback from other dev about that. I don't see any drawbacks, so feel free to send a PR or open an issue.

or read the alias table from a table defined in the body of the function, but that doesn't play well with inheritance

Works fine if you name the table__aliases, and within your helper usegetattr(cls, '_{}__aliases'.format(cls.__name__))

Edit: Wait, in what way does this mess up inheritance? The decorator should only be applying to the top-level class anyway, shouldn't it?

Good point that because the decorator is only applied once (which is actually what you want) there are no problems with inheritance.

Still, per my above comment, I don't really like splitting the aliasing-relevant code into two places (one table in the body that lists the aliases and one decorator at the top). If there's a strong pushback against the current design I can revisit it, so let me know what you prefer.

@efiringipython/ipython#10966 should at least help for future IPython versions.

@anntzer I don't understand your comments. I was imagining something like

@alias_manager({'linewidth': ['lw','linewidths'], ...})classFooBar:   ...

Everything is still in one place, it uses a language provided tools for mucking with class dictionaries between when they are defined and when the user gets the classes, and makes it very clear from looking at the class definition that we are doing so.

That said, do we need to do something fancier to deal with the case where a sub-class overides the thing that is aliased so the aliases point back to the sub-classed version of method?

Basically I didn't like having a huge decorator before the class itself is defined, but it's not a big deal; changed implementation accordingly.
Subclassing should not be an issue because the aliases call getattr at call time and not at function-definition time.

Ping onthis outdated comment on inheritance which I think still applies.

Edit: Now resolved

btw@efiring the next IPython release will show the docstring in this case too.

bump.

OK, seems reasonable - aremany of the aliases tested? I guess the common ones are.

Well, looks like codecov is happy for once :-)

🎉 I am happy this made it in!