SublimeRope Documentation

Contents:

Getting started

Ready to get started? This page gives you a basic introduction to SublimeRope. If you’re looking for detailed information about auto completions go to Auto Completion page. For information about refectoring go to Refactoring page.

SublimeRope

SublimeRope adds Python completions and some IDE-like functions to Sublime Text 2, through the use of the Rope library.

SublimeRope has been tested on the latest dev build working well on OSX, Linux and Windows.

Basic Usage

Just unzip / git clone the folder SublimeRope into ST2’s Packages folder. Basic completion should work and all commands should be reachable through the Command Palette.

Using Package Control

The recommended way to install SublimeRope into ST2 is by using Package Control.

Available Commands

  • Completions, which hook into Sublime’s normal completion system (Ctrl+Space and as-you-type)
  • Go to Definition
  • Show Documentation
  • Refactor->Rename
  • Refactor->Extract Method
  • Refactor->Extract Variable
  • Refactor->Inline Variable
  • Refactor->Restructure
  • Jump to Global: Shows a list of project globals in a quickview and allows to jump to them.
  • Import assist: Looks for possible imports from the project starting with the prefix under the cursor. Will automatically insert the “from X import Z” statement.
  • Regenerate Global Module Cache
  • Regenerate Project Cache

Some notes

SublimeRope is a Free Software project developed and maintained by Julian Eberius and a few collaborators in their free time. To review a full list of SublimeRope developers just look at the project’s GitHub Page.

License

Sublime Rope is distributed under the Free Software Foundation General Public License terms:

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

Have a look at LICENSE.txt file for more information.

Note

This project uses code from other open source projects (Rope) which may include licenses of their own.

Auto Completion

ST2 offers three types of completions itself:

  • Word completions (complete from words present on the current buffer)
  • Explicit completions (those that you can define in syntax-specific files, such as Python.sublime.completions)
  • Autocompletions from plugins.

Note

Some people prefer to disable the default word and/or explicit completions that ST2 offers while using SublimeRope. This can be achieved by setting either of the following settings to true in the User Settings for SublimeRope settings in your ST2 Preferences Menú.

  • suppress_word_completions
  • suppress_explicit_completions

Case-Insensitive Completions

Some users prefer to get more completion proposals by ignoring case of what they type and what Rope has indexed. By setting case_sensitive_completion to false you can enable this behavior. For example, when typing “inde” SublimeRope will offer “IndexError”.

Manual Completions

On larger projects, generating the completion proposals can take a noticeable amount of time. Waiting half a second is no problem usually, but with ST2 automatic as-you-type completions it can slow down your typing. Just set the “complete_as_you_type” option in your SublimeRope.sublime_settings or in your project settings as “rope_complete_as_you_type” to false, and you will only get the lightning fast buffer-based completions from ST2. Then you can manually trigger the more intelligent Rope-based completions using the “PythonManualCompletionRequestCommand”. Bind it to some nice key, e.g. ctrl+alt+space, and you can get them easily when you need them.

Simple Completion

SublimeRope provides completion suggestions based on the rope library, but also offers a fall-back method if rope suggest nothing. Albeit it is sometimes useful, it is disabled by default because some users feels that it slows down the plugin too much.

You can enable it setting use_simple_completion to true in SublimeRope settings file.

How to get autocompletion on dot typing?

Some users want SublimeRope shown the completions just after typing the dot in for example os., ST2 gives us a simple way to setup this desirable behavior.

We should just edit the Python.sublime-settings file in Package/User (or create it in case that you don’t have one already). In this way, this behavior should be only applicable to our Python files and not in all the files we edit with ST2:

"auto_complete_triggers": [ {"selector": "source.python - string - comment - constant.numeroc", "characters": "."} ]

This line makes autocomplete not appear when we type dot inside strings or comments but fails with literal hexadecimal number (seems to be a bug in ST2 itself).

Some Considerations

The list of completions that you will get back when auto completion triggers is determined by the Cache Mechanisms in SublimeRope.

Cache Mechanisms in SublimeRope

Rope library uses binary cache files to offer auto completion, import assist, jump to global and documentation features. Exists different ways of generate and/or regenerate those cache files using SublimeRope.

The Project Cache

When you create a new Rope project, you should use the SublimeRope command Regenerate Project Cache to get the autocompletion, jumps, documentation and auto imports working for the modules under your project root.

This action can be archieved using the ST2 Command Palette.

Adding modules to Autoimport Modules List

This is the recommended way of get global modules auto imports and friends working.

You can also get autocompletion and friends working for modules not under your project root simply adding them to the list of autoimport_modules in your SublimeRope.sublime-settings file and then run the Regenerate Global Module Cache command from ST2 Command Palette or generating a key binding for it.

Note

