# Jedi

> - Dave Halter for creating and maintaining Jedi & Parso.

---

# Source: https://github.com/davidhalter/jedi/blob/master/docs/docs/acknowledgements.rst

.. include global.rst

History & Acknowledgements
==========================

Acknowledgements
----------------

- 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 :ref:`contributors <contributors>`.

A Little Bit of History
-----------------------

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
<https://youtu.be/yHRJLIf7wMU>`_ 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 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 anecdote that happened in 2012, if I remember
correctly. After I explained Guido van Rossum, how some parts of my
auto-completion work, he said:

    *"Oh, that worries me..."*

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

.. _contributors:

.. include:: ../../AUTHORS.txt

---

# Source: https://github.com/davidhalter/jedi/blob/master/docs/docs/api-classes.rst

.. include:: ../global.rst

.. _api-classes:

API Return Classes
------------------

Abstract Base Class
~~~~~~~~~~~~~~~~~~~
.. autoclass:: jedi.api.classes.BaseName
    :members:
    :show-inheritance:

Name
~~~~
.. autoclass:: jedi.api.classes.Name
    :members:
    :show-inheritance:

Completion
~~~~~~~~~~
.. autoclass:: jedi.api.classes.Completion
    :members:
    :show-inheritance:

BaseSignature
~~~~~~~~~~~~~
.. autoclass:: jedi.api.classes.BaseSignature
    :members:
    :show-inheritance:

Signature
~~~~~~~~~
.. autoclass:: jedi.api.classes.Signature
    :members:
    :show-inheritance:

ParamName
~~~~~~~~~
.. autoclass:: jedi.api.classes.ParamName
    :members:
    :show-inheritance:

Refactoring
~~~~~~~~~~~

.. autoclass:: jedi.api.refactoring.Refactoring
    :members:
    :show-inheritance:

.. autoclass:: jedi.api.errors.SyntaxError
    :members:
    :show-inheritance:

---

# Source: https://github.com/davidhalter/jedi/blob/master/docs/docs/api.rst

.. include:: ../global.rst

API Overview
============

.. note:: This documentation is mostly for Plugin developers, who want to
   improve their editors/IDE with Jedi.

.. _api:

The API consists of a few different parts:

- The main starting points for complete/goto: :class:`.Script` and
  :class:`.Interpreter`. If you work with Jedi you want to understand these
  classes first.
- :ref:`API Result Classes <api-classes>`
- :ref:`Python Versions/Virtualenv Support <environments>` with functions like
  :func:`.find_system_environments` and :func:`.find_virtualenvs`
- A way to work with different :ref:`Folders / Projects <projects>`
- Helpful functions: :func:`.preload_module` and :func:`.set_debug_function`

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

.. currentmodule:: jedi

.. autosummary::
   :nosignatures:

    Script.complete
    Script.goto
    Script.infer
    Script.help
    Script.get_signatures
    Script.get_references
    Script.get_context
    Script.get_names
    Script.get_syntax_errors
    Script.rename
    Script.inline
    Script.extract_variable
    Script.extract_function
    Script.search
    Script.complete_search
    Project.search
    Project.complete_search

Script
------

.. autoclass:: jedi.Script
    :members:

Interpreter
-----------
.. autoclass:: jedi.Interpreter
    :members:

.. _projects:

Projects
--------

.. automodule:: jedi.api.project

.. autofunction:: jedi.get_default_project
.. autoclass:: jedi.Project
    :members:

.. _environments:

Environments
------------

.. automodule:: jedi.api.environment

.. autofunction:: jedi.find_system_environments
.. autofunction:: jedi.find_virtualenvs
.. autofunction:: jedi.get_system_environment
.. autofunction:: jedi.create_environment
.. autofunction:: jedi.get_default_environment
.. autoexception:: jedi.InvalidPythonEnvironment
.. autoclass:: jedi.api.environment.Environment
    :members:

Helper Functions
----------------

.. autofunction:: jedi.preload_module
.. autofunction:: jedi.set_debug_function

Errors
------

.. autoexception:: jedi.InternalError
.. autoexception:: jedi.RefactoringError

Examples
--------

Completions
~~~~~~~~~~~

.. sourcecode:: python

   >>> 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'

Type Inference / Goto
~~~~~~~~~~~~~~~~~~~~~

.. sourcecode:: python

    >>> 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'>]

References
~~~~~~~~~~

.. sourcecode:: python

    >>> 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

Deprecations
------------

The deprecation process is as follows:

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

---

# Source: https://github.com/davidhalter/jedi/blob/master/docs/docs/changelog.rst

.. include:: ../../CHANGELOG.rst

---

# Source: https://github.com/davidhalter/jedi/blob/master/docs/docs/development.rst

.. include:: ../global.rst

Jedi Development
================

.. currentmodule:: jedi

.. note:: 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 <api.html>`_.
    It is also important to note that it's a pretty old version and some things
    might not apply anymore.


Introduction
------------

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|:

- :ref:`The Jedi Core <core>`
- :ref:`Core Extensions <core-extensions>`
- :ref:`Imports & Modules <imports-modules>`
- :ref:`Stubs & Annotations <stubs>`
- :ref:`Caching & Recursions <caching-recursions>`
- :ref:`Helper modules <dev-helpers>`

.. note:: Testing is not documented here, you'll find that
   `right here <testing.html>`_.


.. _core:

The Jedi Core
-------------

The core of Jedi consists of three parts:

- :ref:`Parser <parser>`
- :ref:`Python type inference <inference>`
- :ref:`API <dev-api>`

Most people are probably interested in :ref:`type inference <inference>`,
because that's where all the magic happens. I need to introduce the :ref:`parser
<parser>` first, because :mod:`jedi.inference` uses it extensively.

.. _parser:

Parser
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Jedi used to have its internal parser, however this is now a separate project
and is called `parso <http://parso.readthedocs.io>`_.

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 <https://docs.python.org/3/reference/grammar.html>`_.

.. _inference:

Type inference of python code (inference/__init__.py)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. automodule:: jedi.inference

Inference Values (inference/base_value.py)
++++++++++++++++++++++++++++++++++++++++++++++++++++++

.. automodule:: jedi.inference.base_value

.. inheritance-diagram::
   jedi.inference.value.instance.TreeInstance
   jedi.inference.value.klass.ClassValue
   jedi.inference.value.function.FunctionValue
   jedi.inference.value.function.FunctionExecutionContext
   :parts: 1


.. _name_resolution:

Name resolution (inference/finder.py)
+++++++++++++++++++++++++++++++++++++

.. automodule:: jedi.inference.finder


.. _dev-api:

API (api/__init__.py and api/classes.py)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The API has been designed to be as easy to use as possible. The API
documentation can be found `here <api.html>`_. 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:

Core Extensions
---------------

Core Extensions is a summary of the following topics:

