Man1 - python-jedi.1

Jedi is can be used with a variety of plugins, language servers <language-servers> and other software. It is also possible to use Jedi in the Python shell or with IPython.

Below you can also find a list of recipes for type hinting.

• jedi-language-server
• python-language-server
• anakin-language-server

• jedi-vim
• YouCompleteMe
• deoplete-jedi

• Python Extension

• Jedi.el
• elpy
• anaconda-mode

• SublimeJEDI (ST2 & ST3)
• anaconda (only ST3)

• SynJedi

• Textmate (Not sure if it’s actually working)

• Kate version 4.13+ supports it natively, you have to enable it, though.

• autocomplete-python-jedi

• GNOME Builder supports it natively, and is enabled by default.

• gedi

• Eric IDE (Available as a plugin)

• wdb

Jedi is a preinstalled extension in xonsh shell. Run the following command to enable:

#+begin_quote

      xontrib load jedi

#+end_quote

and many more!

Jedi is a dependency of IPython. Autocompletion in IPython is therefore possible without additional configuration.

Here is an example video how REPL completion can look like in a different shell.

There are two different options how you can use Jedi autocompletion in your python interpreter. One with your custom $HOME/.pythonrc.py file and one that uses PYTHONSTARTUP.

To use Jedi completion in Python interpreter, add the following in your shell setup (e.g., .bashrc). This works only on Linux/Mac, because readline is not available on Windows. If you still want Jedi autocompletion in your REPL, just use IPython instead:

#+begin_quote

      export PYTHONSTARTUP="$(python -m jedi repl)"

#+end_quote

Then you will be able to use Jedi completer in your Python interpreter:

#+begin_quote

      $ python
      Python 3.9.2+ (default, Jul 20 2020, 22:15:08)
      [GCC 4.6.1] on linux2
      Type "help", "copyright", "credits" or "license" for more information.
      >>> import os
      >>> os.path.join('a', 'b').split().in<TAB>            # doctest: +SKIP
      ..dex   ..sert

#+end_quote

• jedi.utils.setup_readline(namespace_module=<module ’main’ from ’/usr/bin/sphinx-build’>, fuzzy=False) :: This function sets up readline to use Jedi in a Python interactive shell.

If you want to use a custom PYTHONSTARTUP file (typically $HOME/.pythonrc.py), you can add this piece of code:

#+begin_quote

#+begin_quote

        try:
            from jedi.utils import setup_readline
        except ImportError:
            # Fallback to the stdlib readline completer if it is installed.
            # Taken from http://docs.python.org/2/library/rlcompleter.html
            print("Jedi is not installed, falling back to readline")
            try:
                import readline
                import rlcompleter
                readline.parse_and_bind("tab: complete")
            except ImportError:
                print("Readline is not installed either. No tab completion is enabled.")
        else:
            setup_readline()

#+end_quote

This will fallback to the readline completer if Jedi is not installed. The readline completer will only complete names in the global namespace, so for example:

#+begin_quote

        ran<TAB>

#+end_quote

will complete to range.

With Jedi the following code:

#+begin_quote

        range(10).cou<TAB>

#+end_quote

will complete to range(10).count, this does not work with the default cPython readline completer.

You will also need to add export PYTHONSTARTUP=$HOME/.pythonrc.py to your shell profile (usually .bash_profile or .profile if you use bash). #+end_quote

Here are some tips on how to use Jedi efficiently.

If Jedi cannot detect the type of a function argument correctly (due to the dynamic nature of Python), you can help it by hinting the type using one of the docstring/annotation styles below. Only gradual typing will always work, all the docstring solutions are glorified hacks and more complicated cases will probably not work.

You can read a lot about Python’s gradual typing system in the corresponding PEPs like:

• PEP 484 as an introduction
• PEP 526 for variable annotations
• PEP 589 for TypeDict
• There are probably more :)

Below you can find a few examples how you can use this feature.

Function annotations:

#+begin_quote

      def myfunction(node: ProgramNode, foo: str) -> None:
          """Do something with a ``node``.

          """
          node.| # complete here

#+end_quote

Assignment, for-loop and with-statement type hints:

#+begin_quote

      import typing
      x: int = foo()
      y: typing.Optional[int] = 3

      key: str
      value: Employee
      for key, value in foo.items():
          pass

      f: Union[int, float]
      with foo() as f:
          print(f + 3)

#+end_quote

PEP-0484 should be supported in its entirety. Feel free to open issues if that is not the case. You can also use stub files.

http://www.sphinx-doc.org/en/stable/domains.html#info-field-lists

#+begin_quote

      def myfunction(node, foo):
          """
          Do something with a ``node``.

          :type node: ProgramNode
          :param str foo: foo parameter description
          """
          node.| # complete here

#+end_quote

http://epydoc.sourceforge.net/manual-fields.html

#+begin_quote

      def myfunction(node):
          """
          Do something with a ``node``.

          @type node: ProgramNode
          """
          node.| # complete here

#+end_quote

https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt

In order to support the numpydoc format, you need to install the numpydoc package.

#+begin_quote

      def foo(var1, var2, long_var_name='hi'):
          r"""
          A one-line summary that does not use variable names or the
          function name.

          ...

          Parameters
          ----------
          var1 : array_like
              Array_like means all those objects -- lists, nested lists,
              etc. -- that can be converted to an array. We can also
              refer to variables like `var1`.
          var2 : int
              The type above can either refer to an actual Python type
              (e.g. ``int``), or describe the type of the variable in more
              detail, e.g. ``(N,) ndarray`` or ``array_like``.
          long_variable_name : {'hi', 'ho'}, optional
              Choices in brackets, default first when optional.

          ...

          """
          var2.| # complete here

#+end_quote

Jedi’s main API calls and features are:

• Autocompletion: Script.complete(); It’s also possible to get it working in your REPL (IPython, etc.)
• Goto/Type Inference: Script.goto() and Script.infer()
• Static Analysis: Script.get_names() and Script.get_syntax_errors()
• Refactorings: Script.rename(), Script.inline(), Script.extract_variable() and Script.extract_function()
• Code Search: Script.search() and Project.search()

• Python 3.6+ support
• Ignores syntax errors and wrong indentation
• Can deal with complex module / function / class structures
• Great virtualenv*/*venv support
• Works great with Python’s type hinting,
• Understands stub files
• Can infer function arguments for sphinx, epydoc and basic numpydoc docstrings
• Is overall a very solid piece of software that has been refined for a long time. Bug reports are very welcome and are usually fixed within a few weeks.

Jedi supports many of the widely used Python features:

• builtins
• returns, yields, yield from
• tuple assignments / array indexing / dictionary indexing / star unpacking
• with-statement / exception handling
• *args / **kwargs
• decorators / lambdas / closures
• generators / iterators
• descriptors: property / staticmethod / classmethod / custom descriptors
• some magic methods: __call__, __iter__, __next__, __get__, __getitem__, __init__
• list.append(), set.add(), list.extend(), etc.
• (nested) list comprehensions / ternary expressions
• relative imports
• getattr() / __getattr__ / __getattribute__
• function annotations
• simple/typical sys.path modifications
• isinstance checks for if/while/assert
• namespace packages (includes pkgutil, pkg_resources and PEP420 namespaces)
• Django / Flask / Buildout support
• Understands Pytest fixtures

In general Jedi’s limit is quite high, but for very big projects or very complex code, sometimes Jedi intentionally stops type inference, to avoid hanging for a long time.

Additionally there are some Python patterns Jedi does not support. This is intentional and below should be a complete list:

• Arbitrary metaclasses: Some metaclasses like enums and dataclasses are reimplemented in Jedi to make them work. Most of the time stubs are good enough to get type inference working, even when metaclasses are involved.
• setattr(), __import__()
• Writing to some dicts: globals(), locals(), object.__dict__
• Manipulations of instances outside the instance variables without using methods

Importing numpy can be quite slow sometimes, as well as loading the builtins the first time. If you want to speed things up, you could preload libriaries in Jedi, with preload_module(). However, once loaded, this should not be a problem anymore. The same is true for huge modules like PySide, wx, tensorflow, pandas, etc.

Jedi does not have a very good cache layer. This is probably the biggest and only architectural issue in Jedi. Unfortunately it is not easy to change that. Dave Halter is thinking about rewriting Jedi in Rust, but it has taken Jedi more than 8 years to reach version 1.0, a rewrite will probably also take years.

Security is an important topic for Jedi. By default, no code is executed within Jedi. As long as you write pure Python, everything is inferred statically. If you enable load_unsafe_extensions=True for your Project and you use builtin modules (c_builtin) Jedi will execute those modules. If you don’t trust a code base, please do not enable that option. It might lead to arbitrary code execution.

If you want security for Interpreter, do not use it. Jedi does execute properties and in general is not very careful to avoid code execution. This is intentional: Most people trust the code bases they have imported, because at that point a malicious code base would have had code execution already.

NOTE:

#+begin_quote This documentation is mostly for Plugin developers, who want to improve their editors/IDE with Jedi.

#+end_quote

The API consists of a few different parts:

• The main starting points for complete/goto: Script and Interpreter. If you work with Jedi you want to understand these classes first.
• API Result Classes
• Python Versions/Virtualenv Support with functions like find_system_environments() and find_virtualenvs()
• A way to work with different Folders / Projects
• Helpful functions: preload_module() and set_debug_function()

The methods that you are most likely going to use to work with Jedi are the following ones:

• class jedi.Script(code=None, *, path=None, environment=None, project=None) :: A Script is the base for completions, goto or whatever you want to do with Jedi. The counter part of this class is Interpreter, which works with actual dictionaries and can work with a REPL. This class should be used when a user edits code in an editor.

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

The Script’s sys.path is very customizable:

#+begin_quote

• If project is provided with a sys_path, that is going to be used.
• If environment is provided, its sys.path will be used (see Environment.get_sys_path);
• Otherwise sys.path will match that of the default environment of Jedi, which typically matches the sys path that was used at the time when Jedi was imported.

Most methods have a line and a column parameter. Lines in Jedi are always 1-based and columns are always zero based. To avoid repetition they are not always documented. You can omit both line and column. Jedi will then just do whatever action you are calling at the end of the file. If you provide only the line, just will complete at the end of that line.

WARNING:

#+begin_quote By default jedi.settings.fast_parser is enabled, which means that parso reuses modules (i.e. they are not immutable). With this setting Jedi is not thread safe and it is also not safe to use multiple Script instances and its definitions at the same time.

If you are a normal plugin developer this should not be an issue. It is an issue for people that do more complex stuff with Jedi.

This is purely a performance optimization and works pretty well for all typical usages, however consider to turn the setting off if it causes you problems. See also this discussion.

#+end_quote

Parameters

• code (str) – The source code of the current file, separated by newlines.
• path (str or pathlib.Path or None) – The path of the file in the file system, or ’’ if it hasn’t been saved yet.
• environment (Environment) – Provide a predefined Environment to work with a specific Python version or virtualenv.
• project (Project) – Provide a Project to make sure finding references works well, because the right folder is searched. There are also ways to modify the sys path and other things.

complete(line=None, column=None, *, fuzzy=False)

Completes objects under the cursor.

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

#+begin_quote

Parameters

fuzzy – Default False. Will return fuzzy completions, which means that e.g. ooa will match foobar.

Returns

Completion objects, sorted by name. Normal names appear before “private” names that start with _ and those appear before magic methods and name mangled names that start with __.

Return type

list of Completion

#+end_quote

• infer(line=None, column=None, *, only_stubs=False, prefer_stubs=False) :: Return the definitions of under the cursor. It is basically a wrapper around Jedi’s type inference.

This method 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 depending on an option you can have two different versions of a function.

#+begin_quote

Parameters

• only_stubs – Only return stubs for this method.
• prefer_stubs – Prefer stubs to Python objects for this method.

Return type

list of Name

#+end_quote

• goto(line=None, column=None, *, follow_imports=False, follow_builtin_imports=False, only_stubs=False, prefer_stubs=False) :: Goes to the name that defined the object under the cursor. Optionally you can follow imports. Multiple objects may be returned, depending on an if you can have two different versions of a function.

  Parameters

  • follow_imports – The method will follow imports.
  • follow_builtin_imports – If follow_imports is True will try to look up names in builtins (i.e. compiled or extension modules).
  • only_stubs – Only return stubs for this method.
  • prefer_stubs – Prefer stubs to Python objects for this method.

  Return type

  list of Name

search(string, *, all_scopes=False)

Searches a name in the current file. For a description of how the search string should look like, please have a look at Project.search().

Parameters

all_scopes (bool) – Default False; searches not only for definitions on the top level of a module level, but also in functions and classes.

Yields

Name

complete_search(string, **kwargs)

Like Script.search(), but completes that string. If you want to have all possible definitions in a file you can also provide an empty string.

Parameters

• all_scopes (bool) – Default False; searches not only for definitions on the top level of a module level, but also in functions and classes.
• fuzzy – Default False. Will return fuzzy completions, which means that e.g. ooa will match foobar.

Yields

Completion

help(line=None, column=None)

Used to display a help window to users. Uses Script.goto() and returns additional definitions for keywords and operators.

Typically you will want to display BaseName.docstring() to the user for all the returned definitions.

The additional definitions are Name(…).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.

#+begin_quote

Return type

list of Name

#+end_quote

get_references(line=None, column=None, **kwargs)

Lists all references of a variable in a project. Since this can be quite hard to do for Jedi, if it is too complicated, Jedi will stop searching.

Parameters

• include_builtins – Default True. If False, checks if a definition is a builtin (e.g. sys) and in that case does not return it.
• scope – Default ’project’. If ’file’, include references in the current module only.

Return type

list of Name

get_signatures(line=None, column=None)

Return the function object of the call under the cursor.

E.g. if the cursor is here:

#+begin_quote

#+begin_quote

          abs(# <-- cursor is here

#+end_quote

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

#+begin_quote

          abs()# <-- cursor is here

#+end_quote

This would return an empty list..

Return type

list of Signature

#+end_quote

get_context(line=None, column=None)

Returns the scope context under the cursor. This basically means the function, class or module where the cursor is at.

Return type

Name

get_names(**kwargs)

Returns names defined in the current file.

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.

Return type

list of Name

get_syntax_errors()

Lists all syntax errors in the current file.

Return type

list of SyntaxError

rename(line=None, column=None, *, new_name)

Renames all references of the variable under the cursor.

Parameters

new_name – The variable under the cursor will be renamed to this string.

Raises

RefactoringError

Return type

Refactoring

• extract_variable(line, column, *, new_name, until_line=None, until_column=None) :: Moves an expression to a new statemenet.

For example if you have the cursor on foo and provide a new_name called bar:

#+begin_quote

#+begin_quote

          foo = 3.1
          x = int(foo + 1)

#+end_quote

the code above will become:

#+begin_quote

          foo = 3.1
          bar = foo + 1
          x = int(bar)

#+end_quote

Parameters

• new_name – The expression under the cursor will be renamed to this string.
• until_line (int) – The the selection range ends at this line, when omitted, Jedi will be clever and try to define the range itself.
• until_column (int) – The the selection range ends at this column, when omitted, Jedi will be clever and try to define the range itself.

Raises

RefactoringError

Return type

Refactoring

#+end_quote

• extract_function(line, column, *, new_name, until_line=None, until_column=None) :: Moves an expression to a new function.

For example if you have the cursor on foo and provide a new_name called bar:

#+begin_quote

#+begin_quote

          global_var = 3

          def x():
              foo = 3.1
              x = int(foo + 1 + global_var)

#+end_quote

the code above will become:

#+begin_quote

          global_var = 3

          def bar(foo):
              return int(foo + 1 + global_var)

          def x():
              foo = 3.1
              x = bar(foo)

#+end_quote

Parameters

• new_name – The expression under the cursor will be replaced with a function with this name.
• until_line (int) – The the selection range ends at this line, when omitted, Jedi will be clever and try to define the range itself.
• until_column (int) – The the selection range ends at this column, when omitted, Jedi will be clever and try to define the range itself.

Raises

RefactoringError

Return type

Refactoring

#+end_quote

inline(line=None, column=None)

Inlines a variable under the cursor. This is basically the opposite of extracting a variable. For example with the cursor on bar:

#+begin_quote

          foo = 3.1
          bar = foo + 1
          x = int(bar)

the code above will become:

#+begin_quote

          foo = 3.1
          x = int(foo + 1)

#+end_quote

Raises

RefactoringError

Return type

Refactoring

#+end_quote #+end_quote

• class jedi.Interpreter(code, namespaces, *, project=None, **kwds) :: Jedi’s API for Python REPLs.

Implements all of the methods that are present in Script as well.

In addition to completions that normal REPL completion does like str.upper, Jedi also supports code completion based on static code analysis. For example Jedi will complete str().upper.

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

All keyword arguments are same as the arguments for Script.

#+begin_quote

Parameters

• code (str) – Code to parse.
• namespaces (typing.List[dict]) – A list of namespace dictionaries such as the one returned by globals() and locals().

#+end_quote

Projects are a way to handle Python projects within Jedi. For simpler plugins you might not want to deal with projects, but if you want to give the user more flexibility to define sys paths and Python interpreters for a project, Project is the perfect way to allow for that.

Projects can be saved to disk and loaded again, to allow project definitions to be used across repositories.

jedi.get_default_project(path=None)

If a project is not defined by the user, Jedi tries to define a project by itself as well as possible. Jedi traverses folders until it finds one of the following:

1. A .jedi/config.json
2. One of the following files: setup.py, .git, .hg, requirements.txt and MANIFEST.in.

• class jedi.Project(path, *, environment_path=None, load_unsafe_extensions=False, sys_path=None, added_sys_path=(), smart_sys_path=True) :: Projects are a simple way to manage Python folders and define how Jedi does import resolution. It is mostly used as a parameter to Script. Additionally there are functions to search a whole project.

  Parameters

  • path – The base path for this project.
  • environment_path – The Python executable path, typically the path of a virtual environment.
  • load_unsafe_extensions – Default False, Loads extensions that are not in the sys path and in the local directories. With this option enabled, this is potentially unsafe if you clone a git repository and analyze it’s code, because those compiled extensions will be important and therefore have execution privileges.
  • sys_path – list of str. You can override the sys path if you want. By default the sys.path. is generated by the environment (virtualenvs, etc).
  • added_sys_path – list of str. Adds these paths at the end of the sys path.
  • smart_sys_path – If this is enabled (default), adds paths from local directories. Otherwise you will have to rely on your packages being properly configured on the sys.path.

#+begin_quote

classmethod load(path)

Loads a project from a specific path. You should not provide the path to .jedi/project.json, but rather the path to the project folder.

Parameters

path – The path of the directory you want to use as a project.

save()

Saves the project configuration in the project in .jedi/project.json.

added_sys_path

The sys path that is going to be added at the end of the

property path

The base path for this project.

property sys_path

The sys path provided to this project. This can be None and in that case will be auto generated.

property smart_sys_path

If the sys path is going to be calculated in a smart way, where additional paths are added.

property load_unsafe_extensions

Wheter the project loads unsafe extensions.

search(string, *, all_scopes=False)

Searches a name in the whole project. If the project is very big, at some point Jedi will stop searching. However it’s also very much recommended to not exhaust the generator. Just display the first ten results to the user.

There are currently three different search patterns:

#+begin_quote

• foo to search for a definition foo in any file or a file called foo.py or foo.pyi.
• foo.bar to search for the foo and then an attribute bar in it.
• class foo.bar.Bar or def foo.bar.baz to search for a specific API type.

Parameters

all_scopes (bool) – Default False; searches not only for definitions on the top level of a module level, but also in functions and classes.

Yields

Name

#+end_quote

complete_search(string, **kwargs)

Like Script.search(), but completes that string. An empty string lists all definitions in a project, so be careful with that.

Parameters

all_scopes (bool) – Default False; searches not only for definitions on the top level of a module level, but also in functions and classes.

Yields

Completion

#+end_quote

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(, env_vars=None)*

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.

#+begin_quote

Yields

Environment

#+end_quote

• jedi.find_virtualenvs(paths=None, *, safe=True, use_environment_vars=True) ::

  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, *, env_vars=None)

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, env_vars=None)

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

Raises

InvalidPythonEnvironment

Returns

Environment

jedi.get_default_environment()

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

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, env_vars=None) :: 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()

  The sys path for this environment. Does not include potential modifications from e.g. appending to sys.path.

  Returns

  list of str

jedi.preload_module(*modules)

Preloading modules tells Jedi to load a module now, instead of lazy parsing of modules. This can be useful 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) :: 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.

#+begin_quote

Parameters

func_cb – The callback function for debug messages.

#+end_quote

exception jedi.InternalError

This error might happen a subprocess is crashing. The reason for this is usually broken C code in third party libraries. This is not a very common thing and it is safe to use Jedi again. However using the same calls might result in the same error again.

exception jedi.RefactoringError

Refactorings can fail for various reasons. So if you work with refactorings like Script.rename(), Script.inline(), Script.extract_variable() and Script.extract_function(), make sure to catch these. The descriptions in the errors are ususally valuable for end users.

A typical RefactoringError would tell the user that inlining is not possible if no name is under the cursor.

#+begin_quote

      >>> import jedi
      >>> code = '''import json; json.l'''
      >>> script = jedi.Script(code, path='example.py')
      >>> script
      <Script: 'example.py' <SameEnvironment: 3.9.0 in /usr>>
      >>> completions = script.complete(1, 19)
      >>> completions
      [<Completion: load>, <Completion: loads>]
      >>> completions[1]
      <Completion: loads>
      >>> completions[1].complete
      'oads'
      >>> completions[1].name
      'loads'

#+end_quote

#+begin_quote

      >>> import jedi
      >>> code = '''\
      ... def my_func():
      ...     print 'called'
      ...
      ... alias = my_func
      ... my_list = [1, None, alias]
      ... inception = my_list[2]
      ...
      ... inception()'''
      >>> script = jedi.Script(code)
      >>>
      >>> script.goto(8, 1)
      [<Name full_name='__main__.inception', description='inception = my_list[2]'>]
      >>>
      >>> script.infer(8, 1)
      [<Name full_name='__main__.my_func', description='def my_func'>]

#+end_quote

#+begin_quote

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

#+end_quote

The deprecation process is as follows:

1. A deprecation is announced in any release.
2. The next major release removes the deprecated functionality.

class jedi.api.classes.BaseName(inference_state, name)

Bases: object

The base class for all definitions, completions and signatures.

#+begin_quote

property module_path: Optional[/pathlib.Path/]

Shows the file path of a module. e.g. /usr/lib/python3.9/os.py

property name

Name of variable/function/class/module.

For example, for x = None it returns ’x’.

#+begin_quote

Return type

str or None

#+end_quote

property type

The type of the definition.

Here is an example of the value of this attribute. Let’s consider the following source. As what is in variable is unambiguous to Jedi, jedi.Script.infer() should return a list of definition for sys, f, C and x.

      >>> from jedi import Script
      >>> source = '''
      ... import keyword
      ...
      ... class C:
      ...     pass
      ...
      ... class D:
      ...     pass
      ...
      ... x = D()
      ...
      ... def f():
      ...     pass
      ...
      ... for variable in [keyword, f, C, x]:
      ...     variable'''

      >>> script = Script(source)
      >>> defs = script.infer()

Before showing what is in defs, let’s sort it by line so that it is easy to relate the result to the source code.

      >>> defs = sorted(defs, key=lambda d: d.line)
      >>> print(defs)  
      [<Name full_name='keyword', description='module keyword'>,
       <Name full_name='__main__.C', description='class C'>,
       <Name full_name='__main__.D', description='instance D'>,
       <Name full_name='__main__.f', description='def f'>]

Finally, here is what you can get from type:

      >>> defs = [d.type for d in defs]
      >>> defs[0]
      'module'
      >>> defs[1]
      'class'
      >>> defs[2]
      'instance'
      >>> defs[3]
      'function'

Valid values for type are module, class, instance, function, param, path, keyword, property and statement.

property module_name

The module name, a bit similar to what __name__ is in a random Python module.

      >>> from jedi import Script
      >>> source = 'import json'
      >>> script = Script(source, path='example.py')
      >>> d = script.infer()[0]
      >>> print(d.module_name)  
      json

in_builtin_module()

Returns True, if this is a builtin module.

property line

The line where the definition occurs (starting with 1).

property column

The column where the definition occurs (starting with 0).

get_definition_start_position()

The (row, column) of the start of the definition range. Rows start with 1, columns start with 0.

Return type

Optional[Tuple[/int/, /int/]]

get_definition_end_position()

The (row, column) of the end of the definition range. Rows start with 1, columns start with 0.

Return type

Optional[Tuple[/int/, /int/]]

docstring(raw=False, fast=True)

Return a document string for this completion object.

Example:

      >>> from jedi import Script
      >>> source = '''\
      ... def f(a, b=1):
      ...     "Document for function f."
      ... '''
      >>> script = Script(source, path='example.py')
      >>> doc = script.infer(1, len('def f'))[0].docstring()
      >>> print(doc)
      f(a, b=1)

      Document for function f.

Notice that useful extra information is added to the actual docstring, e.g. function signatures are prepended to their docstrings. If you need the actual docstring, use raw=True instead.

      >>> print(script.infer(1, len('def f'))[0].docstring(raw=True))
      Document for function f.

#+begin_quote

Parameters

fast – Don’t follow imports that are only one level deep like import foo, but follow from foo import bar. This makes sense for speed reasons. Completing import a is slow if you use the foo.docstring(fast=False) on every object, because it parses all libraries starting with a.

#+end_quote

property description

A description of the Name object, which is heavily used in testing. e.g. for isinstance it returns def isinstance.

Example:

      >>> from jedi import Script
      >>> source = '''
      ... def f():
      ...     pass
      ...
      ... class C:
      ...     pass
      ...
      ... variable = f if random.choice([0,1]) else C'''
      >>> script = Script(source)  # line is maximum by default
      >>> defs = script.infer(column=3)
      >>> defs = sorted(defs, key=lambda d: d.line)
      >>> print(defs)  
      [<Name full_name='__main__.f', description='def f'>,
       <Name full_name='__main__.C', description='class C'>]
      >>> str(defs[0].description)
      'def f'
      >>> str(defs[1].description)
      'class C'

property full_name

Dot-separated path of this object.

It is in the form of <module>[.<submodule>[…]][.<object>]. It is useful when you want to look up Python manual of the object at hand.

Example:

      >>> from jedi import Script
      >>> source = '''
      ... import os
      ... os.path.join'''
      >>> script = Script(source, path='example.py')
      >>> print(script.infer(3, len('os.path.join'))[0].full_name)
      os.path.join

Notice that it returns ’os.path.join’ instead of (for example) ’posixpath.join’. This is not correct, since the modules name would be <module ’posixpath’ …>`. However most users find the latter more practical.

is_stub()

Returns True if the current name is defined in a stub file.

is_side_effect()

Checks if a name is defined as self.foo = 3. In case of self, this function would return False, for foo it would return True.

• goto(, follow_imports=False, follow_builtin_imports=False, only_stubs=False, prefer_stubs=False)* :: Like Script.goto() (also supports the same params), but does it for the current name. This is typically useful if you are using something like Script.get_names().

  Parameters

  • follow_imports – The goto call will follow imports.
  • follow_builtin_imports – If follow_imports is True will try to look up names in builtins (i.e. compiled or extension modules).
  • only_stubs – Only return stubs for this goto call.
  • prefer_stubs – Prefer stubs to Python objects for this goto call.

  Return type

  list of Name

infer(, only_stubs=False, prefer_stubs=False)*

Like Script.infer(), it can be useful to understand which type the current name has.

Return the actual definitions. I strongly recommend not using it for your completions, because it might slow down Jedi. If you want to read only a few objects (<=20), it might be useful, especially to get the original docstrings. The basic problem of this function is that it follows all results. This means with 1000 completions (e.g. numpy), it’s just very, very slow.

#+begin_quote

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 Name

#+end_quote

parent()

Returns the parent scope of this identifier.

Return type

Name

get_line_code(before=0, after=0)

Returns the line of code where this object was defined.

Parameters

• before – Add n lines before the current line to the output.
• after – Add n lines after the current line to the output.

Return str

Returns the line(s) of code or an empty string if it’s a builtin.

get_signatures()

Returns all potential signatures for a function or a class. Multiple signatures are typical if you use Python stubs with @overload.

Return type

list of BaseSignature

execute()

Uses type inference to “execute” this identifier and returns the executed objects.

Return type

list of Name

get_type_hint()

Returns type hints like Iterable[int] or Union[int, str].

This method might be quite slow, especially for functions. The problem is finding executions for those functions to return something like Callable[[int, str], str].

#+begin_quote

Return type

str

#+end_quote #+end_quote

class jedi.api.classes.Name(inference_state, definition)

Bases: jedi.api.classes.BaseName

Name objects are returned from many different APIs including Script.goto() or Script.infer().

#+begin_quote

defined_names()

List sub-definitions (e.g., methods in class).

Return type

list of Name

is_definition()

Returns True, if defined as a name in a statement, function or class. Returns False, if it’s a reference to such a definition.

#+end_quote

• class jedi.api.classes.Completion(inference_state, name, stack, like_name_length, is_fuzzy, cached_name=None) :: Bases: jedi.api.classes.BaseName

Completion objects are returned from Script.complete(). They provide additional information about a completion.

#+begin_quote

property complete

Only works with non-fuzzy completions. Returns None if fuzzy completions are used.

Return the rest of the word, e.g. completing isinstance:

#+begin_quote

#+begin_quote

          isinstan# <-- Cursor is here

#+end_quote

would return the string ’ce’. It also adds additional stuff, depending on your settings.py.

Assuming the following function definition:

#+begin_quote

          def foo(param=0):
              pass

#+end_quote

completing foo(par would give a Completion which complete would be am=. #+end_quote

property name_with_symbols

Similar to name, but like name returns also the symbols, for example assuming the following function definition:

#+begin_quote

          def foo(param=0):
              pass

completing foo( would give a Completion which name_with_symbols would be “param=”. #+end_quote

docstring(raw=False, fast=True)

Documented under BaseName.docstring().

property type

Documented under BaseName.type().

get_completion_prefix_length()

Returns the length of the prefix being completed. For example, completing isinstance:

#+begin_quote

          isinstan# <-- Cursor is here

would return 8, because len(’isinstan’) == 8.

Assuming the following function definition:

#+begin_quote

          def foo(param=0):
              pass

#+end_quote

completing foo(par would return 3. #+end_quote #+end_quote

• class jedi.api.classes.BaseSignature(inference_state, signature) :: Bases: jedi.api.classes.Name

These signatures are returned by BaseName.get_signatures() calls.

#+begin_quote

property params

Returns definitions for all parameters that a signature defines. This includes stuff like *args and **kwargs.

Return type

list of ParamName

to_string()

Returns a text representation of the signature. This could for example look like foo(bar, baz: int, **kwargs).

Return type

str

#+end_quote

• class jedi.api.classes.Signature(inference_state, signature, call_details) :: Bases: jedi.api.classes.BaseSignature

A full signature object is the return value of Script.get_signatures().

#+begin_quote

property index

Returns the param index of the current cursor position. Returns None if the index cannot be found in the curent call.

Return type

int

property bracket_start

Returns a line/column tuple of the bracket that is responsible for the last function call. The first line is 1 and the first column 0.

Return type

int, int

#+end_quote

• class jedi.api.classes.ParamName(inference_state, definition) :: Bases: jedi.api.classes.Name

  infer_default()

  Returns default values like the 1 of def foo(x=1):.

  Return type

  list of Name

#+begin_quote

infer_annotation(**kwargs)

Parameters

execute_annotation – Default True; If False, values are not executed and classes are returned instead of instances.

Return type

list of Name

to_string()

Returns a simple representation of a param, like f: Callable[…, Any].

Return type

str

property kind

Returns an enum instance of inspect’s Parameter enum.

Return type

inspect.Parameter.kind

#+end_quote

• class jedi.api.refactoring.Refactoring(inference_state, file_to_node_changes, renames=()) :: Bases: object
  • get_renames() -> Iterable[Tuple[/pathlib.Path/, /pathlib.Path/]] :: Files can be renamed in a refactoring.

#+begin_quote

apply()

Applies the whole refactoring to the files, which includes renames.

#+end_quote

class jedi.api.errors.SyntaxError(parso_error)

Bases: object

Syntax errors are generated by Script.get_syntax_errors().

#+begin_quote

property line

The line where the error starts (starting with 1).

property column

The column where the error starts (starting with 0).

property until_line

The line where the error ends (starting with 1).

property until_column

The column where the error ends (starting with 0).

#+end_quote

WARNING:

#+begin_quote Most people will want to install Jedi as a submodule/vendored and not through pip/system wide. The reason for this is that it makes sense that the plugin that uses Jedi has always access to it. Otherwise Jedi will not work properly when virtualenvs are activated. So please read the documentation of your editor/IDE plugin to install Jedi.

For plugin developers, Jedi works best if it is always available. Vendoring is a pretty good option for that.

#+end_quote

You can either include Jedi as a submodule in your text editor plugin (like jedi-vim does by default), or you can install it systemwide.

NOTE:

#+begin_quote This just installs the Jedi library, not the editor plugins. For information about how to make it work with your editor, refer to the corresponding documentation.

#+end_quote

Most people use Jedi with a editor plugins. Typically you install Jedi by installing an editor plugin. No necessary steps are needed. Just take a look at the instructions for the plugin.

On any system you can install Jedi directly from the Python package index using pip:

#+begin_quote

      sudo pip install jedi

#+end_quote

If you want to install the current development version (master branch):

#+begin_quote

      sudo pip install -e git://github.com/davidhalter/jedi.git#egg=jedi

#+end_quote

You can install Jedi directly from official Arch Linux packages:

• python-jedi

(There is also a packaged version of the vim plugin available: vim-jedi at Arch Linux.)

Debian packages are available in the unstable repository.

We are in the discussion of adding Jedi to the Fedora repositories.

If you prefer not to use an automated package installer, you can clone the source from GitHub and install it manually. To install it, run these commands:

#+begin_quote

      git clone --recurse-submodules https://github.com/davidhalter/jedi
      cd jedi
      sudo python setup.py install

#+end_quote

If you use an editor plugin like jedi-vim, you can simply include Jedi as a git submodule of the plugin directory. Vim plugin managers like Vundle or Pathogen make it very easy to keep submodules up to date.

This module contains variables with global Jedi settings. To change the behavior of Jedi, change the variables defined in jedi.settings.

Plugins should expose an interface so that the user can adjust the configuration.

Example usage:

#+begin_quote

      from jedi import settings
      settings.case_insensitive_completion = True

#+end_quote

jedi.settings.case_insensitive_completion = True

Completions are by default case insensitive.

jedi.settings.add_bracket_after_function = False

Adds an opening bracket after a function for completions.

jedi.settings.cache_directory = ’build.cache/jedi’

The path where the cache is stored.

On Linux, this defaults to ~/.cache/jedi/, on OS X to ~/Library/Caches/Jedi/ and on Windows to %LOCALAPPDATA%\Jedi\Jedi\. On Linux, if the environment variable $XDG_CACHE_HOME is set, $XDG_CACHE_HOME/jedi is used instead of the default one.

jedi.settings.fast_parser = True

Uses Parso’s diff parser. If it is enabled, this might cause issues, please read the warning on Script. This feature makes it possible to only parse the parts again that have changed, while reusing the rest of the syntax tree.

jedi.settings.dynamic_array_additions = True

check for append, etc. on arrays: [], {}, () as well as list/set calls.

jedi.settings.dynamic_params = True

A dynamic param completion, finds the callees of the function, which define the params of a function.

jedi.settings.dynamic_params_for_other_modules = True

Do the same for other modules.

jedi.settings.auto_import_modules = [’gi’]

Modules that will not be analyzed but imported, if they contain Python code. This improves autocompletion for libraries that use setattr or globals() modifications a lot.

jedi.settings.call_signatures_validity = 3.0

Finding function calls might be slow (0.1-0.5s). This is not acceptible for normal writing. Therefore cache it for a short time.

NOTE:

#+begin_quote This documentation is for Jedi developers who want to improve Jedi itself, but have no idea how Jedi works. If you want to use Jedi for your IDE, look at the plugin api. It is also important to note that it’s a pretty old version and some things might not apply anymore.

#+end_quote

This page tries to address the fundamental demand for documentation of the Jedi internals. Understanding a dynamic language is a complex task. Especially because type inference in Python can be a very recursive task. Therefore Jedi couldn’t get rid of complexity. I know that simple is better than complex, but unfortunately it sometimes requires complex solutions to understand complex systems.

In six chapters I’m trying to describe the internals of Jedi:

• The Jedi Core
• Core Extensions
• Imports & Modules
• Stubs & Annotations
• Caching & Recursions
• Helper modules

NOTE:

#+begin_quote Testing is not documented here, you’ll find that right here.

#+end_quote

The core of Jedi consists of three parts:

• Parser
• Python type inference
• API

Most people are probably interested in type inference, because that’s where all the magic happens. I need to introduce the parser first, because jedi.inference uses it extensively.

Jedi used to have its internal parser, however this is now a separate project and is called parso.

The parser creates a syntax tree that Jedi analyses and tries to understand. The grammar that this parser uses is very similar to the official Python grammar files.

Type inference of Python code in Jedi is based on three assumptions:

• The code uses as least side effects as possible. Jedi understands certain list/tuple/set modifications, but there’s no guarantee that Jedi detects everything (list.append in different modules for example).
• No magic is being used:
  • metaclasses
  • setattr() / __import__()
  • writing to globals(), locals(), object.__dict__
• The programmer is not a total dick, e.g. like this :-)

The actual algorithm is based on a principle I call lazy type inference. That said, the typical entry point for static analysis is calling infer_expr_stmt. There’s separate logic for autocompletion in the API, the inference_state is all about inferring an expression.

TODO this paragraph is not what jedi does anymore, it’s similar, but not the same.

Now you need to understand what follows after infer_expr_stmt. Let’s make an example:

#+begin_quote

      import datetime
      datetime.date.toda# <-- cursor here

#+end_quote

First of all, this module doesn’t care about completion. It really just cares about datetime.date. At the end of the procedure infer_expr_stmt will return the date class.

To visualize this (simplified):

• InferenceState.infer_expr_stmt doesn’t do much, because there’s no assignment.
• Context.infer_node cares for resolving the dotted path
• InferenceState.find_types searches for global definitions of datetime, which it finds in the definition of an import, by scanning the syntax tree.
• Using the import logic, the datetime module is found.
• Now find_types is called again by infer_node to find date inside the datetime module.

Now what would happen if we wanted datetime.date.foo.bar? Two more calls to find_types. However the second call would be ignored, because the first one would return nothing (there’s no foo attribute in date).

What if the import would contain another ExprStmt like this:

#+begin_quote

      from foo import bar
      Date = bar.baz

#+end_quote

Well… You get it. Just another infer_expr_stmt recursion. It’s really easy. Python can obviously get way more complicated then this. To understand tuple assignments, list comprehensions and everything else, a lot more code had to be written.

Jedi has been tested very well, so you can just start modifying code. It’s best to write your own test first for your “new” feature. Don’t be scared of breaking stuff. As long as the tests pass, you’re most likely to be fine.

I need to mention now that lazy type inference is really good because it only inferes what needs to be inferred. All the statements and modules that are not used are just being ignored.

Values are the “values” that Python would return. However Values are at the same time also the “values” that a user is currently sitting in.

A ValueSet is typically used to specify the return of a function or any other static analysis operation. In jedi there are always multiple returns and not just one.

Searching for names with given scope and name. This is very central in Jedi and Python. The name resolution is quite complicated with descripter, __getattribute__, __getattr__, global, etc.

If you want to understand name resolution, please read the first few chapters in http://blog.ionelmc.ro/2015/02/09/understanding-python-metaclasses/.

Flow checks are not really mature. There’s only a check for isinstance. It would check whether a flow has the form of if isinstance(a, type_or_tuple). Unfortunately every other thing is being ignored (e.g. a == ’’ would be easy to check for -> a is a string). There’s big potential in these checks.

The API has been designed to be as easy to use as possible. The API documentation can be found here. The API itself contains little code that needs to be mentioned here. Generally I’m trying to be conservative with the API. I’d rather not add new API features if they are not necessary, because it’s much harder to deprecate stuff than to add it later.

Core Extensions is a summary of the following topics:

• Iterables & Dynamic Arrays
• Dynamic Parameters
• Docstrings
• Refactoring

These topics are very important to understand what Jedi additionally does, but they could be removed from Jedi and Jedi would still work. But slower and without some features.

To understand Python on a deeper level, Jedi needs to understand some of the dynamic features of Python like lists that are filled after creation:

Contains all classes and functions to deal with lists, dicts, generators and iterators in general.

One of the really important features of Jedi is to have an option to understand code like this:

#+begin_quote

      def foo(bar):
          bar. # completion here
      foo(1)

#+end_quote

There’s no doubt wheter bar is an int or not, but if there’s also a call like foo(’str’), what would happen? Well, we’ll just show both. Because that’s what a human would expect.

It works as follows:

• Jedi sees a param
• search for function calls named foo
• execute these calls and check the input.

Docstrings are another source of information for functions and classes. jedi.inference.dynamic_params tries to find all executions of functions, while the docstring parsing is much easier. There are three different types of docstrings that Jedi understands:

• Sphinx
• Epydoc
• Numpydoc

For example, the sphinx annotation :type foo: str clearly states that the type of foo is str.

As an addition to parameter searching, this module also provides return annotations.

• Modules
• Builtin Modules
• Imports

jedi.inference.imports is here to resolve import statements and return the modules/classes/functions/whatever, which they stand for. However there’s not any actual importing done. This module is about finding modules in the filesystem. This can be quite tricky sometimes, because Python imports are not always that simple.

This module also supports import autocompletion, which means to complete statements like from datetim (cursor at the end would return datetime).

It is unfortunately not well documented how stubs and annotations work in Jedi. If somebody needs an introduction, please let me know.

• Caching
• Recursions

This caching is very important for speed and memory optimizations. There’s nothing really spectacular, just some decorators. The following cache types are available:

• time_cache can be used to cache something for just a limited time span, which can be useful if there’s user interaction and the user cannot react faster than a certain time.

This module is one of the reasons why Jedi is not thread-safe. As you can see there are global variables, which are holding the cache information. Some of these variables are being cleaned after every API usage.

Recursions are the recipe of Jedi to conquer Python code. However, someone must stop recursions going mad. Some settings are here to make Jedi stop at the right time. You can read more about them here.

Next to the internal jedi.inference.cache this module also makes Jedi not thread-safe, because execution_recursion_decorator uses class variables to count the function calls.

Recursion settings are important if you don’t want extremely recursive python code to go absolutely crazy.

The default values are based on experiments while completing the Jedi library itself (inception!). But I don’t think there’s any other Python library that uses recursion in a similarly extreme way. Completion should also be fast and therefore the quality might not always be maximal.

jedi.inference.recursion.recursion_limit = 15

Like sys.getrecursionlimit(), just for Jedi.

• jedi.inference.recursion.total_function_execution_limit = 200 :: This is a hard limit of how many non-builtin functions can be executed.

jedi.inference.recursion.per_function_execution_limit = 6

The maximal amount of times a specific function may be executed.

jedi.inference.recursion.per_function_recursion_limit = 2

A function may not be executed more than this number of times recursively.

Most other modules are not really central to how Jedi works. They all contain relevant code, but you if you understand the modules above, you pretty much understand Jedi.

The test suite depends on pytest:

#+begin_quote

      pip install pytest

#+end_quote

If you want to test only a specific Python version (e.g. Python 3.8), it is as easy as:

#+begin_quote

      python3.8 -m pytest

#+end_quote

Tests are also run automatically on GitHub Actions.

You want to add a test for Jedi? Great! We love that. Normally you should write your tests as Blackbox Tests. Most tests would fit right in there.

For specific API testing we’re using simple unit tests, with a focus on a simple and readable testing structure.

Jedi is mostly being tested by what I would call “integration tests”. These tests are testing type inference with the public API. This makes a lot of sense for Jedi. Also, it is hard to write doctests/unittests for the internal data structures.

There are different kinds of tests:

• completions / inference #?
• goto: #!
• references: #<

Jedi uses pytest to run unit and integration tests. To run tests, simply run pytest.

Most integration test cases are located in the test/completion directory and each test case starts with one of these comments:

• #? (completions / inference)
• #! (goto)
• #< (references)

There is also support for third party libraries. In a normal test run they are not being executed, you have to provide a –thirdparty option.

In addition to pytest’s -k and -m options, you can use the -T (–test-files`) option to specify which test cases should run. It takes the format of ``FILE_NAME[:LINE[,LINE[,…]]] where FILE_NAME is a file in test/completion and LINE is a line number of the test comment. Here are some examples:

Run tests only in completion/basic.py and completion/imports.py:

#+begin_quote

      pytest test/test_integration.py -T basic.py -T imports.py

#+end_quote

Run test at line 4, 6, and 8 in completion/basic.py:

#+begin_quote

      pytest test/test_integration.py -T basic.py:4,6,8

#+end_quote

See pytest –help for more information.

If you want to debug a test, just use the –pdb option.

If you don’t like the output of pytest, there’s an alternate test runner that you can start by running ./run.py. The above example could be run by:

#+begin_quote

      ./run.py basic 4 6 8 50-80

#+end_quote

The advantage of this runner is simplicity and more customized error reports.

Uses a comment to specify a test on the next line. The comment defines the expected completions. The comment always begins with #?. The last row symbolizes the cursor. For example:

#+begin_quote

      #? ['upper']
      a = 'foo'; a.upp

#+end_quote

Inference tests look very simliar. The difference is that inference tests don’t use brackets:

#+begin_quote

      #? int()
      ab = 3; ab

#+end_quote

Goto Tests look like this:

#+begin_quote

      abc = 1
      #! ['abc=1']
      abc

#+end_quote

Additionally it is possible to specify the column by adding a number, which describes the position of the test (otherwise it’s just the end of line):

#+begin_quote

      #! 2 ['abc=1']
      abc

#+end_quote

Tests look like this:

#+begin_quote

      abc = 1
      #< (1,0), (3,0)
      abc

#+end_quote

Refactoring tests work a little bit similar to integration tests. But the idea is here to compare two versions of code. If you want to add a new test case, just look at the existing ones in the test/refactor folder and copy them.

• Dave Halter for creating and maintaining Jedi & Parso.
• Takafumi Arakaki (@tkf) for creating a solid test environment and a lot of other things.
• Danilo Bargen (@dbrgn) for general housekeeping and being a good friend :).
• Guido van Rossum (@gvanrossum) for creating the parser generator pgen2 (originally used in lib2to3).
• Thanks to all the contributors.

Written by Dave.

The Star Wars Jedi are awesome. My Jedi software tries to imitate a little bit of the precognition the Jedi have. There’s even an awesome scene of Monty Python Jedis :-).

But actually the name has not much to do with Star Wars. It’s part of my second name Jedidjah.

I actually started Jedi back in 2012, because there were no good solutions available for VIM. Most auto-completion solutions just did not work well. The only good solution was PyCharm. But I liked my good old VIM very much. There was also a solution called Rope that did not work at all for me. So I decided to write my own version of a completion engine.

The first idea was to execute non-dangerous code. But I soon realized, that this would not work. So I started to build a static analysis tool. The biggest problem that I had at the time was that I did not know a thing about parsers.I did not did not even know the word static analysis. It turns out they are the foundation of a good static analysis tool. I of course did not know that and tried to write my own poor version of a parser that I ended up throwing away two years later.

Because of my lack of knowledge, everything after 2012 and before 2020 was basically refactoring. I rewrote the core parts of Jedi probably like 5-10 times. The last big rewrite (that I did twice) was the inclusion of gradual typing and stubs.

I learned during that time that it is crucial to have a good understanding of your problem. Otherwise you just end up doing it again. I only wrote features in the beginning and in the end. Everything else was bugfixing and refactoring. However now I am really happy with the result. It works well, bugfixes can be quick and is pretty much feature complete.

-—

I will leave you with a small annectote that happend in 2012, if I remember correctly. After I explained Guido van Rossum, how some parts of my auto-completion work, he said:

#+begin_quote “Oh, that worries me…”

#+end_quote

Now that it is finished, I hope he likes it :-).

• David Halter (@davidhalter) </davidhalter88@gmail.com/>
• Takafumi Arakaki (@tkf) </aka.tkf@gmail.com/>

• Danilo Bargen (@dbrgn) </mail@dbrgn.ch/>
• Laurens Van Houtven (@lvh) </_@lvh.cc/>
• Aldo Stracquadanio (@Astrac) </aldo.strac@gmail.com/>
• Jean-Louis Fuchs (@ganwell) </ganwell@fangorn.ch/>
• tek (@tek)
• Yasha Borevich (@jjay) </j.borevich@gmail.com/>
• Aaron Griffin </aaronmgriffin@gmail.com/>
• andviro (@andviro)
• Mike Gilbert (@floppym) </floppym@gentoo.org/>
• Aaron Meurer (@asmeurer) </asmeurer@gmail.com/>
• Lubos Trilety </ltrilety@redhat.com/>
• Akinori Hattori (@hattya) </hattya@gmail.com/>
• srusskih (@srusskih)
• Steven Silvester (@blink1073)
• Colin Duquesnoy (@ColinDuquesnoy) </colin.duquesnoy@gmail.com/>
• Jorgen Schaefer (@jorgenschaefer) </contact@jorgenschaefer.de/>
• Fredrik Bergroth (@fbergroth)
• Mathias Fußenegger (@mfussenegger)
• Syohei Yoshida (@syohex) </syohex@gmail.com/>
• ppalucky (@ppalucky)
• immerrr (@immerrr) immerrr@gmail.com
• Albertas Agejevas (@alga)
• Savor d’Isavano (@KenetJervet) </newelevenken@163.com/>
• Phillip Berndt (@phillipberndt) </phillip.berndt@gmail.com/>
• Ian Lee (@IanLee1521) </IanLee1521@gmail.com/>
• Farkhad Khatamov (@hatamov) </comsgn@gmail.com/>
• Kevin Kelley (@kelleyk) </kelleyk@kelleyk.net/>
• Sid Shanker (@squidarth) </sid.p.shanker@gmail.com/>
• Reinoud Elhorst (@reinhrst)
• Guido van Rossum (@gvanrossum) </guido@python.org/>
• Dmytro Sadovnychyi (@sadovnychyi) </jedi@dmit.ro/>
• Cristi Burcă (@scribu)
• bstaint (@bstaint)
• Mathias Rav (@Mortal) </rav@cs.au.dk/>
• Daniel Fiterman (@dfit99) </fitermandaniel2@gmail.com/>
• Simon Ruggier (@sruggier)
• Élie Gouzien (@ElieGouzien)
• Robin Roth (@robinro)
• Malte Plath (@langsamer)
• Anton Zub (@zabulazza)
• Maksim Novikov (@m-novikov) </mnovikov.work@gmail.com/>
• Tobias Rzepka (@TobiasRzepka)
• micbou (@micbou)
• Dima Gerasimov (@karlicoss) </karlicoss@gmail.com/>
• Max Woerner Chase (@mwchase) </max.chase@gmail.com/>
• Johannes Maria Frank (@jmfrank63) </jmfrank63@gmail.com/>
• Shane Steinert-Threlkeld (@shanest) </ssshanest@gmail.com/>
• Tim Gates (@timgates42) </tim.gates@iress.com/>
• Lior Goldberg (@goldberglior)
• Ryan Clary (@mrclary)
• Max Mäusezahl (@mmaeusezahl) </maxmaeusezahl@googlemail.com/>
• Vladislav Serebrennikov (@endilll)
• Andrii Kolomoiets (@muffinmad)
• Leo Ryu (@Leo-Ryu)
• Joseph Birkner (@josephbirkner)

And a few more “anonymous” contributors.

Note: (@user) means a github user name.

• Implict namespaces are now a separate types in Name().type
• Python 3.10 support
• Mostly bugfixes

• Dropped Python 2 and Python 3.5
• Using pathlib.Path() as an output instead of str in most places: - Project.path - Script.path - Definition.module_path - Refactoring.get_renames - Refactoring.get_changed_files
• Functions with @property now return property instead of function in Name().type
• Started using annotations
• Better support for the walrus operator
• Project attributes are now read accessible
• Removed all deprecations

This is likely going to be the last minor release before 1.0.

• Added an option to pass environment variables to Environment
• Project(…).path exists now
• Support for Python 3.9
• A few bugfixes

This will be the last release that supports Python 2 and Python 3.5. 0.18.0 will be Python 3.6+.

• Django Model meta class support
• Django Manager support (completion on Managers/QuerySets)
• Added Django Stubs to Jedi, thanks to all contributors of the Django Stubs project
• Added SyntaxError.get_message
• Python 3.9 support
• Bugfixes (mostly towards Generics)

• Added Project support. This allows a user to specify which folders Jedi should work with.
• Added support for Refactoring. The following refactorings have been implemented: Script.rename, Script.inline, Script.extract_variable and Script.extract_function.
• Added Script.get_syntax_errors to display syntax errors in the current script.
• Added code search capabilities both for individual files and projects. The new functions are Project.search, Project.complete_search, Script.search and Script.complete_search.
• Added Script.help to make it easier to display a help window to people. Now returns pydoc information as well for Python keywords/operators. This means that on the class keyword it will now return the docstring of Python’s builtin function help(’class’).
• The API documentation is now way more readable and complete. Check it out under https://jedi.readthedocs.io. A lot of it has been rewritten.
• Removed Python 3.4 support
• Many bugfixes

This is likely going to be the last minor version that supports Python 2 and Python3.5. Bugfixes will be provided in 0.17.1+. The next minor/major version will probably be Jedi 1.0.0.

• Added Script.get_context to get information where you currently are.
• Completions/type inference of Pytest fixtures.
• Tensorflow, Numpy and Pandas completions should now be about 4-10x faster after the first time they are used.
• Dict key completions are working now. e.g. d = {1000: 3}; d[10 will expand to 1000.
• Completion for “proxies” works now. These are classes that have a __getattr__(self, name) method that does a return getattr(x, name). after loading them initially.
• Goto on a function/attribute in a class now goes to the definition in its super class.

• Big Script API Changes:

  • The line and column parameters of jedi.Script are now deprecated
  • completions deprecated, use complete instead
  • goto_assignments deprecated, use goto instead
  • goto_definitions deprecated, use infer instead
  • call_signatures deprecated, use get_signatures instead
  • usages deprecated, use get_references instead
  • jedi.names deprecated, use jedi.Script(…).get_names()

• BaseName.goto_assignments renamed to BaseName.goto
• Add follow_imports to Name.goto. Now its signature matches Script.goto.
• Python 2 support deprecated. For this release it is best effort. Python 2 has reached the end of its life and now it’s just about a smooth transition. Bugs for Python 2 will not be fixed anymore and a third of the tests are already skipped.
• Removed settings.no_completion_duplicates. It wasn’t tested and nobody was probably using it anyway.
• Removed settings.use_filesystem_cache and settings.additional_dynamic_modules, they have no usage anymore. Pretty much nobody was probably using them.

• Signatures are now detected a lot better
• Add fuzzy completions with Script(…).completions(fuzzy=True)
• Files bigger than one MB (about 20kLOC) get cropped to avoid getting stuck completely.
• Many small Bugfixes
• A big refactoring around contexts/values

• Small bugfix and removal of a print statement

• Added file path completions, there’s a new Completion.type now: path. Example: ’/ho -> ’home
• *args*/***kwargs resolving. If possible Jedi replaces the parameters with the actual alternatives.
• Better support for enums/dataclasses
• When using Interpreter, properties are now executed, since a lot of people have complained about this. Discussion in #1299, #1347.

New APIs:

• Name.get_signatures() -> List[Signature]. Signatures are similar to CallSignature. Name.params is therefore deprecated.
• Signature.to_string() to format signatures.
• Signature.params -> List[ParamName], ParamName has the following additional attributes infer_default(), infer_annotation(), to_string(), and kind.
• Name.execute() -> List[Name], makes it possible to infer return values of functions.

• CallSignature.index should now be working a lot better
• A couple of smaller bugfixes

• Added goto_*(prefer_stubs=True) as well as goto_*(prefer_stubs=True)
• Stubs are used now for type inference
• Typeshed is used for better type inference
• Reworked Name.full_name, should have more correct return values

• Fixed an issue with embedded Python, see https://github.com/davidhalter/jedi-vim/issues/870

• Fixed a bug that led to Jedi spawning a lot of subprocesses.

• Bugfixes, because tensorflow completions were still slow.

• A small release. Some bug fixes.
• Remove Python 3.3 support. Python 3.3 support has been dropped by the Python foundation.
• Default environments are now using the same Python version as the Python process. In 0.12.x, we used to load the latest Python version on the system.
• Added include_builtins as a parameter to usages.
• goto_assignments has a new follow_builtin_imports parameter that changes the previous behavior slightly.

• This release forces you to upgrade parso. If you don’t, nothing will work anymore. Otherwise changes should be limited to bug fixes. Unfortunately Jedi still uses a few internals of parso that make it hard to keep compatibility over multiple releases. Parso >=0.3.0 is going to be needed.

