Skip to content

shell.md

Latest commit

 

History

History
128 lines (99 loc) · 3.09 KB

shell.md

File metadata and controls

128 lines (99 loc) · 3.09 KB
Raw

(cli-shell)=

(tmuxp-shell)=

tmuxp shell

Launch an interactive Python shell with libtmux objects pre-loaded. Like Django's shell command, it hands you the current tmux server, sessions, windows, and panes already wired up, so you can poke at a live session or prototype a script without writing boilerplate.

Command

.. argparse::
    :module: tmuxp.cli
    :func: create_parser
    :prog: tmuxp
    :path: shell

Interactive usage

Run tmuxp shell to drop into a Python console with the current tmux {class}server <libtmux.Server>, {class}session <libtmux.Session>, {class}window <libtmux.Window>, and {class}pane <libtmux.Pane> already bound. Pass arguments to select a specific one:

(Pdb) server
<libtmux.server.Server object at 0x7f7dc8e69d10>
(Pdb) server.sessions
[Session($1 your_project)]
(Pdb) session
Session($1 your_project)
(Pdb) session.name
'your_project'
(Pdb) window
Window(@3 1:your_window, Session($1 your_project))
(Pdb) window.name
'your_window'
(Pdb) window.panes
[Pane(%6 Window(@3 1:your_window, Session($1 your_project)))
(Pdb) pane
Pane(%6 Window(@3 1:your_window, Session($1 your_project)))

Running code directly

Pass -c to run a snippet and exit, much like python -c:

$ tmuxp shell -c 'python code'
:width: 878
:height: 109
:loading: lazy

The same objects are in scope. Name a server, then a window, to narrow what the snippet sees:

$ tmuxp shell -c 'print(session.name); print(window.name)'
my_server
my_window
$ tmuxp shell my_server my_window -c 'print(window.name.upper())'
MY_WINDOW

Inside a tmux pane — or attached to the default server — the pane is in scope too:

$ tmuxp shell -c 'print(pane.id); print(pane.window.name)'
%2
my_window

Debugger integration

tmuxp shell supports PEP 553's PYTHONBREAKPOINT and compatible debuggers, such as ipdb:

$ pip install --user ipdb

Inside a uv-managed project, add ipdb as a development dependency:

$ uv add --dev ipdb

For a pipx-style ad hoc install, run it through uvx:

$ uvx --from ipdb ipdb3 --help
$ env PYTHONBREAKPOINT=ipdb.set_trace tmuxp shell

Shell detection

tmuxp shell drops into the richest shell available in your site packages. Pick one yourself with a flag:

  • --pdb: plain {func}breakpoint (python 3.7+) or {func}pdb.set_trace
  • --code: drop into {func}code.interact, accepts --use-pythonrc
  • --bpython: drop into bpython
  • --ipython: drop into IPython
  • --ptpython: drop into ptpython, accepts --use-vi-mode
  • --ptipython: drop into IPython + ptpython, accepts --use-vi-mode