*pymode.txt* For Vim Version 8.0 Last change: 2019 March 08

Version: 0.14.0

CONTENTS *pymode-contents*

1. Intro...........................................................|pymode-intro|

2. Common functionality...........................................|pymode-common|

2.1 Python version....................................|pymode-python-version|

2.2 Python indentation........................................|pymode-indent|

2.3 Python folding...........................................|pymode-folding|

2.4 Vim motion................................................|pymode-motion|

2.5 Show documentation.................................|pymode-documentation|

2.6 Support virtualenv....................................|pymode-virtualenv|

2.7 Run code.....................................................|pymode-run|

2.8 Breakpoints..........................................|pymode-breakpoints|

3. Code checking....................................................|pymode-lint|

3.1 Code checkers options...............................|pymode-lint-options|

4. Rope support.....................................................|pymode-rope|

4.1 Code completion.......................................|pymode-completion|

4.2 Find definition......................................|pymode-rope-findit|

4.3 Refactoring.....................................|pymode-rope-refactoring|

4.4 Undo/Redo changes......................................|pymode-rope-undo|

5. Syntax.........................................................|pymode-syntax|

6. FAQ...............................................................|pymode-faq|

7. Development...............................................|pymode-development|

8. Credits.......................................................|pymode-credits|

9. License.......................................................|pymode-license|

*pymode-intro*

XXX IMPORTANT: As of 2017-11-18 python-mode is going through a major redesign.

Thus some of its functionality may not work as expected. Please be patient and

do report bugs or inconsistencies in its documentation. But remember to look

for already openned bug reports for the same issue before creating a new one.

Python-mode is a vim plugin that allows you to use the pylint, rope, and pydoc

libraries in vim to provide features like python code bug checking,

refactoring, and some other useful things.

This plugin allows you to create python code in vim very easily. There is no

need to install the pylint or rope libraries on your system.

Python-mode contains all you need to develop python applications in Vim.

Features: *pymode-features*

- Support Python version 3.10.13, 3.11.9, 3.12.4, 3.13.0

- Syntax highlighting

- Virtualenv support

- Run python code (``<leader>r``)

- Add/remove breakpoints (``<leader>b``)

- Improved Python indentation

- Python folding

- Python motions and operators (``]]``, ``3[[``, ``]]M``, ``vaC``, ``viM``,

``daC``, ``ciM``, ...)

- Code checking (pylint_, pyflakes_, pylama_, ...) that can be run

simultaneously (``:PymodeLint``)

- Autofix PEP8 errors (``:PymodeLintAuto``)

- Search in python documentation (``K``)

- Code refactoring <rope refactoring library> (rope_)

- Strong code completion (rope_)

- Go to definition (``<C-c>g`` for `:RopeGotoDefinition`)

- And more, more ...

*pymode-common*

This script provides the following options that can customizes the behavior of

python-mode. These options should be set in your |vimrc|.

Find below the default values:

Turn on the whole plugin. *'g:pymode'*

Turn off plugin's warnings. *'g:pymode_warnings'*

Add paths to `sys.path` *'g:pymode_paths'*

Value is list of path's strings.

Trim unused white spaces on save. *'g:pymode_trim_whitespaces'*

Setup default python options. *'g:pymode_options'*

If this option is set to 1, pymode will enable the following options for

python buffers: >

Setup max line length *'g:pymode_options_max_line_length'*

Enable colorcolumn display at max_line_length. *'g:pymode_options_colorcolumn'*

Setup pymode |quickfix| window.

*'g:pymode_quickfix_maxheight'* *'g:pymode_quickfix_minheight'*

Set pymode |preview| window height. *'g:pymode_preview_height'*

Preview window is used to show documentation and ouput from |pymode-run|.

Set where pymode |preview| window will appear. *'g:pymode_preview_position'*

Value is command which can influcece where new window created by `:new` command

will appear, eg. `:botright`.

*pymode-python-version*

By default pymode will attempt to use Python 3, if available. However, you can

also disable all Python features of pymode.

*'g:pymode_python'*

Values are `python3`, `disable`. If value set to `disable` most

python-features of **pymode** will be disabled.

Set value to `python3` if you are working with python3 projects. You could use

+ Currently supported Python versions: 3.10.13, 3.11.9, 3.12.4, 3.13.0

+

+ For testing with different Python versions, see the Docker testing environment

+ described in the Development section.

*pymode-indent*

Pymode supports PEP8-compatible python indent.

Enable pymode indentation *'g:pymode_indent'*

Customization:

Hanging indent size after an open parenthesis or bracket (but nothing after the

parenthesis), when vertical alignment is not used. Defaults to `&shiftwidth`.

*'g:pymode_indent_hanging_width'*

*pymode-folding*

Enable pymode folding *'g:pymode_folding'*

Currently folding is considered experimental. There are several issues with

its implementation.

*pymode-motion*

Support Vim motion (See |operator|) for python objects (such as functions,

class and methods).

`C` — means class

`M` — means method or function

*pymode-motion-keys*

Key Command

[[ Jump to previous class or function (normal, visual, operator modes)

]] Jump to next class or function (normal, visual, operator modes)

[M Jump to previous class or method (normal, visual, operator modes)

]M Jump to next class or method (normal, visual, operator modes)

aC Select a class. Ex: vaC, daC, yaC, caC (operator modes)

iC Select inner class. Ex: viC, diC, yiC, ciC (operator modes)

aM Select a function or method. Ex: vaM, daM, yaM, caM (operator modes)

iM Select inner function or method. Ex: viM, diM, yiM, ciM (operator modes)

V Select logical line. Ex: dV, yV, cV (operator modes), also works with count

Enable pymode-motion *'g:pymode_motion'*

*pymode-documentation*

Pymode could show documentation for current word by `pydoc`.

Commands:

*:PymodeDoc* <args> — show documentation

Turns on the documentation script *'g:pymode_doc'*

Bind keys to show documentation for current word (selection)

*'g:pymode_doc_bind'*

*pymode-virtualenv*

Commands:

*:PymodeVirtualenv* <path> -- Activate virtualenv (path can be absolute or

relative to current working directory)

Enable automatic virtualenv detection *'g:pymode_virtualenv'*

Set path to virtualenv manually *'g:pymode_virtualenv_path'*

*pymode-run*

Commands:

*:PymodeRun* -- Run current buffer or selection

Turn on the run code script *'g:pymode_run'*

Binds keys to run python code *'g:pymode_run_bind'*

*pymode-breakpoints*

Pymode automatically detects available debugger (like pdb, ipdb, pudb) and user

can set/unset breakpoint with one key and without code checking and etc.

Enable functionality *'g:pymode_breakpoint'*

Bind keys

Manually set breakpoint command (leave empty for automatic detection)

*pymode-lint*

Pymode supports `pylint`, `pep257`, `pycodestyle`, `pyflakes`, `mccabe` code

checkers. You could run several similar checkers.

Pymode uses Pylama library for code checking. Many options like skip

files, errors and etc could be defined in `pylama.ini` file or modelines.

Check Pylama documentation for details.

Pylint options (ex. disable messages) may be defined in `$HOME/pylint.rc`

See pylint documentation.

Commands:

*:PymodeLint* -- Check code in current buffer

*:PymodeLintToggle* -- Toggle code checking

*:PymodeLintAuto* -- Fix PEP8 errors in current buffer automatically

Turn on code checking *'g:pymode_lint'*

Check code on every save (if file has been modified) *'g:pymode_lint_on_write'*

Check code on every save (every) *'g:pymode_lint_unmodified'*

Check code when editing (on the fly) *'g:pymode_lint_on_fly'*

Show error message if cursor placed at the error line *'g:pymode_lint_message'*

Default code checkers (you could set several) *'g:pymode_lint_checkers'*

Values may be chosen from: `pylint`, `pycodestyle`, `mccabe`, `pep257`, `pyflakes`.

Skip errors and warnings *'g:pymode_lint_ignore'*

E.g. ["W", "E2"] (Skip all Warnings and the Errors starting with E2) etc.

Select some error or warnings. *'g:pymode_lint_select'*

By example you disable all warnings starting from 'W', but want to see warning

'W0011' and warning 'W430'

Sort errors by relevance *'g:pymode_lint_sort'*

If not empty, errors will be sort by defined relevance

E.g. let g:pymode_lint_sort = ['E', 'C', 'I'] " Errors first 'E',

after them 'C' and ...

Auto open cwindow (quickfix) if any errors have been found

*'g:pymode_lint_cwindow'*

Place error |signs| *'g:pymode_signs'*

Definitions for |signs|

*pymode-lint-options*

Pymode has the ability to set code checkers options from pymode variables:

Set PEP8 options *'g:pymode_lint_options_pycodestyle'*

