Fork me on GitHub

The Plugin API

Note: This documentation is for Plugin developers, who want to improve their editors/IDE autocompletion

If you want to use Jedi, you first need to import jedi. You then have direct access to the Script. You can then call the functions documented here. These functions return API classes.

Deprecations

The deprecation process is as follows:

  1. A deprecation is announced in the next major/minor release.
  2. We wait either at least a year & at least two minor releases until we remove the deprecated functionality.

API documentation

API Interface

The API basically only provides one class. You can create a Script and use its methods.

Additionally you can add a debug function with set_debug_function() and catch NotFoundError which is being raised if your completion is not possible.

Warning

Please, note that Jedi is not thread safe.

exception jedi.api.NotFoundError[source]

A custom error to avoid catching the wrong exceptions.

class jedi.api.Script(source=None, line=None, column=None, path=None, encoding='utf-8', source_path=None, source_encoding=None)[source]

A Script is the base for completions, goto or whatever you want to do with Jedi.

You can either use the source parameter or path to read a file. Usually you’re going to want to use both of them (in an editor).

Parameters:
  • source (str) – The source code of the current file, separated by newlines.
  • line (int) – The line to perform actions on (starting with 1).
  • col (int) – The column of the cursor (starting with 0).
  • path (str or None) – The path of the file in the file system, or '' if it hasn’t been saved yet.
  • encoding (str) – The encoding of source, if it is not a unicode object (default 'utf-8').
  • source_encoding – The encoding of source, if it is not a unicode object (default 'utf-8').
completions()[source]

Return classes.Completion objects. Those objects contain information about the completions, more than just names.

Returns:Completion objects, sorted by name and __ comes last.
Return type:list of classes.Completion
goto_definitions()[source]

Return the definitions of a the path under the cursor. goto function! This follows complicated paths and returns the end, not the first definition. The big difference between goto_assignments() and goto_definitions() is that goto_assignments() doesn’t follow imports and statements. Multiple objects may be returned, because Python itself is a dynamic language, which means depending on an option you can have two different versions of a function.

Return type:list of classes.Definition
goto_assignments()[source]

Return the first definition found. Imports and statements aren’t followed. Multiple objects may be returned, because Python itself is a dynamic language, which means depending on an option you can have two different versions of a function.

Return type:list of classes.Definition
usages(additional_module_paths=())[source]

Return classes.Definition objects, which contain all names that point to the definition of the name under the cursor. This is very useful for refactoring (renaming), or to show all usages of a variable.

Return type:list of classes.Definition
call_signatures()[source]

Return the function object of the call you’re currently in.

E.g. if the cursor is here:

abs(# <-- cursor is here

This would return the abs function. On the other hand:

abs()# <-- cursor is here

This would return None.

Return type:list of classes.CallSignature
class jedi.api.Interpreter(source, namespaces=, []**kwds)[source]

Jedi API for Python REPLs.

In addition to completion of simple attribute access, Jedi supports code completion based on static code analysis. Jedi can complete attributes of object which is not initialized yet.

>>> from os.path import join
>>> namespace = locals()
>>> script = Interpreter('join().up', [namespace])
>>> print(script.completions()[0].name)
upper

Parse source and mixin interpreted Python objects from namespaces.

Parameters:
  • source (str) – Code to parse.
  • namespaces (list of dict) – a list of namespace dictionaries such as the one returned by locals().

Other optional arguments are same as the ones for Script. If line and column are None, they are assumed be at the end of source.

jedi.api.defined_names(source, path=None, encoding='utf-8')[source]

Get all definitions in source sorted by its position.

This functions can be used for listing functions, classes and data defined in a file. This can be useful if you want to list them in “sidebar”. Each element in the returned list also has defined_names method which can be used to get sub-definitions (e.g., methods in class).

Return type:list of classes.Definition
jedi.api.preload_module(*modules)[source]

Preloading modules tells Jedi to load a module now, instead of lazy parsing of modules. Usful for IDEs, to control which modules to load on startup.

Parameters:modules – different module names, list of string.
jedi.api.set_debug_function(func_cb=<function print_to_stdout at 0x7f899fc4ac80>, warnings=True, notices=True, speed=True)[source]

Define a callback debug function to get all the debug messages.

Parameters:func_cb – The callback function for debug messages, with n params.

Examples

Completions:

>>> import jedi
>>> source = '''import json; json.l'''
>>> script = jedi.Script(source, 1, 19, '')
>>> script
<jedi.api.Script object at 0x2121b10>
>>> completions = script.complete()
>>> completions
[<Completion: load>, <Completion: loads>]
>>> completions[1]
<Completion: loads>
>>> completions[1].complete
'oads'
>>> completions[1].word
'loads'

Definitions / Goto:

>>> import jedi
>>> source = '''def my_func():
...     print 'called'
...
... alias = my_func
... my_list = [1, None, alias]
... inception = my_list[2]
...
... inception()'''
>>> script = jedi.Script(source, 8, 1, '')
>>>
>>> script.goto_assignments()
[<Definition inception=my_list[2]>]
>>>
>>> script.goto_definitions()
[<Definition def my_func>]

Related names:

>>> import jedi
>>> source = '''x = 3
... if 1 == 2:
...     x = 4
... else:
...     del x'''
>>> script = jedi.Script(source, 5, 8, '')
>>> rns = script.related_names()
>>> rns
[<RelatedName x@3,4>, <RelatedName x@1,0>]
>>> rns[0].start_pos
(3, 4)
>>> rns[0].is_keyword
False
>>> rns[0].text
'x'