Using the TermSocket handler#

terminado.TermSocket is the main API in Terminado. It is a subclass of tornado.web.WebSocketHandler, used to communicate between a pseudoterminal and term.js. You add it to your web application as a handler like any other:

app = tornado.web.Application([
        # ... other handlers ...
        (r"/websocket", terminado.TermSocket,
            {'term_manager': terminado.SingleTermManager(shell_command=['bash'])}),
    ], **kwargs)

Now, a page in your application can connect to ws://<host>/websocket. Using terminado/_static/terminado.js, you can do this using:

make_terminal(target_html_element, {rows:25, cols:80}, "ws://<host>/websocket");

Warning

TermSocket does not authenticate the connection at all, and using it with a program like bash means that anyone who can connect to it can run commands on your server. It is up to you to integrate the handler with whatever authentication system your application uses. For instance, in IPython, we subclass it like this:

class TermSocket(terminado.TermSocket, IPythonHandler):
    def get(self, *args, **kwargs):
        if not self.get_current_user():
            raise web.HTTPError(403)
        return super(TermSocket, self).get(*args, **kwargs)

Terminal managers#

The terminal manager control the behaviour when you connect and disconnect websockets. Terminado offers three options:

class terminado.SingleTermManager(**kwargs: Any)#: All connections to the websocket share a common terminal.

class terminado.UniqueTermManager(max_terminals: int | None = None, **kwargs: Any)#: Give each websocket a unique terminal to use.

class terminado.NamedTermManager(max_terminals: Any = None, **kwargs: Any)#: Share terminals between websockets connected to the same endpoint.

You can also define your own behaviours, by subclassing any of these, or the base class. The important methods are described here:

class terminado.TermManagerBase(shell_command: str, server_url: str = '', term_settings: Any = None, extra_env: Any = None, ioloop: Any = None, blocking_io_executor: Any = None)#

Base class for a terminal manager.

get_terminal(url_component: Any = None) → PtyWithClients#

Override in a subclass to give a terminal to a new websocket connection

The TermSocket handler works with zero or one URL components (capturing groups in the URL spec regex). If it receives one, it is passed as the url_component parameter; otherwise, this is None.

new_terminal(**kwargs: Any) → PtyWithClients#: Make a new terminal, return a PtyWithClients instance.

start_reading(ptywclients: PtyWithClients) → None#: Connect a terminal to the tornado event loop to read data from it.

client_disconnected(websocket: Any) → None#: Override this to e.g. kill terminals on client disconnection.

This may still be subject to change as we work out the best API.

In the example above, the terminal manager was only attached to the websocket handler. If you want to access it from other handlers, for instance to list running terminals, attach the instance to your application, for instance in the settings dictionary.