ipython/ipython — pull request #2636 by rmcgibbo (2012-12-02 02:09:17+00:00)
Title: Function annotation based hooks into the tab completion system

This PR adds a way for user code to hook into the ipython tab completion system via function annotations [PEP 3107](http://www.python.org/dev/peps/pep-3107/). python 2.x support is provided via a decorator.

This feature was [discussed](http://mail.scipy.org/pipermail/ipython-dev/2012-November/010697.html) on IPython-dev along with the use of function annotations for the feature on [Python-ideas](http://code.activestate.com/lists/python-ideas/17971/) as it relates to interoperability between annotation schemes.

For example, using the glob tab completion, only files matching the appropriate ending (and directories) are shown:
```
>>> from IPython.extensions.annotations import tab_glob
>>> def f(x : tab_glob('*.txt')):
... pass
>>> load(
'COPYING.txt' 'build/' 'ipython.egg-info/' 'setupext/'
'IPython/' 'docs/' 'scripts/' 'tools/'
```

Currently, the annotations provided are
- `tab_glob`, which recommends string literals that are directories or files matching a pattern
- `tab_literal`, which recommends from a set of enumerated literals
- `tab_instance`, which recommends objects that exist in the current namespace that are instances of a supplied (set of) class(es).

The API for adding new annotations is pretty simple (the implementation of tab_instance is ~15 LOC), so users can easily both add these annotations to their functions or add new annotations that implement other types of matches.

I'm sure their are some bugs. One that I know about is poor handling by `tab_glob` of filenames with spaces, since the spaces cause the tokenizer to token-break where you don't want it to.

This feature is complicated enough to require a significant number of tests (which I haven't written yet -- I've just been testing it interactively). Testing it is a challenge in and of itself, since you need to somehow simulate the TAB key in the testing environment and parse the output of readline. If anyone has any ideas for how to test the final product automatically, that would be awesome. Obviously the methods can be tested individually, which is straightforward.

[Also, the completion machinery currently in ipython could use some serious refactoring, but I didn't try to tackle that here]

----

I'm not really sure what the next step forward on this is. It's a big enough change, IMO, that it deserves some serious discussion, user-facing documentation (IMHO I wrote good docstrings, but that's not enough), etc.

Also, I don't really like the names `tab_glob`, `tab_literal`, and `tab_instance`.

Thoughts?