1###################################################################
2Jedi - an awesome autocompletion/static analysis library for Python
3###################################################################
4
5.. image:: https://secure.travis-ci.org/davidhalter/jedi.png?branch=master
6    :target: http://travis-ci.org/davidhalter/jedi
7    :alt: Travis-CI build status
8
9.. image:: https://coveralls.io/repos/davidhalter/jedi/badge.png?branch=master
10    :target: https://coveralls.io/r/davidhalter/jedi
11    :alt: Coverage Status
12
13
14*If you have specific questions, please add an issue or ask on* `stackoverflow
15<https://stackoverflow.com>`_ *with the label* ``python-jedi``.
16
17
18Jedi is a static analysis tool for Python that can be used in IDEs/editors. Its
19historic focus is autocompletion, but does static analysis for now as well.
20Jedi is fast and is very well tested. It understands Python on a deeper level
21than all other static analysis frameworks for Python.
22
23Jedi has support for two different goto functions. It's possible to search for
24related names and to list all names in a Python file and infer them. Jedi
25understands docstrings and you can use Jedi autocompletion in your REPL as
26well.
27
28Jedi uses a very simple API to connect with IDE's. There's a reference
29implementation as a `VIM-Plugin <https://github.com/davidhalter/jedi-vim>`_,
30which uses Jedi's autocompletion.  We encourage you to use Jedi in your IDEs.
31It's really easy.
32
33Jedi can currently be used with the following editors/projects:
34
35- Vim (jedi-vim_, YouCompleteMe_, deoplete-jedi_)
36- Emacs (Jedi.el_, company-mode_, elpy_, anaconda-mode_, ycmd_)
37- Sublime Text (SublimeJEDI_ [ST2 + ST3], anaconda_ [only ST3])
38- TextMate_ (Not sure if it's actually working)
39- Kate_ version 4.13+ supports it natively, you have to enable it, though. [`proof
40  <https://projects.kde.org/projects/kde/applications/kate/repository/show?rev=KDE%2F4.13>`_]
41- Atom_ (autocomplete-python_)
42- SourceLair_
43- `GNOME Builder`_ (with support for GObject Introspection)
44- `Visual Studio Code`_ (via `Python Extension <https://marketplace.visualstudio.com/items?itemName=donjayamanne.python>`_)
45- Gedit (gedi_)
46- wdb_ - Web Debugger
47- `Eric IDE`_ (Available as a plugin)
48
49and many more!
50
51
52Here are some pictures taken from jedi-vim_:
53
54.. image:: https://github.com/davidhalter/jedi/raw/master/docs/_screenshots/screenshot_complete.png
55
56Completion for almost anything (Ctrl+Space).
57
58.. image:: https://github.com/davidhalter/jedi/raw/master/docs/_screenshots/screenshot_function.png
59
60Display of function/class bodies, docstrings.
61
62.. image:: https://github.com/davidhalter/jedi/raw/master/docs/_screenshots/screenshot_pydoc.png
63
64Pydoc support (Shift+k).
65
66There is also support for goto and renaming.
67
68Get the latest version from `github <https://github.com/davidhalter/jedi>`_
69(master branch should always be kind of stable/working).
70
71Docs are available at `https://jedi.readthedocs.org/en/latest/
72<https://jedi.readthedocs.org/en/latest/>`_. Pull requests with documentation
73enhancements and/or fixes are awesome and most welcome. Jedi uses `semantic
74versioning <http://semver.org/>`_.
75
76
77Installation
78============
79
80    pip install jedi
81
82Note: This just installs the Jedi library, not the editor plugins. For
83information about how to make it work with your editor, refer to the
84corresponding documentation.
85
86You don't want to use ``pip``? Please refer to the `manual
87<https://jedi.readthedocs.org/en/latest/docs/installation.html>`_.
88
89
90Feature Support and Caveats
91===========================
92
93Jedi really understands your Python code. For a comprehensive list what Jedi
94understands, see: `Features
95<https://jedi.readthedocs.org/en/latest/docs/features.html>`_. A list of
96caveats can be found on the same page.
97
98You can run Jedi on cPython 2.6, 2.7, 3.3, 3.4 or 3.5 but it should also
99understand/parse code older than those versions.
100
101Tips on how to use Jedi efficiently can be found `here
102<https://jedi.readthedocs.org/en/latest/docs/features.html#recipes>`_.
103
104API
105---
106
107You can find the documentation for the `API here <https://jedi.readthedocs.org/en/latest/docs/plugin-api.html>`_.
108
109
110Autocompletion / Goto / Pydoc
111-----------------------------
112
113Please check the API for a good explanation. There are the following commands:
114
115- ``jedi.Script.goto_assignments``
116- ``jedi.Script.completions``
117- ``jedi.Script.usages``
118
119The returned objects are very powerful and really all you might need.
120
121
122Autocompletion in your REPL (IPython, etc.)
123-------------------------------------------
124
125It's possible to have Jedi autocompletion in REPL modes - `example video <https://vimeo.com/122332037>`_.
126This means that IPython and others are `supported
127<https://jedi.readthedocs.org/en/latest/docs/usage.html#tab-completion-in-the-python-shell>`_.
128
129
130Static Analysis / Linter
131------------------------
132
133To do all forms of static analysis, please try to use ``jedi.names``. It will
134return a list of names that you can use to infer types and so on.
135
136Linting is another thing that is going to be part of Jedi. For now you can try
137an alpha version ``python -m jedi linter``. The API might change though and
138it's still buggy. It's Jedi's goal to be smarter than classic linter and
139understand ``AttributeError`` and other code issues.
140
141
142Refactoring
143-----------
144
145Jedi's parser would support refactoring, but there's no API to use it right
146now.  If you're interested in helping out here, let me know. With the latest
147parser changes, it should be very easy to actually make it work.
148
149
150Development
151===========
152
153There's a pretty good and extensive `development documentation
154<https://jedi.readthedocs.org/en/latest/docs/development.html>`_.
155
156
157Testing
158=======
159
160The test suite depends on ``tox`` and ``pytest``::
161
162    pip install tox pytest
163
164To run the tests for all supported Python versions::
165
166    tox
167
168If you want to test only a specific Python version (e.g. Python 2.7), it's as
169easy as ::
170
171    tox -e py27
172
173Tests are also run automatically on `Travis CI
174<https://travis-ci.org/davidhalter/jedi/>`_.
175
176For more detailed information visit the `testing documentation
177<https://jedi.readthedocs.org/en/latest/docs/testing.html>`_
178
179
180Acknowledgements
181================
182
183- Takafumi Arakaki (@tkf) for creating a solid test environment and a lot of
184  other things.
185- Danilo Bargen (@dbrgn) for general housekeeping and being a good friend :).
186- Guido van Rossum (@gvanrossum) for creating the parser generator pgen2
187  (originally used in lib2to3).
188
189
190
191.. _jedi-vim: https://github.com/davidhalter/jedi-vim
192.. _youcompleteme: http://valloric.github.io/YouCompleteMe/
193.. _deoplete-jedi: https://github.com/zchee/deoplete-jedi
194.. _Jedi.el: https://github.com/tkf/emacs-jedi
195.. _company-mode: https://github.com/syohex/emacs-company-jedi
196.. _elpy: https://github.com/jorgenschaefer/elpy
197.. _anaconda-mode: https://github.com/proofit404/anaconda-mode
198.. _ycmd: https://github.com/abingham/emacs-ycmd
199.. _sublimejedi: https://github.com/srusskih/SublimeJEDI
200.. _anaconda: https://github.com/DamnWidget/anaconda
201.. _wdb: https://github.com/Kozea/wdb
202.. _TextMate: https://github.com/lawrenceakka/python-jedi.tmbundle
203.. _Kate: http://kate-editor.org
204.. _Atom: https://atom.io/
205.. _autocomplete-python: https://atom.io/packages/autocomplete-python
206.. _SourceLair: https://www.sourcelair.com
207.. _GNOME Builder: https://wiki.gnome.org/Apps/Builder
208.. _Visual Studio Code: https://code.visualstudio.com/
209.. _gedi: https://github.com/isamert/gedi
210.. _Eric IDE: http://eric-ide.python-projects.org
211