See https://pep8.readthedocs.org/en/1.4.6/intro.html#configuration for more

info.

Set Pyflakes options *'g:pymode_lint_options_pyflakes'*

Set mccabe options *'g:pymode_lint_options_mccabe'*

Set pep257 options *'g:pymode_lint_options_pep257'*

Set pylint options *'g:pymode_lint_options_pylint'*

See http://docs.pylint.org/features.html#options for more info.

*pymode-rope*

Pymode supports Rope refactoring operations, code completion and code assists.

Commands:

|:PymodeRopeAutoImport| -- Resolve import for element under cursor

|:PymodeRopeModuleToPackage| -- Convert current module to package

|:PymodeRopeNewProject| -- Open new Rope project in current working directory

|:PymodeRopeRedo| -- Redo changes from last refactoring

|:PymodeRopeRegenerate| -- Regenerate the project cache

|:PymodeRopeRenameModule| -- Rename current module

|:PymodeRopeUndo| -- Undo changes from last refactoring

Turn on the rope script *'g:pymode_rope'*

Set the prefix for rope commands *'g:pymode_rope_prefix'*

*.ropeproject*

*:PymodeRopeNewProject* [<path>] -- Open new Rope project in the given path

*:PymodeRopeRegenerate* -- Regenerate the project cache

Rope uses a folder inside projects for holding project configuration and data.

Its default name is `.ropeproject`. It is recommended that you do not add the

.ropeproject folder to version control system.

Currently it is used for things such as:

* The config.py file in this folder contains project configuration. Have

a look at the default config.py file (which is created when it

does not exist) for more information.

* It can be used for saving project history, so that the next time you open the

project you can undo past changes.

* It can be used to save information about object inferences.

* It can be used to save a global name cache, which is used for auto-import.

By default, if `.ropeproject` is not found in the current directory, rope will

look recursively for it in parent folders.

Warning: If rope finds `.ropeproject` in a parent dir, it will use it with

all its child directories, which may slow scanning down (because of many,

possibly unrelated, files)

Enable searching for |.ropeproject| in parent directories

*'g:pymode_rope_lookup_project'*

You can also manually set the rope project directory. If not specified rope will

use the current directory.

*'g:pymode_rope_project_root'*

The location of the `.ropeproject` folder may also be overridden if you wish to

keep it outside of your project root. The rope library treats this folder as a

project resource, so the path will always be relative to your project root (a

leading '/' will be ignored). You may use `'..'` path segments to place the

folder outside of your project root.

*'g:pymode_rope_ropefolder'*

Show documentation for object under cursor. *'g:pymode_rope_show_doc_bind'*

Leave empty to disable the key binding.

Regenerate project cache on every save (if file has been modified)

*pymode-completion*

By default you can use <Ctrl-Space> for autocompletion. The first entry will

be automatically selected and you can press <Return> to insert the entry in

your code. <C-X><C-O> and <C-P>/<C-N> works too.

Autocompletion is also called by typing a period in |Insert| mode by default.

If there's only one complete item, vim may be inserting it automatically

instead of using a popup menu. If the complete item which inserted is not

your wanted, you can roll it back use '<c-w>' in |Insert| mode or setup

'completeopt' with `menuone` and `noinsert` in your vimrc. .e.g.

Turn on code completion support in the plugin *'g:pymode_rope_completion'*

Turn on autocompletion when typing a period

*'g:pymode_rope_complete_on_dot'*

Keymap for autocomplete *'g:pymode_rope_completion_bind'*

Extended autocompletion (rope could complete objects which have not been

imported) from project *'g:pymode_rope_autoimport'*

Load modules to autoimport by default *'g:pymode_rope_autoimport_modules'*

Offer to unresolved import object after completion.

*pymode-rope-findit*

By default when you press *<C-C>g* on any object in your code you will be moved

to definition.

Leave empty for disable key binding. *'g:pymode_rope_goto_definition_bind'*

Command for open window when definition has been found

Values are (`e`, `new`, `vnew`) *'g:pymode_rope_goto_definition_cmd'*

*pymode-rope-refactoring*

Pymode can rename everything: classes, functions, modules, packages, methods,

variables and keyword arguments.

Keymap for rename method/function/class/variables under cursor

*'g:pymode_rope_rename_bind'*

*:PymodeRopeRenameModule* -- Rename current module

Keymap for rename current module *'g:pymode_rope_rename_module_bind'*

*:PymodeRopeAutoImport* -- Resolve import for element under cursor

Organize imports sorts imports, too. It does that according to PEP8. Unused

imports will be dropped.

Keymap *'g:pymode_rope_organize_imports_bind'*

Insert import for current word under cursor *'g:pymode_rope_autoimport_bind'*

Should be enabled |'g:pymode_rope_autoimport'|

*'g:pymode_rope_module_to_package_bind'*

*:PymodeRopeModuleToPackage* -- convert current module to package

Keybinding:

*pymode-rope-extract*

Extract method/variable from selected lines.

*'g:pymode_rope_extract_method_bind'*

*'g:pymode_rope_extract_variable_bind'*

*pymode-rope-use*

It tries to find the places in which a function can be used and changes the

code to call it instead.

*pymode-rope-move*

Moving method/fields

It happens when you perform move refactoring on a method of a class. In this

refactoring, a method of a class is moved to the class of one of its

attributes. The old method will call the new method. If you want to change all

of the occurrences of the old method to use the new method you can inline it

afterwards.

Moving global variable/class/function into another module

It happens when you perform move refactoring on global variable/class/function.

In this refactoring, the object being refactored will be moved to a destination

module. All references to the object being moved will be updated to point to

the new location.

Moving module variable/class/function into a package

It happens when you perform move refactoring on a name referencing a module.

In this refactoring, the module being refactored will be moved to a destination

package. All references to the object being moved will be updated to point to

the new location.

*pymode-rope-undo*

*pymode-rope-redo*

Commands:

*:PymodeRopeUndo* -- Undo last changes in the project

*:PymodeRopeRedo* -- Redo last changes in the project

*pymode-syntax*

Turn on pymode syntax *'g:pymode_syntax'*

Slower syntax synchronization that is better at handling code blocks in

docstrings. Consider disabling this on slower hardware.

*'g:pymode_syntax_slow_sync'*

Enable all python highlights *'g:pymode_syntax_all'*

Highlight "print" as a function *'g:pymode_syntax_print_as_function'*

Highlight "async/await" keywords *'g:pymode_syntax_highlight_async_await'*

Highlight '=' operator *'g:pymode_syntax_highlight_equal_operator'*

Highlight ':=' operator *'g:pymode_syntax_highlight_walrus_operator'*

Highlight '*' operator *'g:pymode_syntax_highlight_stars_operator'*

Highlight 'self' keyword *'g:pymode_syntax_highlight_self'*

Highlight indent's errors *'g:pymode_syntax_indent_errors'*

Highlight space's errors *'g:pymode_syntax_space_errors'*

Highlight string formatting *'g:pymode_syntax_string_formatting'*

*'g:pymode_syntax_string_format'*

*'g:pymode_syntax_string_templates'*

*'g:pymode_syntax_doctests'*

Highlight builtin objects (True, False, ...) *'g:pymode_syntax_builtin_objs'*

Highlight builtin types (str, list, ...) *'g:pymode_syntax_builtin_types'*

Highlight exceptions (TypeError, ValueError, ...)

*'g:pymode_syntax_highlight_exceptions'*

Highlight docstrings as pythonDocstring (otherwise as pythonString)

*'g:pymode_syntax_docstrings'*

*pymode-faq*

1. Python-mode doesn't work

First remember to get the latest and updated version of the project source

code and also update the project submodules.

Clear all python cache/compiled files (`*.pyc` files and `__pycache__`

directory and everything under it). In Linux/Unix/MacOS you can run:

`find . -type f -name '*.pyc' -delete && find . -type d -name '__pycache__' -delete`

Then start python mode with:

`vim -i NONE -u <path_to_pymode>/debugvimrc.vim`

Reproduce the error and submit your python mode debug file. You can check its

location with `:messages` for something like:

`pymode debug msg 1: Starting debug on: 2017-11-18 16:44:13 with file /tmp/pymode_debug_file.txt`

Please submit the entire content of the file along with a reasoning of why the

plugin seems broken.

2. Rope completion is very slow *pymode-rope-slow*

Rope creates a project-level service directory in |.ropeproject|

If ``.ropeproject`` is not found in the current directory, rope will walk

upwards looking for a ``.ropeproject`` in every dir of the parent path. If

rope finds ``.ropeproject`` in a parent dir, it sets the project for all child

dirs and the scan may be slow for so many dirs and files.

Solutions:

- Delete `.ropeproject` from the parent dir to make rope create `.ropeproject`

in the current dir.

