Python tips

Here are some ideas for using the Python (Python3) language with DomTerm. I am not a Python expert, so recommendations for better ways to do these things are welcome.

Setup and prompts

In your shell startup file (e.g .bashrc), define PYTHONSTARTUP and PYTHONPATH, for example:

export PYTHONSTARTUP=$HOME/.config/python/python-startup.py
export PYTHONPATH=$HOME/.config/python

Copy the following to $PYTHONSTARTUP:

import os
import sys
is_domterm = os.getenv("DOMTERM", "")!=""
session_key = 'Py%d' % os.getpid()
sys.ps1 = '>>> '
sys.ps2 = '... '

if is_domterm :
    sys.ps1 = '\001\033]133;N;aid=' + session_key + ';cl=m\007\002'+ sys.ps1 + '\001\033]133;I\007\002'
    sys.ps2 = '\001\033]133;P;k=c\007\002' + sys.ps2 + '\001\033]133;I\007\002'
    import domterm.utils as dtutils
    dtutils.set_notebook_mode()

Setting sys.ps1 and sys.ps2 wraps the prompts with DomTerm-specific escape sequences that provide some benefits:

Installing domterm/utils.py defines the following useful functions.

Function: dtutils.print_html (html_string)

Send the html_string to the terminal, and display it as would be done in a browser.

Function: dtutils.display_html (html, overwrite=False, name='python_image', inline=False)

Similar to print_html, but supports replace-in-place of existing output: If overwrite is False, it wraps the html in another element (a <span> if inline or a <div> otherwise), and attaches a key name to that wrapper element. (This key does not use the id attribute, and need not be unique.)

If overwrite is True, DomTerm searches for the most recent element that has a key matching name. If found, it replaces the contents (child nodes) of that wrapper element with html.

Function: dtutils.set_notebook_mode(enable=True)

Controls how auto-display (the “print” part of the Python REPL) handles objects that have a _repr_html_ attribute: If enable is True, then _repr_html_ is called, and the result is printed as if by dtutils.print_html. Otherwise, the default display is done. The python-startup.py above starts out with enable=True.

Clickable errors

The domterm.utils module overrides Python’s sys.excepthook, as show in the screenshot. The error message is wrapped in <span std="err"> elements, which is by default styled with red.

Lines of the form File "filename", line line are converted to clickable links (visible when you hover over it). (Note the effective URL in the blue box.) Right-clicking on the link brings up an Open Link menu entry, which normally brings up a text editor at the specified line; you can customize this action.

Using Pandas

Here is an example using Pandas, the Pandas Data Analysis Library.

Note how a DataFrame by default is displayed as an HTML table (assuming dtutils.set_notebook_mode(True) has been called).

Using matplotlib

Matplotlib is popular plotting library. If you do:

import domterm.matplot

it will “patch” matplotlib so graphical output is displayed inline in a DomTerm terminal. (Note that domterm.matplot is very experimental, so the API may change.)

Function: plt.show (overwrite=do_overwrite, format="svg")

Display the current image inline. By default, the image is presented using SVG (Structured Vector Graphics), but you can also specify the format as "png" or "jpg".

The overwrite argument specifies whether to create a new display area (overwrite=False) or re-use the most recent previous one (if (overwrite=True); the default is False for the first call to show and True for subsequent calls.