Python layer

• Support for the following backends:
  • anaconda (default),
  • Language Server Protocol (experimental - 2 implementations),
    • python-lsp-server
    • Microsoft pyright language server
• Auto-completion
• Code Navigation
• Documentation Lookup using anaconda-mode and pylookup
• Test Runners using pytest or nose.el
• Virtual Environment using pyvenv and pyenv as well as pipenv, poetry, and UV
• semantic mode is enabled
• PEP8 compliant formatting via YAPF, black, or ruff
• PEP8 checks with flake8 or pylint
• Suppression of unused import with autoflake
• Use the % key to jump between blocks with evil-matchit
• Sort imports with isort
• Fix a missing import statement with importmagic
• Pip package manager with pippel
• Interactive debugger using dap-mode
• Support for ipython notebook and MATLAB-like cells using using code-cells

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.

To choose a default backend set the layer variable python-backend:

(python :variables python-backend 'anaconda)

Alternatively the lsp backend will be automatically chosen if the layer lsp is used and you did not specify any value for python-backend.

Backend can be chosen on a per project basis using directory local variables (files named .dir-locals.el at the root of a project), an example to use the lsp backend:

;;; Directory Local Variables
;;; For more information see (info "(emacs) Directory Variables")

((python-mode (python-backend . lsp)))

Note: you can easily add a directory local variable with SPC f v d.

The available options are:

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.13.0" "json-rpc>=1.8.1" "service_factory>=0.1.5"

If you encounter problems with Jedi 1.0 consider downgrading to 0.13.0. See this issue for details.

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

The lsp backend can use either of the following language server implementations:

pylsp is default value for python-lsp-server, an example for use pylsp:

(python :variables python-backend 'lsp)

To use the Microsoft pyright language server, set the python-lsp-server layer variable as follows:

(python :variables python-backend 'lsp python-lsp-server 'pyright)

Syntax checking uses flake8 package:

pip install flake8

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

(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.

One of YAPF, black, ruff or lsp may be selected as the formatter, via python-formatter, as yapf, black, ruff or lsp respectively.

(setq-default dotspacemacs-configuration-layers '(
  (python :variables python-formatter 'yapf)))

The default python-formatter is yapf, with the following exception: When both the lsp layer is used, and python-lsp-server is pylsp, the default formatter is lsp.

Note that the pyright language server does not support formatting, but it can be used alongside with ruff, which does support it.

The key binding SPC m = invokes the selected formatter on the current buffer when in non LSP python mode otherwise SPC m == is used.

Note that a specific formatter may also be invoked unconditionally via yapfify-buffer, blacken-buffer, ruff-format-buffer or lsp-format-buffer, provided these are installed.

To enable automatic buffer formatting on save set the variable python-format-on-save to t. The formatter specified by python-formatter will be used.

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

By default a buffer is automatically saved before tests are executed upon it, you can disable this feature by setting python-save-before-test to nil.

(setq-default dotspacemacs-configuration-layers '(
  (python :variables python-save-before-test nil)))

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

pip install autoflake

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

To use dap-mode for debugging do:

pip install debugpy

To use code-cells-mode with ipython notebook automatically you should install jupytext. Make sure that the ipython-notebook layer is not used.

Then you can evaluate the current cell in a REPL process with SPC m s c or all the cells above with SPC m s a. You can also move to the next cell with SPC m g F and to the previous cell with SPC m g B.

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)))

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).

Install importmagic and epc for importmagic functionality, it will start a epc instance on background to serve the requests.

The importmagic is a heavy feature, will take time to prepare the background server, especially slow with ipython or ipython3, set the importmagic-python-interpreter to python or python3 (if it is the interpreter of ipython) will have performance benefit. Fox example:

(setq-default dotspacemacs-configuration-layers
  '((python :variables importmagic-python-interpreter "python3")))

To disable the importmagic, set the python-enable-importmagic in the python layer config section:

(setq-default dotspacemacs-configuration-layers
  '((python :variables python-enable-importmagic nil)))

pip install importmagic epc

Sometimes, it is convenient to be able to use python virtual environments from other modes. For this reason, the python layer provides the variables spacemacs--python-pyenv-modes, spacemacs--python-pyvenv-modes, spacemacs--python-poetry-modes and spacemacs--python-pipenv-modes. If you wish to be able to access these functionalities from other modes, in your user config section, do:

(add-to-list 'spacemacs--python-pipenv-modes 'your-mode)

This will allow you to use pipenv bindings from the mode your-mode. You can add to the other two lists analogously.

To enable the pet-mode, set the variable python-virtualenv-management to pet, for example:

(setq-default dotspacemacs-configuration-layers '(
  (python :variables python-virtualenv-management 'pet)))

In general virtual environments are automatically used when active using pet-mode, following additional packages are high recommended to enable full pet-mode features:

Independent of this you can activate and switch virtual environments manually with below tools.

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 key bindings:

If you need multiple Python versions (e.g. Python 2 and Python 3) then take a look at pyenv. It enables the installation and management 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 key bindings.

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

Pipenv is the new standard tool to manage your virtual environments. It can act as a replacement for both pyenv and venv on a per-repository basis. An overview of how to use the tool is provided here.

Spacemacs integration for pipenv is provided by the pipenv package. It provides the following key bindings:

Poetry is a tool for dependency management and packaging in Python. It allows you to declare the libraries your project depends on and it will manage (install/update) them for you.

Spacemacs integration for Poetry is provided by the poetry package. It provides the following key bindings:

UV is a fast Python package installer and resolver written in Rust. It's designed to be a drop-in replacement for pip and pip-tools, offering significantly faster package installation and dependency resolution.

Spacemacs integration for UV is provided by the uv.el package. It provides the following key bindings:

To enable UV support, add uv to your python-enable-tools list:

(setq-default dotspacemacs-configuration-layers
              '((python :variables python-enable-tools '(uv))))

Note: You need to install the uv command-line tool first. See the UV documentation for installation instructions.

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:

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.

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

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.

In python buffer type SPC m P to open buffer listing all installed pip packages in the currently activated virtual environment.

Note: To open this menu from outside a python buffer type SPC SPC pippel-list-packages RET.

In the package list buffer:

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

Using the dap layer you'll get access to all the DAP key bindings, see the complete list of key bindings on the dap layer description.