- Run ``:PymodeRopeNewProject`` to make rope create ``.ropeproject`` in the

current dir.

- Set |'g:pymode_rope_lookup_project'| to 0 for prevent searching in parent

dirs.

You may also set |'g:pymode_rope_project_root'| to manually specify the project

root path.

3. Pylint check is very slow

In some projects pylint may check slowly, because it also scans imported

modules if possible. Try using another code checker: see

|'g:pymode_lint_checkers'|.

You may set |exrc| and |secure| in your |vimrc| to auto-set custom settings

from `.vimrc` from your projects directories.

4. OSX cannot import urandom

See: https://groups.google.com/forum/?fromgroups=#!topic/vim_dev/2NXKF6kDONo

The sequence of commands that fixed this:

5. Folding is slow

Python mode adds folding for definitions and multi line docstrings. These may

be costly to compute on large files. To disable them one simple has to to add:

let g:pymode_folding = 1

to their vimrc file.

Beware that when editing python files in multiple windows vim computes the

folding for every typed character. Thus it may be useful to define:

augroup unset_folding_in_insert_mode

autocmd!

autocmd InsertEnter *.py setlocal foldmethod=marker

autocmd InsertLeave *.py setlocal foldmethod=expr

augroup END

*pymode-development*

This section briefly defines development guidelines for python-mode.

1. This help file uses vim's conventions defined at |help-writing|.

2. The name of the plugin shall be referred to as 'python-mode' throughout

documentation (except as a first word in a sentence in which case is

'Python-mode').

3. All defined functions should use vim's conventions and start with 'Pymode'.

4. Special marks for project development are `XXX` and `TODO`. They provide a

easy way for developers to check pending issues.

5. If submitting a pull request then a test should be added which smartly

covers the found bug/new feature. Tests are written using the Vader test

framework. Check out the existing test files in `tests/vader/` (1) for examples.

A suggested structure is the following: add your test to `tests/vader/` (2)

as a `.vader` file. You can make use of the existing sample files at

`tests/test_python_sample_code` (3). Vader tests use Vimscript syntax and

can directly test python-mode functionality. See `tests/vader/setup.vim` (4)

for test setup utilities. The test runner is at `scripts/user/run_tests.sh` (5).

6. Testing Environment: The project uses Docker for consistent testing across

different Python versions. See `README-Docker.md` for detailed information about

the Docker testing environment.

7. CI/CD: The project uses GitHub Actions for continuous integration, building

Docker images for each supported Python version and running tests automatically.

8. Supported Python Versions: The project currently supports Python 3.10.13,

3.11.9, 3.12.4, and 3.13.0. All tests are run against these versions in the

CI environment.

9. Docker Testing: To run tests locally with Docker:

- Use `./scripts/user/run-tests-docker.sh` to run tests with the default Python version

- Use `./scripts/user/run-tests-docker.sh 3.11` to test with Python 3.11.9

- Use `./scripts/user/test-all-python-versions.sh` to test with all supported versions

*pymode-credits*

Kirill Klenov

http://klen.github.com/

http://github.com/klen/

Rope

Copyright (C) 2006-2010 Ali Gholami Rudi

Copyright (C) 2009-2010 Anton Gritsay

Pylint

Copyright (C) 2003-2011 LOGILAB S.A. (Paris, FRANCE).

http://www.logilab.fr/

Pyflakes:

Copyright (c) 2005-2011 Divmod, Inc.

Copyright (c) 2013-2014 Florent Xicluna

https://github.com/PyCQA/pyflakes

PEP8:

Copyright (c) 2006 Johann C. Rocholl <johann@rocholl.net>

http://github.com/jcrocholl/pep8

autopep8:

Copyright (c) 2012 hhatto <hhatto.jp@gmail.com>

https://github.com/hhatto/autopep8

Python syntax for vim:

Copyright (c) 2010 Dmitry Vasiliev

http://www.hlabs.spb.ru/vim/python.vim

PEP8 VIM indentation

Copyright (c) 2012 Hynek Schlawack <hs@ox.cx>

http://github.com/hynek/vim-python-pep8-indent

*pymode-license*

Python-mode is released under the GNU lesser general public license.

See: http://www.gnu.org/copyleft/lesser.html

If you like this plugin, I would very appreciated if you kindly send me a

postcard :)

My address is: "Russia, 143500, MO, Istra, pos. Severny 8-3" to "Kirill

Klenov". Thanks for your support!

vim:tw=79:ts=8:ft=help:norl: