Add an API for registering magic aliases.

[bfroehle]

Original Issue:

Following up on #2086, we can also use %alias_magic to register %ed, %hist and %recall.

Since the coupling between the original function (%edit) and alias (%ed) is a bit looser now, I've modified the docstring examples for %edit to use edit instead of ed.

New idea, as @fperez wrote in #2144:

I actually agree with @takluyver here, if we need to use this both internally (programatically) and in a mode with user-friendly output, the best thing to do is to split it into a python funcitonal API and the magic entry point being only a thin wrapper. This also has the side benefit of letting us test things without worrying about stdout side effects.

Current Issue:

Add a method register_alias to MagicsManager which can be used to register new magic aliases. Each magic alias is an instance of MagicAlias, a helper class whose __call__ looks up the target of the alias (at call time) and dispatches the magic call.

As a future benefit, this could be easily extended to allow for new aliases which contain some flags to pass to the function. For example, it would be easy to change the behavior to allow the creation of an %ex alias for %edit -x.

[Carreau]

line 240 above this one, there is a

if 'rep' in h :
   continue

Maybe we should change it for 'rep' in h or 'recall' in h.

[bfroehle]

Yes, well the point of this line is to prevent matching the current line you are executing (or any previous line), however just blindly looking for 'rep' or 'recall' in the sequence is pretty fragile. Nonetheless I've included your suggestion and pushed the change.

[Carreau]

Except from the small comment above, from which I'm not even sure what to think of it, I'm fine with merging this.

[bfroehle]

Test results for commit c2266b1 merged into master
Platform: linux2

• python2.7: OK
• python3.2: OK (libraries not available: oct2py pymongo rpy2 wx wx.aui)

Not available for testing: python2.6, python3.1

[bfroehle]

This will need to be updated with --quiet if #2144 is committed.

[bfroehle]

I've updated this pull request to include the addition of a new method MagicsManger.register_alias which can be used to register aliases. In addition, I've created a new class MagicAlias to hold the information about the alias. This should prove to be a more versatile and robust solution.

In addition, I've subsumed #2144 into this pull request (since it becomes a trivial addition).

If this approach looks reasonable, I'll add some tests. (Although this is already being tested, at least a little, by the tests for %alias_magic).

[takluyver]

I think that approach looks sensible.

[Carreau]

Looks find to me.

Once this is merge, what do you think of excluding the aliases magics from lsmagics, qt console gui etc ?
I have arguments for and against it, so I want to know what others think.

[takluyver]

I'd be inclined to exclude them from %lsmagic and the Qt console menus

• it's just confusing to have duplicate items around. %magic should
  still mention them, and maybe the docstrings for individual aliases
  should mention aliases.

[Carreau]

Devil advocate :

But for user defined alias, it would make a convenient menu...

[takluyver]

I think the main reason to declare an alias is to save typing for
something you use often. E.g. %hist instead of %history. That's not
really a concern if you're clicking on something in a menu.

Of course, a short menu of recently used magics might have uses (like
a recent files list in many applications), but:

• I'm not sure that the benefits are worth the added complexity. The
  menu is handy for discoverability, but for quick access you can easily
  type magic commands in (or use up-arrow to get them from command
  history).
• There are probably better ways to pick frequently/recently used
  magics than what the user has declared aliases for; many magics are
  short enough that you would never need to define your own alias.

[Carreau]

Find with me, i'll do that once this one is merged.

[fperez]

Great, clean code. I do like the idea of future uses with default flags, which matches how %alias works. Excellent job, thanks @bfroehle!