Take care, there is also another command, Regenerate Project Cache, which rebuilds the cache just for your project not for global modules.

You can specify rope_autoimport_modules in your project settings instead of your global SublimeRope.sublime-settings file.

Note

note that although using the global configuration file works, using your project settings file is the recommended way

To archieve this you should navigate to Project->Edit Project and add your modules there in the settings section. If this section doesn’t exists just create it:

"settings":
{
    "rope_autoimport_modules":
    [
        "twisted.*",
        "numpy.*",
        "libsaas.*",
        ...
    ]
}

Warning

Non-trivial/nested modules like numpy or twisted will have to be added in the form twisted.* or Rope will not index them correctly.

The old way: editing Rope python path

Warning

This is NOT the recommended way of settings cache to get all auto completions working anymore.

Basically, anything you want completions for (or auto import, jump to globals, documentation) has to be in the Rope’s python path. You can extend the Rope’s python path editing the .ropeproject/config.py (If you don’t know what .ropeproject directory is you should look at create_project)

If you are using virtualenv for your project, add the path to the virtualenv in .ropeproject/config.py if you don’t set it at project creation (there should be a commented-out already line in the set_prefs configuration key in the file):

prefs.add('python_path', '/Users/<username>/Development/Twisted-12.0/')

Also, if you are not using the same Python as ST2 (e.g. using a custom Python os OSX or using the latest Ubuntu release), add your site-packages (dist-packages in some Linux distributions), so that ST2 picks them up:

prefs.add('python_path', '/usr/lib/python2.7/site-packages')

A special case are Django projects, which use global imports and not relative ones, e.g., in views.py they use “import Project.App.models” and not just “import models”. In this case, you project has to be on the Python path as well. Add the parent dir of your project:

prefs.add('python_path', '/Users/<username>/my_django_projects')

Auto Import

SublimeRope offers auto importing features through Rope library. It looks for possible imports from the project starting with the prefix under the cursor.

In order to use auto import you should look for Rope: Import Assist in the Control Palette or just add a shortcut in your configuration. We provide a serie of possible Key Bindings in this Documentation as well.

Auto Import Improvements

When Auto Import Improvements are enabled all the undefined words in the current file should be checked (in a different thread) looking for an auto import for them. If SublimeRope finds a possible autoimport for them should show you so you can choose it and the import will be automatically applied to your file.

You can disable Auto Import Improvements in your SublimeRope’s settings file just setting the use_autoimport_improvements to false if you feels that its slowing down your ST2.

Some Considerations

The list of modules that you will get when doing auto import is determined by the Cache Mechanisms in SublimeRope.

Jump to Global

To use the jump to global feature in SublimeRope just select the Rope: Jump to Global entry in the ST2’s Control Palette, a list of all the possible globals that you can jump on will be shown.

Some Considerations

The available global jumps positions that will be accesible are determined by the Cache Mechanisms in SublimeRope

Show Documentation

To use the show documentation feature in SublimeRope just write the name of the function you are going to use and select the Rope: Show Documentation from the ST2’s Control Palette. We suggest you use a key binding for this action.

Some Considerations

The available documentation that will be accesible are determined by the Cache Mechanisms in SublimeRope.

Refactoring

SublimeRope offers a few refactors through Rope library.

Renaming

Consider the following code:

class First(object):
    """First Class"""
    def __init__(self):
        self.id = 1

    def change_id(self, arg):
        self.id = id

    def print_id(self):
        print self.id

first = First()
first.change_id(123)
first.print_id()

We can just put the cursor over id in the __init__ method and rename it to new_id after that our code should looks like:

class First(object):
    """First Class"""
    def __init__(self):
        self.new_id = 1

    def change_id(self, arg):
        self.new_id = new_id

    def print_id(self):
        print self.new_id

first = First()
first.change_id(123)
first.print_id()

After renaming print_id method to identify_me all the references in our project should change to our new function name.

Note

ST2 already offer some interesting features to archieve the same results really fast

Extract Method

Let’s imagine we have the following code:

def some_func():
    a = 10
    b = 20
    c = ``a * 2 + b * 3``

After performing extract method of the highlighted operation above we should get:

def some_func():
    a = 10
    b = 20
    c = new_func(a, b)

def new_func(a, b):
    return a * 2 + b * 3

Extracting Decorated Methods

Extract method can handle static and class methods that use the decorators @staticmethod and @classmethod as for example in:

class First(object):

    @staticmethod
    def a_method(arg):
        aux = arg * 2

After extract a * 2 as a method called twice we should get:

class First(object):

    @staticmethod
    def a_method(arg):
        aux = First.twice(arg)

    @staticmethod
    def twice(arg):
        return arg * 2

Extract Variable

Imagine we have this expression:

x = 2 * 3

After extract a variable with name six we should have:

six = 2 * 3
x = six

