py-vterm-interaction.el/README.org

99 lines
5 KiB
Org Mode
Raw Normal View History

2020-10-04 14:57:18 +09:00
# -*- eval: (visual-line-mode 1) -*-
#+STARTUP: showall
2024-05-11 16:29:05 -04:00
*This* is a straight port of [[https://github.com/shg/julia-vterm.el][julia-vterm.el]]. I only modified the code slightly to deal correctly with python environments
and play nicely with =ipython=.
2020-10-04 14:57:18 +09:00
2024-05-11 16:29:05 -04:00
* python-vterm
2024-05-11 16:29:05 -04:00
Python-vterm provides a major-mode for an inferior Python process (or REPL) that runs in vterm, and a minor-mode that extends python-mode with the ability to interact with the inferior Python process. This is particularly useful for *fancy repls like =ipython= or =ptpython=*.
2020-10-04 14:57:18 +09:00
2022-07-07 08:21:15 +09:00
The functionalities required for typical REPL interaction have been implemented. While I would like to keep this package simple, suggestions are always welcome.
2020-10-04 14:57:18 +09:00
2024-05-11 16:29:05 -04:00
If you want to use Python with [[https://orgmode.org/worg/org-contrib/babel/][Org Babel]], please consider trying [[https://github.com/shg/ob-python-vterm.el][ob-python-vterm]]. It uses python-vterm and provides a solid babel development experience with session and asynchronous execution support.
2020-10-04 14:57:18 +09:00
2020-10-07 19:26:30 +09:00
** Installation
2024-05-11 16:29:05 -04:00
You can install this package from MELPA. The package name is “python-vterm”.
2024-05-11 16:29:05 -04:00
For manual installation, download =python-vterm.el= into somewhere in your local directory and use =package-install-file= command. Please make sure [[https://github.com/PythonEditorSupport/python-emacs][python-mode]] and [[https://github.com/akermu/emacs-libvterm][emacs-libvterm]] are installed and configured correctly.
2020-10-09 10:05:26 +09:00
2024-05-11 16:29:05 -04:00
Turn on =python-vterm-mode= in a =python-mode= buffer to use this package. A symbol “⁂” in the mode line indicates that the python-mode buffer is ready to interact with the python-vterm REPL. Add the following line to your init file to enable =python-vterm-mode= in =python-mode= buffers automatically.
2020-10-09 10:05:26 +09:00
#+BEGIN_SRC emacs-lisp
2024-05-11 16:29:05 -04:00
(add-hook 'python-mode-hook #'python-vterm-mode)
2020-10-07 19:26:30 +09:00
#+END_SRC
2024-05-11 16:29:05 -04:00
By default, the command named =python= in your =PATH= is used. You can use a Python executable in any path by setting the =python-vterm-repl-program= variable to its absolute path. The variable can contain switches for the =python= command. For example, you can use a =python= executable at a certain path, with 4 threads enabled, by the line like the following.
2021-04-28 01:30:38 -06:00
#+BEGIN_SRC emacs-lisp
2024-05-11 16:29:05 -04:00
(setq python-vterm-repl-program "ipython -i")
2021-04-28 01:30:38 -06:00
#+END_SRC
2020-10-07 19:26:30 +09:00
** How to use
2024-05-11 16:29:05 -04:00
=M-x python-vterm-repl= (or =M-x python= if no other packages define it before python-vterm is loaded) opens an inferior Python REPL buffer.
2022-07-07 08:21:15 +09:00
2024-05-11 16:29:05 -04:00
In a python script buffer with =python-vterm-mode= on, you can open a Python REPL with =M-x python-vterm-switch-to-repl-buffer= (or =C-c C-z=). See below for other commands.
Both of the above operations open a REPL with the default session name =main=. You can specify a different session name by using the prefix argument =C-u=. A new session will be created and opened if there is no REPL with that session name.
2024-05-11 16:29:05 -04:00
You can also specify a session name by defining a file local variable =python-vterm-session= (or =python-session= if no other packages pre-define it). If the variable is defined, =C-c C-z= will open a REPL with that session name.
2020-10-07 19:26:30 +09:00
** Key bindings
2024-05-11 16:29:05 -04:00
*** python-vterm-mode
2022-07-06 19:38:00 +09:00
#+begin_example
Key Command / Description
2022-07-07 23:48:56 +09:00
------------------------------------------------------------------------------------------
2024-05-11 16:29:05 -04:00
C-c C-z python-vterm-switch-to-repl-buffer
2022-07-06 19:38:00 +09:00
Switch to the paired REPL buffer or to the one with a specified session name.
With prefix ARG, prompt for session name.
2024-05-11 16:29:05 -04:00
C-c C-c python-vterm-send-region-or-current-line
2022-07-07 23:48:56 +09:00
Send the content of the region if the region is active, or send the current
line.
2022-07-06 19:38:00 +09:00
2024-05-11 16:29:05 -04:00
C-c C-b python-vterm-send-buffer
Send the whole content of the script buffer to the Python REPL line by line.
2022-07-06 19:38:00 +09:00
C-c C-r python-vterm-send-run-buffer-file
Send a line to evaluate the buffer's file using ipython %run magic.
This is only useful when using ipython.
2022-07-06 19:38:00 +09:00
2024-05-11 16:29:05 -04:00
C-c C-d python-vterm-send-cd-to-buffer-directory
Send %cd function call to the Python REPL to change the current working
2022-07-07 23:48:56 +09:00
directory of REPL to the buffer's directory.
2022-07-06 19:38:00 +09:00
#+end_example
2024-05-11 16:29:05 -04:00
*** python-vterm-repl-mode
2022-07-06 19:38:00 +09:00
#+begin_example
Key Command / Description
2022-07-07 23:48:56 +09:00
------------------------------------------------------------------------------------------
2024-05-11 16:29:05 -04:00
C-c C-z python-vterm-repl-switch-to-script-buffer
Switch to the script buffer that is paired with the current Python REPL buffer.
2022-07-06 19:38:00 +09:00
2024-05-11 16:29:05 -04:00
M-k python-vterm-repl-clear-buffer
Clear the content of the Python REPL buffer.
2020-10-07 19:26:30 +09:00
2024-05-11 16:29:05 -04:00
C-c C-t python-vterm-repl-copy-mode
2022-07-06 19:38:00 +09:00
Enter copy mode.
#+end_example
2020-10-07 19:26:30 +09:00
2024-05-11 16:29:05 -04:00
*** python-vterm-repl-mode (copy mode)
2020-10-07 19:26:30 +09:00
2022-07-06 19:38:00 +09:00
#+begin_example
Key Command / Description
2022-07-07 23:48:56 +09:00
------------------------------------------------------------------------------------------
2024-05-11 16:29:05 -04:00
C-c C-t python-vterm-repl-copy-mode
2022-07-06 19:38:00 +09:00
Exit copy mode.
2020-10-07 19:26:30 +09:00
2024-05-11 16:29:05 -04:00
<return> python-vterm-repl-copy-mode-done
2022-07-06 19:38:00 +09:00
Copy the region to the kill ring and exit copy mode.
2020-10-07 19:26:30 +09:00
2022-07-06 19:38:00 +09:00
C-c C-r vterm-reset-cursor-point
Call the vterm command that moves point to where it should be.
#+end_example