vim mode that uses rope library to provide features like python refactorings and code-assists
Note: Please note that this project has been moved to
GitHub python-rope / ropevim_
.. _
GitHub python-rope / ropevim: https://github.com/python-rope/ropevim
======================
Ropevim is a vim mode that uses rope_ library to provide features like python refactorings and code-assists. You should install rope_ library before using ropevim.
.. _rope: https://github.com/python-rope/rope
extended completefeature (disabled by default)
A simple way to download and install, which does not rely on any vim package managers, is:
.. code:: bash
$ sudo pip3 install rope ropemode ropevim $ wget -P ~/.vim/ https://raw.githubusercontent.com/python-rope/ropevim/master/ftplugin/pythonropevim.vim $ echo "source ~/.vim/pythonropevim.vim" >> ~/.vimrc
(rope, ropemode and ropevim are pure python libraries which do not need to talk to vim directly, they are installed by pip into the usual Python path. Only python_ropevim.vim needs to be seen by vim, and it handles loading the pure python modules.)
If using pathogen.vim, and then simply copy and paste:
.. code:: bash
$ cd ~/.vim/bundle $ git clone https://github.com/python-rope/ropevim.git
(or even add this repo as a submodule to
~/.vim/bundlegit repo if you have setup
~/.vim/bundlein this way and you should)
Once help tags have been generated, you can view the manual with
:help ropevim.
For using the repository version of rope, see
docs/ropevim.rst(or vim command
:help ropevim)
Ropevim refactorings use a special kind of dialog. Depending on the refactoring, you'll be asked about the essential information a refactoring needs to know (like the new name in rename refactoring).
Next you'll see the base prompt of a refactoring dialog that shows something like "Choose what to do". By entering the name of a refactoring option you can set its value. After setting each option you'll be returned back to the base prompt. Finally, you can ask rope to perform, preview or cancel the refactoring.
See keybinding_ section and try the refactorings yourself.
By using
RopeFindFile(
C-x p fby default), you can search for files in your project. When you complete the minibuffer you'll see all files in the project; files are shown as their reversed paths. For instance
projectroot/docs/todo.txtis shown like
todo.txt. This way you can find files faster in your project.RopeFindFileOtherWindow(C-x p 4 f) opens the file in the other window.Code-Assist
RopeCodeAssistcommand (M-/) will let you select from a list of completions.RopeLuckyAssistcommand (M-?) does not ask anything; instead, it inserts the first proposal.You can tell ropevim to use vim's complete function in insert mode; Add::
let ropevimvimcompletion=1
to your
~/.vimrcfile.Note that when this variable is set, autoimport completions no longer work since they need to insert an import to the top of the module, too.
By default autocomplete feature will use plain list of proposed completion items. You can enable showing extended information about completion proposals by setting ::
let ropevimextendedcomplete=1
Completion menu list will show the proposed name itself, one letter which shows where this proposal came from (it can be "L" for locals, "G" for globals, "B" for builtins, or empty string if such scope definition is not applicable), a short object type description (such as "func", "param", "meth" and so forth) and a first line of proposed object's docstring (if it has one). For function's keyword parameters the last field shows "*" symbol if this param is required or "= " if it is not.
Note that you'll need rope r1558:0d76aa9d0614 or later and ropemode r35:bd77ca42b04d or later for extended complete feature to work.
Enabling Autoimport
Rope can propose and automatically import global names in other modules. Rope maintains a cache of global names for each project. It updates the cache only when modules are changed; if you want to cache all your modules at once, use
RopeGenerateAutoimportCache. It will cache all of the modules inside the project plus those whose names are listed inropevim_autoimport_moduleslist::# add the name of modules you want to autoimport let g:ropevimautoimportmodules = ["os", "shutil"]
Now if you are in a buffer that contains::
rmtree
and you execute
RopeAutoImportyou'll end up with::from shutil import rmtree rmtree
Also
RopeCodeAssistandRopeLuckyAssistpropose auto-imported names by usingname : modulestyle. Selecting them will import the module automatically.Filtering Resources
Some refactorings, restructuring and find occurrences take an option called resources. This option can be used to limit the resources on which a refactoring should be applied.
It uses a simple format: each line starts with either '+' or '-'. Each '+' means include the file (or its children if it's a folder) that comes after it. '-' has the same meaning for exclusion. So using::
+rope +ropetest -rope/contrib
means include all python files inside
ropeandropetestfolders and their subfolder, but those that are inrope/contrib. Or::-ropetest -setup.py
means include all python files inside the project but
setup.pyand those underropetestfolder.Finding Occurrences
The find occurrences command (
C-c fby default) can be used to find the occurrences of a python name. Ifunsureoption isyes, it will also show unsure occurrences; unsure occurrences are indicated with a?mark in the end. Note that ropevim uses the quickfix feature of vim for marking occurrence locations.Dialog
batchsetCommandWhen you use ropevim dialogs there is a command called
batchset. It can set many options at the same time. After selecting this command from dialog base prompt, you are asked to enter a string.batchsetstrings can set the value of configs in two ways. The single line form is like this::name1 value1 name2 value2
That is the name of config is followed its value. For multi-line values you can use::
name1 line1 line2
name2 line3
Each line of the definition should start with a space or a tab. Note that blank lines before the name of config definitions are ignored.
batchsetcommand is useful when performing refactorings with long configs, like restructurings::pattern ${pycore}.create_module(${project}.root, ${name})
goal generate.create_module(${project}, ${name})
imports from rope.contrib import generate
args pycore: type=rope.base.pycore.PyCore project: type=rope.base.project.Project
.. ignore the two-space indents
This is a valid
batchsetstring for restructurings.Just for the sake of completeness, the reverse of the above restructuring can be::
pattern ${create_module}(${project}, ${name})
goal ${project}.pycore.create_module(${project}.root, ${name})
args createmodule: name=rope.contrib.generate.createmodule project: type=rope.base.project.Project
Variables
ropevim_codeassist_maxfixes: The maximum number of syntax errors to fix for code assists. The default value is
1.
ropevim_local_prefix: The prefix for ropevim refactorings. Defaults to
C-c r.
ropevim_global_prefix: The prefix for ropevim project commands Defaults to
C-x p.
ropevim_enable_shortcuts: Shows whether to bind ropevim shortcuts keys. Defaults to
1.
ropevim_guess_project: If non-zero, ropevim tries to guess and open the project that contains the file on which a ropevim command is performed when no project is already open.
ropevim_enable_autoimport: Shows whether to enable autoimport.
ropevim_autoimport_modules: The name of modules whose global names should be cached.
RopeGenerateAutoimportCachereads this list and fills its cache.
ropevim_autoimport_underlineds: If set, autoimport will cache names starting with underlines, too.
ropevim_goto_def_newwin: If set, ropevim will open a new buffer for "go to definition" result if the definition found is located in another file. By default the file is open in the same buffer.
g:ropevim_open_files_in_tabs: If non-zero, ropevim will open files in tabs. This is disabled by default, and it is now deprecated in favor of
g:ropevim_goto_def_newwinset to
"tabnew".
Uses almost the same keybinding as ropemacs. Note that global commands have a
C-x pprefix and local commands have a
C-c rprefix. You can change that (see variables_ section).
+-----------------+-------------------------------------------------------+ |Key | Command | +=================+=======================================================+ |C-x p o | RopeOpenProject | +-----------------+-------------------------------------------------------+ |C-x p k | RopeCloseProject | +-----------------+-------------------------------------------------------+ |C-x p f | RopeFindFile | +-----------------+-------------------------------------------------------+ |C-x p 4 f | RopeFindFileOtherWindow | +-----------------+-------------------------------------------------------+ |C-x p u | RopeUndo | +-----------------+-------------------------------------------------------+ |C-x p r | RopeRedo | +-----------------+-------------------------------------------------------+ |C-x p c | RopeProjectConfig | +-----------------+-------------------------------------------------------+ |C-x p n [mpfd] | RopeCreate(Module|Package|File|Directory) | +-----------------+-------------------------------------------------------+ | | RopeWriteProject | +-----------------+-------------------------------------------------------+ | | | +-----------------+-------------------------------------------------------+ |C-c r r | RopeRename | +-----------------+-------------------------------------------------------+ |C-c r l | RopeExtractVariable | +-----------------+-------------------------------------------------------+ |C-c r m | RopeExtractMethod | +-----------------+-------------------------------------------------------+ |C-c r i | RopeInline | +-----------------+-------------------------------------------------------+ |C-c r v | RopeMove | +-----------------+-------------------------------------------------------+ |C-c r x | RopeRestructure | +-----------------+-------------------------------------------------------+ |C-c r u | RopeUseFunction | +-----------------+-------------------------------------------------------+ |C-c r f | RopeIntroduceFactory | +-----------------+-------------------------------------------------------+ |C-c r s | RopeChangeSignature | +-----------------+-------------------------------------------------------+ |C-c r 1 r | RopeRenameCurrentModule | +-----------------+-------------------------------------------------------+ |C-c r 1 v | RopeMoveCurrentModule | +-----------------+-------------------------------------------------------+ |C-c r 1 p | RopeModuleToPackage | +-----------------+-------------------------------------------------------+ | | | +-----------------+-------------------------------------------------------+ |C-c r o | RopeOrganizeImports | +-----------------+-------------------------------------------------------+ |C-c r n [vfcmp] | RopeGenerate(Variable|Function|Class|Module|Package) | +-----------------+-------------------------------------------------------+ | | | +-----------------+-------------------------------------------------------+ |C-c r a / | RopeCodeAssist | +-----------------+-------------------------------------------------------+ |C-c r a g | RopeGotoDefinition | +-----------------+-------------------------------------------------------+ |C-c r a d | RopeShowDoc | +-----------------+-------------------------------------------------------+ |C-c r a f | RopeFindOccurrences | +-----------------+-------------------------------------------------------+ |C-c r a ? | RopeLuckyAssist | +-----------------+-------------------------------------------------------+ |C-c r a j | RopeJumpToGlobal | +-----------------+-------------------------------------------------------+ |C-c r a c | RopeShowCalltip | +-----------------+-------------------------------------------------------+ | | RopeAnalyzeModule | +-----------------+-------------------------------------------------------+ | | RopeAutoImport | +-----------------+-------------------------------------------------------+ | | RopeGenerateAutoimportCache | +-----------------+-------------------------------------------------------+
Some commands are used very frequently; specially the commands in
code-assist group. You can define your own shortcuts like this::
:noremap g :call RopeGotoDefinition()
Ropevim itself comes with a few shortcuts. These shortcuts will be
used only when
ropevim_enable_shortcutsis set.
================ ============================ Key Command ================ ============================ M-/ RopeCodeAssist M-? RopeLuckyAssist C-c g RopeGotoDefinition C-c d RopeShowDoc C-c f RopeFindOccurrences ================ ============================
You can enable using Rope as providing for Omni completion by setting omnifunc variable to
RopeCompleteFunc. E.g., by putting something like this in your
~/.vimrc::
autocmd FileType python setlocal omnifunc=RopeCompleteFunc
Send your bug reports, feature requests and patches to
rope-dev (at) googlegroups.com_.
.. _
rope-dev (at) googlegroups.com: http://groups.google.com/group/rope-dev
This program is under the terms of GPL (GNU General Public License). Have a look at
COPYINGfile for more information.