158 lines
6.9 KiB
Org Mode
158 lines
6.9 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 (=mspyls=, =pyls=, or =pyright=)
|
|
|
|
** 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~. Requires [[doom-module::tools lsp]] and a langserver
|
|
(supports mspyls, pyls, and pyright).
|
|
- +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]]
|
|
- +pyright ::
|
|
Use the pyright LSP server instead of mspyls or pyls (requires [[doom-module:+lsp]]).
|
|
- +tree-sitter ::
|
|
Leverages tree-sitter for better syntax highlighting and structural text
|
|
editing. Requires [[doom-module::tools tree-sitter]].
|
|
|
|
** Packages
|
|
- [[doom-package:anaconda-mode]]
|
|
- [[doom-package:conda]]
|
|
- [[doom-package:nose]]
|
|
- [[doom-package:pipenv]]
|
|
- [[doom-package:pip-requirements]]
|
|
- [[doom-package:poetry]] if [[doom-module:+poetry]]
|
|
- [[doom-package:pyenv]]
|
|
- [[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]]
|
|
- else
|
|
- [[doom-package:lsp-python-ms]]
|
|
|
|
** Hacks
|
|
- [[doom-package:anaconda-mode]] is configured to activate when [[doom-package:lsp-mode]] (or [[doom-package:eglot]]) don't -- or
|
|
fail to.
|
|
|
|
** 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://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. By default, it supports [[doom-package:mspyls]] and [[doom-package:pyls]], in that order. With the
|
|
[[doom-module:+pyright]] flag, it will try Pyright first.
|
|
|
|
An alternative LSP server can be used by installing them through the
|
|
[[cmd:][lsp-install-server]] command, or an external package manager. For example:
|
|
- To install [[https://pypi.org/project/python-language-server/][*pyls*]]: ~$ pip install python-language-server[all]~.
|
|
- To install *mspyls*: ~M-x lsp-install-server RET mspyls~.
|
|
- To install *pyright*: ~$ pip install pyright~ or ~$ npm i -g pyright~.
|
|
|
|
** Formatter
|
|
|
|
Formatting is handled using the [[doom-module::editor format]] module via [[https://black.readthedocs.io/en/stable/getting_started.html#installation][black]].
|
|
|
|
* TODO Usage
|
|
#+begin_quote
|
|
/This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
|
|
#+end_quote
|
|
|
|
This module supports LSP. It requires installation of [[https://pypi.org/project/python-language-server/][Python Language Server]],
|
|
[[https://github.com/Microsoft/python-language-server][Microsoft Language Server]], or [[https://github.com/microsoft/pyright][pyright]], 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~ |
|
|
| [[kbd:][<localleader> g d]] | ~anaconda-mode-find-definitions~ |
|
|
| [[kbd:][<localleader> g h]] | ~anaconda-mode-show-doc~ |
|
|
| [[kbd:][<localleader> g a]] | ~anaconda-mode-find-assignments~ |
|
|
| [[kbd:][<localleader> g f]] | ~anaconda-mode-find-file~ |
|
|
| [[kbd:][<localleader> g u]] | ~anaconda-mode-find-references~ |
|
|
|
|
* 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
|