mirror of
https://github.com/davidhalter/jedi.git
synced 2026-01-11 14:32:20 +08:00
Converted README: markdown to rst (fixexs #13)
This commit is contained in:
Danilo Bargen
@@ -1,5 +1,6 @@
|
||||
######################################
|
||||
Jedi - a clever Python auto-completion
|
||||
============================
|
||||
######################################
|
||||
|
||||
**now in alpha testing phase**
|
||||
|
||||
@@ -23,10 +24,11 @@ problems with licensing, just contact me.
|
||||
At the moment Jedi can be used as a **VIM-Plugin**. So, if you want to test
|
||||
Jedi for now, you'll have to use VIM. Just check the chapter on VIM bellow.
|
||||
|
||||
Get the latest from [github](http://github.com/davidhalter/jedi).
|
||||
Get the latest from `github <http://github.com/davidhalter/jedi>`_.
|
||||
|
||||
|
||||
Support
|
||||
-------
|
||||
=======
|
||||
|
||||
Jedi supports Python 2.5 up to 3.x. There is just one code base, for both
|
||||
Python 2 and 3.
|
||||
@@ -43,17 +45,17 @@ Jedi supports many of the widely used Python features:
|
||||
- descriptors -> property / staticmethod / classmethod
|
||||
- closures
|
||||
- generators (yield statement) / iterators
|
||||
- support for some magic methods: `__call__`, `__iter__`, `__next__`,
|
||||
`__get__`, `__getitem__`, `__init__`
|
||||
- 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__`
|
||||
- ``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
|
||||
- simple/usual ``sys.path`` modifications
|
||||
|
||||
However, it does not yet support (and probably will in future versions, because
|
||||
they are on my todo list):
|
||||
@@ -69,28 +71,28 @@ It does not support (and most probably will not in future versions):
|
||||
- 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!
|
||||
- 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
|
||||
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.
|
||||
anymore. The same is true for huge modules like ``PySide``, ``wx``, etc.
|
||||
|
||||
A little history
|
||||
----------------
|
||||
================
|
||||
|
||||
The Star Wars Jedi are awesome. My Jedi software tries to imitate a little bit
|
||||
of the precognition the Jedi have.
|
||||
@@ -101,7 +103,7 @@ 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*
|
||||
*Oh, that worries me*
|
||||
|
||||
When it's finished, I hope he'll like it :-)
|
||||
|
||||
@@ -118,83 +120,110 @@ By the way, I really tried to program it as understandable as possible. But I
|
||||
think understanding it might need 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
|
||||
If you want to set up an IDE with Jedi, you need to ``import jedi``. You should
|
||||
have the following objects available:
|
||||
|
||||
`Script`
|
||||
> 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`
|
||||
|
||||
`Script().goto`
|
||||
> Similar to complete. The returned `api.Definition` objects contain
|
||||
> information about the definitions found.
|
||||
Returns a script object, that contains the relevant information for the
|
||||
other functions to work without params.
|
||||
|
||||
`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().complete`
|
||||
|
||||
`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.
|
||||
Returns ``api.Completion`` objects. Those objects have got
|
||||
informations about the completions. More than just names.
|
||||
|
||||
`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`.
|
||||
`Script().goto`
|
||||
|
||||
`settings`
|
||||
> Access to the `settings.py` module. The settings are described there.
|
||||
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.
|
||||
|
||||
VIM Plugin
|
||||
-------------------
|
||||
==========
|
||||
|
||||
At the moment jedi is also a VIM plugin. It is some sort of reference
|
||||
implementation for other IDE's.
|
||||
The VIM plugin is located under `plugin/jedi.vim`.
|
||||
The VIM plugin is located under ``plugin/jedi.vim``.
|
||||
|
||||
You might want to use [pathogen](https://github.com/tpope/vim-pathogen) to
|
||||
You might want to use `pathogen <https://github.com/tpope/vim-pathogen>`_ to
|
||||
install jedi in VIM. Also you need a VIM version that was compiled with
|
||||
`+python`, which is typical for most distributions on Linux.
|
||||
``+python``, which is typical for most distributions on Linux.
|
||||
|
||||
Jedi is automatically initialized. If you don't want that I suggest you
|
||||
disable the auto-initialization in your `.vimrc`:
|
||||
disable the auto-initialization in your ``.vimrc``:
|
||||
|
||||
let g:jedi#auto_initialization = 0
|
||||
|
||||
The autocompletion can be used with \<ctrl+space\>, if you want it to work with
|
||||
\<tab\> you can use [supertab](https://github.com/ervandew/supertab).
|
||||
The goto is by default on \<leader g\>. If you want to change that:
|
||||
The autocompletion can be used with <ctrl+space>, if you want it to work with
|
||||
<tab> you can use `supertab <https://github.com/ervandew/supertab>`_.
|
||||
The goto is by default on <leader g>. If you want to change that:
|
||||
|
||||
let g:jedi#goto_command = "<leader>g"
|
||||
|
||||
`get_definition` is by default on \<leader d\>. If you want to change that:
|
||||
``get_definition`` is by default on <leader d>. If you want to change that:
|
||||
|
||||
let g:jedi#get_definition_command = "<leader>d"
|
||||
|
||||
Showing the pydoc is by default on `K` If you want to change that:
|
||||
Showing the pydoc is by default on ``K`` If you want to change that:
|
||||
|
||||
let g:jedi#pydoc = "K"
|
||||
|
||||
If you are a person who likes to use VIM-buffers not tabs, you might want to
|
||||
put that in your `.vimrc`:
|
||||
put that in your ``.vimrc``:
|
||||
|
||||
let g:jedi#use_tabs_not_buffers = 0
|
||||
|
||||
Jedi automatically starts the completion, if you type a dot, e.g. `str.`, if
|
||||
Jedi automatically starts the completion, if you type a dot, e.g. ``str.``, if
|
||||
you don't want this:
|
||||
|
||||
let g:jedi#popup_on_dot = 0
|
||||
@@ -207,4 +236,6 @@ And you can list all names that are related (have the same origin):
|
||||
let g:jedi#related_names_command = "<leader>n"
|
||||
|
||||
|
||||
[](http://travis-ci.org/davidhalter/jedi)
|
||||
.. image:: https://secure.travis-ci.org/davidhalter/jedi.png?branch=master
|
||||
:target: http://travis-ci.org/davidhalter/jedi
|
||||
:alt: Travis-CI build status
|
||||
Reference in New Issue
Block a user