gav451/emacs.d
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Improve the documentation of the Python setup

Browse Source
This commit is contained in:
Gerard Vermeulen 2021-12-28 08:37:13 +01:00
parent 9f51a5c599
commit b04c75545c
1 changed files with 49 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

63
README.org
View File

@ -1605,11 +1605,13 @@ built-in ~python-mode~. Here, the focus is on two packages:
into [[https://sheer.tj/the_way_of_emacs.html][the Way of Emacs]] as this discussion on [[https://github.com/joaotavora/eglot/issues/523][org-mode source code blocks]]
shows.
2. [[https://github.com/pythonic-emacs/anaconda-mode][Anaconda - code navigation, documentation lookup, and completion for Python]].
In my opinion, [[https://github.com/joaotavora/eglot][eglot]] has more potential than [[https://github.com/pythonic-emacs/anaconda-mode][anaconda]], but [[https://github.com/pythonic-emacs/anaconda-mode][anaconda]] is
compatible with [[info:org#Editing Source Code][source code block editing]] while [[https://github.com/joaotavora/eglot][eglot]] is not. Listing
[[lst:configure-python]] configures [[https://www.python.org][Python]].
#+caption[Configure =python=]:
#+caption: Configure =python=.
#+label: lst:configure-python
#+name: lst:configure-python
#+begin_src elisp
(with-eval-after-load 'python
(custom-set-variables
@ -1617,27 +1619,48 @@ built-in ~python-mode~. Here, the focus is on two packages:
'(python-shell-interpreter-args "-i -E")))
#+end_src
Listing [[lst:configure-eglot-for-python]] configures [[https://github.com/joaotavora/eglot][eglot]] for [[https://www.python.org][Python]]. It may be a
good idea to launch [[https://github.com/joaotavora/eglot][eglot]] by means of [[info:emacs#Directory Variables][directory variables]] in the root directory
of any [[https://www.python.org][Python]] project. Listing [[lst:eglot-directory-variables-for-python]] does a
proposal.
#+caption[Configure =eglot= for Python]:
#+caption: Configure =eglot= for Python.
#+label: lst:configure-eglot-for-python
#+name: lst:configure-eglot-for-python
#+begin_src emacs-lisp
(with-eval-after-load 'eglot
(add-to-list 'eglot-server-programs '(python-mode "pylsp"))
(setq-default
eglot-workspace-configuration
`((:pylsp . (:plugins (:jedi_completion (:eager nil))))
(:pylsp . (:plugins (:jedi_completion (:cache_for ,(vconcat '("astropy"
"numpy"
"scipy")))))))))
`((:pylsp . (:plugins (:jedi_completion
(:cache_for ,(vconcat '("astropy"
"numpy"
"scipy"))))))
(:pylsp . (:plugins (:jedi_completion (:eager nil)))))))
#+end_src
The snippet below initializes [[https://github.com/pythonic-emacs/anaconda-mode][anaconda]]. See [[https://github.com/jorgenschaefer/elpy/blob/8d0de310d41ebf06b22321a8534546447456870c/elpy.el#L2775][elpy-module-company]] for how to
handle ~company-backends~ as a local variable and the call to [[info:elisp#Advising Functions][advice-add]] opens
Python org-mode edit-buffers in ~anaconda-mode~.
#+caption[Propose =directory-variables= to launch =eglot=]:
#+caption: Propose =directory-variables= in the root of any Python project to
#+caption: launch =eglot=.
#+name: lst:eglot-directory-variables-for-python
#+begin_src emacs-lisp :tangle no
;; Proposal for a .dir-locals.el file in the root of any Python project.
((python-mode
. ((eglot-workspace-configuration
. `((:pylsp . (:plugins (:jedi_completion
(:cache_for ,(vconcat '("astropy"
"numpy"
"scipy"))))))
(:pylsp . (:plugins (:jedi_completion (:eager nil)))))))))
#+end_src
Listing [[lst:configure-anaconda-for-python]] configures [[https://github.com/pythonic-emacs/anaconda-mode][anaconda]]. See
[[https://github.com/jorgenschaefer/elpy/blob/8d0de310d41ebf06b22321a8534546447456870c/elpy.el#L2775][elpy-module-company]] for how to handle ~company-backends~ as a local variable and
the call to [[info:elisp#Advising Functions][advice-add]] opens Python org-mode edit-buffers in ~anaconda-mode~.
#+caption[Configure =anaconda= for Python]:
#+caption: Configure =anaconda= for Python.
#+label: lst:configure-anaconda-for-python
#+name: lst:configure-anaconda-for-python
#+begin_src emacs-lisp
(with-eval-after-load 'python
(with-eval-after-load 'company
@ -1688,9 +1711,16 @@ Python org-mode edit-buffers in ~anaconda-mode~.
(my-enable-anaconda-mode)))))
#+end_src
Listing [[lst:example-py]] is a [[https://www.python.org][Python]] example showing differences in the handling
of compiled foreign language modules and pure [[https://www.python.org][Python]] modules. The underlying
[[https://jedi.readthedocs.io/en/latest/][jedi]] library parses modules (instead of imports) in order to handle completion
and documentation request. Therefore, [[https://jedi.readthedocs.io/en/latest/][jedi]] and consequently [[https://github.com/joaotavora/eglot][eglot]] as well as
[[https://github.com/pythonic-emacs/anaconda-mode][anaconda]] treat compiled foreign language modules as second zone citizens. This
is noticible when coding certain functions of for instance [[https://numpy.org/][numpy]] and [[https://scipy.org/][scipy]].
#+caption[Tangle the =example.py= file]:
#+caption: Tangle the =example.py= file.
#+label: lst:example-py
#+name: lst:example-py
#+begin_src python :tangle example.py :comments link
import numpy
import astropy.units as apu
@ -1701,9 +1731,11 @@ Python org-mode edit-buffers in ~anaconda-mode~.
print(q)
#+end_src
Listing [[lst:enable-pyenv-mode]] configures and enables =pyenv-mode=.
#+caption[Enable =pyenv-mode=]:
#+caption: Enable =pyenv-mode=.
#+label: lst:enable-pyenv-mode
#+name: lst:enable-pyenv-mode
#+begin_src emacs-lisp
(when (and (executable-find "pyenv")
(require 'pyenv-mode nil 'noerror))
@ -1711,9 +1743,12 @@ Python org-mode edit-buffers in ~anaconda-mode~.
(pyenv-mode-set "3.9.9/envs/python-3.9.9"))
#+end_src
Listing [[lst:configure-info]] adds a path in my home directory to the places where
=info= looks for files.
#+caption[Configure =info=]:
#+caption: Configure =info=.
#+label: lst:configure-info
#+name: lst:configure-info
#+begin_src emacs-lisp
(with-eval-after-load 'info
(add-to-list 'Info-directory-list