IPython.core.completer

Completion for IPython.

This module started as fork of the rlcompleter module in the Python standard library. The original enhancements made to rlcompleter have been sent upstream and were accepted as of Python 2.3,

This module now support a wide variety of completion mechanism both available for normal classic Python code, as well as completer for IPython specific Syntax like magics.

Latex and Unicode completion

IPython and compatible frontends not only can complete your code, but can help you to input a wide range of characters. In particular we allow you to insert a unicode character using the tab completion mechanism.

Forward latex/unicode completion

Forward completion allows you to easily type a unicode character using its latex name, or unicode long description. To do so type a backslash follow by the relevant name and press tab:

Using latex completion:

\alpha<tab>
α

or using unicode completion:

\GREEK SMALL LETTER ALPHA<tab>
α

Only valid Python identifiers will complete. Combining characters (like arrow or dots) are also available, unlike latex they need to be put after the their counterpart that is to say, F\\vec<tab> is correct, not \\vec<tab>F.

Some browsers are known to display combining characters incorrectly.

Backward latex completion

It is sometime challenging to know how to type a character, if you are using IPython, or any compatible frontend you can prepend backslash to the character and press Tab to expand it to its latex form.

\α<tab>
\alpha

Both forward and backward completions can be deactivated by setting the Completer.backslash_combining_completions option to False.

Experimental

Starting with IPython 6.0, this module can make use of the Jedi library to generate completions both using static analysis of the code, and dynamically inspecting multiple namespaces. Jedi is an autocompletion and static analysis for Python. The APIs attached to this new mechanism is unstable and will raise unless use in an provisionalcompleter context manager.

You will find that the following are experimental:

• provisionalcompleter

• IPCompleter.completions

• Completion

• rectify_completions

We welcome any feedback on these new API, and we also encourage you to try this module in debug mode (start IPython with --Completer.debug=True) in order to have extra logging information if jedi is crashing, or if current IPython completer pending deprecations are returning results not yet handled by jedi

Using Jedi for tab completion allow snippets like the following to work without having to execute any code:

>>> myvar = ['hello', 42]
... myvar[1].bi<tab>

Tab completion will be able to infer that myvar[1] is a real number without executing almost any code unlike the deprecated IPCompleter.greedy option.

Be sure to update jedi to the latest stable version or to try the current development version to get better completions.

Matchers

All completions routines are implemented using unified Matchers API. The matchers API is provisional and subject to change without notice.

The built-in matchers include:

• IPCompleter.dict_key_matcher: dictionary key completions,

• IPCompleter.magic_matcher: completions for magics,

• IPCompleter.unicode_name_matcher, IPCompleter.fwd_unicode_matcher and IPCompleter.latex_name_matcher: see Forward latex/unicode completion,

• back_unicode_name_matcher and back_latex_name_matcher: see Backward latex completion,

• IPCompleter.file_matcher: paths to files and directories,

• IPCompleter.python_func_kw_matcher - function keywords,

• IPCompleter.python_matches - globals and attributes (v1 API),

• IPCompleter.jedi_matcher - static analysis with Jedi,

• IPCompleter.custom_completer_matcher - pluggable completer with a default implementation in InteractiveShell which uses IPython hooks system (complete_command) with string dispatch (including regular expressions). Differently to other matchers, custom_completer_matcher will not suppress Jedi results to match behaviour in earlier IPython versions.

Custom matchers can be added by appending to IPCompleter.custom_matchers list.

Matcher API

Simplifying some details, the Matcher interface can described as

MatcherAPIv1 = Callable[[str], list[str]]
MatcherAPIv2 = Callable[[CompletionContext], SimpleMatcherResult]

Matcher = MatcherAPIv1 | MatcherAPIv2

The MatcherAPIv1 reflects the matcher API as available prior to IPython 8.6.0 and remains supported as a simplest way for generating completions. This is also currently the only API supported by the IPython hooks system complete_command.

To distinguish between matcher versions matcher_api_version attribute is used. More precisely, the API allows to omit matcher_api_version for v1 Matchers, and requires a literal 2 for v2 Matchers.

Once the API stabilises future versions may relax the requirement for specifying matcher_api_version by switching to functools.singledispatch, therefore please do not rely on the presence of matcher_api_version for any purposes.

Suppression of competing matchers

By default results from all matchers are combined, in the order determined by their priority. Matchers can request to suppress results from subsequent matchers by setting suppress to True in the MatcherResult.

When multiple matchers simultaneously request suppression, the results from of the matcher with higher priority will be returned.

Sometimes it is desirable to suppress most but not all other matchers; this can be achieved by adding a set of identifiers of matchers which should not be suppressed to MatcherResult under do_not_suppress key.

The suppression behaviour can is user-configurable via IPCompleter.suppress_competing_matchers.