Restructuring

A restructuring is a program transformation; not as well defined as other refactorings like rename. In its basic form, we have a pattern and a goal. Consider we were not aware of the ** operator and wrote our own:

def pow(x, y):
    result = 1
    for i in range(y);
        result *= x
    return result

print pow(2, 3)

When we realice that ** exists we want to use it wherever pow is used. We can use a pattern like:

pattern: pow(${param1} ** ${param2})

Goal can be something like:

goal: ${param1} ** ${param2}

The matched names in pattern should be replaced with the string that was matched in each occurrence. So the outcome of the restructuring should be:

def pow(x, y):
    result = 1
    for i in range(y):
        result *= x
    return result

print 2 ** 3

It seems to be working but what if pow is imported in some module or we have some other function defined in some other module that uses the same name and we don’t want to change it. Wildcard arguments come to rescue. Wildcard arguments is a mapping; Its keys are wildcard names that appear in the pattern (the names inside ${...}).

The values are the parameters that are passed to wildcard matchers. The arguments a wildcard takes is based on its type.

For checking the type of a wildcard, we can pass type=value as an argument; value should be resolved to a python variable (or reference). For instance for specifying pow in this example we can use mod.pow. As you see, this string should start from module name. For referencing python builtin types and functions you can use __builtin__ module (for instance __builtin__.int).

For solving the mentioned problem, we change our pattern. But goal remains the same:

pattern: ${pow_func} (${param1}, ${param2})
goal: ${param1} ** ${param2}

Consider the name of the module containing our pow function is mod. args can be:

pow_func: name=mod.pow

If we need to pass more arguments to a wildcard matcher we can use , to separate them. Such as name: type=mod.MyClass,exact.

This restructuring handles aliases; like in:

mypow = pow
result = mypow(2, 3)
Transforms into:

mypow = pow
result = 2 ** 3

If we want to ignore aliases we can pass exact as another wildcard argument:

pattern: ${pow}(${param1}, ${param2})
goal: ${param1} ** ${param2}
args: pow: name=mod.pow, exact

${name}, by default, matches every expression at that point; if exact argument is passed to a wildcard only the specified name will match (for instance, if exact is specified , ${name} matches name and x.name but not var nor (1 + 2) while a normal ${name} can match all of them).

Key Bindings

SublimeRope provides no default keybindings at the moment, so you need to set them yourself. We suggest this bindings as a template that you can modify at your convenience:

{ "keys": ["ctrl+r", "ctrl+d"], "command": "goto_python_definition", "context":
    [
        { "key": "selector", "operator": "equal", "operand": "source.python" }
    ]
},
{ "keys": ["ctrl+r", "ctrl+h"], "command": "python_get_documentation", "context":
    [
        { "key": "selector", "operator": "equal", "operand": "source.python" }
    ]
},
{ "keys": ["ctrl+r", "ctrl+r"], "command": "python_refactor_rename", "context":
    [
        { "key": "selector", "operator": "equal", "operand": "source.python" }
    ]
},
{ "keys": ["ctrl+r", "ctrl+e"], "command": "python_refactor_extract_method", "context":
    [
        { "key": "selector", "operator": "equal", "operand": "source.python" }
    ]
},
{ "keys": ["ctrl+r", "ctrl+v"], "command": "python_refactor_extract_variable", "context":
    [
        { "key": "selector", "operator": "equal", "operand": "source.python" }
    ]
},
{ "keys": ["ctrl+r", "ctrl+n"], "command": "python_refactor_inline_variable", "context":
    [
        { "key": "selector", "operator": "equal", "operand": "source.python" }
    ]
},
{ "keys": ["ctrl+r", "ctrl+j"], "command": "python_jump_to_global", "context":
    [
        { "key": "selector", "operator": "equal", "operand": "source.python" }
    ]
},
{ "keys": ["ctrl+r", "ctrl+i"], "command": "python_auto_import", "context":
    [
        { "key": "selector", "operator": "equal", "operand": "source.python" }
    ]
},
{ "keys": ["ctrl+r", "ctrl+c"], "command": "python_regenerate_cache", "context":
    [
        { "key": "selector", "operator": "equal", "operand": "source.python" }
    ]
},
{ "keys": ["ctrl+r", "ctrl+f"], "command": "python_refactor_restructure", "context":
    [
        { "key": "selector", "operator": "equal", "operand": "source.python"}
    ]
},
{ "keys": ["ctrl+r", "ctrl+m"], "command": "python_generate_modules_cache", "context":
    [
        { "key": "selector", "operator": "equal", "operand": "source.python"}
    ]
},
{ "keys": ["ctrl+alt+space"], "command": "python_manual_completion_request", "context":
    [
        { "key": "selector", "operator": "equal", "operand": "source.python" }
    ]
},

Indices and tables