Declare property aliases in a single place #9475

anntzer · 2017-10-19T00:14:22Z

PR Summary

Define property aliases in a more systematic manner. Note that there were some "funny" aliases that I needed to work around, e.g. Text.set_name is an alias for Text.set_family but Text.get_name is different from Text.get_family.
Also use the aliases for kwarg normalization.
For collections, prefer normalizing get_facecolors, etc. to the singular form, as this is more consistent with the Artist interface.
This will add some setters/getters that were not defined before, e.g. there was a Patch.set_aa (set_antialiased) but no Patch.get_aa; this PR adds the missing method.

PR Checklist

Has Pytest style unit tests... in the sense that tests still pass.
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)
Documented in doc/api/api_changes.rst if API changed in a backward-incompatible way

eric-wieser

Looks like nice cleanup, but I'd go with

def try_make_alias(local_d, old_name, new_name):
    try:
        old_func = local_d[old_name]
    except KeyError:
        return False
    @functools.wraps(old_func)  # sets __signature__ and __wrapped__
    def method(*args, **kwargs):
        return old_func(*args, **kwargs)
    method.__name__ = new_name
    method.__doc__ = "alias for `{}`".format(old_name) # backticks for a sphinx link
    local_d[new_name] = method
    return True

for prop, aliases in alias_d.items():
    found_prop = any(
        try_make_alias(local_d, prefix + prop, prefix + alias)
        for prefix in ["get_", "set_"]
    )
    if not found_prop:
        raise ValueError("property {} does not exist".format(prop))

eric-wieser · 2017-12-15T07:39:19Z

lib/matplotlib/cbook/__init__.py

+                exists = True
+                for alias in aliases:
+                    method = make_alias(prefix + prop)
+                    method.__name__ = str(prefix + alias)  # Py2 compat.


I think this line should be handled by make_alias(orig_name, alias_name)

I'd rather make make_alias not know what the name of the resulting function is. Really its only goal is to make a closure over the name (so I'm even going to move the __doc__ out, in fact).

~~I think you should close over the value, not the name~~

Can you explain what the py2 compat issue is? Seems that this doesn't matter for anything other than printing the __name__, which py3 does too.

py2 does not want unicode strings as function names, which we do end up passing because of the unicode_literals future alias. There's a similar issue with the first argument to subprocess on Windows + Py2, again we would pass in unicode strings because of unicode_literals, so we have to wrap them in a call to str().

eric-wieser · 2017-12-15T07:42:44Z

lib/matplotlib/cbook/__init__.py

+        def method(self, *args, **kwargs):
+            return getattr(self, name)(*args, **kwargs)
+        method.__doc__ = "alias for {}".format(name)
+        return method


Why not do the getattr call outside of method?

So that patching the base method gets propagated to the alias method.

Ah, I see. That makes sense to me now

anntzer · 2017-12-15T08:46:24Z

lib/matplotlib/cbook/__init__.py

+                    method = make_alias(prefix + prop)
+                    method.__name__ = str(prefix + alias)  # Py2 compat.
+                    local_d[prefix + alias] = method
+        if not exists:


I think this is more explicit than the any(...) you propose.

eric-wieser · 2017-12-15T08:59:55Z

lib/matplotlib/cbook/__init__.py

+                for alias in aliases:
+                    method = make_alias(prefix + prop)
+                    method.__name__ = str(prefix + alias)  # Py2 compat.
+                    method.__doc__ = "alias for `{}`".format(prefix + prop)


I suppose setting __signature__ through functools.wraps also does the wrong thing for overriden properties...

I'm mostly too lazy to add a dep on funcsigs for this PR (I actually do add such a dependency for the pyplot PR, so that'd also mean merge conflicts and sadness).

eric-wieser · 2017-12-15T09:03:53Z

A novel idea for future: have a global MATPLOTLIB_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.

eric-wieser · 2017-12-15T09:25:20Z

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

class AliasedMethod(object):
	def __init__(self, base_name):
		self.base_name = base_name
	def __get__(self, instance, cls):
		base_method = getattr(cls, self.base_name)
		@functools.wraps(base_method)
		def method(obj, *args, **kwargs):
			return base_method(obj, *args, **kwargs)
                method.__doc__ = "alias of `{}`".format(self.base_name)
		return method.__get__(instance, cls)

More expensive though since it constructs a function upon attribute lookup

anntzer · 2017-12-15T09:51:07Z

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

eric-wieser · 2017-12-16T02:30:26Z

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

efiring · 2017-12-27T21:13:30Z

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__.py
Type:      method

