#+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]]
- +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.

** 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]]

** 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. 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
(after! 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:
(after! 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
(after! 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