283 lines
12 KiB
Text
283 lines
12 KiB
Text
|
Metadata-Version: 1.1
|
||
|
|
Name: jedi
|
||
|
|
Version: 0.5b5
|
||
|
|
Summary: An autocompletion tool for Python that can be used for text editors.
|
||
|
|
Home-page: https://github.com/davidhalter/jedi
|
||
|
|
Author: David Halter
|
||
|
|
Author-email: davidhalter88@gmail.com
|
||
|
|
License: LGPLv3
|
||
|
|
Description: ########################################
|
||
|
|
Jedi - an awesome Python auto-completion
|
||
|
|
########################################
|
||
|
|
|
||
|
|
.. image:: https://secure.travis-ci.org/davidhalter/jedi.png?branch=master
|
||
|
|
:target: http://travis-ci.org/davidhalter/jedi
|
||
|
|
:alt: Travis-CI build status
|
||
|
|
|
||
|
|
**beta testing**
|
||
|
|
|
||
|
|
*If you have any comments or feature requests, please tell me! I really want to
|
||
|
|
know, what you think about Jedi.*
|
||
|
|
|
||
|
|
Jedi is an autocompletion tool for Python. It works. With and without syntax
|
||
|
|
errors. Sometimes it sucks, but that's normal in dynamic languages. But it
|
||
|
|
sucks less than other tools. It understands almost all of the basic Python
|
||
|
|
syntax elements including many builtins.
|
||
|
|
|
||
|
|
Jedi suports two different goto functions and has support for renaming.
|
||
|
|
Probably it will also have some support for refactoring in the future.
|
||
|
|
|
||
|
|
Jedi uses a very simple interface to connect with IDE's. As an reference, there
|
||
|
|
is a VIM implementation, which uses Jedi's autocompletion. However, I encourage
|
||
|
|
you to use Jedi in your IDEs. Start writing plugins! If there are problems with
|
||
|
|
licensing, just contact me.
|
||
|
|
|
||
|
|
At the moment Jedi can be used as a
|
||
|
|
`VIM-Plugin <http://github.com/davidhalter/jedi-vim>`_. So, if you want to test
|
||
|
|
Jedi for now, you'll have to use VIM. But there are new plugins emerging:
|
||
|
|
|
||
|
|
- `Emacs-Plugin <https://github.com/tkf/emacs-jedi>`_
|
||
|
|
- `Sublime-Plugin <https://github.com/svaiter/SublimeJEDI>`_ **Under construction**
|
||
|
|
|
||
|
|
Here are some pictures:
|
||
|
|
|
||
|
|
.. image:: https://github.com/davidhalter/jedi/raw/master/screenshot_complete.png
|
||
|
|
|
||
|
|
Completion for almost anything (Ctrl+Space).
|
||
|
|
|
||
|
|
.. image:: https://github.com/davidhalter/jedi/raw/master/screenshot_function.png
|
||
|
|
|
||
|
|
Display of function/class bodies, docstrings.
|
||
|
|
|
||
|
|
.. image:: https://github.com/davidhalter/jedi/raw/master/screenshot_pydoc.png
|
||
|
|
|
||
|
|
Pydoc support (with highlighting, Shift+k).
|
||
|
|
|
||
|
|
There is also support for goto and renaming.
|
||
|
|
|
||
|
|
Get the latest from `github <http://github.com/davidhalter/jedi>`_.
|
||
|
|
|
||
|
|
|
||
|
|
Installation
|
||
|
|
============
|
||
|
|
|
||
|
|
You can either include Jedi as a submodule in your text editor plugin (like
|
||
|
|
jedi-vim_ does it by default), or you
|
||
|
|
can install Jedi systemwide.
|
||
|
|
|
||
|
|
The preferred way to install the Jedi library into your system is by using
|
||
|
|
pip_::
|
||
|
|
|
||
|
|
sudo pip install jedi
|
||
|
|
|
||
|
|
If you want to install the current development version::
|
||
|
|
|
||
|
|
sudo pip install -e git://github.com/davidhalter/jedi.git#egg=jedi
|
||
|
|
|
||
|
|
Note: 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.
|
||
|
|
|
||
|
|
|
||
|
|
Support
|
||
|
|
=======
|
||
|
|
|
||
|
|
Jedi supports Python 2.5 up to 3.x. There is just one code base, for both
|
||
|
|
Python 2 and 3.
|
||
|
|
Jedi supports many of the widely used Python features:
|
||
|
|
|
||
|
|
- builtin functions/classes support
|
||
|
|
- complex module / function / class structures
|
||
|
|
- ignores syntax and indentation errors
|
||
|
|
- multiple returns / yields
|
||
|
|
- tuple assignments / array indexing / dictionary indexing
|
||
|
|
- exceptions / with-statement
|
||
|
|
- \*args / \*\*kwargs
|
||
|
|
- decorators
|
||
|
|
- descriptors -> property / staticmethod / classmethod
|
||
|
|
- closures
|
||
|
|
- generators (yield statement) / iterators
|
||
|
|
- support for some magic methods: ``__call__``, ``__iter__``, ``__next__``,
|
||
|
|
``__get__``, ``__getitem__``, ``__init__``
|
||
|
|
- support for list.append, set.add, list.extend, etc.
|
||
|
|
- (nested) list comprehensions / ternary expressions
|
||
|
|
- relative imports
|
||
|
|
- ``getattr()`` / ``__getattr__`` / ``__getattribute__``
|
||
|
|
- function annotations (py3k feature, are ignored right now, but being parsed.
|
||
|
|
I don't know what to do with them.)
|
||
|
|
- class decorators (py3k feature, are being ignored too, until I find a use
|
||
|
|
case, that doesn't work with Jedi)
|
||
|
|
- simple/usual ``sys.path`` modifications
|
||
|
|
- ``isinstance`` checks for if/while/assert
|
||
|
|
- virtualenv support
|
||
|
|
- infer function arguments with sphinx (and other) docstrings
|
||
|
|
|
||
|
|
However, it does not yet support (and probably will in future versions, because
|
||
|
|
they are on my todo list):
|
||
|
|
|
||
|
|
- manipulations of instances outside the instance variables, without using
|
||
|
|
functions
|
||
|
|
|
||
|
|
It does not support (and most probably will not in future versions):
|
||
|
|
|
||
|
|
- metaclasses (how could an auto-completion ever support this)
|
||
|
|
- ``setattr()``, ``__import__()``
|
||
|
|
- Writing to some dicts: ``globals()``, ``locals()``, ``object.__dict__``
|
||
|
|
- evaluate ``if`` / ``while``
|
||
|
|
|
||
|
|
|
||
|
|
Caveats
|
||
|
|
=======
|
||
|
|
|
||
|
|
This framework should work for both Python 2/3. However, some things were just
|
||
|
|
not as *pythonic* in Python 2 as things should be. To keep things simple, some
|
||
|
|
things have been held back:
|
||
|
|
|
||
|
|
- Classes: Always Python 3 like, therefore all classes inherit from ``object``.
|
||
|
|
- Generators: No ``next`` method. The ``__next__`` method is used instead.
|
||
|
|
- Exceptions are only looked at in the form of ``Exception as e``, no comma!
|
||
|
|
|
||
|
|
Syntax errors and other strange stuff, that is defined differently in the
|
||
|
|
Python language, may lead to undefined behaviour of the completion. Jedi is
|
||
|
|
**NOT** a Python compiler, that tries to correct you. It is a tool that wants
|
||
|
|
to help you. But **YOU** have to know Python, not Jedi.
|
||
|
|
|
||
|
|
Importing ``numpy`` can be quite slow sometimes, as well as loading the builtins
|
||
|
|
the first time. If you want to speed it up, you could write import hooks in
|
||
|
|
jedi, which preloads this stuff. However, once loaded, this is not a problem
|
||
|
|
anymore. The same is true for huge modules like ``PySide``, ``wx``, etc.
|
||
|
|
|
||
|
|
Security is an important issue for Jedi. Therefore no Python code is executed.
|
||
|
|
As long as you write pure python, everything is evaluated statically. But: If
|
||
|
|
you use builtin modules (`c_builtin`) there is no other option than to execute
|
||
|
|
those modules. However: Execute isn't that critical (as e.g. in pythoncomplete,
|
||
|
|
which used to execute *every* import!), because it means one import and no
|
||
|
|
more. So basically the only dangerous thing is using the import itself. If your
|
||
|
|
`c_builtin` uses some strange initializations, it might be dangerous. But if it
|
||
|
|
does you're screwed anyways, because eventualy you're going to execute your
|
||
|
|
code, which executes the import.
|
||
|
|
|
||
|
|
|
||
|
|
A little history
|
||
|
|
================
|
||
|
|
|
||
|
|
The Star Wars Jedi are awesome. My Jedi software tries to imitate a little bit
|
||
|
|
of the precognition the Jedi have. There is even an awesome `scene
|
||
|
|
<http://www.youtube.com/watch?v=5BDO3pyavOY>`_ of Monty Python Jedi's :-).
|
||
|
|
|
||
|
|
But actually the name hasn't so much to do with Star Wars. It's part of my
|
||
|
|
second name.
|
||
|
|
|
||
|
|
After I explained Guido van Rossum, how some parts of my auto-completion work,
|
||
|
|
he said (we drank a beer or two):
|
||
|
|
|
||
|
|
*Oh, that worries me*
|
||
|
|
|
||
|
|
When it's finished, I hope he'll like it :-)
|
||
|
|
|
||
|
|
I actually started Jedi, because there were no good solutions available for
|
||
|
|
VIM. Most auto-completions just didn't work well. The only good solution was
|
||
|
|
PyCharm. I just like my good old VIM. Rope was never really intended to be an
|
||
|
|
auto-completion (and also I really hate project folders for my Python scripts).
|
||
|
|
It's more of a refactoring suite. So I decided to do my own version of a
|
||
|
|
completion, which would execute non-dangerous code. But I soon realized, that
|
||
|
|
this wouldn't work. So I built an extremely recursive thing which understands
|
||
|
|
many of Python's key features.
|
||
|
|
|
||
|
|
By the way, I really tried to program it as understandable as possible. But I
|
||
|
|
think understanding it might need quite some time, because of its recursive
|
||
|
|
nature.
|
||
|
|
|
||
|
|
|
||
|
|
API-Design for IDEs
|
||
|
|
===================
|
||
|
|
|
||
|
|
If you want to set up an IDE with Jedi, you need to ``import jedi``. You should
|
||
|
|
have the following objects available:
|
||
|
|
|
||
|
|
::
|
||
|
|
|
||
|
|
Script(source, line, column, source_path)
|
||
|
|
|
||
|
|
``source`` would be the source of your python file/script, separated by new
|
||
|
|
lines. ``line`` is the current line you want to perform actions on (starting
|
||
|
|
with line #1 as the first line). ``column`` represents the current
|
||
|
|
column/indent of the cursor (starting with zero). ``source_path`` should be the
|
||
|
|
path of your file in the file system.
|
||
|
|
|
||
|
|
It returns a script object that contains the relevant information for the other
|
||
|
|
functions to work without params.
|
||
|
|
|
||
|
|
::
|
||
|
|
|
||
|
|
Script().complete
|
||
|
|
|
||
|
|
Returns ``api.Completion`` objects. Those objects have got
|
||
|
|
informations about the completions. More than just names.
|
||
|
|
|
||
|
|
::
|
||
|
|
|
||
|
|
Script().goto
|
||
|
|
|
||
|
|
Similar to complete. The returned ``api.Definition`` objects contain
|
||
|
|
information about the definitions found.
|
||
|
|
|
||
|
|
::
|
||
|
|
|
||
|
|
Script().get_definition
|
||
|
|
|
||
|
|
Mostly used for tests. Like goto, but follows statements and imports and
|
||
|
|
doesn't break there. You probably don't want to use this function. It's
|
||
|
|
mostly for testing.
|
||
|
|
|
||
|
|
::
|
||
|
|
|
||
|
|
Script().related_names
|
||
|
|
|
||
|
|
Returns all names that point to the definition of the name under the
|
||
|
|
cursor. This is also very useful for refactoring (renaming).
|
||
|
|
|
||
|
|
::
|
||
|
|
|
||
|
|
Script().get_in_function_call
|
||
|
|
|
||
|
|
Get the ``Function`` object of the call you're currently in, e.g.: ``abs(``
|
||
|
|
with the cursor at the end would return the builtin ``abs`` function.
|
||
|
|
|
||
|
|
::
|
||
|
|
|
||
|
|
NotFoundError
|
||
|
|
|
||
|
|
If you use the goto function and no valid identifier (name) is at the
|
||
|
|
place of the cursor (position). It will raise this exception.
|
||
|
|
|
||
|
|
::
|
||
|
|
|
||
|
|
set_debug_function
|
||
|
|
|
||
|
|
Sets a callback function for ``debug.py``. This function is called with
|
||
|
|
multiple text objects, in python 3 you could insert ``print``.
|
||
|
|
|
||
|
|
::
|
||
|
|
|
||
|
|
settings
|
||
|
|
|
||
|
|
Access to the ``settings.py`` module. The settings are described there.
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
.. _jedi-vim: http://github.com/davidhalter/jedi-vim
|
||
|
|
.. _pip: http://www.pip-installer.org/
|
||
|
|
|
||
|
|
Keywords: python completion refactoring vim
|
||
|
|
Platform: any
|
||
|
|
Classifier: Development Status :: 4 - Beta
|
||
|
|
Classifier: Environment :: Plugins
|
||
|
|
Classifier: Intended Audience :: Developers
|
||
|
|
Classifier: License :: OSI Approved :: GNU Library or Lesser General Public License (LGPL)
|
||
|
|
Classifier: Operating System :: OS Independent
|
||
|
|
Classifier: Programming Language :: Python
|
||
|
|
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
||
|
|
Classifier: Topic :: Text Editors :: Integrated Development Environments (IDE)
|
||
|
|
Classifier: Topic :: Utilities
|