.. include:: ../global.rst

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

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

.. _api:

API Documentation
-----------------

The API consists of a few different parts:

- The main starting points for complete/goto: :class:`.Script` and :class:`.Interpreter`
- Helpful functions: :func:`.preload_module` and :func:`.set_debug_function`
- :ref:`API Result Classes <api-classes>`
- :ref:`Python Versions/Virtualenv Support <environments>` with functions like
  :func:`.find_system_environments` and :func:`.find_virtualenvs`

Script
~~~~~~

.. autoclass:: jedi.Script
    :members:

Interpreter
~~~~~~~~~~~
.. autoclass:: jedi.Interpreter
    :members:

Helper Functions
~~~~~~~~~~~~~~~~

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

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

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.5.2 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)
    [<Definition full_name='__main__.inception', description='inception = my_list[2]'>]
    >>>
    >>> script.infer(8, 1)
    [<Definition 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
    [<Definition full_name='__main__.x', description='x = 3'>,
     <Definition full_name='__main__.x', description='x = 4'>,
     <Definition 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 the next major/minor release.
2. We wait either at least a year and at least two minor releases until we
   remove the deprecated functionality.