*jedi-vim.txt* - For Vim version 7.3 - Last change: 2013/3/1 __ _______ _______ __ ____ ____ __ .___ ___.~ | | | ____|| \ | | \ \ / / | | | \/ |~ | | | |__ | .--. || | _____\ \/ / | | | \ / |~ .--. | | | __| | | | || | |______\ / | | | |\/| |~ | `--' | | |____ | '--' || | \ / | | | | | |~ \______/ |_______||_______/ |__| \__/ |__| |__| |__|~ jedi-vim - awesome Python autocompletion with Vim **now in beta testing phase** ============================================================================== Contents *jedi-vim-contents* 1. Introduction |jedi-vim-introduction| 2. Installation |jedi-vim-installation| 2.0. Requirements |jedi-vim-installation-requirements| 2.1. Manually |jedi-vim-installation-manually| 2.2. Using Pathogen |jedi-vim-installation-pathogen| 2.3. Using Vundle |jedi-vim-installation-vundle| 3. Supported Python features |jedi-vim-support| 4. Usage |jedi-vim-usage| 5. Mappings |jedi-vim-mappings| 5.1. Start completion |g:jedi#autocompletion_command| 5.2. Go to definition |g:jedi#goto_command| 5.3. Get original definition |g:jedi#get_definition_command| 5.4. Show documentation |g:jedi#pydoc_command| 5.5. Rename variables |g:jedi#rename_command| 5.6. Show related names |g:jedi#related_names_command| 6. Configuration |jedi-vim-configuration| 6.1. auto_initialization |g:jedi#auto_initialization| 6.2. auto_vim_configuration |g:jedi#auto_vim_configuration| 6.3. popup_on_dot |g:jedi#popup_on_dot| 6.4. popup_select_first |g:jedi#popup_select_first| 6.5. auto_close_doc |g:jedi#auto_close_doc| 6.6. show_function_definition |g:jedi#show_function_def| 6.7. use_tabs_not_buffers |g:jedi#use_tabs_not_buffers| 6.8. squelch_py_warning |g:jedi#squelch_py_warning| 7. Contributing |jedi-vim-contributing| ============================================================================== 1. Introduction *jedi-vim-introduction* jedi-vim is a is a Vim binding to the awesome Python autocompletion library `Jedi`. Among Jedi's (and, therefore, Jedi-Vim's) features are: - Completion for a wide array of Python features (see |jedi-vim-support|) - Robust in dealing with syntax errors and wrong indentation - Parses complex module/function/class structures - Infers function arguments from Sphinx/Epydoc strings - Doesn't execute Python code - Supports Virtualenv - Supports Python 2.5+ and 3.2+ By leveraging this library, Jedi-Vim adds the following capabilities to Vim: - Displaying function/class bodies - "Go to definition" command - Displaying docstrings - Renaming and refactoring - Looking up related names ============================================================================== 2. Installation *jedi-vim-installation* ------------------------------------------------------------------------------ 2.0. Requirements *jedi-vim-installation-requirements* First of all, Jedi-Vim requires Vim to be compiled with the `+python` option. The Jedi library has to be installed for Jedi-Vim to work properly. You can install it first, by using your e.g. your distribution's package manager, or by using pip: > pip install jedi However, you can also install it as a git submodule if you don't want to use Jedi for anything but this plugin. How to do this is detailed below. ------------------------------------------------------------------------------ 2.1. Installing manually *jedi-vim-installation-manually* 1a. Get the latest repository from Github: > git clone http://github.com/davidhalter/jedi-vim 1b. If you want to install Jedi as a submodule, issue this command instead: > git clone --recursive http://github/davidhalter/jedi-vim 2. Put the plugin files into their corresponding folders in your vim runtime directory (usually ~/.vim). Be sure to pay attention to the directory structure! 3. Update the Vim help tags with > :helptags /doc ------------------------------------------------------------------------------ 2.1. Installing using Pathogen *jedi-vim-installation-pathogen* Pathogen simplifies installation considerably. 1.a Clone the git repository into your bundles directory: > git clone http://github.com/davidhalter/jedi-vim 1b. Again, if you want to install `Jedi` as a submodule, use this command instead: > git clone --recursive http://github/davidhalter/jedi-vim ------------------------------------------------------------------------------ 2.3. Installing using Vundle *jedi-vim-installation-vundle* 1. Vundle automatically downloads subrepositories as git submodules, so you will automatically get the Jedi library with the Jedi-Vim plugin. Add the following to the correct section in your .vimrc file: > Bundle 'git://github.com/davidhalter/jedi-vim' 2. Issue the following command in Vim: > :BundleInstall Help tags are generated automatically, so you should be good to go. ============================================================================== 3. Supported Python features *jedi-vim-support* The Jedi library does all the hard work behind the scenes. It supports a large number of Python features to be completed, among them: - builtins - multiple `return`s or `yield`s - tuple assignments/array indexing/dictionary indexing - `with`-statement/exception handling - `*args`/`**kwargs` - decorators/lambdas/closures - generators/iterators - some descriptors: `property`/`staticmethod`/`classmethod` - some magic methods: `__call__`, `__iter__`, `__next__`, `__get__`, `__getitem__`, `__init__` - `list.append()`, `set.add()`, `list.extend()`, etc. - (nested) list comprehensions/ternary expressions - relative `import`s - `getattr()`/`__getattr__`/`__getattribute__` - function annotations (py3k feature, are ignored right now, but being parsed) - class decorators (py3k feature, are being ignored too at the moment) - simple/usual `sys.path` modifications - `isinstance` checks for `if`/`while`/`assert` case, that doesn’t work with Jedi) Note: This list is not necessarily up to date. For a complete list of features, please refer to the Jedi documentation at http://jedi.readthedocs.org. ============================================================================== 4. Usage *jedi-vim-usage* The autocompletion can be used with , if you want it to work with you can use the Supertab plugin. ============================================================================== 5. Key Bindings *jedi-vim-keybindings* All keybindings can be mapped by setting the appropriate global option. For example, to set the keybinding for starting omnicompletion to instead of , add the following setting to your .vimrc file: > let g:jedi#autocompletion_command = "" Note: If you have |g:jedi#auto_initialization| set to 0, you have to create the mappings yourself by calling the corresponding functions: > " Using for omnicompletion inoremap " Use r (by default <\-r>) for renaming nnoremap r :call jedi#rename() " etc. ------------------------------------------------------------------------------ 5.1. `g:jedi#autocompletion_command` *g:jedi#autocompletion_command* Function: n/a; see above Default: Start completion Starts completion. ------------------------------------------------------------------------------ 5.2. `g:jedi#goto_command` *g:jedi#goto_command* Function: `jedi#goto()` Default: g Go to definition This finds the first definition of the function/class under the cursor. ------------------------------------------------------------------------------ 5.3. `g:jedi#get_definition_command` *g:jedi#get_definition_command* Function: `jedi#get_definition()` Default: d Go to original definition This command tries to find the original definition of the function/class under the cursor. If the function is e.g. imported from another module, this tries to follow the "import chain" to the end. It does not work with modules written in C. ------------------------------------------------------------------------------ 5.4. `g:jedi#pydoc` *g:jedi#pydoc_command* Function: `jedi#show_pydoc()` Default: Show pydoc documentation This shows the pydoc documentation for the item currently under the cursor. The documentation is opened in a horizontally split buffer. ------------------------------------------------------------------------------ 5.5. `g:jedi#rename_command` *g:jedi#rename_command* Function: `jedi#rename()` Default: r Rename variables Jedi-Vim deletes the word currently under the cursor and puts Vim in insert mode, where the user is expected to enter the new variable name. Upon leaving insert mode, Jedi-Vim then renames all occurences of the old variable name with the new one. The number of renames is displayed in the command line. ------------------------------------------------------------------------------ 5.6. `g:jedi#related_names_command` *g:jedi#related_names_command* Function: `jedi#related_names()` Default: n Show related names The quickfix window is populated with a list of all names which point to the definition of the name under the cursor. ============================================================================== 6. Configuration *jedi-vim-configuration* ------------------------------------------------------------------------------ 6.1. `g:jedi#auto_initialization` *g:jedi#auto_initialization* Upon initialization, Jedi-Vim performs the following steps: 1. Set the current buffers 'omnifunc' to its own completion function `jedi#complete` 2. Create mappings to commands specified in |jedi-vim-mappings| 3. Call `jedi#configure_function_definition()` if `g:jedi#show_function_definition` is set You can disable the default initialization routine by setting this option to 0. Beware that you have to perform the above steps yourself, though. Options: 0 or 1 Default: 1 (Perform automatic initialization) ------------------------------------------------------------------------------ 6.2. `g:jedi#auto_vim_configuration` *g:jedi#auto_vim_configuration* Jedi-Vim sets 'completeopt' to `menuone,longest,preview` by default. It also remaps to in insert mode. If you want to keep your own configuration, disable this setting. Options: 0 or 1 Default: 1 (Set 'completeopt' and mapping as described above) ------------------------------------------------------------------------------ 6.3. `g:jedi#popup_on_dot` *g:jedi#popup_on_dot* Jedi automatically starts completion upon typing a period in insert mode. However, when working with large modules, this can slow down your typing flow since you have to wait for Jedi to parse the module and show the completion menu. By disabling this setting, completion is only started when you manually press the completion key. Options: 0 or 1 Default: 1 (Start completion on typing a period) ------------------------------------------------------------------------------ 6.4. `g:jedi#popup_select_first` *g:jedi#popup_select_first* Upon starting completion, Jedi-Vim can automatically select the first entry that pops up (but without actually inserting it). This leads to a better typing flow: As you type more characters, the entries in the completion menu are narrowed down. If they are narrowed down enough, you can just press to insert the first match. Options: 0 or 1 Default: 1 (Automatically select first completion entry) ------------------------------------------------------------------------------ 6.5. `g:jedi#auto_close_doc` *g:jedi#auto_close_doc* When doing completion, Jedi-Vim shows the docstring of the currently selected item in a preview window. This window is by default closed when inserting a completion item. Set this to 1 to leave the preview window open. This could be useful if you want to browse longer docstrings. Options: 0 or 1 Default: 1 (Automatically close preview window upon finishing completion) ------------------------------------------------------------------------------ 6.6. `g:jedi#show_function_definition` *g:jedi#show_function_def* Vim-Jedi can display a small window detailing the arguments of the currently completed function and highlighting the currently selected argument. This can be disabled by setting this option to 0. Options: 0 or 1 Default: 1 (Show function definition window) Note: This setting is ignored if |g:jedi#auto_initialization| is set to 0. In that case, if you want to see function definitions, you have to set this up manually by calling a function in your configuration file: > call jedi#configure_function_definition() ------------------------------------------------------------------------------ 6.7. `g:jedi#use_tabs_not_buffers` *g:jedi#use_tabs_not_buffers* By default, Jedi-Vim opens a new tab if you use the "go to", "show definition", or "related names" commands. When you set this option to 0, they open in the current buffer instead. Options: 0 or 1 Default: 1 (Command output is put in a new tab) ------------------------------------------------------------------------------ 6.8. `g:jedi#squelch_py_warning` *g:jedi#squelch_py_warning* When Vim has not been compiled with +python, Jedi shows a warning to that effect and aborts loading itself. Set this to 1 to suppress that warning. Options: 0 or 1 Default: 0 (Warning is shown) ============================================================================== 7. Contributing *jedi-vim-contributing* If you have any comments or feature requests, please tell me! I really want to know, what you think about Jedi and jedi-vim. vim: textwidth=78 tabstop=8 filetype=help:norightleft: