Debian Codegraph @

vim/doc/jedi-vim.txt

raw
1 *jedi-vim.txt* - For Vim version 7.3 - Last change: 2014/07/29
2 __ _______ _______ __ ____ ____ __ .___ ___.~
3 | | | ____|| \ | | \ \ / / | | | \/ |~
4 | | | |__ | .--. || | _____\ \/ / | | | \ / |~
5 .--. | | | __| | | | || | |______\ / | | | |\/| |~
6 | `--' | | |____ | '--' || | \ / | | | | | |~
7 \______/ |_______||_______/ |__| \__/ |__| |__| |__|~
8
9 jedi-vim - awesome Python autocompletion with Vim
10
11 ==============================================================================
12 Contents *jedi-vim-contents*
13
14 1. Introduction |jedi-vim-introduction|
15 2. Installation |jedi-vim-installation|
16 2.0. Requirements |jedi-vim-installation-requirements|
17 2.1. Manually |jedi-vim-installation-manually|
18 2.2. Using Pathogen |jedi-vim-installation-pathogen|
19 2.3. Using Vundle |jedi-vim-installation-vundle|
20 2.4. Installing from Repositories |jedi-vim-installation-repos|
21 3. Supported Python features |jedi-vim-support|
22 4. Usage |jedi-vim-usage|
23 5. Mappings |jedi-vim-keybindings|
24 5.1. Start completion |g:jedi#completions_command|
25 5.2. Go to definition |g:jedi#goto_command|
26 5.3. Go to assignment |g:jedi#goto_assignments_command|
27 5.4 Go to stub |g:jedi#goto_stubs_command|
28 5.5. Show documentation |g:jedi#documentation_command|
29 5.6. Rename variables |g:jedi#rename_command|
30 5.7. Rename variables (Reuse name) |g:jedi#rename_command_keep_name|
31 5.8. Show name usages |g:jedi#usages_command|
32 5.9. Open module by name |:Pyimport|
33 6. Configuration |jedi-vim-configuration|
34 6.1. auto_initialization |g:jedi#auto_initialization|
35 6.2. auto_vim_configuration |g:jedi#auto_vim_configuration|
36 6.3. popup_on_dot |g:jedi#popup_on_dot|
37 6.4. popup_select_first |g:jedi#popup_select_first|
38 6.5. auto_close_doc |g:jedi#auto_close_doc|
39 6.6. show_call_signatures |g:jedi#show_call_signatures|
40 6.7. show_call_signatures_delay |g:jedi#show_call_signatures_delay|
41 6.8. use_tabs_not_buffers |g:jedi#use_tabs_not_buffers|
42 6.9. squelch_py_warning |g:jedi#squelch_py_warning|
43 6.10. completions_enabled |g:jedi#completions_enabled|
44 6.11. use_splits_not_buffers |g:jedi#use_splits_not_buffers|
45 6.12. force_py_version |g:jedi#force_py_version|
46 6.13. smart_auto_mappings |g:jedi#smart_auto_mappings|
47 6.14. use_tag_stack |g:jedi#use_tag_stack|
48 6.15. environment_path |g:jedi#environment_path|
49 |b:jedi_environment_path|
50 6.16. added_sys_path |g:jedi#added_sys_path|
51 |b:jedi_added_sys_path|
52 6.17. case_insensitive_completion |g:jedi#case_insensitive_completion|
53 |b:jedi_case_insensitive_completion|
54 7. Testing |jedi-vim-testing|
55 8. Contributing |jedi-vim-contributing|
56 9. License |jedi-vim-license|
57
58 ==============================================================================
59 1. Introduction *jedi-vim-introduction*
60
61 Jedi-vim is a Vim binding to the awesome Python autocompletion library
62 `jedi`. Among jedi's (and, therefore, jedi-vim's) features are:
63
64 - Completion for a wide array of Python features (see |jedi-vim-support|)
65 - Robust in dealing with syntax errors and wrong indentation
66 - Parses complex module/function/class structures
67 - Infers function arguments from Sphinx/Epydoc strings
68 - Doesn't execute Python code
69 - Supports Virtualenv
70 - Supports Python 2.7 and 3.4+
71
72 By leveraging this library, jedi-vim adds the following capabilities to Vim:
73
74 - Displaying function/class bodies
75 - "Go to definition" command
76 - Displaying docstrings
77 - Renaming and refactoring
78 - Looking up related names
79
80 ==============================================================================
81 2. Installation *jedi-vim-installation*
82
83 ------------------------------------------------------------------------------
84 2.0. Requirements *jedi-vim-installation-requirements*
85
86 First of all, jedi-vim requires Vim to be compiled with the `+python` option.
87
88 It is best if you have VIM >= 7.3, compiled with the `+conceal` option. With
89 older versions, you will probably not see the parameter recommendation list
90 for functions after typing the open bracket. Some platforms (including OS X
91 releases) do not ship a VIM with `+conceal`. You can check if your VIM has the
92 feature with >
93
94 :ver
95
96 and look for "`+conceal`" (as opposed to "`-conceal`") or >
97
98 :echo has('conceal')
99
100 which will report 0 (not included) or 1 (included). If your VIM lacks this
101 feature and you would like function parameter completion, you will need to
102 build your own VIM, or use a package for your operating system that has this
103 feature (such as MacVim on OS X, which also contains a console binary).
104
105 ------------------------------------------------------------------------------
106 2.1. Installing manually *jedi-vim-installation-manually*
107
108 1. If you want to install jedi as a submodule instead, issue this command: >
109
110 git clone --recursive http://github.com/davidhalter/jedi-vim
111
112 2. Put the plugin files into their respective folders in your vim runtime
113 directory (usually ~/.vim). Be sure to pay attention to the directory
114 structure!
115 3. Update the Vim help tags with >
116
117 :helptags <path/to/vimruntime>/doc
118
119 ------------------------------------------------------------------------------
120 2.2. Installing using Pathogen *jedi-vim-installation-pathogen*
121
122 Pathogen simplifies installation considerably.
123
124 1.a Clone the git repository into your bundles directory: >
125
126 git clone http://github.com/davidhalter/jedi-vim path/to/bundles/jedi-vim
127
128 1b. Again, if you want to install jedi as a submodule, use this command
129 instead: >
130
131 git clone --recursive http://github.com/davidhalter/jedi-vim
132
133 ------------------------------------------------------------------------------
134 2.3. Installing using Vundle *jedi-vim-installation-vundle*
135
136 1. Vundle automatically downloads subrepositories as git submodules, so you
137 will automatically get the jedi library with the jedi-vim plugin. Add the
138 following to the Bundles section in your .vimrc file: >
139
140 Plugin 'davidhalter/jedi-vim'
141
142 2. Issue the following command in Vim: >
143
144 :PluginInstall
145
146 Help tags are generated automatically, so you should be good to go.
147
148 ------------------------------------------------------------------------------
149 2.4. Installing from Repositories *jedi-vim-installation-repos*
150
151 Some Linux distributions have jedi-vim packages in their official
152 repositories. On Arch Linux, install vim-jedi. On Debian (8+) or Ubuntu
153 (14.04+) install vim-python-jedi.
154
155 ==============================================================================
156 3. Supported Python features *jedi-vim-support*
157
158 The Jedi library does all the hard work behind the scenes. It understands most
159 Python features, among them:
160
161 - Builtins
162 - Multiple `return`s or `yield`s
163 - Tuple assignments/array indexing/dictionary indexing
164 - `with`-statement/exception handling
165 - `*args` and `**kwargs`
166 - Decorators, lambdas, closures
167 - Generators, iterators
168 - Some descriptors: `property`/`staticmethod`/`classmethod`
169 - Some magic methods: `__call__`, `__iter__`, `__next__`, `__get__`,
170 `__getitem__`, `__init__`
171 - `list.append()`, `set.add()`, `list.extend()`, etc.
172 - (Nested) list comprehensions and ternary expressions
173 - Relative `import`s
174 - `getattr()`/`__getattr__`/`__getattribute__`
175 - Function annotations (py3k feature, are being ignored at the moment, but are
176 parsed)
177 - Class decorators (py3k feature, are being ignored at the moment, but are
178 parsed)
179 - Simple/usual `sys.path` modifications
180 - `isinstance` checks for `if`/`while`/`assert` case, that doesn't work with
181 Jedi
182 - Stubs
183 - And more...
184
185 Note: This list is not necessarily up to date. For a complete list of
186 features, please refer to the Jedi documentation at
187 http://jedi.readthedocs.io.
188
189 ==============================================================================
190 4. Usage *jedi-vim-usage*
191
192 With the default settings, autocompletion can be triggered by typing
193 <Ctrl-Space>. The first entry will automatically be selected, so you can press
194 <Return> to insert it into your code or keep typing and narrow down your
195 completion options. The usual <C-X><C-O> and <C-P>/<C-N> keybindings work as
196 well. Autocompletion is also triggered by typing a period in insert mode.
197 Since periods rarely occur in Python code outside of method/import lookups,
198 this is handy to have (but can be disabled).
199
200 When it encounters a new module, jedi might take a few seconds to parse that
201 module's contents. Afterwards, the contents are cached and completion will be
202 almost instantaneous.
203
204 ==============================================================================
205 5. Key Bindings *jedi-vim-keybindings*
206
207 All keybindings can be mapped by setting the appropriate global option. For
208 example, to set the keybinding for starting omnicompletion to <C-N> instead of
209 <Ctrl-Space>, add the following setting to your .vimrc file: >
210
211 let g:jedi#completions_command = "<C-N>"
212
213 Note: If you have |g:jedi#auto_initialization| set to 0, you have to create
214 a mapping yourself by calling a function: >
215
216 " Using <C-N> for omnicompletion
217 inoremap <silent> <buffer> <C-N> <c-x><c-o>
218 " Use <localleader>r (by default <\-r>) for renaming
219 nnoremap <silent> <buffer> <localleader>r :call jedi#rename()<cr>
220 " etc.
221
222 Note: You can set commands to '', which means that they are empty and not
223 assigned. It's an easy way to "disable" functionality of jedi-vim.
224
225 ------------------------------------------------------------------------------
226 5.1. `g:jedi#completions_command` *g:jedi#completions_command*
227 Function: n/a; see above
228 Default: <Ctrl-Space> Start completion
229
230 Performs autocompletion (or omnicompletion, to be precise).
231
232 Note: If you want to use <Tab> for completion, please install Supertab:
233 https://github.com/ervandew/supertab.
234
235 ------------------------------------------------------------------------------
236 5.2. `g:jedi#goto_command` *g:jedi#goto_command*
237 Function: `jedi#goto()`
238 Default: <leader>d Go to definition (or assignment)
239
240 This function first tries |jedi#goto_definitions|, and falls back to
241 |jedi#goto_assignments| for builtin modules. It produces an error if nothing
242 could be found.
243 NOTE: this implementation is subject to change.
244 Ref: https://github.com/davidhalter/jedi/issues/570
245
246 This command tries to find the original definition of the function/class under
247 the cursor. Just like the `jedi#goto_assignments()` function, it does not work
248 if the definition isn't in a Python source file.
249
250 The difference between `jedi#goto_assignments()` and `jedi#goto_definitions()`
251 is that the latter performs recursive lookups. Take, for example, the
252 following module structure: >
253
254 # file1.py:
255 from file2 import foo
256
257 # file2.py:
258 from file3 import bar as foo
259
260 # file3.py
261 def bar():
262 pass
263
264 The `jedi#goto_assignments()` function will take you to the >
265
266 from file2 import foo
267
268 statement in file1.py, while the `jedi#goto_definitions()` function will take
269 you all the way to the >
270
271 def bar():
272
273 line in file3.py.
274
275 ------------------------------------------------------------------------------
276 5.3. `g:jedi#goto_assignments_command` *g:jedi#goto_assignments_command*
277 Function: `jedi#goto_assignments()`
278 Default: <leader>g Go to assignment
279
280 This function finds the first definition of the function/class under the
281 cursor. It produces an error if the definition is not in a Python file.
282
283 ------------------------------------------------------------------------------
284 5.4. `g:jedi#goto_stubs_command` *g:jedi#goto_stubs_command*
285 Function: `jedi#goto_stubs()`
286 Default: <leader>s Go to stub
287
288 Finds the stub of the function/class under the cursor.
289
290 ------------------------------------------------------------------------------
291 5.5. `g:jedi#documentation_command` *g:jedi#documentation_command*
292 Function: `jedi#show_documentation()`
293 Default: <K> Show pydoc documentation
294
295 This shows the pydoc documentation for the item currently under the cursor.
296 The documentation is opened in a horizontally split buffer. The height of this
297 buffer is controlled by `g:jedi#max_doc_height` (set by default to 30).
298
299 ------------------------------------------------------------------------------
300 5.6. `g:jedi#rename_command` *g:jedi#rename_command*
301 Function: `jedi#rename()`
302 Default: <leader>r Rename variables
303
304 Jedi-vim deletes the word currently under the cursor and puts Vim in insert
305 mode, where the user is expected to enter the new variable name. Upon leaving
306 insert mode, jedi-vim then renames all occurrences of the old variable name
307 with the new one. The number of performed renames is displayed in the command
308 line.
309
310 ------------------------------------------------------------------------------
311 5.7. `g:jedi#rename_command_keep_name` *g:jedi#rename_command_keep_name*
312 Function: `jedi#rename()`
313 Default: <leader>R Rename variables
314 (This key mapping does not delete the word under the cursor)
315
316 Jedi-vim keeps the word currently under the cursor, moves the cursor to the end
317 of the word, and puts Vim in insert mode, where the user is expected to enter
318 the new variable name. Upon leaving insert mode, Jedi-vim then renames all
319 occurrences of the old variable name with the new one. The number of performed
320 renames is displayed in the command line.
321
322 ------------------------------------------------------------------------------
323 5.8. `g:jedi#usages_command` *g:jedi#usages_command*
324 Function: `jedi#usages()`
325 Default: <leader>n Show usages of a name.
326
327 The quickfix window is populated with a list of all names which point to the
328 definition of the name under the cursor.
329
330 ------------------------------------------------------------------------------
331 5.9. Open module by name *:Pyimport*
332 Function: `jedi#py_import(args)`
333 Default: :Pyimport e.g. `:Pyimport os` shows os.py in VIM.
334
335 Simulate an import and open that module in VIM.
336
337 ==============================================================================
338 6. Configuration *jedi-vim-configuration*
339
340 Note: You currently have to set these options in your .vimrc. Setting them in
341 an ftplugin (e.g. ~/.vim/ftplugin/python/jedi-vim-settings.vim) will not work
342 because jedi-vim is not set up as an filetype plugin, but as a "regular"
343 plugin.
344
345 ------------------------------------------------------------------------------
346 6.1. `g:jedi#auto_initialization` *g:jedi#auto_initialization*
347
348 Upon initialization, jedi-vim performs the following steps:
349
350 1. Set the current buffers 'omnifunc' to its own completion function
351 `jedi#completions`
352 2. Create mappings to commands specified in |jedi-vim-keybindings|
353 3. Call `jedi#configure_call_signatures()` if
354 `g:jedi#show_call_signatures` is set
355
356 You can disable the default initialization routine by setting this option to
357 0. Beware that you have to perform the above steps yourself, though.
358
359 Options: 0 or 1
360 Default: 1 (Perform automatic initialization)
361
362 ------------------------------------------------------------------------------
363 6.2. `g:jedi#auto_vim_configuration` *g:jedi#auto_vim_configuration*
364
365 Jedi-vim sets 'completeopt' to `menuone,longest` and `popup` (for Vim version
366 numbers higher than 8.1.1882) respectively `preview` by default, if
367 'completeopt' is not changed from Vim's default.
368 It also remaps <Ctrl-C> to <Esc> in insert mode.
369
370 If you want to keep your own configuration, disable this setting.
371
372 Options: 0 or 1
373 Default: 1 (Set 'completeopt' and mapping as described above)
374
375 ------------------------------------------------------------------------------
376 6.3. `g:jedi#popup_on_dot` *g:jedi#popup_on_dot*
377
378 Jedi-vim automatically starts completion upon typing a period in insert mode.
379
380 However, when working with large modules, this can slow down your typing flow
381 since you have to wait for jedi to parse the module and show the completion
382 menu. By disabling this setting, completion is only started when you manually
383 press the completion key.
384 You need to also have `g:jedi#completions_enabled` enabled for this.
385
386 Options: 0 or 1
387 Default: 1 (Start completion on typing a period)
388
389 ------------------------------------------------------------------------------
390 6.4. `g:jedi#popup_select_first` *g:jedi#popup_select_first*
391
392 Upon starting completion, jedi-vim can automatically select the first entry
393 that pops up (without actually inserting it).
394
395 This leads to a better typing flow: As you type more characters, the entries
396 in the completion menu are narrowed down. If they are narrowed down enough,
397 you can just press <Return> to insert the first match.
398
399 Options: 0 or 1
400 Default: 1 (Automatically select first completion entry)
401
402 ------------------------------------------------------------------------------
403 6.5. `g:jedi#auto_close_doc` *g:jedi#auto_close_doc*
404
405 When doing completion and jedi-vim shows the docstring of the currently selected
406 item in a preview (not a popup) window, this window is being closed after
407 insertion of a completion item.
408
409 Set this to 0 to leave the preview window open even after leaving insert mode.
410 This could be useful if you want to browse longer docstrings.
411
412 This setting is ignored if a popup instead of a preview window is used.
413
414 Options: 0 or 1
415 Default: 1 (Automatically close preview window upon leaving insert mode)
416
417 ------------------------------------------------------------------------------
418 6.6. `g:jedi#show_call_signatures` *g:jedi#show_call_signatures*
419
420 Jedi-vim can display a small window detailing the arguments of the currently
421 completed function and highlighting the currently selected argument. This can
422 be disabled by setting this option to 0. Setting this option to 2 shows call
423 signatures in the command line instead of a popup window.
424
425 Options: 0, 1, or 2
426 Default: 1 (Show call signatures window)
427
428 Note: 'showmode' must be disabled for command line call signatures to be
429 visible.
430
431 Note: This setting is ignored if |g:jedi#auto_initialization| is set to 0. In
432 that case, if you want to see call signatures, you have to set it up
433 manually by calling a function in your configuration file: >
434
435 call jedi#configure_call_signatures()
436
437 ------------------------------------------------------------------------------
438 6.7. `g:jedi#show_call_signatures_delay` *g:jedi#show_call_signatures_delay*
439
440 The delay to be used with |g:jedi#show_call_signatures|. If it is greater
441 than 0 it will use Vim's |CursorHoldI| event instead of |CursorMovedI|.
442 It will temporarily set Vim's |'updatetime'| option during insert mode.
443
444 Options: delay in milliseconds
445 Default: 500
446
447 ------------------------------------------------------------------------------
448 6.8. `g:jedi#use_tabs_not_buffers` *g:jedi#use_tabs_not_buffers*
449
450 You can make jedi-vim open a new tab if you use the "go to", "show
451 definition", or "related names" commands. When you leave this at the default
452 (0), they open in the current window instead.
453
454 Options: 0 or 1
455 Default: 0 (Command output reuses current window)
456
457 ------------------------------------------------------------------------------
458 6.9. `g:jedi#squelch_py_warning` *g:jedi#squelch_py_warning*
459
460 When Vim has not been compiled with +python, jedi-vim shows a warning to that
461 effect and aborts loading itself. Set this to 1 to suppress that warning.
462
463 Options: 0 or 1
464 Default: 0 (Warning is shown)
465
466 ------------------------------------------------------------------------------
467 6.10. `g:jedi#completions_enabled` *g:jedi#completions_enabled*
468
469 If you don't want Jedi completion, but all the other features, you can disable
470 it in favor of another completion engine (that probably also uses Jedi, like
471 YCM).
472
473 Options: 0 or 1
474 Default: 1
475
476 ------------------------------------------------------------------------------
477 6.11. `g:jedi#use_splits_not_buffers` *g:jedi#use_splits_not_buffers*
478
479 If you want to open new split for "go to", you could set this option to the
480 direction which you want to open a split with.
481
482 Options: top, left, right, bottom or winwidth
483 Default: "" (not enabled by default)
484
485 Note: with the 'winwidth' option the window is split vertically or horizontally
486 depending on the width of the window relative to 'textwidth'. This essentially
487 means that if the window is big enough it will be split vertically but if it is
488 small a horizontal split happens.
489
490 ------------------------------------------------------------------------------
491 6.12. `g:jedi#force_py_version` *g:jedi#force_py_version*
492
493 If you have installed multiple Python versions, you can force the Python
494 version that is going to be used.
495 You don't have to compile VIM with multiple Python versions.
496 The variable can be set in the .vimrc like this to force python 2:
497
498 let g:jedi#force_py_version = 2
499
500 By default jedi loads the latest Python version installed on your system that
501 can be found.
502
503 This variable can be changed during runtime.
504
505 Options: 2, 2.7, 3, 3.5, 3.6, ...
506 Default: "auto"
507 ------------------------------------------------------------------------------
508 6.13. `g:jedi#smart_auto_mappings` *g:jedi#smart_auto_mappings*
509
510 When you start typing `from module.name<space>` jedi-vim automatically
511 can add the "import" statement and trigger the autocompletion popup.
512
513 You can enable this using: >
514
515 let g:jedi#smart_auto_mappings = 1
516 <
517 Options: 0 or 1
518 Default: 0 (disabled by default)
519
520 ------------------------------------------------------------------------------
521 6.14. `g:jedi#use_tag_stack` *g:jedi#use_tag_stack*
522
523 Write results of |jedi#goto| to a temporary file and use the |:tjump| command
524 to enable full |tagstack| functionality. Use of the tag stack allows
525 returning to the usage of a function with CTRL-T after exploring the
526 definition with arbitrary changes to the |jumplist|.
527
528 Options: 0 or 1
529 Default: 1 (enabled by default)
530
531 ------------------------------------------------------------------------------
532 6.15. `g:jedi#environment_path` *g:jedi#environment_path*
533 *b:jedi_environment_path*
534
535 To use a specific virtualenv or a specific Python version it is possible to
536 set an interpreter.
537
538 Both setting the directory and setting a project is working.
539
540 Examples: "/usr/bin/python3.9", "venv", "../venv", "../venv/bin/python"
541
542 The buffer-local variable `b:jedi_environment_path` can be used to override the
543 global variable `g:jedi#environment_path`.
544
545 Default: "auto"
546
547 ------------------------------------------------------------------------------
548 6.16. `g:jedi#added_sys_path` *g:jedi#added_sys_path*
549 *b:jedi_added_sys_path*
550
551 To add extra sys_path.
552
553 The buffer-local variable `b:jedi_added_sys_path` can be used to add
554 additional extra sys_path.
555
556 Examples: ["../site-packages"]
557 Default: []
558
559 ------------------------------------------------------------------------------
560 6.17. `g:jedi#case_insensitive_completion` *g:jedi#case_insensitive_completion*
561 *b:jedi_case_insensitive_completion*
562
563 0 to disable case insensitive completion.
564 1 to enable case insensitive completion (default).
565
566 The buffer-local variable `b:jedi_case_insensitive_completion` can be used to
567 override the global variable `g:jedi#case_insensitive_completion`.
568
569 Default: 1
570
571 ==============================================================================
572 7. Testing *jedi-vim-testing*
573
574 jedi-vim is being tested with a combination of vspec
575 https://github.com/kana/vim-vspec and py.test http://pytest.org/.
576
577 The tests are in the test subdirectory, you can run them calling::
578
579 py.test
580
581 The tests are automatically run with `travis
582 <https://travis-ci.org/davidhalter/jedi-vim>`_.
583
584 ==============================================================================
585 8. Contributing *jedi-vim-contributing*
586
587 We love Pull Requests! Read the instructions in `CONTRIBUTING.md`.
588
589 ==============================================================================
590 9. License *jedi-vim-license*
591
592 Jedi-vim is licensed with the MIT license.
593
594 vim: textwidth=78 et filetype=help:norightleft: