*pymode.txt*  *python-mode.txt*  *pymode* *python-mode*

     ____  _  _  ____  _   _  _____  _  _     __  __  _____  ____  ____      ~
    (  _ \( \/ )(_  _)( )_( )(  _  )( \( )___(  \/  )(  _  )(  _ \( ___)     ~
     )___/ \  /   )(   ) _ (  )(_)(  )  ((___))    (  )(_)(  )(_) ))__)      ~
    (__)   (__)  (__) (_) (_)(_____)(_)\_)   (_/\/\_)(_____)(____/(____)     ~


                          Version: 0.7.5b

==============================================================================
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|
    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.Credits...................................................|pymode-credits|
    8.License...................................................|pymode-license|

==============================================================================
1. Intro ~
                                                                  *pymode-intro*

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 containts all you need to develop python applications in Vim.

Features:                                                      *pymode-features*

- Support Python version 2.6+ and 3.2+
- 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 ...


==============================================================================
2. Common functionality ~
                                                                 *pymode-common*

This script provides the following options that can customise the behaviour of
PythonMode. These options should be set in your |vimrc|.

        Bellow shows the default values.


Turn on the whole plugin                                            *'g:pymode'*
>
    let g:pymode = 1

Trun off plugin's warnings                                 *'g:pymode_warnings'*
>
    let g:pymode_warnings = 1

Add paths to `sys.path`                                         *'g:pymode_paths'*
Value is list of path's strings. 
>
    let g:pymode_paths = []

Trim unused whitespaces on save                    *'g:pymode_trim_whitespaces'*
>
    let g:pymode_trim_whitespaces = 1

Setup default python options                                *'g:pymode_options'*
>
    let g:pymode_options = 1

If this option is set to 1, pymode will enable the following options for
python buffers: >

    setlocal complete+=t
    setlocal formatoptions-=t
    if v:version > 702 && !&relativenumber
        setlocal number
    endif
    setlocal nowrap
    setlocal textwidth=79
    setlocal commentstring=#%s
    setlocal define=^\s*\\(def\\\\|class\\)

Setup pymode |quickfix| window

                    *'g:pymode_quickfix_maxheght'* *'g:pymode_quickfix_minheight'*
>
    let g:pymode_quickfix_minheight = 3
    let g:pymode_quickfix_maxheight = 6

------------------------------------------------------------------------------
2.1. Python version ~
                                                         *pymode-python-version*

By default pymode looks for current python version supported in your Vim. 
You could choose prefer version, but value will be testsed on loading.

                                                             *'g:pymode_python'* 
>
    let g:pymode_python = 'python'

Values are `python`, `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
|exrc|

------------------------------------------------------------------------------
2.2 Python indentation ~
                                                                 *pymode-indent*

Pymode support PEP8-compatible python indent.
Enable pymode indentatation                                  *'g:pymode_indent'*
>
    let g:pymode_indent = []

------------------------------------------------------------------------------
2.3 Python folding ~
                                                                *pymode-folding*

Fast and usual python folding in Vim.
Enable pymode folding                                       *'g:pymode_folding'*
>
    let g:pymode_folding = 1

------------------------------------------------------------------------------
2.4 Vim motion ~
                                                                *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 (normal, operator modes)
iC                Select inner class. Ex: viC, diC, yiC, ciC (normal, operator modes)
aM                Select a function or method. Ex: vaM, daM, yaM, caM (normal, operator modes)
iM                Select inner function or method. Ex: viM, diM, yiM, ciM (normal, operator modes)
================  ============================

Enable pymode-motion                                         *'g:pymode_motion'*
>
    let g:pymode_motion = 1

------------------------------------------------------------------------------
2.5 Show documentation ~
                                                          *pymode-documentation*

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

Commands:
*:PymodeDoc* <args> — show documentation 

Turns on the documentation script                               *'g:pymode_doc'*
>
    let g:pymode_doc = 1

Bind keys to show documentation for current word (selection)
                                                           *'g:pymode_doc_bind'*
>
    let g:pymode_doc_bind = 'K'

------------------------------------------------------------------------------
2.6 Support virtualenv ~
                                                             *pymode-virtualenv*

Commands:
*:PymodeVirtualenv* <path> -- Activate virtualenv (path is related to
current working directory)

Enable automatic virtualenv detection                     *'g:pymode_virtualenv'*
>
    let g:pymode_virtualenv = 1

Set path to virtualenv by manually                  *'g:pymode_virtualenv_path'*
>
    let g:pymode_virtualenv_path = $VIRTUAL_ENV

------------------------------------------------------------------------------
2.7 Run code ~
                                                                    *pymode-run*

Commands:
*:PymodeRun* -- Run current buffer or selection

Turn on the run code script                                     *'g:pymode_run'*
>
    let g:pymode_run = 1

Binds keys to run python code                              *'g:pymode_run_bind'*
>
    let g:pymode_run_bind = '<leader>r'

------------------------------------------------------------------------------
2.8 Breakpoints ~
                                                            *pymode-breakpoints*

Pymode automatically detect available debugger (like pdb, ipdb, pudb) and user
could set/unset breakpoint with one key and without code checking and etc.

Enable functionality                                     *'g:pymode_breakpoint'*
>
    let g:pymode_breakpoint = 1

Bind keys
>
    let g:pymode_breakpoint_bind = '<leader>b'

Manually set breakpoint command (leave empty for automatic detection)
>
    let g:pymode_breakpoint_cmd = ''


==============================================================================
3. Code checking ~
                                                                   *pymode-lint*

Pymode supports `pylint`, `pep257`, `pep8`, `pyflakes`, `mccabe` code
checkers. You could run several checkers are simular.

        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'*
>
    let g:pymode_lint = 1

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

Check code on every save (every)                    *'g:pymode_lint_unmodified'*
>
    let g:pymode_lint_unmodified = 1

Check code when editting (onfly)                        *'g:pymode_lint_on_fly'*
>
    let g:pymode_lint_on_fly = 1

Show error message if cursor placed at the error line  *'g:pymode_lint_message'*
>
    let g:pymode_lint_message = 1

Default code checkers (you could set several)         *'g:pymode_lint_checkers'*
>
    let g:pymode_lint_checkers = ['pyflakes', 'pep8', 'mccabe']

Values may be choosen from: `pylint`, `pep8`, `mccabe`, `pep257`, `pyflakes`.

Skip errors and warnings                                *'g:pymode_lint_ignore'*
E.g. "E501,W002", "E2,W" (Skip all Warnings and Errors startswith E2) and etc
>
    let g:pymode_lint_ignore = "E501,W"

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'
>
    let g:pymode_lint_select = "E501,W0011,W430"

Sort errors by relevance                                  *'g:pymode_lint_sort'*
If not emply, errors will be sort by defined relevance
E.g. let g:pymode_lint_sort = ['E', 'C', 'I']  " Errors first 'E',
after them 'C' and ...
>
    let g:pymode_lint_sort = []

Auto open cwindow (quickfix) if any errors has been finded
                                                       *'g:pymode_lint_cwindow'*
>
    let g:pymode_lint_cwindow = 1

Place error |signs|                                             *'g:pymode_signs'*
>
    let g:pymode_lint_signs = 1

Definitions for |signs|
>
    let g:pymode_lint_todo_symbol = 'WW'
    let g:pymode_lint_comment_symbol = 'CC'
    let g:pymode_lint_visual_symbol = 'RR'
    let g:pymode_lint_error_symbol = 'EE'
    let g:pymode_lint_info_symbol = 'II'
    let g:pymode_lint_pyflakes_symbol = 'FF'


==============================================================================
3. Rope support ~
                                                                   *pymode-rope*

Pymode support 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'*
>
    let g:pymode_rope = 1

.roperoject Folder ~
                                                                  *.ropeproject*

*:PymodeRopeNewProject* -- Open new Rope project in current working directory
*:PymodeRopeRegenerate* -- Regenerate the project cache

Rope uses a folder inside projects for holding project configuration and data.
Its default name is `.ropeproject`.

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.

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'*
>
    let g:pymode_rope_lookup_project = 1


Show documentation for element under cursor ~

Show documentation for object under cursor.      *'g:pymode_rope_show_doc_bind'*
Leave empty to disable the key binding.
>
    let g:pymode_rope_show_doc_bind = '<C-c>d'

Regenerate project cache on every save (if file has been modified)
>
    let g:pymode_rope_regenerate_on_write = 1

------------------------------------------------------------------------------
4.1 Completion ~
                                                             *pymode-completion*

By default you can use <Ctrl-Space> for autocompletion. Will be
automatically selected first entry and you can press <Return> to insert 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.


Turn on code completion support in the plugin       *'g:pymode_rope_completion'*
>
    let g:pymode_rope_completion = 1

Turn on autocompletion when typing a period
                                               *'g:pymode_rope_complete_on_dot'*
>
    let g:pymode_rope_complete_on_dot = 1

Keymap for autocomplete                        *'g:pymode_rope_completion_bind'*
>
    let g:pymode_rope_completion_bind = '<C-Space>'

Extended autocompletion (rope could complete objects which have not been
imported) from project                              *'g:pymode_rope_autoimport'*
>
    let g:pymode_rope_autoimport = 1

Load modules to autoimport by default       *'g:pymode_rope_autoimport_modules'*
>
    let g:pymode_rope_autoimport_modules = ['os', 'shutil', 'datetime'])

Offer to unresolved import object after completion.
>
    let g:pymode_rope_autoimport_import_after_complete = 0


------------------------------------------------------------------------------
4.2 Find definition ~
                                                            *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'*
>
    let g:pymode_rope_goto_definition_bind = '<C-c>g'

Command for open window when definition has been finded
Values are (`e`, `new`, `vnew`)                  *'g:pymode_rope_goto_definition_cmd'*
>
    let g:pymode_rope_goto_definition_cmd = 'new'

------------------------------------------------------------------------------
4.3 Refactoring ~
                                                       *pymode-rope-refactoring*

Rename method/function/class/variable in the project ~

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'*
>
    let g:pymode_rope_rename_bind = '<C-c>rr'


Rename a current module/package ~

*:PymodeRopeRenameModule* -- Rename current module

Keymap for rename current module            *'g:pymode_rope_rename_module_bind'*
>
    let g:pymode_rope_rename_bind = '<C-c>rr'


Imports ~

*: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'*
>
    let g:pymode_rope_organize_imports_bind = '<C-c>ro'

Insert import for current word under cursor    *'g:pymode_rope_autoimport_bind'*
Should be enabled |'g:pymode_rope_autoimport'|
>
    let g:pymode_rope_autoimport_bind = '<C-c>ra'


Convert module to package ~
                                        *'g:pymode_rope_module_to_package_bind'*

*:PymodeRopeModuleToPackage* -- convert current module to package

Keybinding:
>
    let g:pymode_rope_module_to_package_bind = '<C-c>r1p'


Extract method/variable ~
                                                           *pymode-rope-extract*

Extract method/variable from selected lines.

                                           *'g:pymode_rope_extract_method_bind'*
                                         *'g:pymode_rope_extract_variable_bind'*
>
    let g:pymode_rope_extract_method_bind = '<C-c>rm'
    let g:pymode_rope_extract_variable_bind = '<C-c>rl'


Use function ~
                                                               *pymode-rope-use*

It tries to find the places in which a function can be used and changes the
code to call it instead.
>
    let g:pymode_rope_use_function_bind = '<C-c>ru'


Move method/fields ~
                                                              *pymode-rope-move*

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.
>
    let g:pymode_rope_move_bind = '<C-c>rv'

Change function signature ~
>
    let g:pymode_rope_change_signature_bind = '<C-c>rs'


------------------------------------------------------------------------------
4.4 Undo/Redo changes ~
                                                              *pymode-rope-undo* 
                                                              *pymode-rope-redo*

Commands:

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


==============================================================================
5. Syntax ~
                                                                 *pymode-syntax*

Turn on pymode syntax                                        *'g:pymode_syntax'*
>
    let g:pymode_syntax = 1

More slow synchronizing. Disable on the slow machine, but code in docstrings
could be broken.                                   *'g:pymode_syntax_slow_sync'*
>
    let g:pymode_syntax_slow_sync = 1

Enable all python highlightings                          *'g:pymode_syntax_all'*
>
    let g:pymode_syntax_all = 1

Highlight "print" as a function            *'g:pymode_syntax_print_as_function'*
>
    let g:pymode_syntax_print_as_function = 0

Highlight '=' operator              *'g:pymode_syntax_highlight_equal_operator'*
>
    let g:pymode_syntax_highlight_equal_operator = g:pymode_syntax_all

Highlight '*' operator              *'g:pymode_syntax_highlight_stars_operator'*
>
    let g:pymode_syntax_highlight_stars_operator = g:pymode_syntax_all

Highlight 'self' keyword                      *'g:pymode_syntax_highlight_self'*
>
    let g:pymode_syntax_highlight_self = g:pymode_syntax_all

Highlight indent's errors                      *'g:pymode_syntax_indent_errors'*
>
    let g:pymode_syntax_indent_errors = g:pymode_syntax_all

Highlight space's errors                        *'g:pymode_syntax_space_errors'*
>
    let g:pymode_syntax_space_errors = g:pymode_syntax_all

Highlight string formatting                 *'g:pymode_syntax_string_formating'*
                                               *'g:pymode_syntax_string_format'*
                                            *'g:pymode_syntax_string_templates'*
                                                    *'g:pymode_syntax_doctests'*
>
    let g:pymode_syntax_string_formatting = g:pymode_syntax_all
    let g:pymode_syntax_string_format = g:pymode_syntax_all
    let g:pymode_syntax_string_templates = g:pymode_syntax_all
    let g:pymode_syntax_doctests = g:pymode_syntax_all

Highlight builtin objects (True, False, ...)    *'g:pymode_syntax_builtin_objs'*
>
    let g:pymode_syntax_builtin_objs = g:pymode_syntax_all

Highlight builtin types (str, list, ...)       *'g:pymode_syntax_builtin_types'*
>
    let g:pymode_syntax_builtin_types = g:pymode_syntax_all

Highlight exceptions (TypeError, ValueError, ...) 
                                        *'g:pymode_syntax_highlight_exceptions'*
>
    let g:pymode_syntax_highlight_exceptions = g:pymode_syntax_all

Highlight docstrings as pythonDocstring (otherwise as pythonString)
                                                  *'g:pymode_syntax_docstrings'*
>
    let g:pymode_syntax_docstrings = g:pymode_syntax_all


==============================================================================
6. FAQ ~
                                                                    *pymode-faq*

Python-mode doesn't work
------------------------

Open any python file and run ":call pymode#troubleshooting#Test()",
fix the warning or send me the output.


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.


Pylint check is very slow
-------------------------

In some projects pylint may check slowly, because it also scans imported
modules if possible. Try using another code checkiers: 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.


OSX cannot import urandom
-------------------------

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

The sequence of commands that fixed this:
>
    brew unlink python
    brew unlink macvim
    brew remove macvim
    brew install -v --force macvim
    brew link macvim
    brew link python
<

==============================================================================
7. Credits ~
                                                                *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 Divmod, Inc.
        http://www.divmod.com/

    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


==============================================================================
8. License ~
                                                                *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, you can send me a postcard :)

My address is: "Russia, 143401, Krasnogorsk, Shkolnaya 1-19" to "Kirill
Klenov". Thanks for your support!


------------------------------------------------------------------------------

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