API Overview¶

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:

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

API Documentation¶

The API consists of a few different parts:

The main starting points for complete/goto: Script and Interpreter
Helpful functions: preload_module() and set_debug_function()
API Result Classes
Python Versions/Virtualenv Support with functions like find_system_environments() and find_virtualenvs()

Static Analysis Interface¶

Jedi is a static analysis tool for Python that can be used in IDEs/editors. Jedi has a focus on autocompletion and goto functionality. Jedi is fast and is very well tested. It understands Python and stubs on a deep level.

Jedi has support for different goto functions. It’s possible to search for references and list names in a Python file to get information about them.

Jedi uses a very simple API to connect with IDE’s. There’s a reference implementation as a VIM-Plugin, which uses Jedi’s autocompletion. We encourage you to use Jedi in your IDEs. Autocompletion in your REPL is also possible, IPython uses it natively and for the CPython REPL you have to install it.

Here’s a simple example of the autocompletion feature:

>>> import jedi
>>> source = '''
... import json
... json.lo'''
>>> script = jedi.Script(source, path='example.py')
>>> script
<Script: 'example.py' ...>
>>> completions = script.complete(3, len('json.lo'))
>>> completions
[<Completion: load>, <Completion: loads>]
>>> print(completions[0].complete)
ad
>>> print(completions[0].name)
load

As you see Jedi is pretty simple and allows you to concentrate on writing a good text editor, while still having very good IDE features for Python.

class jedi.Script(source=None, line=None, column=None, path=None, encoding='utf-8', sys_path=None, environment=None, _project=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).

The script might be analyzed in a different sys.path than Jedi:

if sys_path parameter is not None, it will be used as sys.path for the script;
if sys_path parameter is None and VIRTUAL_ENV environment variable is defined, sys.path for the specified environment will be guessed (see jedi.inference.sys_path.get_venv_path()) and used for the script;
otherwise sys.path will match that of Jedi.

Parameters:

source (str) – The source code of the current file, separated by newlines.
line (int) – Deprecated, please use it directly on e.g. .complete
column (int) – Deprecated, please use it directly on e.g. .complete
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').
sys_path (list) – sys.path to use during analysis of the script
environment (Environment) – TODO

complete(line=None, column=None, *args, **kwargs)[source]¶

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

Parameters:	fuzzy – Default False. Will return fuzzy completions, which means that e.g. `ooa` will match `foobar`.
Returns:	Completion objects, sorted by name and `__` comes last.
Return type:	list of `classes.Completion`

infer(line=None, column=None, *args, **kwargs)[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() and infer() is that goto() 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.

Parameters:	only_stubs – Only return stubs for this goto call. prefer_stubs – Prefer stubs to Python objects for this type inference call.
Return type:	list of `classes.Definition`

goto(line=None, column=None, *args, **kwargs)[source]¶

Return the first definition found, while optionally following imports. 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.

Parameters:	follow_imports – The goto call will follow imports. follow_builtin_imports – If follow_imports is True will decide if it follow builtin imports. only_stubs – Only return stubs for this goto call. prefer_stubs – Prefer stubs to Python objects for this goto call.
Return type:	list of `classes.Definition`

help(line=None, column=None, *args, **kwargs)[source]¶

Works like goto and returns a list of Definition objects. Returns additional definitions for keywords and operators.

The additional definitions are of Definition(...).type == 'keyword'. These definitions do not have a lot of value apart from their docstring attribute, which contains the output of Python’s help() function.

Return type:	list of `classes.Definition`

get_references(line=None, column=None, *args, **kwargs)[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 references of a variable.

Parameters:	include_builtins – Default True, checks if a reference is a builtin (e.g. `sys`) and in that case does not return it.
Return type:	list of `classes.Definition`

get_signatures(line=None, column=None, *args, **kwargs)[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 an empty list..

Return type:	list of `classes.Signature`

get_names(**kwargs)[source]¶

Returns a list of Definition objects, containing name parts. This means you can call Definition.goto() and get the reference of a name.

Parameters:	all_scopes – If True lists the names of all scopes instead of only the module namespace. definitions – If True lists the names that have been defined by a class, function or a statement (`a = b` returns `a`). references – If True lists all the names that are not listed by `definitions=True`. E.g. `a = b` returns `b`.

class jedi.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.complete()[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.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.set_debug_function(func_cb=<function print_to_stdout>, warnings=True, notices=True, speed=True)[source]¶

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

If you don’t specify any arguments, debug messages will be printed to stdout.

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

Environments¶

Environments are a way to activate different Python versions or Virtualenvs for static analysis. The Python binary in that environment is going to be executed.

jedi.find_system_environments()[source]¶

Ignores virtualenvs and returns the Python versions that were installed on your system. This might return nothing, if you’re running Python e.g. from a portable version.

The environments are sorted from latest to oldest Python version.

Yields:	`Environment`

jedi.find_virtualenvs(paths=None, **kwargs)[source]¶

Parameters:

paths – A list of paths in your file system to be scanned for Virtualenvs. It will search in these paths and potentially execute the Python binaries.
safe – Default True. In case this is False, it will allow this function to execute potential python environments. An attacker might be able to drop an executable in a path this function is searching by default. If the executable has not been installed by root, it will not be executed.
use_environment_vars – Default True. If True, the VIRTUAL_ENV variable will be checked if it contains a valid VirtualEnv. CONDA_PREFIX will be checked to see if it contains a valid conda environment.

Yields:

Environment

jedi.get_system_environment(version)[source]¶

Return the first Python environment found for a string of the form ‘X.Y’ where X and Y are the major and minor versions of Python.

Raises:	`InvalidPythonEnvironment`
Returns:	`Environment`

jedi.create_environment(path, safe=True)[source]¶

Make it possible to manually create an Environment object by specifying a Virtualenv path or an executable path.

Raises:	`InvalidPythonEnvironment`
Returns:	`Environment`

jedi.get_default_environment()[source]¶

Tries to return an active Virtualenv or conda environment. If there is no VIRTUAL_ENV variable or no CONDA_PREFIX variable set set it will return the latest Python version installed on the system. This makes it possible to use as many new Python features as possible when using autocompletion and other functionality.

Returns:	`Environment`

exception jedi.InvalidPythonEnvironment[source]¶: If you see this exception, the Python executable or Virtualenv you have been trying to use is probably not a correct Python version.

class jedi.api.environment.Environment(executable)[source]¶

This class is supposed to be created by internal Jedi architecture. You should not create it directly. Please use create_environment or the other functions instead. It is then returned by that function.

get_sys_path(*args, **kwargs)[source]¶

The sys path for this environment. Does not include potential modifications like sys.path.append.

Returns:	list of str

Examples¶

Completions:

>>> import jedi
>>> source = '''import json; json.l'''
>>> script = jedi.Script(source, path='')
>>> script
<jedi.api.Script object at 0x2121b10>
>>> completions = script.complete(1, 19)
>>> completions
[<Completion: load>, <Completion: loads>]
>>> completions[1]
<Completion: loads>
>>> completions[1].complete
'oads'
>>> completions[1].name
'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, path='')
>>>
>>> script.goto(8, 1)
[<Definition inception=my_list[2]>]
>>>
>>> script.infer(8, 1)
[<Definition def my_func>]

References:

>>> import jedi
>>> source = '''x = 3
... if 1 == 2:
...     x = 4
... else:
...     del x'''
>>> script = jedi.Script(source, '')
>>> rns = script.get_references(5, 8)
>>> rns
[<Definition full_name='__main__.x', description='x = 3'>,
 <Definition full_name='__main__.x', description='x'>]
>>> rns[1].line
5
>>> rns[0].column
8