- :ref:`Iterables & Dynamic Arrays <iterables>`
- :ref:`Dynamic Parameters <dynamic_params>`
- :ref:`Docstrings <docstrings>`
- :ref:`Refactoring <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.

.. _iterables:

Iterables & Dynamic Arrays (inference/value/iterable.py)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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:

.. automodule:: jedi.inference.value.iterable


.. _dynamic_params:

Parameter completion (inference/dynamic_params.py)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. automodule:: jedi.inference.dynamic_params


.. _docstrings:

Docstrings (inference/docstrings.py)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. automodule:: jedi.inference.docstrings

.. _refactoring:

Refactoring (api/refactoring.py)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. automodule:: jedi.api.refactoring


.. _imports-modules:

Imports & Modules
-----------------


- :ref:`Modules <modules>`
- :ref:`Builtin Modules <builtin>`
- :ref:`Imports <imports>`


.. _builtin:

Compiled Modules (inference/compiled.py)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. automodule:: jedi.inference.compiled


.. _imports:

Imports (inference/imports.py)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. automodule:: jedi.inference.imports

.. _stubs:

Stubs & Annotations (inference/gradual)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. automodule:: jedi.inference.gradual

.. _caching-recursions:

Caching & Recursions
--------------------


- :ref:`Caching <cache>`
- :ref:`Recursions <recursion>`

.. _cache:

Caching (cache.py)
~~~~~~~~~~~~~~~~~~

.. automodule:: jedi.cache

.. _recursion:

Recursions (recursion.py)
~~~~~~~~~~~~~~~~~~~~~~~~~

.. automodule:: jedi.inference.recursion


.. _dev-helpers:

Helper Modules
--------------

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.

---

# Source: https://github.com/davidhalter/jedi/blob/master/docs/docs/features.rst

.. include:: ../global.rst

Features and Limitations
========================

Jedi's main API calls and features are:

- Autocompletion: :meth:`.Script.complete`; It's also possible to get it
  working in :ref:`your REPL (IPython, etc.) <repl-completion>`
- Goto/Type Inference: :meth:`.Script.goto` and :meth:`.Script.infer`
- Static Analysis: :meth:`.Script.get_names` and :meth:`.Script.get_syntax_errors`
- Refactorings: :meth:`.Script.rename`, :meth:`.Script.inline`,
  :meth:`.Script.extract_variable` and :meth:`.Script.extract_function`
- Code Search: :meth:`.Script.search` and :meth:`.Project.search`

Basic Features
--------------

- Python 3.8+ support
- Ignores syntax errors and wrong indentation
- Can deal with complex module / function / class structures
- Great ``virtualenv``/``venv`` support
- Works great with Python's :ref:`type hinting <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.


Supported Python Features
-------------------------

|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


Limitations
-----------

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 

Performance Issues
~~~~~~~~~~~~~~~~~~

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
libraries in |jedi|, with :func:`.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 <https://github.com/davidhalter/jedi/issues/1059>`_ 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
--------

For :class:`.Script`
~~~~~~~~~~~~~~~~~~~~

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
:class:`.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.

For :class:`.Interpreter`
~~~~~~~~~~~~~~~~~~~~~~~~~

If you want security for :class:`.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.

---

# Source: https://github.com/davidhalter/jedi/blob/master/docs/docs/installation.rst

.. include:: ../global.rst

Installation and Configuration
==============================

.. warning:: 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.

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:: This just installs the |jedi| library, not the :ref:`editor plugins
    <editor-plugins>`. For information about how to make it work with your
    editor, refer to the corresponding documentation.


The normal way
--------------

Most people use Jedi with a :ref:`editor plugins<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.


With pip
--------

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

    sudo pip install jedi

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

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


System-wide installation via a package manager
----------------------------------------------

Arch Linux
~~~~~~~~~~

You can install |jedi| directly from official Arch Linux packages:

- `python-jedi <https://www.archlinux.org/packages/community/any/python-jedi/>`__

(There is also a packaged version of the vim plugin available: 
`vim-jedi at Arch Linux <https://www.archlinux.org/packages/community/any/vim-jedi/>`__.)

Debian
~~~~~~

Debian packages are available in the `unstable repository
<https://packages.debian.org/search?keywords=python%20jedi>`__.

Others
~~~~~~

We are in the discussion of adding |jedi| to the Fedora repositories.


Manual installation from GitHub
---------------------------------------------

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::

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

Inclusion as a submodule
------------------------

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.


.. _jedi-vim: https://github.com/davidhalter/jedi-vim
.. _vundle: https://github.com/gmarik/vundle
.. _pathogen: https://github.com/tpope/vim-pathogen

---

# Source: https://github.com/davidhalter/jedi/blob/master/docs/docs/settings.rst

.. include:: ../global.rst

Settings
========

.. automodule:: jedi.settings

---

# Source: https://github.com/davidhalter/jedi/blob/master/docs/docs/testing.rst

.. include:: ../global.rst

Jedi Testing
============

