mirror of
https://github.com/doomemacs/doomemacs.git
synced 2026-03-09 16:21:11 -07:00
6f40ad55f5
There's little reason for users to use these macros in their private configs over plain ol' `with-eval-after-load` and `use-package`, unless they're writing their own modules. It's my fault for signal boosting them in documentation and whenever I'm asked for help, because beginners now believe they are somehow required for Doom to work correctly (there are guides out there telling beginners that migrating to Doom involves replacing all instances of `with-eval-after-load` and `use-package` in their pre-existing configs with `after!` and `use-package!` -- which was never true). What's more, I plan to replace `use-package`, internally, so the `use-package!` macro won't exist for much longer.
187 lines
7.5 KiB
Org Mode
187 lines
7.5 KiB
Org Mode
#+title: :lang python
|
|
#+subtitle: Beautiful is better than ugly
|
|
#+created: June 15, 2015
|
|
#+since: 0.7
|
|
|
|
* Description :unfold:
|
|
This module adds [[https://www.python.org/][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
|
|
- [[doom-user:][@hlissner]]
|
|
|
|
[[doom-contrib-maintainer:][Become a maintainer?]]
|
|
|
|
** Module flags
|
|
- +conda ::
|
|
Enable python virtual environment support via [[https://conda.io/en/latest/][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 [[https://python-poetry.org/][Poetry]].
|
|
- +pyenv ::
|
|
Enable Python virtual environment support via [[https://github.com/pyenv/pyenv][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 [[https://github.com/astral-sh/uv][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 section will be machine generated. Don't edit it by hand.
|
|
/This module does not have a changelog yet./
|
|
|
|
* Installation
|
|
[[id:01cffea4-3329-45e2-a892-95a384ab2338][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 [[https://github.com/timothycrosley/isort][isort]] to be installed: ~pip install isort~
|
|
- Python virtual environments install instructions at:
|
|
- [[https://github.com/pyenv/pyenv][pyenv]]
|
|
- [[https://github.com/astral-sh/uv][uv]]
|
|
- [[https://conda.io/en/latest/][Conda]]
|
|
- [[https://python-poetry.org/][Poetry]]
|
|
- [[https://pipenv.readthedocs.io/en/latest/][pipenv]]
|
|
- ~cython~ requires [[https://cython.org/][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. [[https://github.com/astral-sh/ty][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.
|
|
|
|
- [[https://docs.astral.sh/ty/installation][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~:
|
|
#+begin_src elisp
|
|
;;; 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
|
|
#+end_src
|
|
|
|
** Formatter
|
|
Formatting is handled by the [[doom-module::editor format]] module. Python buffers
|
|
use [[https://black.readthedocs.io/en/stable/getting_started.html#installation][black]], by default. [[https://github.com/astral-sh/ruff][ruff]] is also supported:
|
|
#+begin_src elisp
|
|
;;; Add to $DOOMDIR/config.el
|
|
(with-eval-after-load 'python
|
|
(set-formatter! 'ruff :modes '(python-mode python-ts-mode)))
|
|
#+end_src
|
|
|
|
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
|
|
#+begin_quote
|
|
/This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
|
|
#+end_quote
|
|
|
|
This module supports LSP. It requires an LSP server, like [[https://github.com/astral-sh/ty][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 |
|
|
|-------------------+-----------------------------|
|
|
| [[kbd:][<localleader> c c]] | ~Compile Cython buffer~ |
|
|
| [[kbd:][<localleader> i i]] | ~Insert missing imports~ |
|
|
| [[kbd:][<localleader> i r]] | ~Remove unused imports~ |
|
|
| [[kbd:][<localleader> i s]] | ~Sort imports~ |
|
|
| [[kbd:][<localleader> i o]] | ~Optimize imports~ |
|
|
| [[kbd:][<localleader> t r]] | ~nosetests-again~ |
|
|
| [[kbd:][<localleader> t a]] | ~nosetests-all~ |
|
|
| [[kbd:][<localleader> t s]] | ~nosetests-one~ |
|
|
| [[kbd:][<localleader> t v]] | ~nosetests-module~ |
|
|
| [[kbd:][<localleader> t A]] | ~nosetests-pdb-all~ |
|
|
| [[kbd:][<localleader> t O]] | ~nosetests-pdb-one~ |
|
|
| [[kbd:][<localleader> t V]] | ~nosetests-pdb-module~ |
|
|
| [[kbd:][<localleader> t f]] | ~python-pytest-file~ |
|
|
| [[kbd:][<localleader> t k]] | ~python-pytest-file-dwim~ |
|
|
| [[kbd:][<localleader> t t]] | ~python-pytest-function~ |
|
|
| [[kbd:][<localleader> t m]] | ~python-pytest-function-dwim~ |
|
|
| [[kbd:][<localleader> t r]] | ~python-pytest-repeat~ |
|
|
| [[kbd:][<localleader> t p]] | ~python-pytest-popup~ |
|
|
|
|
* TODO Configuration
|
|
#+begin_quote
|
|
/This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
|
|
#+end_quote
|
|
|
|
The arguments passed to the [[https://ipython.org/][ipython]] or [[https://jupyter.org/][jupyter]] shells can be altered through
|
|
these two variables:
|
|
#+begin_src emacs-lisp
|
|
;; in $DOOMDIR/config.el
|
|
(setq +python-ipython-repl-args '("-i" "--simple-prompt" "--no-color-info"))
|
|
(setq +python-jupyter-repl-args '("--simple-prompt"))
|
|
#+end_src
|
|
|
|
* Troubleshooting
|
|
/There are no known problems with this module./ [[doom-report:][Report one?]]
|
|
|
|
* Frequently asked questions
|
|
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
|
|
|
|
* TODO Appendix
|
|
#+begin_quote
|
|
This module has no appendix yet. [[doom-contrib-module:][Write one?]]
|
|
#+end_quote
|