doomemacs/modules/lang/python/README.org

:lang python

• Description
  • Maintainers
  • Module flags
  • Packages
  • Hacks
  • Changelog
• Installation
  • Language Server Protocol Support
  • Formatter
• Usage
  • Keybindings
• Configuration
• Troubleshooting
• Frequently asked questions
• Appendix

Description   unfold

This module adds Python support to Doom Emacs.

• Syntax checking (doom-package:flycheck)
• Snippets
• Run tests (doom-package:nose, doom-package:pytest)
• Auto-format (with black, requires doom-module::editor format)
• LSP integration (pyls, jedi, ruff, pyright, or basedpyright)

Maintainers

• @hlissner

Become a maintainer?

Module flags

+conda

Enable python virtual environment support via Conda.

+cython

Enable support for Cython files support.

+lsp

Enable LSP support for python-mode and python-ts-mode. Requires doom-module::tools lsp and an LSP server (e.g. ty (recommended), pyright, basedpyright, jedi, ruff).

+poetry

Enable Python packaging, dependency management, and virtual environment support via Poetry.

+pyenv

Enable Python virtual environment support via pyenv. Cannot be used together with doom-module:+uv.

+pyright

Add support for the pyright LSP server (requires doom-module:+lsp).

+tree-sitter

Leverages tree-sitter for better syntax highlighting and structural text editing. Requires doom-module::tools tree-sitter. Support is much improved on Emacs 30 and newer.

+uv

Enable Python virtual environment support via uv. Cannot be used together with doom-module:+pyenv.

Packages

• doom-package:conda if doom-module:+conda
• doom-package:nose
• doom-package:pipenv
• doom-package:pip-requirements
• doom-package:poetry if doom-module:+poetry
• doom-package:pyenv if doom-module:+pyenv
• doom-package:uvenv if doom-module:+uv
• doom-package:pyimport
• doom-package:py-isort
• doom-package:python-pytest

• if doom-module:+cython

  • doom-package:cython-mode
  • doom-package:flycheck-cython if doom-module::checkers syntax

• if doom-module:+lsp

  • if doom-module:+pyright

    • doom-package:lsp-pyright

Hacks

No hacks documented for this module.

TODO Changelog

This module does not have a changelog yet.

Installation

Enable this module in your doom! block.

This module has no hard requirements, but softly depends on:

• For this module's supported test runners:

  • $ pip install pytest
  • $ pip install nose
• The doom-module::editor format module uses Black for python files: $ pip install black
• doom-package:pyimport requires Python's module pyflakes: $ pip install pyflakes
• doom-package:py-isort requires isort to be installed: pip install isort

• Python virtual environments install instructions at:

  • pyenv
  • uv
  • Conda
  • Poetry
  • pipenv
• cython requires Cython

Language Server Protocol Support

For LSP support the doom-module::tools lsp module must be enabled, along with this module's doom-module:+lsp flag. It supports anything that lsp-mode and Eglot support. ty is recommended. Some can be installed from within Emacs using M-x lsp-install-server, others are available through OS package managers or pip. E.g.

ty

$ pip install ty

basedpyright

$ pip install basedpyright

pyright

$ pip install pyright or $ npm i -g pyright.

If you have multiple LSP servers installed and on your $PATH, lsp-mode and eglot prioritizes which will be used depending on the client's :priority (in lsp-mode) or their order in eglot-server-programs.

To prioritize ty:

;;; add to $DOOMDIR/config.el

;; for eglot users
(with-eval-after-load 'python
  (set-eglot-client! '(python-mode python-ts-mode) '("ty" "server")))

;; Not necessary for lsp-mode users, because `ty-ls' is already priority = -1
;; (lower = higher priority). Including this for posterity:
(with-eval-after-load 'python
  (set-lsp-priority! 'ty-ls -5)) ; default is -1

Formatter

Formatting is handled by the doom-module::editor format module. Python buffers use black, by default. ruff is also supported:

;;; Add to $DOOMDIR/config.el
(with-eval-after-load 'python
  (set-formatter! 'ruff :modes '(python-mode python-ts-mode)))

Formatters can also be set per-project in a .dir-locals.el file or file-local variables. See doom-module::editor format's documentation for details.

TODO Usage

󱌣 This module's usage documentation is incomplete. Complete it?

This module supports LSP. It requires an LSP server, like ty (recommended). See [[Language Server Protocol Support][LSP Support]].

To enable support for auto-formatting with black enable [[doom-module::editor format]].

Keybindings

Binding	Description
<localleader> c c	Compile Cython buffer
<localleader> i i	Insert missing imports
<localleader> i r	Remove unused imports
<localleader> i s	Sort imports
<localleader> i o	Optimize imports
<localleader> t r	nosetests-again
<localleader> t a	nosetests-all
<localleader> t s	nosetests-one
<localleader> t v	nosetests-module
<localleader> t A	nosetests-pdb-all
<localleader> t O	nosetests-pdb-one
<localleader> t V	nosetests-pdb-module
<localleader> t f	python-pytest-file
<localleader> t k	python-pytest-file-dwim
<localleader> t t	python-pytest-function
<localleader> t m	python-pytest-function-dwim
<localleader> t r	python-pytest-repeat
<localleader> t p	python-pytest-popup

TODO Configuration

󱌣 This module's configuration documentation is incomplete. Complete it?

The arguments passed to the ipython or jupyter shells can be altered through these two variables:

;; in $DOOMDIR/config.el
(setq +python-ipython-repl-args '("-i" "--simple-prompt" "--no-color-info"))
(setq +python-jupyter-repl-args '("--simple-prompt"))

Troubleshooting

There are no known problems with this module. Report one?

Frequently asked questions

This module has no FAQs yet. Ask one?

TODO Appendix

󱌣 This module has no appendix yet. Write one?