In %magic help, remove duplicate aliases

[bfroehle]

This pull request removes duplicate aliases from %magic help, while still preserving the regular docstrings.

This means that %ed? and %edit both return usage instructions, but %magic returns:

%ed:
        Alias for `%edit`.
%edit:
        Bring up an editor and execute the resulting code.
...

To create an alias, you need only to set the _magic_alias attribute to the name of the primary magic function.

I've gone through and attempted to locate most aliases (%ed, %loadpy, %hist, %recall) and set this attribute.

[bfroehle]

Closes #641 and replaces #1971.

[takluyver]

Can we integrate this into the magics API, so you do e.g.:

@line_magic('edit', 'ed')
def edit(self, parameter_s):
    ...

The first one would be the canonical name.

Also, the list in %magic is quite long already - I think it should just skip aliases.

[fperez]

Sorry to backtrack on my own words, but I'd like to reconsider the whole thing: we're adding a fair amount of complexity just to enable what's arguably a rather obscure feature: the ability to create an alias for a magic, as a builtin feature.

I'm beginning to think that what we should do is remove all magic aliases from the configuration we ship by default, and just stick to single names for all the magics.

If a user wants to make their own alias, that's fine, and they can deal with the duplicate name, they can make it the ugly way (magic 'a' calls magic 'b', period).

I'm just not convinced anymore this 'feature' (which I know I was the one to add ages ago, with %ed and %hist) is really worth the hassle in more delicate code.

@minrk, @ellisonbg, what's your thought here?

And sorry @bfroehle if we end up pulling back here, I'll owe you one :) It's just that I'm now really striving for simplicity and comprehensibility in our core...

[bfroehle]

No worries, I think I agree that we should only ship a canonical name.

Maybe a simple new %magic_alias is in order?

[fperez]

Sure, a %magic_alias would be fine, it would do the ugly thing (i.e. any alias would show up twice), and would only be called by users. That is, we'd never actually use it in the default configuration ourselves.

That gives people an easy way to make their own aliases, but doesn't clutter the code with obscure flags or duplication.

[bfroehle]

Can the existing aliases be removed in 0.13? Or should we print a
deprecation warning?

[fperez]

That's one of the tough calls to make now. I'm loathe to remove them this late in the release cycle, so perhaps we can have a little manual section where we make them, prepend to their docstrings (by hand) a fat deprecation warning, and nuke that little section out once we open 0.14.dev.

It is a bit too late for something like this to slip in, that will potentially break people's habits.

[minrk]

What is the benefit in removing them? I think there should be a pretty high bar for pissing people off by breaking backwards-compatibility for no reason other than cleanliness.

[fperez]

Well, the options we have are:

1. Leave them as-is for good, though possibly implemented via a convenience %magic_alias or somesuch. The drawback here is that they show up twice on all listings as we have no concept of 'real' aliases.
2. Leave them for now but deprecated and remove later on.
3. Build up machinery to have a first-class concept of magic aliases. That's what this PR was doing.

I'm starting to think that 3 is just too much complexity for a fairly obscure feature. But if we want to avoid more user habit breakage, a good alternative would be to go with 1, with an implementation of magic_alias that simply auto-creates the new method with a standard docstring that reads Alias for magic %foo, see its docstring for details.

That would give us no deprecation but at least short docstrings for the duplicates in the big %magic listing and an easy to use interface for users who may like to add their own aliases.

I actually like this as a design brief, what do you guys think?

[fperez]

Something tells me we'll want to close this one and go with the alternate approach above, do you folks agree?