https://github.com/python-rope/ropevim
vim mode that uses rope library to provide features like python refactorings and code-assists
https://github.com/python-rope/ropevim
Last synced: 12 months ago
JSON representation
vim mode that uses rope library to provide features like python refactorings and code-assists
- Host: GitHub
- URL: https://github.com/python-rope/ropevim
- Owner: python-rope
- License: gpl-2.0
- Created: 2013-12-01T21:56:11.000Z (about 12 years ago)
- Default Branch: master
- Last Pushed: 2022-12-14T11:50:28.000Z (about 3 years ago)
- Last Synced: 2025-02-09T16:21:52.164Z (about 1 year ago)
- Language: Python
- Size: 209 KB
- Stars: 250
- Watchers: 8
- Forks: 34
- Open Issues: 6
-
Metadata Files:
- Readme: README.rst
- Changelog: ChangeLog
- License: COPYING
Awesome Lists containing this project
README
======================
ropevim, rope in vim
======================
.. csv-table::
"❗If you are using ropevim, consider using `pylsp-rope`_ in Vim. Also see, `setup guide for pylsp-rope in Vim`_."
.. _pylsp-rope: https://github.com/python-rope/pylsp-rope
.. _setup guide for pylsp-rope in Vim: https://github.com/python-rope/rope/wiki/Rope-in-Vim-or-Neovim
Overview
========
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
New Features
============
* works only with python3 ATM (python2 is not supported anymore)
* improved support of multibyte sources
* implemented `extended complete` feature (disabled by default)
* ropemode is not part of the distribution now
Installation
============
Using Minpac
------------
.. code:: vim
filetype plugin on
call minpac#add('python-rope/ropevim')
.. code:: bash
$ pip install ropevim
If you're using **Neovim**, you will also need to
`install neovim python providers`_ using ``pip install pynvim``.
Using Packer
--------------
.. code:: lua
use({
'python-rope/ropevim',
ft = "python"
})
.. code:: bash
$ pip install ropevim
If you're using **Neovim**, you will also need to
`install neovim python providers`_ using ``pip install pynvim``.
Using Vim-Plug
--------------
.. code:: vim
filetype plugin on
Plug 'python-rope/ropevim'
.. code:: bash
$ pip install ropevim
If you're using **Neovim**, you will also need to
`install neovim python providers`_ using ``pip install pynvim``.
Using Vundle
------------
.. code:: vim
filetype plugin on
Plugin 'python-rope/ropevim'
.. code:: bash
$ pip install ropevim
If you're using **Neovim**, you will also need to
`install neovim python providers`_ using ``pip install pynvim``.
Basic Installation
------------------
A simple way to download and install, which does just uses native
packaging system (requires Vim 8):
.. code:: bash
$ mkdir -p ~/.vim/pack/plugins/start/
$ git clone https://github.com/python-rope/ropevim.git ~/.vim/pack/plugins/start/ropevim
$ pip install ropevim
Or on older Vim:
.. code:: bash
$ sudo pip3 install ropevim
$ wget -P ~/.vim/ https://raw.githubusercontent.com/python-rope/ropevim/master/ftplugin/python_ropevim.vim
$ echo "source ~/.vim/python_ropevim.vim" >> ~/.vimrc
$ pip install ropevim
(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 you're using **Neovim**, you will also need to
`install neovim python providers`_ using ``pip install pynvim``.
Installation with pathogen
--------------------------
If using pathogen.vim, and then simply copy and paste:
.. code:: bash
$ cd ~/.vim/bundle
$ git clone https://github.com/python-rope/ropevim.git
$ pip install ropevim
(or even add this repo as a submodule to ``~/.vim/bundle`` git repo if
you have setup ``~/.vim/bundle`` in this way and you should)
Once help tags have been generated, you can view the manual with ``:help
ropevim.``
If you're using **Neovim**, you will also need to
`install neovim python providers`_ using ``pip install pynvim``.
Installation of repo version
----------------------------
For using the repository version of rope, see ``docs/ropevim.rst`` (or
vim command ``:help ropevim``)
.. _install neovim python providers: https://neovim.io/doc/user/provider.html
Getting Started
===============
Refactoring Dialog
------------------
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.
Finding Files
-------------
By using ``RopeFindFile`` (``C-x p f`` by 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.txt`` is shown like
``todo.txt" 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 in ``ropevim_autoimport_modules`` list::
# add the name of modules you want to autoimport
let g:ropevim_autoimport_modules = ["os", "shutil"]
Now if you are in a buffer that contains::
rmtree
and you execute ``RopeAutoImport`` you'll end up with::
from shutil import rmtree
rmtree
Also ``RopeCodeAssist`` and ``RopeLuckyAssist`` propose auto-imported
names by using ``name : module`` style. 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 ``rope`` and ``ropetest``
folders and their subfolder, but those that are in ``rope/contrib``.
Or::
-ropetest
-setup.py
means include all python files inside the project but ``setup.py`` and
those under ``ropetest`` folder.
Finding Occurrences
-------------------
The find occurrences command (``C-c f`` by default) can be used to
find the occurrences of a python name. If ``unsure`` option is
``yes``, 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 ``batchset`` Command
---------------------------
When 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.
``batchset`` strings 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.
``batchset`` command 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 ``batchset`` string 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
create_module: name=rope.contrib.generate.create_module
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. `RopeGenerateAutoimportCache` reads 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_newwin`` set to ``"tabnew"``.
Keybinding
==========
Uses almost the same keybinding as ropemacs. Note that global
commands have a ``C-x p`` prefix and local commands have a ``C-c r``
prefix. 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 |
+-----------------+-------------------------------------------------------+
Shortcuts
---------
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_shortcuts`` is set.
================ ============================
Key Command
================ ============================
M-/ RopeCodeAssist
M-? RopeLuckyAssist
C-c g RopeGotoDefinition
C-c d RopeShowDoc
C-c f RopeFindOccurrences
================ ============================
Support for Omni completion
---------------------------
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
Contributing
============
Send your bug reports, feature requests and patches to `ropevim Github
Issue Tracker`_ or `rope Github Discussions`_.
.. _`ropevim Github Issue Tracker`: https://github.com/python-rope/ropevim/issues
.. _`rope Github Discussions`: https://github.com/python-rope/rope/discussions
License
=======
This program is under the terms of GPL (GNU General Public License).
Have a look at ``COPYING`` file for more information.