• Virtualenv/Environment support
• F-String Completion/Goto Support
• Cannot crash with segfaults anymore
• Cleaned up import logic
• Understand async/await and autocomplete it (including async generators)
• Better namespace completions
• Passing tests for Windows (including CI for Windows)
• Remove Python 2.6 support

• Parso update - the caching layer was broken
• Better usages - a lot of internal code was ripped out and improved.

• Split Jedi’s parser into a separate project called parso.
• Avoiding side effects in REPL completion.
• Numpy docstring support should be much better.
• Moved the settings.*recursion* away, they are no longer usable.

• Python Packaging sucks. Some files were not included in 0.10.1.

• Fixed a few very annoying bugs.
• Prepared the parser to be factored out of Jedi.

• Actual semantic completions for the complete Python syntax.
• Basic type inference for yield from PEP 380.
• PEP 484 support (most of the important features of it). Thanks Claude! (@reinhrst)
• Added get_line_code to Name and Completion objects.
• Completely rewritten the type inference engine.
• A new and better parser for (fast) parsing diffs of Python code.

• The import logic has been rewritten to look more like Python’s. There is now an InferState.modules import cache, which resembles sys.modules.
• Integrated the parser of 2to3. This will make refactoring possible. It will also be possible to check for error messages (like compiling an AST would give) in the future.
• With the new parser, the type inference also completely changed. It’s now simpler and more readable.
• Completely rewritten REPL completion.
• Added jedi.names, a command to do static analysis. Thanks to that sourcegraph guys for sponsoring this!
• Alpha version of the linter.

• Bugfix release, the last release forgot to include files that improve autocompletion for builtin libraries. Fixed.

• Memory Consumption for compiled modules (e.g. builtins, sys) has been reduced drastically. Loading times are down as well (it takes basically as long as an import).
• REPL completion is starting to become usable.
• Various small API changes. Generally this release focuses on stability and refactoring of internal APIs.
• Introducing operator precedence, which makes calculating correct Array indices and __getattr__ strings possible.

• Switched from LGPL to MIT license.
• Added an Interpreter class to the API to make autocompletion in REPL possible.
• Added autocompletion support for namespace packages.
• Add sith.py, a new random testing method.

• Much faster parser with builtin part caching.
• A test suite, thanks @tkf.

• Initial development.