Overview¶

You can read a quick tour of Emacs, or read the built-in tutorial by running C-h t in the editor. That is, you hold down the control key and hit h (the canonical help key in Emacs), release both, and hit t (for tutorial).

For Python, you can read the basic tutorial. If you already know Python, you should check out some best practices.

Once you have these basics, you can go on to install Elpy.

Installation¶

(require 'package)
(add-to-list 'package-archives
             '("melpa-stable" . "https://stable.melpa.org/packages/"))

Now you can run M-x package-refresh-contents to download a fresh copy of the archive contents, and M-x package-install RET elpy RET to install elpy. If you want to enable Elpy by default, you can simply add the following to your .emacs:

(package-initialize)
(elpy-enable)

Congratulations, Elpy is now successfully installed!

In order to use all the features (such as navigation with M-.), you'll need to install some python libraries. You can do that easily by typing M-x elpy-config RET, and following the instructions.

Useful keybindings¶

C-c C-c evaluates the current script (or region if something is selected) in an interactive python shell. The python shell is automatically displayed aside of your script (if not already there).

C-RET evaluates the current statement (current line plus the following nested lines).

C-c C-z switches between your script and the interactive shell.

C-c C-d displays documentation for the thing under cursor (function or module). The documentation will pop in a different buffer, that can be closed with q.

Go further¶

Configuration¶

The RPC Process¶

Every project and virtual env combination gets their own RPC process. You can see them both in the process list (M-x list-process) as well as in the buffer list (C-x C-b) as buffers named *elpy-rpc[...]*.

By default, Elpy will also find the library root of the current file and pass that to the RPC functions. The library root is the directory from which the current file can be imported.

There are a few options and commands related to the RPC process.

Backends¶

Virtual Envs¶

Outside of RPC processes, though, it is not easy to have more than one virtual env active at the same time. Elpy allows you to set a single global virtual env and change it whenever you like, though.

Elpy won't pollute your Emacs command namespaces, but it might be an idea to create an alias for the workon command:

(defalias 'workon 'pyvenv-workon)

Modules¶

Emacs Basics¶

Movement keys in Emacs often use fbnp for forward, backward, next (down) and previous (up). k and backspace (DEL) are for deleting. These are combined with the Control, Meta and Control-Meta modifiers. Control generally refers to the simplest form. C-f moves one character forward. Meta changes this to affect words, that is, consecutive sequences of alphanumeric characters. The Control-Meta combination then affects whole expressions.

In the following table, | refers to the position of point.

Expression-based commands will also work on strings, tuples, dictionaries, or any balanced groups of parentheses. This works for all movement keys (f, b, n, p`), with next and previous moving to the next or previous group of parens. It also works with forward and backward deletion (d and DEL/<backspace>, respectively) for character and word groups, but not for expressions. To delete the expression after point, use C-M-k. For the expression before point, you can use C-M-b C-M-k.

If you enable subword-mode, Emacs will also consider CamelCase to be two words instead of one for the purpose of these operations.

In addition to the above, Emacs also supports moving up or down inside nested parentheses groups. C-M-d will move down into the next enclosed group of parentheses, while C-M-u will move up to the directly enclosing group of parentheses.

Finally, a lot of Elpy's commands change their behavior when the prefix argument is given. That is, hit C-u before the command. In Elpy, the prefix argument often disables any attempt by the command at being smart, in case it would get it wrong.

Moving By Indentation¶

Moving the Current Region¶

Projects¶

In addition to these two commands, elpy-check also supports optionally checking all files in the current project.

Elpy's idea of the project root and which files belong to a project and which don't can be influenced as well.

To configure Elpy specifically for a single project, you can use Emacs' Directory Variables. Elpy provides a simple interface to this.

Completion¶

You can use cursor keys or M-n and M-p to scroll through the options, RET to use the selected completion, or TAB to complete the common part.

On any completion option, C-d or <f1> will display a temporary window with documentation. C-w will display a temporary window showing the source code of the completion to get some context.

Elpy uses Company Mode for the completion interface, so its documentation is a good place for further information.

Navigation¶

If you use an Emacs version superior to 25, elpy will define the necessary backends for the xref package.

Interactive Python¶

Interpreter Setup¶

Use the Python standard interpreter (default):

(setq python-shell-interpreter "python"
      python-shell-interpreter-args "-i")

Use Jupyter console (recommended for interactive Python):

(setq python-shell-interpreter "jupyter"
      python-shell-interpreter-args "console --simple-prompt"
      python-shell-prompt-detect-failure-warning nil)
(add-to-list 'python-shell-completion-native-disabled-interpreters
             "jupyter")

Use IPython:

(setq python-shell-interpreter "ipython"
      python-shell-interpreter-args "-i --simple-prompt")

Note that various issues with plotting have been reported when running IPython 5 in Emacs under Windows. We recommend using Jupyter console instead.

If you have an older version of IPython and the above code does not work for you, you may also try:

(setenv "IPY_TEST_SIMPLE_PROMPT" "1")
(setq python-shell-interpreter "ipython"
      python-shell-interpreter-args "-i")
As an IPython_ user, you might be interested in the `Emacs IPython
Notebook`_ or an `Elpy layer`_ for Spacemacs_, too.

The Shell Buffer¶

(add-hook 'elpy-mode-hook (lambda () (elpy-shell-toggle-dedicated-shell 1)))

(add-hook 'elpy-mode-hook (lambda () (elpy-shell-set-local-shell (elpy-project-root))))

Evaluating code fragments¶

Each of the commands to send code fragments to the shell has four variants, one for each combination of: whether or not the point should move after sending ("step"), and whether or not the Python shell should be focused after sending ("go"). Step is activated by C-, go by S-. For example:

Elpy provides support for sending multiple statements to the shell.

The functions for sending the entire buffer have special support for avoiding accidental code execution, e.g.:

The list of remaining commands to send code fragments is:

Shell feedback¶

Syntax Checking¶

Elpy uses the built-in Flymake library to find syntax errors on the fly, so see there for more configuration options.

Documentation¶

If the autodoc module is enabled (not the case by default) the documentation is automatically updated with the symbol at point or the currently selected company candidate.

Testing¶

Elpy's test interface is built around Emacs' compilation framework. Elpy will run test commands as a compilation job, with all the advantages this brings.

This enables a good workflow. You write a test and use C-c C-t to watch it fail. You then go to your implementation file, for example using C-u C-c C-f, and make the test pass. You can use a key bound to recompile (I use <f5> for this) to just re-run that one test. Once that passes, you can use C-c C-t again to run all tests to make sure they all pass as well. Repeat.

For an even more automated way, you can use tdd.el, which will run your last compile command whenever you save a file.

Refactoring¶

Django¶

Profiling¶

Writing Modules¶

To achieve this, a module function receives one or more arguments, the first of which is the command specifier symbol, which can be one of the following:

To activate a module, the user has to add the function to elpy-modules.

Writing Test Runners¶

Test runners should use an interactive spec of (interactive (elpy-test-at-point)) so they can be called directly by the user. For their main work, they can use the helper function elpy-test-run. See the elpy-test-discover-runner for an example.

To make it possible to set the test runner as a file-, directory- or project-local variable, the function symbol should get the elpy-test-runner property with a value of t.

Running Tests:¶

virtualenv ~/.virtualenvs/elpy
source ~/.virtualenvs/elpy/bin/activate
./scripts/setup

You can now run ./scripts/test to run Elpy's test suite.