In [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__.py
Type:      method

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

anntzer · 2017-12-27T21:55:34Z

fwiw the relevant code in IPython is in IPython.core.oinspect (_info); specifically https://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 :-)

tacaswell · 2017-12-28T05:20:02Z

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

eric-wieser · 2017-12-28T07:03:45Z

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 use cls.__dict__[name] instead of getattr(cls, name) to avoid that though.

eric-wieser · 2017-12-28T07:05:39Z

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

Carreau · 2017-12-28T13:54:33Z

@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.

anntzer · 2017-12-28T20:12:13Z

@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 at https://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 · 2017-12-29T09:34:48Z

@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.

eric-wieser · 2017-12-29T09:46:38Z

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 use getattr(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?

anntzer · 2017-12-29T19:42:08Z

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.

anntzer · 2017-12-30T23:12:03Z

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

tacaswell · 2018-01-01T01:13:57Z

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

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

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?

anntzer · 2018-01-01T01:32:21Z

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.

eric-wieser · 2018-01-01T06:34:52Z

lib/matplotlib/cbook/__init__.py

+        if not exists:
+            raise ValueError("property {} does not exist".format(prop))
+
+    cls._alias_map = alias_d


I might be tempted to have _define_aliases read this directly, rather than include it in the decorator argument and have it set it anyway - that means the aliases come after the definitions too, and that it becomes more obvious where _alias_map comes from when calling normalize_kwargs

I really would prefer the aliases to stay close to the decorator, at least.

I prefer it this way, to keep the decorator and the alias map close together.

Would it make sense to have the decorator also add a _normalize_kw method as

def normalize_kvwargs(self, kw): return normalize_kwargs(kw, self._alias_map)

?

Might also be better to check if the class already has an _alias_map and if so recursively update it so that the decorator can be used on sub-classes.

if so recursively update it

What you really want here is a collections.ChainMap, but it's not there in python 2.7.

Or maybe

@staticmethod def _get_alias_map(self): d = {} for cls in self.mro(): for k, aliases in cls.__dict__.get('_alias_map',{}).items() d.setdefault(k, []).extend(aliases)

edit: updated

I don't think ChainMap helps here, ex

@_define_aliases({'linewidth': ['lw']}) class A: ... @_define_aliases({'linewidth': ['linewidths', 'lws']}) class B(A): ...

You would want B._alias_map['linewidth'] == ['lw', 'linewidths', 'lws']

Good point. Updated my other comment to reflect that update doesn't work either

tacaswell · 2018-01-01T23:54:19Z

lib/matplotlib/cbook/__init__.py

+                    method.__doc__ = "alias for `{}`".format(prefix + prop)
+                    setattr(cls, prefix + alias, method)
+        if not exists:
+            raise ValueError("property {} does not exist".format(prop))


Can we use a different word than 'property' here? They are not python @property instances which may lead to confusion.

How about "getter or setter methods for {!r} do not exist"?

edit: or "neither getter nor setter methods for {!r} exist"

eric-wieser · 2018-01-02T00:10:39Z

lib/matplotlib/collections.py

+    "edgecolor": ["edgecolors"],
+    "facecolor": ["facecolors"],
+    "linestyle": ["linestyles", "dashes"],
+    "linewidth": ["linewidths", "lw"],


Why not sets, instead of lists? Duplicates wouldn't make any sense here. (edit: because normalize_kwargs requires it to be so)

eric-wieser · 2018-01-02T04:34:23Z

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

Edit: Now resolved

eric-wieser · 2018-01-02T04:57:36Z

lib/matplotlib/cbook/__init__.py

+                "Neither getter nor setter exists for {!r}".format(prop))
+
+    if hasattr(cls, "_alias_map"):
+        raise NotImplementedError("Parent class already defines aliases")


A comment here along the lines of # supporting inheritance requires us to have a plan for conflicting aliases would be good, so that someone doesn't just come along and add a naive implementation.

PeterPablo · 2018-01-02T06:55:06Z

lib/matplotlib/cbook/__init__.py

+    if cls is None:
+        return functools.partial(_define_aliases, alias_d)
+
+    def make_alias(name):  # Enfore a closure over *name*.


typo enforce?

anntzer · 2018-01-04T19:52:16Z

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

efiring

It looks to me like this has converged via discussion to the point where it should go in so we can see whether any real-world problems turn up.
The consolidation of the alias declarations is a big gain.

anntzer · 2018-03-15T19:07:19Z

bump.

jklymak · 2018-03-15T19:25:33Z

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

anntzer · 2018-03-15T19:32:45Z

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

tacaswell · 2018-03-16T23:08:47Z

🎉 I am happy this made it in!

anntzer force-pushed the unify-aliases branch from 0e2bfee to 5a2abf0 Compare October 19, 2017 00:42

anntzer force-pushed the unify-aliases branch from 5a2abf0 to 48c9d21 Compare November 4, 2017 05:51

anntzer force-pushed the unify-aliases branch 2 times, most recently from cc7b870 to 5d04619 Compare December 1, 2017 19:26

eric-wieser reviewed Dec 15, 2017

View reviewed changes

anntzer commented Dec 15, 2017

View reviewed changes

eric-wieser reviewed Dec 15, 2017

View reviewed changes

tacaswell added this to the v2.2 milestone Dec 28, 2017

anntzer force-pushed the unify-aliases branch from 486aa0c to f789c2a Compare December 28, 2017 20:59

anntzer mentioned this pull request Dec 30, 2017

In obj??, display the docstring if it is not in the source. ipython/ipython#10966

Merged

eric-wieser reviewed Jan 1, 2018

View reviewed changes

tacaswell reviewed Jan 1, 2018

View reviewed changes

eric-wieser reviewed Jan 2, 2018

View reviewed changes

anntzer force-pushed the unify-aliases branch from b3d4636 to 2d66f0f Compare January 2, 2018 04:19

anntzer force-pushed the unify-aliases branch from 2d66f0f to 07a7311 Compare January 2, 2018 04:52

eric-wieser reviewed Jan 2, 2018

View reviewed changes

anntzer force-pushed the unify-aliases branch from 07a7311 to 882b306 Compare January 2, 2018 05:18

PeterPablo reviewed Jan 2, 2018

View reviewed changes

anntzer force-pushed the unify-aliases branch from 882b306 to 2941847 Compare January 2, 2018 07:27

anntzer force-pushed the unify-aliases branch from 2941847 to fb67c60 Compare February 2, 2018 08:25

anntzer added 5 commits February 2, 2018 08:57

Declare all property aliases together.

ef7a035

Reuse the alias map.

413144a

Fix some problematic aliases.

7c40fdf

Minor style changes.

a7f698e

Drop need for Py2 unicode hack.

b442049

anntzer force-pushed the unify-aliases branch from fb67c60 to f6d8cbc Compare February 2, 2018 16:58

anntzer added 2 commits February 2, 2018 10:52

Make _define_aliases a class decorator.

2c83bdb

Error out in case of alias inheritance.

473590c

anntzer force-pushed the unify-aliases branch from f6d8cbc to 473590c Compare February 2, 2018 18:55

efiring approved these changes Feb 25, 2018

View reviewed changes

jklymak modified the milestones: needs sorting, v3.0 Mar 15, 2018

jklymak merged commit b083c2a into matplotlib:master Mar 15, 2018

anntzer deleted the unify-aliases branch March 15, 2018 19:36

anntzer mentioned this pull request Sep 6, 2018

Fix ArtistInspector.get_aliases. #12037

Merged

6 tasks

This was referenced Feb 13, 2019

Doc: Alias names disappeared from documentation #13278

Closed

Really fix ArtistInspector.get_aliases #13432

Merged

Uh oh!

Declare property aliases in a single place #9475

Declare property aliases in a single place #9475

Uh oh!

Conversation

anntzer commented Oct 19, 2017

PR Summary

PR Checklist

Uh oh!

eric-wieser left a comment • 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!

Choose a reason for hiding this comment

Uh oh!

eric-wieser Dec 15, 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!

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!

Choose a reason for hiding this comment

Uh oh!

eric-wieser commented Dec 15, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

eric-wieser commented Dec 15, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

anntzer commented Dec 15, 2017

Uh oh!

eric-wieser commented Dec 16, 2017

Uh oh!

efiring commented Dec 27, 2017

Uh oh!

anntzer commented Dec 27, 2017

Uh oh!

tacaswell commented Dec 28, 2017

Uh oh!

eric-wieser commented Dec 28, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

eric-wieser commented Dec 28, 2017

Uh oh!

Carreau commented Dec 28, 2017

Uh oh!

anntzer commented Dec 28, 2017

Uh oh!

Carreau commented Dec 29, 2017

Uh oh!

eric-wieser commented Dec 29, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

anntzer commented Dec 29, 2017

Uh oh!

anntzer commented Dec 30, 2017

Uh oh!

tacaswell commented Jan 1, 2018

Uh oh!

anntzer commented Jan 1, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

eric-wieser Jan 1, 2018 • 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!

eric-wieser left a comment •

edited

Loading

eric-wieser Dec 15, 2017 •

edited

Loading

eric-wieser commented Dec 15, 2017 •

edited

Loading

eric-wieser commented Dec 15, 2017 •

edited

Loading

eric-wieser commented Dec 28, 2017 •

edited

Loading

eric-wieser commented Dec 29, 2017 •

edited

Loading

anntzer commented Jan 1, 2018 •

edited

Loading

eric-wieser Jan 1, 2018 •

edited

Loading

tacaswell Jan 1, 2018 •

edited

Loading

eric-wieser Jan 2, 2018 •

edited

Loading

eric-wieser Jan 1, 2018 •

edited

Loading

eric-wieser Jan 2, 2018 •

edited

Loading

eric-wieser commented Jan 2, 2018 •

edited

Loading