Find file History

README.org

Python layer

img/python.png

Table of Contents

Description

This layer adds support for the Python language.

Features

Install

Layer

To use this configuration layer, add it to your ~/.spacemacs. You will need to add python to the existing dotspacemacs-configuration-layers list in this file.

Dependencies

Auto-completion: Anaconda dependencies

anaconda-mode tries to install the dependencies itself but sometimes it does not work and you may encounter the following message when opening a python buffer:

Blocking call to accept-process-output with quit inhibited!!

To fix this, install the anaconda-mode anaconda-deps by hand:

pip install --upgrade "jedi>=0.9.0" "json-rpc>=1.8.1" "service_factory>=0.1.5"

Source: https://github.com/proofit404/anaconda-mode#issues

If you are facing errors such as “Unable to run anaconda-mode server”, try setting your PYTHONPATH as explained at https://github.com/proofit404/anaconda-mode#pythonpath

Syntax checking

Syntax checking uses `flake8` package:

pip install flake8

Test runner

Both nose and pytest are supported. By default nose is used. To choose your test runner set the layer variable python-test-runner to either nose or pytest.

(setq-default dotspacemacs-configuration-layers
  '((python :variables python-test-runner 'pytest)))

If you need both then you can set python-test-runner to a list like this:

(setq-default dotspacemacs-configuration-layers
  '((python :variables python-test-runner '(pytest nose))))

This means that pytest is your primary test runner. To use the secondary test runner you can call the test functions with a prefix argument e.g. SPC u SPC m t t to run one test with nose.

To set project specific test runners you can set python-test-runner in a directory local variable in your project root. SPC f v d in Spacemacs. See the official documentation for more information.

The root of the project is detected with a .git directory or a setup.cfg file.

Automatic buffer formatting on save

To enable automatic buffer formatting on save with YAPF set the variable python-enable-yapf-format-on-save to t.

(setq-default dotspacemacs-configuration-layers '(
  (python :variables python-enable-yapf-format-on-save t)))

autoflake

To be able to suppress unused imports easily, install autoflake:

pip install autoflake

pylookup

To use pylookup on SPC m h H, make sure you update the database first, using SPC SPC pylookup-update.

Hy-mode

To be able to connect to an inferior lisp repl in hy-mode, you need to make sure that hy is installed.

pip install hy

Management of Python versions and virtual environments

Manage virtual environments with pyvenv

A virtual environment provides isolation of your Python package versions. For a general overview see this site. Virtualenvwrapper which is also explained in the previous link, is a program which manages your virtual environments in a central location set by the WORKON_HOME environment variable.

Spacemacs integration of virtual environments and virtualenvwrapper is provided by the pyvenv package. It provides the following keybindings:

Key BindingDescription
SPC m V aactivate a virtual environment in any directory
SPC m V ddeactivate active virtual environment
SPC m V wwork on virtual environment in WORKON_HOME

Manage multiple Python versions with pyenv

If you need multiple Python versions (e.g. Python 2 and Python 3) then take a look at pyenv. It enables the installation and managment of multiple Python versions. This blogpost gives a good overview on how to use the tool. Spacemacs integration is provided by pyenv mode which has the following keybindings.

Key BindingDescription
SPC m v sset a pyenv environment with pyenv
SPC m v uunset a pyenv environment with pyenv

Pyenv can also manage virtual environments for each of the Python versions it has installed. Those will be listed alongside your Python versions.

Automatic activation of local pyenv version

A project-specific pyenv version may be written to a file called .python-version using the pyenv local command.

Spacemacs can search in parent directories for this file, and automatically set the pyenv version. The behavior can be set with the variable python-auto-set-local-pyenv-version to:

  • on-visit (default) set the version when you visit a python buffer,
  • on-project-switch set the version when you switch projects,
  • nil to disable.

The same is also possible on pyvenv with a file called .venv. The behavior can be set with the variable python-auto-set-local-pyvenv-virtualenv= to:

  • on-visit (default) set the virtualenv when you visit a python buffer,
  • on-project-switch set the virtualenv when you switch projects,
  • nil to disable.

Key Bindings

Inferior REPL process

Start a Python or iPython inferior REPL process with SPC m s i. If ipython is available in system executable search paths, ipython will be used to launch python shell; otherwise, default python interpreter will be used. You may change your system executable search path by activating a virtual environment.

Send code to inferior process commands:

Key BindingDescription
SPC m s bsend buffer and keep code buffer focused
SPC m s Bsend buffer and switch to REPL in insert mode
SPC m s fsend function and keep code buffer focused
SPC m s Fsend function and switch to REPL in insert mode
SPC m s istart inferior REPL process
SPC m s rsend region and keep code buffer focused
SPC m s Rsend region and switch to REPL in insert mode
CTRL+jnext item in REPL history
CTRL+kprevious item in REPL history

Running Python Script in shell

To run a Python script like you would in the shell press SPC m c c to start the Python script in comint mode. This is useful when working with multiple Python files since the REPL does not reload changes made in other modules.

Key BindingDescription
SPC m c cExecute current file in a comint shell
SPC m c CExecute current file in a comint shell and switch to it in insert state

Note: With the universal argument SPC u you can enter a new compilation command.

Testing

Test commands start with m t. To use the secondary test runner call the function with a prefix argument, for example SPC u SPC m t a.

No DebugDescription
SPC m t alaunch all tests of the project
SPC m t blaunch all tests of the current buffer (same as module)
SPC m t mlaunch all tests of the current module
SPC m t slaunch all tests of the current suite (only with nose)
SPC m t tlaunch the current test (function)
DebugDescription
SPC m t Alaunch all tests of the project in debug mode
SPC m t Blaunch all tests of the current buffer (module) in debug mode
SPC m t Mlaunch all tests of the current module in debug mode
SPC m t Slaunch all tests of the current suite in debug mode (only with nose)
SPC m t Tlaunch the current test (function) in debug mode

Refactoring

Key BindingDescription
SPC m r iremove unused imports with autoflake
SPC m r Isort imports with isort

Live coding

Live coding is provided by the live-py-plugin.

Key BindingDescription
SPC m lToggle live-py-mode

Hy REPL process

Start a Hy inferior repel process with SPC m s i. If hy is available in system executable search paths, hy will be used to launch the shell. You may change your system executable search path by activating a virtual enviornment.

Send code to hy REPL commands:

Key BindingDescription
SPC m s bsend buffer and keep code buffer focused
SPC m s Bswitch to REPL
SPC m s esend sexp in front of the cursor to the REPL
SPC m s fsend function to REPL and stay in buffer
SPC m s Fsend function to REPL and switch to repl buffer
SPC m s istart inferior hy repl
SPC m s rsend current region to the REPL and stay in buffer
SPC m s Rsend current region to the REPL and switch to repl buffer

Other Python commands

Key BindingDescription
SPC m =Reformat the buffer according to PEP8 using YAPF
SPC m d btoggle a breakpoint using wdb, ipdb, pudb or pdb
SPC m g ggo to definition using anaconda-mode-find-definitions (C-o to jump back)
SPC m g ago to assignment using anaconda-mode-find-assignments (C-o to jump back)
SPC m g bjump back
SPC m g unavigate between usages with anaconda-mode-find-references
SPC m h dlook for documentation using helm-pydoc
SPC m h hquick documentation using anaconda
SPC m h Hopen documentation in firefox using pylookup
SPC m v sset a pyenv environment with pyenv
SPC m v uunset a pyenv environment with pyenv
SPC m V wwork on virtual environment in WORKON_HOME
SPC m V aactivate a virtual environment in any directory
SPC m V ddeactivate active virtual environment

Configuration

Fill column

If you want to customize the fill column value, use something like this inside the user-init function in your .spacemacs:

(setq-default dotspacemacs-configuration-layers '(
    (python :variables python-fill-column 99)))

Sort imports

If you want imports to be automatically sorted when you save a file (using isort), set the python-sort-imports-on-save variable in the python layer config section:

(setq-default dotspacemacs-configuration-layers
  '((python :variables python-sort-imports-on-save t)))

or as a directory-local variable (for per-project settings).