.\" Man page generated from reStructuredText.
.
.TH "ELPY" "1" "Jun 30, 2020" "1.34.0" "Elpy"
.SH NAME
elpy \- Elpy Documentation
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.sp
Elpy is the Emacs Python Development Environment. It aims to provide
an easy to install, fully\-featured environment for Python development.
.SH INTRODUCTION
.SS Overview
.sp
Elpy is an extension for the \fI\%Emacs\fP text editor to work with \fI\%Python\fP
projects. This documentation explains how to use Elpy to work
on Python project using Emacs, but it does not aim to be an
introduction to either Emacs or Python.
.sp
You can read a \fI\%quick tour\fP of Emacs, or read the built\-in tutorial
by running \fBC\-h t\fP in the editor. That is, you hold down the
\fBcontrol\fP key and hit \fBh\fP (the canonical \fIhelp\fP key in Emacs),
release both, and hit \fBt\fP (for tutorial).
.sp
For Python, you can read the \fI\%basic tutorial\fP\&. If you already know
Python, you should check out some \fI\%best practices\fP\&.
.sp
Once you have these basics, you can go on to install Elpy.
.SS Installation
.SS With use\-package
.sp
Simply add the following lines to you \fB\&.emacs\fP (or \fB\&.emacs.d/init.el\fP, or equivalent):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
(use\-package elpy
  :ensure t
  :init
  (elpy\-enable))
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Or if you want to defer Elpy loading:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
(use\-package elpy
  :ensure t
  :defer t
  :init
  (advice\-add \(aqpython\-mode :before \(aqelpy\-enable))
.ft P
.fi
.UNINDENT
.UNINDENT
.SS From apt (Debian ≥10 an Ubuntu ≥18.10)
.sp
Users of Debian ≥10 or Ubuntu ≥18.10 can skip the instructions above
this line and may simply install Elpy and all of its recommended
dependencies with the following command::
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sudo apt install elpa\-elpy
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Elpy can then be activated by running \fBM\-x elpy\-enable\fP\&.
This can be made automatic by adding the following to your \fB\&.emacs\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
(elpy\-enable)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In order to use all the features (such as navigation with \fBM\-.\fP),
you\(aqll need to install some python libraries.  You can do that easily
by typing \fBM\-x elpy\-config RET\fP, and following the instructions.
.SS Manually from Melpa
.sp
The main Elpy package is installed via the Emacs package interface,
\fBpackage.el\fP\&. First, you have to add Elpy\(aqs package archive to your
list of archives, though. Add the following code to your \fB\&.emacs\fP
file and restart Emacs:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
(require \(aqpackage)
(add\-to\-list \(aqpackage\-archives
             \(aq("melpa\-stable" . "https://stable.melpa.org/packages/"))
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Now you can run \fIM\-x package\-refresh\-contents\fP to download a fresh
copy of the archive contents, and \fBM\-x package\-install RET elpy RET\fP
to install elpy. If you want to enable Elpy by default, you can simply
add the following to your .emacs:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
(package\-initialize)
(elpy\-enable)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Congratulations, Elpy is now successfully installed!
.SS Manually from sources
.sp
If you want to test a specific branch or a PR that has not been merged
yet, you will have to install Elpy from sources.
.INDENT 0.0
.IP \(bu 2
First, clone the repository containing the branch you are interested in:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
git clone https://github.com/USER/elpy.git
cd elpy
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Then check out the branch associated to the PR you want to try:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
git checkout BRANCH_NAME
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
Now switch to Emacs and add Elpy\(aqs sources to the load path:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
(add\-to\-list \(aqload\-path "/path/to/elpy")
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
Finally, load Elpy files:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
(load "elpy")
(load "elpy\-rpc")
(load "elpy\-shell")
(load "elpy\-profile")
(load "elpy\-refactor")
(load "elpy\-django")
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Configuration
.sp
You can easily configure Elpy to your own preferences. All options are
available through a unified interface, accessible with the following
command:
.INDENT 0.0
.TP
.B M\-x elpy\-config
Show the current Elpy configuration, point out possible problems,
and provide a quick interface to relevant customization options.
.sp
Packages needed by Elpy can be installed and updated from this
interface.
.UNINDENT
.SH QUICKSTART
.sp
Once installed, Elpy will automatically provide \fI\%code completion\fP, \fI\%syntax error highlighting\fP and function signature (in the modeline) for python files.
.SS Useful keybindings
.sp
Elpy has quite a lot of keybindings, but the following ones should be enough to get you started:
.INDENT 0.0
.TP
.B C\-c C\-c (elpy\-shell\-send\-region\-or\-buffer)
Evaluate the current script (or region if something is selected) in an interactive python shell.
The python shell is automatically displayed aside of your script.
.UNINDENT
.INDENT 0.0
.TP
.B C\-RET (elpy\-shell\-send\-statement\-and\-step)
Evaluate the current statement (current line plus the following nested lines).
Useful for evaluating a function or class definition or a for loop.
.UNINDENT
.INDENT 0.0
.TP
.B C\-c C\-z (elpy\-shell\-switch\-to\-shell)
Switch between your script and the interactive shell.
.UNINDENT
.INDENT 0.0
.TP
.B C\-c C\-d (elpy\-doc)
Display documentation for the thing under cursor (function or module).
The documentation will pop in a different buffer, that can be closed with \fBq\fP\&.
.UNINDENT
.SS Go further
.sp
Elpy offers a lot of features, including \fI\%code navigation\fP, \fI\%debugging\fP, \fI\%testing\fP, \fI\%profiling\fP and support for \fI\%virtual environments\fP\&.
Feel free to explore the documentation, everything is there !
.SH EDITING
.SS Emacs Basics
.sp
Elpy is an extension to Emacs, and as such the standard bindings in
Emacs are available. This manual is not meant to be an introduction to
Emacs, but this section will still highlight some features in Emacs
that are especially useful for Python editing.
.sp
Movement keys in Emacs often use \fBfbnp\fP for forward, backward, next
(down) and previous (up). \fBk\fP and \fBbackspace\fP (\fBDEL\fP) are for
deleting. These are combined with the \fBControl\fP, \fBMeta\fP and
\fBControl\-Meta\fP modifiers. Control generally refers to the simplest
form. \fBC\-f\fP moves one character forward. Meta changes this to affect
\fIwords\fP, that is, consecutive sequences of alphanumeric characters.
The Control\-Meta combination then affects whole expressions.
.sp
In the following table, \fB|\fP refers to the position of point.
.TS
center;
|l|l|l|.
_
T{
Before
T}	T{
Key
T}	T{
After
T}
_
T{
\fB|hello_world\fP
T}	T{
\fBC\-f\fP
T}	T{
\fBh|ello_world\fP
T}
_
T{
\fB|hello_world\fP
T}	T{
\fBM\-f\fP
T}	T{
\fBhello|_world\fP
T}
_
T{
\fB|hello_world\fP
T}	T{
\fBC\-M\-f\fP
T}	T{
\fBhello_world|\fP
T}
_
.TE
.sp
Expression\-based commands will also work on strings, tuples,
dictionaries, or any balanced groups of parentheses. This works for
all movement keys (\fBf\fP, \fBb\fP, \fBn\fP, \fBp\fP), with
\fInext\fP and \fIprevious\fP moving to the next or previous group of parens.
It also works with forward and backward deletion (\fBd\fP and
\fBDEL\fP/\fB<backspace>\fP, respectively) for character and word
groups, but not for expressions. To delete the expression after point,
use \fBC\-M\-k\fP\&. For the expression before point, you can use
\fBC\-M\-b C\-M\-k\fP\&.
.sp
If you enable \fBsubword\-mode\fP, Emacs will also consider
CamelCase to be two words instead of one for the purpose of these
operations.
.sp
In addition to the above, Emacs also supports moving up or down inside
nested parentheses groups. \fBC\-M\-d\fP will move \fIdown\fP into the next
enclosed group of parentheses, while \fBC\-M\-u\fP will move \fIup\fP to
the directly enclosing group of parentheses.
.sp
Finally, a lot of Elpy\(aqs commands change their behavior when the
prefix argument is given. That is, hit \fBC\-u\fP 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.
.SS Moving By Indentation
.INDENT 0.0
.TP
.B C\-down (elpy\-nav\-forward\-block)
.UNINDENT
.INDENT 0.0
.TP
.B C\-up (elpy\-nav\-backward\-block)
These commands are used to navigate between lines with same
indentation as the current line. Point should be placed on the
first non\-whitespace character of the line and then use \fIC\-down\fP
to move forward or \fIC\-up\fP to move backward.
.UNINDENT
.INDENT 0.0
.TP
.B C\-left (elpy\-nav\-backward\-indent)
.UNINDENT
.INDENT 0.0
.TP
.B C\-right (elpy\-nav\-forward\-indent)
These commands are used to navigate between indentation levels.
\fIC\-left\fP moves point to previous indent level or over previous word.
\fIC\-right\fP moves point to next indent level or over the next word.
.UNINDENT
.SS Moving the Current Region
.INDENT 0.0
.TP
.B M\-down (elpy\-nav\-move\-line\-or\-region\-down)
.UNINDENT
.INDENT 0.0
.TP
.B M\-up (elpy\-nav\-move\-line\-or\-region\-up)
.UNINDENT
.INDENT 0.0
.TP
.B M\-left (elpy\-nav\-indent\-shift\-left)
.UNINDENT
.INDENT 0.0
.TP
.B M\-right (elpy\-nav\-indent\-shift\-right)
Elpy can move the selected region (or the current line if no region is
selected) by using the cursor keys with meta. Left and right will
dedent or indent the code, while up and down will move it line\-wise up
or down, respectively.
.UNINDENT
.SH IDE FEATURES
.SS Projects
.sp
Elpy supports the notion of \fIprojects\fP, a related collection of files
under a common directory. This common directory is called the
project root\&. A number of Elpy\(aqs commands work on all files
inside the project root.
.INDENT 0.0
.TP
.B C\-c C\-f (elpy\-find\-file)
Find a file in the current project. This uses a search\-as\-you\-type
interface for all files under the project root.
.sp
A prefix argument enables "do what I mean" mode. On an import
statement, it will try to open the module imported. Elsewhere in a
file, it will look for an associated test or implementation file,
and if found, open that. If this fails, either way, it will fall
back to the normal find file in project behavior.
.sp
If the current file is called \fBfoo.py\fP, then this will search for
a \fBtest_foo.py\fP in the same directory, or in a \fBtest\fP or
\fBtests\fP subdirectory. If the current file is already called
\fBtest_foo.py\fP, it will try and find a \fBfoo.py\fP nearby.
.sp
This command uses \fI\%projectile\fP or \fI\%find\-file\-in\-project\fP under the hood, so you
need one of them to be installed.
.UNINDENT
.INDENT 0.0
.TP
.B C\-c C\-s (elpy\-rgrep\-symbol)
Search the files in the current project for a string. By default,
this uses the symbol at point. With a prefix argument, it will
prompt for a regular expression to search.
.sp
This is basically a \fBgrep \-r\fP through the project.
.UNINDENT
.sp
In addition to these two commands, \fI\%elpy\-check\fP also supports
optionally checking all files in the current project.
.sp
Elpy\(aqs idea of the project root and which files belong to a project
and which don\(aqt can be influenced as well.
.INDENT 0.0
.TP
.B M\-x elpy\-set\-project\-root
Set the current project root directory. This directory should
contain all files related to the current project.
.UNINDENT
.INDENT 0.0
.TP
.B elpy\-project\-ignored\-directories (Customize Option)
When Elpy searches for files in the current project, it will ignore
files in directories listed here.
.UNINDENT
.INDENT 0.0
.TP
.B elpy\-project\-root\-finder\-functions (Customize Option)
To find the project root, Elpy can utilize a number of heuristics.
With this option, you can configure which are used.
.UNINDENT
.sp
To configure Elpy specifically for a single project, you can use
Emacs\(aq \fI\%Directory Variables\fP\&. Elpy provides a simple interface to
this.
.INDENT 0.0
.TP
.B M\-x elpy\-set\-project\-variable
Set or change the value of a project\-wide variable. With a prefix
argument, the value for the variable is removed.
.sp
This only takes effect in new buffers.
.UNINDENT
.SS Completion
.sp
When you type Python code, Elpy will try and figure out possible
completions and provide them in a suggestion window. If Elpy doesn\(aqt
do so automatically, you can force it to complete right where you are.
.INDENT 0.0
.TP
.B M\-TAB (elpy\-company\-backend)
Provide completion suggestions for a completion at point.
.UNINDENT
.sp
You can use cursor keys or \fBM\-n\fP and \fBM\-p\fP to scroll through
the options, \fBRET\fP to use the selected completion, or \fBTAB\fP
to complete the common part.
.sp
On any completion option, \fBC\-d\fP or \fB<f1>\fP will display a
temporary window with documentation. \fBC\-w\fP will display a
temporary window showing the source code of the completion to get some
context.
.sp
Elpy uses \fI\%Company Mode\fP for the completion interface, so its
documentation is a good place for further information.
.INDENT 0.0
.TP
.B elpy\-get\-info\-from\-shell (Customize Option)
If \fIt\fP, use the shell to gather docstrings and completions. Normally elpy
provides completion and documentation using static code analysis (from
jedi). With this option, elpy will add the completion candidates
and the docstrings from the associated python shell; This activates
fallback completion candidates for cases when the static code analysis
fails.
.UNINDENT
.SS Navigation
.sp
Elpy supports advanced navigation features.
.INDENT 0.0
.TP
.B M\-. (elpy\-goto\-definition)
Go to the location where the identifier at point is defined. This
is not always easy to make out, so the result can be wrong. Also,
the backends can not always identify what kind of symbol is at
point. Especially after a few indirections, they have basically no
hope of guessing right, so they don\(aqt.
.UNINDENT
.INDENT 0.0
.TP
.B C\-x 4 M\-. (elpy\-goto\-definition\-other\-window)
Same as \fIelpy\-go\-to\-definition\fP (with the same caveats) but goes to
the definition of the symbol at point in other window, if defined.
.UNINDENT
.INDENT 0.0
.TP
.B M\-* (pop\-tag\-mark)
Go back to the last place where \fBM\-.\fP was used, effectively
turning \fBM\-.\fP and \fBM\-*\fP into a forward and backward
motion for definition lookups.
.UNINDENT
.INDENT 0.0
.TP
.B C\-c C\-o (elpy\-occur\-definitions)
Search the buffer for a list of definitions of classes and functions.
.UNINDENT
.INDENT 0.0
.TP
.B M\-x elpy\-goto\-assignment
Go to the location where the identifier at point is assigned.
It is not bound by default, so you will have to bind it manually.
You can also use it as a replacement to \fBelpy\-goto\-definition\fP (see \fI\%Jumping to assignment\fP).
.UNINDENT
.sp
If you use an Emacs version superior to 25, Elpy will define the
necessary backends for the \fI\%xref\fP package.
.INDENT 0.0
.TP
.B M\-. (xref\-find\-definitions)
Find the definition of the identifier at point.
.UNINDENT
.INDENT 0.0
.TP
.B C\-x 4 . (xref\-find\-definition\-other\-window)
Like \fBM\-.\fP but switch to the other window.
.UNINDENT
.INDENT 0.0
.TP
.B C\-x 5 . (xref\-find\-definition\-other\-frame)
Like \fBM\-.\fP but switch to the other frame.
.UNINDENT
.INDENT 0.0
.TP
.B M\-, (xref\-pop\-marker\-stack)
Go back to the last place where \fBM\-.\fP was used, effectively
turning \fBM\-.\fP and \fBM\-,\fP into a forward and backward
motion for definition lookups.
.UNINDENT
.INDENT 0.0
.TP
.B M\-? (xref\-find\-references)
Find references for an identifier of the current buffer.
.UNINDENT
.INDENT 0.0
.TP
.B C\-M\-. (xref\-find\-apropos)
Find all meaningful symbols that match a given pattern.
.UNINDENT
.SS Interactive Python
.sp
Emacs can run a Python interpreter in a special buffer, making it much easier to
send code snippets over. Elpy provides additional functionality to seamlessly
work with interactive Python in a style similar to \fI\%ESS\fP\&.
.SS Interpreter Setup
.sp
Elpy uses the Python interpreter setup from the Emacs \fBpython\fP package. This
section briefly summarizes some common setups; add the one you need to your
\fB\&.emacs\fP file. Note that the code below (and Elpy in general) require at least
Emacs 24.4.
.sp
Use the Python standard interpreter (default):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
(setq python\-shell\-interpreter "python"
      python\-shell\-interpreter\-args "\-i")
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Use Jupyter console (recommended for interactive Python):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
(setq python\-shell\-interpreter "jupyter"
      python\-shell\-interpreter\-args "console \-\-simple\-prompt"
      python\-shell\-prompt\-detect\-failure\-warning nil)
(add\-to\-list \(aqpython\-shell\-completion\-native\-disabled\-interpreters
             "jupyter")
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Use IPython:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
(setq python\-shell\-interpreter "ipython"
      python\-shell\-interpreter\-args "\-i \-\-simple\-prompt")
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note that various issues with plotting have been reported when running IPython 5
in Emacs under Windows. We recommend using Jupyter console instead.
.sp
If you have an older version of IPython and the above code does not work for
you, you may also try:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
(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 \(gaEmacs IPython
Notebook\(ga_ or an \(gaElpy layer\(ga_ for Spacemacs_, too.
.ft P
.fi
.UNINDENT
.UNINDENT
.SS The Shell Buffer
.INDENT 0.0
.TP
.B C\-c C\-z (elpy\-shell\-switch\-to\-shell)
Switch to buffer with a Python interpreter running, starting one if
necessary.
.sp
By default, Elpy tries to find the root directory of the current project
(git, svn or hg repository, python package or projectile project) and
starts the python interpreter here. This behaviour can be suppressed
with the option \fBelpy\-shell\-starting\-directory\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B elpy\-shell\-starting\-directory (Customize Option)
Govern the directory in which Python shells will be started.
Can be \fB\(aqproject\-root\fP (default) to use the current project root,
\fB\(aqcurrent\-directory\fP to use the buffer current directory, or a
string indicating a specific path.
.UNINDENT
.INDENT 0.0
.TP
.B M\-x elpy\-shell\-toggle\-dedicated\-shell
By default, python buffers are all attached to a same python shell
(that lies in the \fI*Python*\fP buffer), meaning that all buffers and
code fragments will be send to this shell.
\fIelpy\-shell\-toggle\-dedicated\-shell\fP attaches a dedicated python shell
(not shared with the other python buffers) to the current python buffer.
To make this the default behavior (like the deprecated option
\fIelpy\-dedicated\-shells\fP did), use the following snippet:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
(add\-hook \(aqelpy\-mode\-hook (lambda () (elpy\-shell\-toggle\-dedicated\-shell 1)))
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B M\-x elpy\-shell\-set\-local\-shell
Attach the current python buffer to a specific python shell (whose name is
asked with completion).
You can use this function to have one python shell per project, with:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
(add\-hook \(aqelpy\-mode\-hook (lambda () (elpy\-shell\-set\-local\-shell (elpy\-project\-root))))
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B C\-c C\-k (elpy\-shell\-kill)
Kill the associated python shell.
.UNINDENT
.INDENT 0.0
.TP
.B C\-c C\-K (elpy\-shell\-kill\-all)
Kill all active python shells.
.UNINDENT
.SS Evaluating code fragments
.sp
Elpy provides commands to send the current Python statement (\fBe\fP), function
definition (\fBf\fP), class definition (\fBc\fP), top\-level statement
(\fBs\fP), group of Python statements (\fBg\fP), cell (\fBw\fP), region
(\fBr\fP), or buffer (\fBb\fP) to the Python shell for evaluation. These
commands are bound to prefix \fBC\-c C\-y\fP, followed by the single character
indicating what to send; e.g., \fBC\-c C\-y e\fP sends the Python statement at
point.
.sp
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 \fBC\-\fP, go by \fBS\-\fP\&. For example:
.INDENT 0.0
.TP
.B C\-c C\-y e (elpy\-shell\-send\-statement)
Send the current statement to the Python shell and keep point position. Here
statement refers to the Python statement the point is on, including
potentially nested statements. If point is on an if/elif/else clause send the
entire if statement (with all its elif/else clauses). If point is on a
decorated function, send the decorator as well.
.UNINDENT
.INDENT 0.0
.TP
.B C\-c C\-y C\-e (elpy\-shell\-send\-statement\-and\-step)
Send the current statement to the Python shell and move point to first
subsequent statement.
.sp
Also bound to \fBC\-RET\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B C\-c C\-y E (elpy\-shell\-send\-statement\-and\-go)
Send the current statement to the Python shell, keeping point position, and
switch focus to the Python shell buffer.
.UNINDENT
.INDENT 0.0
.TP
.B C\-c C\-y C\-S\-E (elpy\-shell\-send\-statement\-and\-step\-and\-go)
Send the current statement to the Python shell, move point to first
subsequent statement, and switch focus to the Python shell buffer.
.UNINDENT
.sp
Elpy provides support for sending multiple statements to the shell.
.INDENT 0.0
.TP
.B C\-c C\-y O (elpy\-shell\-send\-group\-and\-step)
Send the current or next group of top\-level statements to the Python shell
and step. A sequence of top\-level statements is a group if they are not
separated by empty lines. Empty lines within each top\-level statement are
ignored.
.sp
If the point is within a statement, send the group around this statement.
Otherwise, go to the top\-level statement below point and send the group
around this statement.
.UNINDENT
.INDENT 0.0
.TP
.B C\-c C\-y W (elpy\-shell\-send\-codecell\-and\-step)
Send the current code cell to the Python shell and step. A code cell is a
piece of code surrounded by special separator lines; see below. For example,
you can insert two lines starting with \fB##\fP to quickly send the code
in\-between.
.UNINDENT
.INDENT 0.0
.TP
.B elpy\-shell\-codecell\-beginning\-regexp (Customize Option)
Regular expression for matching a line indicating the beginning of a code
cell. By default, \fB##.*\fP is treated as a beginning of a code cell, as are
the code cell beginnings in Python files exported from IPython or Jupyter
notebooks (e.g., \fB# <codecell>\fP or \fB# In[1]:\fP).
.UNINDENT
.INDENT 0.0
.TP
.B elpy\-shell\-cell\-boundary\-regexp (Customize Option)
Regular expression for matching a line indicating the boundary of a cell
(beginning or ending). By default, \fB##.*\fP is treated as a cell boundary, as
are the boundaries in Python files exported from IPython or Jupyter notebooks
(e.g., \fB# <markdowncell>\fP, \fB# In[1]:\fP, or \fB# Out[1]:\fP).
.sp
Note that \fI\%elpy\-shell\-codecell\-beginning\-regexp\fP must also match the
cell boundaries defined here.
.UNINDENT
.sp
The functions for sending the entire buffer have special support for avoiding
accidental code execution, e.g.:
.INDENT 0.0
.TP
.B C\-c C\-y r (elpy\-shell\-send\-region\-or\-buffer)
Send the the active region (if any) or the entire buffer (otherwise) to the
Python shell and keep point position.
.sp
When sending the whole buffer, this command will also escape any uses of the
\fBif __name__ == \(aq__main__\(aq\fP idiom, to prevent accidental execution of a
script. If you want this to be evaluated, pass a prefix argument with
\fBC\-u\fP\&.
.sp
Also bound to \fBC\-c C\-c\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B elpy\-shell\-add\-to\-shell\-history (Customize Option)
If \fIt\fP, Elpy will make the code sent available in the shell
history. This allows to use \fIcomint\-previous\-input\fP (\fBC\-up\fP)
in the python shell to get back the pieces of code sent by Elpy.
.UNINDENT
.sp
The list of remaining commands to send code fragments is:
.INDENT 0.0
.TP
.B C\-c C\-y s (elpy\-shell\-send\-top\-statement)
.UNINDENT
.INDENT 0.0
.TP
.B C\-c C\-y S (elpy\-shell\-send\-top\-statement\-and\-go)
.UNINDENT
.INDENT 0.0
.TP
.B C\-c C\-y f (elpy\-shell\-send\-defun)
.UNINDENT
.INDENT 0.0
.TP
.B C\-c C\-y F (elpy\-shell\-send\-defun\-and\-go)
.UNINDENT
.INDENT 0.0
.TP
.B C\-c C\-y c (elpy\-shell\-send\-defclass)
.UNINDENT
.INDENT 0.0
.TP
.B C\-c C\-y C (elpy\-shell\-send\-defclass\-and\-go)
.UNINDENT
.INDENT 0.0
.TP
.B C\-c C\-y o (elpy\-shell\-send\-group)
.UNINDENT
.INDENT 0.0
.TP
.B C\-c C\-y O (elpy\-shell\-send\-group\-and\-go)
.UNINDENT
.INDENT 0.0
.TP
.B C\-c C\-y w (elpy\-shell\-send\-codecell)
.UNINDENT
.INDENT 0.0
.TP
.B C\-c C\-y W (elpy\-shell\-send\-codecell\-and\-go)
.UNINDENT
.INDENT 0.0
.TP
.B C\-c C\-y R (elpy\-shell\-send\-region\-or\-buffer\-and\-go)
.UNINDENT
.INDENT 0.0
.TP
.B C\-c C\-y b (elpy\-shell\-send\-buffer)
.UNINDENT
.INDENT 0.0
.TP
.B C\-c C\-y B (elpy\-shell\-send\-buffer\-and\-go)
.UNINDENT
.INDENT 0.0
.TP
.B C\-c C\-y C\-s (elpy\-shell\-send\-top\-statement\-and\-step)
.UNINDENT
.INDENT 0.0
.TP
.B C\-c C\-y C\-S\-S (elpy\-shell\-send\-top\-statement\-and\-step\-and\-go)
.UNINDENT
.INDENT 0.0
.TP
.B C\-c C\-y C\-f (elpy\-shell\-send\-defun\-and\-step)
.UNINDENT
.INDENT 0.0
.TP
.B C\-c C\-y C\-S\-F (elpy\-shell\-send\-defun\-and\-step\-and\-go)
.UNINDENT
.INDENT 0.0
.TP
.B C\-c C\-y C\-c (elpy\-shell\-send\-defclass\-and\-step)
.UNINDENT
.INDENT 0.0
.TP
.B C\-c C\-y C\-S\-C (elpy\-shell\-send\-defclass\-and\-step\-and\-go)
.UNINDENT
.INDENT 0.0
.TP
.B C\-c C\-y C\-S\-O (elpy\-shell\-send\-group\-and\-step\-and\-go)
.UNINDENT
.INDENT 0.0
.TP
.B C\-c C\-y C\-W (elpy\-shell\-send\-codecell\-and\-step\-and\-go)
.UNINDENT
.INDENT 0.0
.TP
.B C\-c C\-y C\-r (elpy\-shell\-send\-region\-or\-buffer\-and\-step)
.UNINDENT
.INDENT 0.0
.TP
.B C\-c C\-y C\-S\-R (elpy\-shell\-send\-region\-or\-buffer\-and\-step\-and\-go)
.UNINDENT
.INDENT 0.0
.TP
.B C\-c C\-y C\-b (elpy\-shell\-send\-buffer\-and\-step)
.UNINDENT
.INDENT 0.0
.TP
.B C\-c C\-y C\-S\-B (elpy\-shell\-send\-buffer\-and\-step\-and\-go)
.UNINDENT
.SS Shell feedback
.sp
When package \fI\%eval\-sexp\-fu\fP is loaded and \fBeval\-sexp\-fu\-flash\-mode\fP is
active, the statements sent to the shell are briefly flashed after running an
evaluation command, thereby providing visual feedback.
.INDENT 0.0
.TP
.B elpy\-shell\-echo\-input (Customize Option)
Whenever a code fragment is sent to the Python shell, Elpy prints it in the
Python shell buffer (i.e., it looks as if it was actually typed into the
shell). This behavior can be turned on and off via the custom variable
\fIelpy\-shell\-echo\-input\fP and further customized via
\fBelpy\-shell\-echo\-input\-cont\-prompt\fP (whether to show continuation prompts
for multi\-line inputs) and \fBelpy\-shell\-echo\-input\-lines\-head\fP /
\fBelpy\-shell\-echo\-input\-lines\-tail\fP (how much to cut when input is long).
.UNINDENT
.INDENT 0.0
.TP
.B elpy\-shell\-echo\-output (Customize Option)
Elpy shows the output produced by a code fragment sent to the shell in the
echo area when the shell buffer is currently invisible. This behavior can be
controlled via \fIelpy\-shell\-echo\-output\fP (never, always, or only when shell
invisible). Output echoing is particularly useful if the custom variable
\fI\%elpy\-shell\-display\-buffer\-after\-send\fP is set to \fBnil\fP (the default
value). Then, no window is needed to display the shell (thereby saving screen
real estate), but the outputs can still be seen in the echo area.
.UNINDENT
.INDENT 0.0
.TP
.B elpy\-shell\-display\-buffer\-after\-send (Customize Option)
Whether to display the Python shell after sending something to it (default
\fBnil\fP).
.UNINDENT
.SS Syntax Checking
.sp
Whenever you save a file, Elpy will run a syntax check and highlight
possible errors or warnings inline.
.INDENT 0.0
.TP
.B C\-c C\-n (elpy\-flymake\-next\-error)
.UNINDENT
.INDENT 0.0
.TP
.B C\-c C\-p (elpy\-flymake\-previous\-error)
You can navigate between any error messages with these keys. The
current error will be shown in the minibuffer.
.UNINDENT
.sp
Elpy uses the built\-in \fI\%Flymake\fP library to find syntax errors on the
fly, so see there for more configuration options.
.INDENT 0.0
.TP
.B C\-c C\-v (elpy\-check)
Alternatively, you can run a syntax check on the current file where
the output is displayed in a new buffer, giving you an overview and
allowing you to jump to the errors from there.
.sp
With a prefix argument, this will run the syntax check on all files
in the current project.
.UNINDENT
.INDENT 0.0
.TP
.B python\-check\-command (Customize Option)
To change which command is used for syntax checks, you can
customize this option. By default, Elpy uses the \fBflake8\fP
program, which you have to install separately. The
\fBelpy\-config\fP command will prompt you to do this if Elpy
can\(aqt find the program.
.sp
It is possible to create a single virtual env for the sole purpose
of installing \fBflake8\fP in there, and then simply link the command
script to a directory inside your \fBPATH\fP, meaning you do
not need to install the program in every virtual env separately.
.UNINDENT
.SS Folding
.sp
Elpy offers code folding by enhancing the builtin folding minor mode \fBHideshow\fP\&.
.sp
When opening a python buffer, Elpy will indicate foldable things with an arrow in the left fringe.
Clicking on an arrow will fold the corresponding code blocks.
Folded code blocks can be unfolded by clicking on the \fI\&...\fP button at the end of the line.
.sp
If you don\(aqt want to use your mouse, you can achieve the same thing with the function
.INDENT 0.0
.TP
.B C\-c @ C\-c (elpy\-folding\-toggle\-at\-point)
Toggle folding for the thing at point, it can be a docstring, a comment or a code block.
.UNINDENT
.sp
The display of arrows in the fringe can be disable with the option
.INDENT 0.0
.TP
.B elpy\-folding\-fringe\-indicators (Customize Option)
If elpy should display folding fringe indicators or not.
.UNINDENT
.sp
Elpy also provides some other useful features:
.INDENT 0.0
.TP
.B C\-c @ C\-b (elpy\-folding\-toggle\-docstrings)
Toggle folding of all python docstrings.
.UNINDENT
.INDENT 0.0
.TP
.B C\-c @ C\-m (elpy\-folding\-toggle\-comments)
Toggle folding of all comments.
.UNINDENT
.INDENT 0.0
.TP
.B C\-c @ C\-f (elpy\-folding\-hide\-leafs)
Hide all code leafs, i.e. code blocks that do not contains any other blocks.
.UNINDENT
.sp
The classical keybindings for hideshow are also available, e.g.:
.INDENT 0.0
.TP
.B C\-c @ C\-a (hs\-show\-all)
Unfold everything.
.UNINDENT
.sp
(see \fI\%Hideshow\fP documentation for more information)
.SS Documentation
.sp
Elpy provides a single interface to documentation.
.INDENT 0.0
.TP
.B C\-c C\-d (elpy\-doc)
When point is on a symbol, Elpy will try and find the documentation
for that object, and display that. If it can\(aqt find the
documentation for whatever reason, it will try and look up the
symbol at point in pydoc. If it\(aqs not there, either, it will prompt
the user for a string to look up in pydoc.
.sp
With a prefix argument, Elpy will skip all the guessing and just
prompt the user for a string to look up in pydoc.
.UNINDENT
.sp
If the \fIautodoc\fP module is enabled (not by default) the
documentation is automatically updated with the symbol at point or the
currently selected company candidate.
.INDENT 0.0
.TP
.B elpy\-autodoc\-delay (Customize Option)
The idle delay in seconds until documentation is updated automatically.
.UNINDENT
.SS Snippets
.sp
Elpy uses \fI\%yasnippet\fP to provide code templates that helps writing common pieces of code faster.
You can access a template by typing a "template key" and hitting \fBTAB\fP to expand it.
You may then be asked to fill some fields in the template, just hit \fBTAB\fP when you are done to proceed to the next field.
.sp
The sequel presents a list of templates provided by Elpy.
.SS Special methods
.sp
Elpy provides a large range of templates for special class methods (\fB__init__\fP, \fB__call__\fP, \fB__add__\fP, ...).
To call them, simply type \fB_\fP followed by the method name (for example \fB_init\fP) and hit \fBTAB\fP\&.
.SS Other useful snippets
.INDENT 0.0
.IP \(bu 2
\fBenc\fP: Encoding statement
.IP \(bu 2
\fBenv\fP: Hashbang statement
.IP \(bu 2
\fBfrom\fP: Import statement
.IP \(bu 2
\fBpdb\fP: Snippet to run pdb at the current script position
.IP \(bu 2
\fBsuper\fP: Super statement to call parent methods
.IP \(bu 2
\fBdef\fP: Function definition
.IP \(bu 2
\fBclass\fP: Class definition
.IP \(bu 2
\fBdefs\fP: Class method definition
.UNINDENT
.SS Debugging
.sp
Elpy provides an interface to \fI\%pdb\fP, the builtin Python debugger.
Note that this interface is only available for Emacs 25 and above.
.INDENT 0.0
.TP
.B C\-c C\-u d (elpy\-pdb\-debug\-buffer)
Run pdb on the current buffer. If no breakpoints has been set using
\fI\%elpy\-pdb\-toggle\-breakpoint\-at\-point\fP, the debugger will
pause at the beginning of the buffer. Else, the debugger will pause
at the first breakpoint. Once pdb is started, the \fI\%pdb commands\fP
can be used to step through and look into the code evaluation.
.sp
With a prefix argument \fBC\-u\fP, ignore the breakpoints and
always pause at the beginning of the buffer.
.UNINDENT
.INDENT 0.0
.TP
.B C\-c C\-u b (elpy\-pdb\-toggle\-breakpoint\-at\-point)
Add (or remove) a breakpoint on the current line. Elpy adds a red
circle to the fringe to indicate the presence of a breakpoint. You
can then use \fI\%elpy\-pdb\-debug\-buffer\fP to start pdb and
pause at each of the breakpoints.
.sp
With a prefix argument \fBC\-u\fP, remove all the breakpoints.
.UNINDENT
.INDENT 0.0
.TP
.B C\-c C\-u p (elpy\-pdb\-break\-at\-point)
Run pdb on the current buffer and pause at the cursor position.
.UNINDENT
.INDENT 0.0
.TP
.B C\-c C\-u e (elpy\-pdb\-debug\-last\-exception)
Run post\-mortem pdb on the last exception.
.UNINDENT
.SS Testing
.sp
Testing is an important part of programming. Elpy provides a central
interface to testing, which allows for a good workflow for tests.
.sp
Elpy\(aqs test interface is built around Emacs\(aq \fI\%compilation framework\fP\&.
Elpy will run test commands as a compilation job, with all the
advantages this brings.
.INDENT 0.0
.TP
.B C\-c C\-t (elpy\-test)
Start a test run. This uses the currently configured test runner to
discover and run tests. If point is inside a test case, the test
runner will run exactly that test case. Otherwise, or if a prefix
argument is given, it will run all tests.
.UNINDENT
.INDENT 0.0
.TP
.B M\-x elpy\-set\-test\-runner
This changes the current test runner. Elpy supports the standard
unittest discovery runner, the Django discovery runner, nose,
green, py.test and Twisted trial. You can also write your own, as
described in Writing Test Runners\&.
.sp
Note on Django runners: Elpy tries to find \fImanage.py\fP within your project
structure. If it\(aqs unable to find it, it falls back to \fIdjango\-admin.py\fP\&.
You must set the environment variable \fBDJANGO_SETTINGS_MODULE\fP accordingly.
.UNINDENT
.sp
This enables a good workflow. You write a test and use \fBC\-c C\-t\fP
to watch it fail. You then go to your implementation file, for example
using \fBC\-u C\-c C\-f\fP, and make the test pass. You can use a key
bound to \fBrecompile\fP (I use \fB<f5>\fP for this) to just re\-run
that one test. Once that passes, you can use \fBC\-c C\-t\fP again to
run all tests to make sure they all pass as well. Repeat.
.sp
For an even more automated way, you can use \fI\%tdd.el\fP, which will run
your last compile command whenever you save a file.
.SS Refactoring
.INDENT 0.0
.TP
.B C\-c C\-e (elpy\-multiedit\-python\-symbol\-at\-point)
Edit all occurrences of the symbol at point at once. This will
highlight all such occurrences, and editing one of them will edit
all. This is an easy way to rename identifiers.
.sp
If the backend does not support finding occurrences (currently only
Jedi does), or if a prefix argument is given, this will edit
syntactic occurrences instead of semantic ones. This can match more
occurrences than it should, so be careful. You can narrow the
current buffer to the current function using \fBC\-x n d\fP to
restrict where this matches.
.sp
Finally, if there is a region active, Elpy will edit all
occurrences of the text in the region.
.UNINDENT
.INDENT 0.0
.TP
.B C\-c C\-r f (elpy\-format\-code)
Format code using the available formatter.
.sp
This command formats code using the first formatter found amongst
\fI\%yapf\fP , \fI\%autopep8\fP and \fI\%black\fP\&.
If a region is selected, only that region is formatted.
Otherwise current buffer is formatted.
.sp
\fI\%yapf\fP and \fI\%autopep8\fP can be configured with style files placed in
the project root directory (determined by \fBelpy\-project\-root\fP).
.UNINDENT
.SS Profiling
.sp
Elpy allows one to profile python scripts asynchronously using \fIcProfile\fP\&.
.INDENT 0.0
.TP
.B M\-x elpy\-profile\-buffer\-or\-region
Send the current buffer or region to the profiler and display the result with
\fBelpy\-profile\-visualizer\fP\&.
The default visualizer is \fI\%snakeviz\fP, a browser\-based graphical profile viewer that can be installed with \fIpip install snakeviz\fP\&. \fI\%RunSnakeRun\fP (Python\-2 only GTK GUI) and \fI\%pyprof2calltree\fP (uses QCacheGrind or KCacheGrind for display) are supported alternatives and can be similarly installed with pip.
.UNINDENT
.SS Django
.sp
Elpy has basic Django support such as parsing either \fImanage.py\fP or \fIdjango\-admin.py\fP (If it
does not find \fImanage.py\fP it falls back to \fIdjango\-admin.py\fP) for command completion assistance.
Can also start \fIrunserver\fP automatically and you can give an ip address and port.
.INDENT 0.0
.TP
.B C\-c C\-x c (elpy\-django\-command)
Choose what command you\(aqd like to run via \fIdjango\-admin.py\fP or \fImanage.py\fP\&.
Please note that for compatibility reasons, the \fIshell\fP command will use
python (instead of ipython by default).
.UNINDENT
.INDENT 0.0
.TP
.B C\-c C\-x r (elpy\-django\-runserver)
Start the development server command, \fIrunserver\fP\&. Default arguments are \fI127.0.0.1\fP for
ip address and \fI8000\fP for port. These can be changed via \fBelpy\-django\-server\-ipaddr\fP and
\fBelpy\-django\-server\-port\fP\&.
.UNINDENT
.SH CONCEPTS
.SS The RPC Process
.sp
Elpy works by starting a Python process in the background and
communicating with it through a basic \fIRemote Procedure Call\fP (RPC)
interface. Ideally, you should never see this process and not worry
about it, but when things don\(aqt work as expected, it\(aqs good to know
what\(aqs going on in the background.
.sp
Every project and virtual env combination gets their own RPC process.
You can see them both in the process list (\fBM\-x list\-process\fP) as
well as in the buffer list (\fBC\-x C\-b\fP) as buffers named
\fB*elpy\-rpc[...]*\fP\&.
.sp
RPC processes are used to provide code completion, documentation and
other features. To do so, they use python packages (jedi, yapf, rope, ...)
that are installed in a dedicated virtualenv
(\fB\&.emacs.d/elpy/rpc\-venv\fP by default). Those packages can be updated
through the configuration panel (accessible with \fBM\-x
elpy\-config\fP).
.sp
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.
.sp
There are a few options and commands related to the RPC process.
.INDENT 0.0
.TP
.B M\-x elpy\-rpc\-restart
Close all running RPC processes. Elpy will re\-start them on demand
with current settings.
.UNINDENT
.INDENT 0.0
.TP
.B elpy\-rpc\-python\-command (Customize Option)
The Python interpreter Elpy should use to run the RPC process. This
defaults to \fB"python"\fP, which should be correct for most cases.
.sp
Please do note that this is \fInot\fP an interactive interpreter, so do
not set this to \fB"ipython"\fP, \fB"jupyter"\fP or similar.
.sp
As the RPC should be independent of any virtual environment, Elpy
will try to use the system interpreter if it exists. If you wish
to use a specific python interpreter (from a virtual environment
for example), set this to the full interpreter path.
.UNINDENT
.INDENT 0.0
.TP
.B elpy\-rpc\-virtualenv\-path (Customize Option)
Path to the virtualenv used by the RPC.
.sp
Can be \fI\(aqdefault\fP (create a dedicated virtualenv
\fB\&.emacs.d/elpy/rpc\-venv\fP), \fI\(aqsystem\fP (use the system
environment), \fI\(aqcurrent\fP (use the currently active environment), a
virtualenv path or a function returning a virtualenv path.
.sp
If the default virtual environment does not exist, it will be
created using \fIelpy\-rpc\-python\-command\fP and populated with the
needed packages from \fIelpy\-rpc\-\-get\-package\-list\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B elpy\-rpc\-large\-buffer\-size (Customize Option)
The size in character starting from which Elpy will transfer buffer
contents via temporary files instead of via the normal RPC
mechanism.
.sp
When Elpy communicates with the RPC process, it often needs to tell
Python about the contents of the current buffer. As the RPC
protocol encodes all data in JSON, this can be a bit slow for large
buffers. To speed things up, Elpy can transfer file contents in
temporary files, which is a lot faster for large files, but
slightly slower for small ones.
.UNINDENT
.INDENT 0.0
.TP
.B elpy\-rpc\-pythonpath (Customize Option)
A directory to add to the \fBPYTHONPATH\fP for the RPC process.
This should point to the directory where the \fBelpy\fP module is
installed. Usually, there is no need to change this.
.UNINDENT
.SS Backends
.sp
For introspection and analysis of Python sources, Elpy mainly relies
on \fI\%Jedi\fP, a python package for static code analysis.
.sp
Due to the dynamic nature of python and its minimalist structure syntax, python code can be difficult to understand in certain situations.
Jedi documentation provides some \fI\%tips\fP to make jedi job easier.
.SS Virtual Envs
.sp
Elpy has full support for Python\(aqs virtual envs. Every RPC process is
associated with a specific virtual env and completions are done based
on that environment.
.sp
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.
.INDENT 0.0
.TP
.B M\-x pyvenv\-workon
.UNINDENT
.INDENT 0.0
.TP
.B M\-x pyvenv\-activate
.UNINDENT
.INDENT 0.0
.TP
.B M\-x pyvenv\-deactivate
These commands are the main interaction point with virtual envs,
mirroring the normal \fBactivate\fP and \fBdeactivate\fP
commands of virtual envs and the \fBworkon\fP command of
\fBvirtualenvwrapper.sh\fP\&.
.sp
The \fI\%pyvenv\-workon\fP command will allow auto\-completion of
existing virtual envs and also supports virtualenvwrapper\(aqs setup
hooks to set environment variables.
.UNINDENT
.sp
Elpy won\(aqt pollute your Emacs command namespaces, but it might be an
idea to create an alias for the workon command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
(defalias \(aqworkon \(aqpyvenv\-workon)
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Modules
.sp
As the last concept, Elpy has a number of optional features you can
enable or disable as per your preferences.
.INDENT 0.0
.TP
.B elpy\-modules (Customize Option)
The list of modules to activate by default. See the section on
Writing Modules for details on how to write your own modules.
.UNINDENT
.SH EXTENDING ELPY
.SS Writing Modules
.sp
Modules are a way of easily extending Elpy with modular extensions. In
essence, a module is a function which is called once to initialize
itself globally, then once every time elpy\-mode is enabled or
disabled, and also once if elpy is disabled globally.
.sp
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:
.INDENT 0.0
.TP
.B \fBglobal\-init\fP
Called once, when Elpy is enabled using \fBelpy\-enable\fP\&.
.TP
.B \fBglobal\-stop\fP
Called once, when Elpy is disabled using \fBelpy\-disable\fP\&.
.TP
.B \fBbuffer\-init\fP
Called in a buffer when \fBelpy\-mode\fP is enabled.
.TP
.B \fBbuffer\-stop\fP
Called in a buffer when \fBelpy\-mode\fP is disabled.
.UNINDENT
.sp
To activate a module, the user has to add the function to
\fBelpy\-modules\fP\&.
.SS Writing Test Runners
.sp
A test runner is a function that receives four arguments, described in
the docstring of \fBelpy\-test\-at\-point\fP\&. If only the first
argument is given, the test runner should find tests under this
directory and run them. If the others are given, the test runner
should run the specified test only, or as few as it can.
.sp
Test runners should use an interactive spec of \fB(interactive
(elpy\-test\-at\-point))\fP so they can be called directly by the user.
For their main work, they can use the helper function
\fBelpy\-test\-run\fP\&. See the
\fBelpy\-test\-discover\-runner\fP for an example.
.sp
To make it possible to set the test runner as a file\-, directory\- or
project\-local variable, the function symbol should get the
\fBelpy\-test\-runner\fP property with a value of \fBt\fP\&.
.SS Running Tests:
.sp
You can set up a working environment for Elpy using \fBpip\fP and
\fBcask\fP\&. After installing \fI\%Cask\fP, create a new virtual environment
and run the \fBsetup\fP script in it:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
virtualenv ~/.virtualenvs/elpy
source ~/.virtualenvs/elpy/bin/activate
\&./scripts/setup
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
You can now run \fB\&./scripts/test\fP to run Elpy\(aqs test suite.
.sp
If you cannot (or do not want to) use virtual environments on your
system, you can set the environment variable
ELPY_TEST_DONT_USE_VIRTUALENV to skip tests involving virtual
environments: \fBELPY_TEST_DONT_USE_VIRTUALENV=t ./scripts/test\fP\&.
.SH CUSTOMIZATION TIPS
.SS Use flycheck instead of flymake
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
(when (load "flycheck" t t)
  (setq elpy\-modules (delq \(aqelpy\-module\-flymake elpy\-modules))
  (add\-hook \(aqelpy\-mode\-hook \(aqflycheck\-mode))
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Enable emacs 26 flymake indicators in an otherwise light modeline
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
(setq elpy\-remove\-modeline\-lighter t)

(advice\-add \(aqelpy\-modules\-remove\-modeline\-lighter
            :around (lambda (fun &rest args)
                      (unless (eq (car args) \(aqflymake\-mode)
                        (apply fun args))))
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
See also the \fI\%associated issue\fP
.SS Auto\-format code on save
.sp
Elpy allows you to auto\-format your code with \fBC\-c C\-r f\fP (\fBelpy\-format\-code\fP).
Many people find it useful to auto\-format their code automatically on save.
This can be achieved with the following snippet:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
(add\-hook \(aqelpy\-mode\-hook (lambda ()
                            (add\-hook \(aqbefore\-save\-hook
                                      \(aqelpy\-format\-code nil t)))
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The formatting function (\fBelpy\-format\-code\fP here) can be replaced with your prefered one.
For example to use black:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
(add\-hook \(aqelpy\-mode\-hook (lambda ()
                            (add\-hook \(aqbefore\-save\-hook
                                      \(aqelpy\-black\-fix\-code nil t)))
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Alternatives to \fBelpy\-goto\-definition\fP
.SS Fallback to rgrep
.sp
You may sometimes find when you try to navigate to a function/class definition with \fI\%elpy\-goto\-definition\fP (\fBM\-.\fP), that instead of jumping to the definition, you get the message "No definition found". If you see this error often (because of the nature of the code you work on), you can use the following function instead of/in addition to \fBelpy\-goto\-definition\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
(defun elpy\-goto\-definition\-or\-rgrep ()
  "Go to the definition of the symbol at point, if found. Otherwise, run \(gaelpy\-rgrep\-symbol\(aq."
    (interactive)
    (ring\-insert find\-tag\-marker\-ring (point\-marker))
    (condition\-case nil (elpy\-goto\-definition)
        (error (elpy\-rgrep\-symbol
                   (concat "\e\e(def\e\e|class\e\e)\es" (thing\-at\-point \(aqsymbol) "(")))))
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This function will try to find the definition of the symbol at point using \fBelpy\-goto\-definition\fP, but will do \fI\%elpy\-rgrep\-symbol\fP  instead, if the former function fails to return a result. You can bind this function to the key combination of your choice, or you can bind it to \fBM\-.\fP to use it as a replacement for the the default \fBgoto\-definition\fP function:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
(define\-key elpy\-mode\-map (kbd "M\-.") \(aqelpy\-goto\-definition\-or\-rgrep)
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Jumping to assignment
.sp
As an alternative to \fIelpy\-goto\-definition\fP, Elpy also provides the function \fI\%elpy\-goto\-assignment\fP that jumps to the line where the symbol at point has been assigned.
For functions and classes, it behaves roughly like \fIelpy\-goto\-definition\fP but has some advantages in certain situations (like if you want to jump to a decorated function).
You can try this alternative with the following code:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
(define\-key map (kbd "M\-.") \(aqelpy\-goto\-assignment
(define\-key map (kbd "C\-x 4 M\-.") \(aqelpy\-goto\-assignment\-other\-window)
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Enable full font locking of inputs in the python shell
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
(advice\-add \(aqelpy\-shell\-\-insert\-and\-font\-lock
            :around (lambda (f string face &optional no\-font\-lock)
                      (if (not (eq face \(aqcomint\-highlight\-input))
                          (funcall f string face no\-font\-lock)
                        (funcall f string face t)
                        (python\-shell\-font\-lock\-post\-command\-hook))))

(advice\-add \(aqcomint\-send\-input
            :around (lambda (f &rest args)
                      (if (eq major\-mode \(aqinferior\-python\-mode)
                          (cl\-letf ((g (symbol\-function \(aqadd\-text\-properties))
                                    ((symbol\-function \(aqadd\-text\-properties)
                                     (lambda (start end properties &optional object)
                                       (unless (eq (nth 3 properties) \(aqcomint\-highlight\-input)
                                         (funcall g start end properties object)))))
                            (apply f args))
                        (apply f args))))
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
See details in \fI\%https://github.com/jorgenschaefer/elpy/issues/1428\fP and \fI\%https://debbugs.gnu.org/cgi/bugreport.cgi?bug=32344\fP\&.
.SH FAQ
.SS Q: Can I tell elpy not to load one of the minor modes it enables by default?
.sp
\fBA:\fP You can simply remove the appropriate symbol from
\fBelpy\-modules\fP\&.
.SS Q: How do I make Elpy work well with org\-mode?
.sp
\fBA:\fP You can try the following customization by @mankoff:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
(setq python\-shell\-interpreter "ipython"
      python\-shell\-interpreter\-args "\-\-pylab=osx \-\-pdb \-\-nosep \-\-classic"
      python\-shell\-prompt\-regexp ">>> "
      python\-shell\-prompt\-output\-regexp ""
      python\-shell\-completion\-setup\-code "from IPython.core.completerlib import module_completion"
      python\-shell\-completion\-module\-string\-code "\(aq;\(aq.join(module_completion(\(aq\(aq\(aq%s\(aq\(aq\(aq))\en"
      python\-shell\-completion\-string\-code "\(aq;\(aq.join(get_ipython().Completer.all_completions(\(aq\(aq\(aq%s\(aq\(aq\(aq))\en")
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
See \fI\%#191\fP for a discussion and background.
.SS Q: Can I get documentation as pop\-ups next to the completion pop\-up?
.sp
\fBA:\fP Not by default with company\-mode, but there’s expez’ excellent
\fI\%company\-quickhelp\fP package you can install for this feature. It’s
available from MELPA.
.SS Q: How to solve company, yasnippet conflicts?
.sp
\fBA:\fP Add this snippet to your emacs configuration to avoid that.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
(defun company\-yasnippet\-or\-completion ()
  "Solve company yasnippet conflicts."
  (interactive)
  (let ((yas\-fallback\-behavior
         (apply \(aqcompany\-complete\-common nil)))
    (yas\-expand)))

(add\-hook \(aqcompany\-mode\-hook
          (lambda ()
            (substitute\-key\-definition
             \(aqcompany\-complete\-common
             \(aqcompany\-yasnippet\-or\-completion
             company\-active\-map)))
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Q: How do I install development version of elpy?
.sp
\fBA:\fP Remove existing elpy if you already installed it.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
rm \-rf ~/.emacs.d/elpa/elpy*
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Install dependencies
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
(package\-install \(aqcompany)
(package\-install \(aqyasnippet)
(package\-install \(aqpyvenv)
(package\-install \(aqhighlight\-indentation)
(package\-install \(aqs)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Get latest code from github
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mkdir ~/Projects
cd ~/Projects
git clone https://github.com/jorgenschaefer/elpy
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Add the following to your ~/.emacs.d/init.el or ~/.emacs:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
(add\-to\-list \(aqload\-path "~/Projects/elpy")
(load "elpy" nil t)
(elpy\-enable)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To update, run \fBgit pull \-\-rebase\fP, \fBM\-x load\-library RET elpy RET\fP and \fBM\-x elpy\-rpc\-reload\fP\&.
.INDENT 0.0
.IP \(bu 2
genindex
.IP \(bu 2
search
.UNINDENT
.SH AUTHOR
Jorgen Schäfer
.SH COPYRIGHT
2020, Jorgen Schäfer
.\" Generated by docutils manpage writer.
.