The test suite depends on ``pytest``::

    pip install pytest

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

    python3.8 -m pytest

Tests are also run automatically on `GitHub Actions
<https://github.com/davidhalter/jedi/actions>`_.

You want to add a test for |jedi|? Great! We love that. Normally you should
write your tests as :ref:`Blackbox Tests <blackbox>`. 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.

.. _blackbox:

Integration Tests (run.py)
~~~~~~~~~~~~~~~~~~~~~~~~~~

.. automodule:: test.run

Refactoring Tests (refactor.py)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. automodule:: test.refactor

---

# Source: https://github.com/davidhalter/jedi/blob/master/docs/docs/usage.rst

.. include:: ../global.rst

Using Jedi
==========

|jedi| is can be used with a variety of :ref:`plugins <editor-plugins>`,
:ref:`language servers <language-servers>` and other software.
It is also possible to use |jedi| in the :ref:`Python shell or with IPython
<repl-completion>`.

Below you can also find a list of :ref:`recipes for type hinting <recipes>`.

.. _language-servers:

Language Servers
--------------

- `jedi-language-server <https://github.com/pappasam/jedi-language-server>`_
- `python-language-server <https://github.com/palantir/python-language-server>`_ (currently unmaintained)
- `python-lsp-server <https://github.com/python-lsp/python-lsp-server>`_ (fork from python-language-server)
- `anakin-language-server <https://github.com/muffinmad/anakin-language-server>`_

.. _editor-plugins:

Editor Plugins
--------------

Vim
~~~

- jedi-vim_
- YouCompleteMe_
- deoplete-jedi_

Visual Studio Code
~~~~~~~~~~~~~~~~~~

- `Python Extension`_

Emacs
~~~~~

- Jedi.el_
- elpy_
- anaconda-mode_

Sublime Text 2/3
~~~~~~~~~~~~~~~~

- SublimeJEDI_ (ST2 & ST3)
- anaconda_ (only ST3)

SynWrite
~~~~~~~~

- SynJedi_

TextMate
~~~~~~~~

- Textmate_ (Not sure if it's actually working)

Kate
~~~~

- Kate_ version 4.13+ `supports it natively
  <https://projects.kde.org/projects/kde/applications/kate/repository/entry/addons/kate/pate/src/plugins/python_autocomplete_jedi.py?rev=KDE%2F4.13>`__,
  you have to enable it, though.

Atom
~~~~

- autocomplete-python-jedi_

GNOME Builder
~~~~~~~~~~~~~

- `GNOME Builder`_ `supports it natively
  <https://git.gnome.org/browse/gnome-builder/tree/plugins/jedi>`__,
  and is enabled by default.

Gedit
~~~~~

- gedi_

Eric IDE
~~~~~~~~

- `Eric IDE`_

Web Debugger
~~~~~~~~~~~~

- wdb_

xonsh shell
~~~~~~~~~~~

Jedi is a preinstalled extension in `xonsh shell <https://xon.sh/contents.html>`_. 
Run the following command to enable:

::

    xontrib load jedi

and many more!

.. _repl-completion:

Tab Completion in the Python Shell
----------------------------------

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

Here is an `example video <https://vimeo.com/122332037>`_ 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``.

Using ``PYTHONSTARTUP``
~~~~~~~~~~~~~~~~~~~~~~~

.. automodule:: jedi.api.replstartup

Using a Custom ``$HOME/.pythonrc.py``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. autofunction:: jedi.utils.setup_readline

.. _recipes:

Recipes
-------

Here are some tips on how to use |jedi| efficiently.


.. _type-hinting:

Type Hinting
~~~~~~~~~~~~

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.

Official Gradual Typing (Recommended)
+++++++++++++++++++++++++++++++++++++

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

- `PEP 484 <https://www.python.org/dev/peps/pep-0484/>`_ as an introduction
- `PEP 526 <https://www.python.org/dev/peps/pep-0526/>`_ for variable annotations
- `PEP 589 <https://www.python.org/dev/peps/pep-0589/>`_ for ``TypeDict``
- There are probably more :)

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

Function annotations::

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

        """
        node.| # complete here


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

    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)

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.


Sphinx style
++++++++++++

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

::

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

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

Epydoc
++++++

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

::

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

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

Numpydoc
++++++++

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
<https://pypi.python.org/pypi/numpydoc>`__ package.

::

    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

.. _jedi-vim: https://github.com/davidhalter/jedi-vim
.. _youcompleteme: https://valloric.github.io/YouCompleteMe/
.. _deoplete-jedi: https://github.com/zchee/deoplete-jedi
.. _Jedi.el: https://github.com/tkf/emacs-jedi
.. _elpy: https://github.com/jorgenschaefer/elpy
.. _anaconda-mode: https://github.com/proofit404/anaconda-mode
.. _sublimejedi: https://github.com/srusskih/SublimeJEDI
.. _anaconda: https://github.com/DamnWidget/anaconda
.. _SynJedi: http://uvviewsoft.com/synjedi/
.. _wdb: https://github.com/Kozea/wdb
.. _TextMate: https://github.com/lawrenceakka/python-jedi.tmbundle
.. _kate: https://kate-editor.org/
.. _autocomplete-python-jedi: https://atom.io/packages/autocomplete-python-jedi
.. _GNOME Builder: https://wiki.gnome.org/Apps/Builder/
.. _gedi: https://github.com/isamert/gedi
.. _Eric IDE: https://eric-ide.python-projects.org
.. _Python Extension: https://marketplace.visualstudio.com/items?itemName=ms-python.python

---

# Source: https://github.com/davidhalter/jedi/blob/master/docs/global.rst

:orphan:

.. |jedi| replace:: Jedi

---

# Source: https://github.com/davidhalter/jedi/blob/master/docs/index.rst

.. include global.rst

.. meta::
    :github_url: https://github.com/davidhalter/jedi

Jedi - an awesome autocompletion, static analysis and refactoring library for Python
====================================================================================

.. image:: https://img.shields.io/github/stars/davidhalter/jedi.svg?style=social&label=Star&maxAge=2592000
    :target: https://github.com/davidhalter/jedi
    :alt: GitHub stars

.. image:: http://isitmaintained.com/badge/open/davidhalter/jedi.svg
    :target: https://github.com/davidhalter/jedi/issues
    :alt: The percentage of open issues and pull requests

.. image:: http://isitmaintained.com/badge/resolution/davidhalter/jedi.svg
    :target: https://github.com/davidhalter/jedi/issues
    :alt: The resolution time is the median time an issue or pull request stays open.

.. image:: https://github.com/davidhalter/jedi/workflows/ci/badge.svg?branch=master
    :target: https://github.com/davidhalter/jedi/actions
    :alt: Tests

.. image:: https://coveralls.io/repos/davidhalter/jedi/badge.svg?branch=master
    :target: https://coveralls.io/r/davidhalter/jedi
    :alt: Coverage status

.. image:: https://pepy.tech/badge/jedi
    :target: https://pepy.tech/project/jedi
    :alt: PyPI Downloads

`Github Repository <https://github.com/davidhalter/jedi>`_

.. automodule:: jedi

Autocompletion can for example look like this in jedi-vim:

.. figure:: _screenshots/screenshot_complete.png


.. _toc:

Docs
----

.. toctree::
   :maxdepth: 1

   docs/usage
   docs/features
   docs/api
   docs/api-classes
   docs/installation
   docs/settings
   docs/development
   docs/testing
   docs/acknowledgements
   docs/changelog


.. _resources:

Resources
---------

If you want to stay **up-to-date** with releases, please **subscribe** to this
mailing list: https://groups.google.com/g/jedi-announce. To subscribe you can
simply send an empty email to ``jedi-announce+subscribe@googlegroups.com``.

- `Source Code on Github <https://github.com/davidhalter/jedi>`_
- `Python Package Index <https://pypi.python.org/pypi/jedi/>`_