Terminado

https://terminado.readthedocs.io/en/stable/
Admin
Terminado is a Tornado websocket backend for the Xterm.js Javascript terminal emulator library,...
Tokens:1,884
Snippets:25
Trust Score:9.6
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install Terminado locally

Source: https://terminado.readthedocs.io/en/stable/index.html

Install the package in editable mode with test dependencies.

```bash
$ pip install -e .[test]
```

--------------------------------

### Implement a basic Terminado application

Source: https://terminado.readthedocs.io/en/stable/index.html

A minimal example demonstrating how to set up a terminal manager and websocket handler within a Tornado application. Requires tornado_xstatic and XStatic-term.js.

```python
import os.path
import tornado.web
import tornado.ioloop

# This demo requires tornado_xstatic and XStatic-term.js
import tornado_xstatic

import terminado

STATIC_DIR = os.path.join(os.path.dirname(terminado.__file__), "_static")


class TerminalPageHandler(tornado.web.RequestHandler):
    def get(self):
        return self.render(
            "termpage.html",
            static=self.static_url,
            xstatic=self.application.settings["xstatic_url"],
            ws_url_path="/websocket",
        )


if __name__ == "__main__":
    term_manager = terminado.SingleTermManager(shell_command=["bash"])
    handlers = [
        (r"/websocket", terminado.TermSocket, {"term_manager": term_manager}),
        (r"/", TerminalPageHandler),
        (
            r"/xstatic/(.*)",
            tornado_xstatic.XStaticFileHandler,
            {"allowed_modules": ["termjs"]},
        ),
    ]
    app = tornado.web.Application(
        handlers,
        static_path=STATIC_DIR,
        xstatic_url=tornado_xstatic.url_maker("/xstatic/"),
    )
    # Serve at http://localhost:8765/ N.B. Leaving out 'localhost' here will
    # work, but it will listen on the public network interface as well.
    # Given what terminado does, that would be rather a security hole.
    app.listen(8765, "localhost")
    try:
        tornado.ioloop.IOLoop.instance().start()
    finally:
        term_manager.shutdown()
```

--------------------------------

### Initialize Terminal in Frontend

Source: https://terminado.readthedocs.io/en/stable/_sources/websocket.rst.txt

Connect to the WebSocket endpoint using the provided terminado.js library.

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

--------------------------------

### Run unit tests

Source: https://terminado.readthedocs.io/en/stable/index.html

Execute the project's test suite using pytest.

```bash
$ pytest
```

--------------------------------

### Embedding a Terminal in a Template

Source: https://terminado.readthedocs.io/en/stable/_sources/uimodule.rst.txt

Use the module tag in a Tornado template to render the terminal interface.

```html
{% module Terminal("/websocket", rows=30, cols=90) %}
```

--------------------------------

### Registering the Terminal UI Module

Source: https://terminado.readthedocs.io/en/stable/_sources/uimodule.rst.txt

Add the Terminal module to the ui_modules dictionary in the Tornado application configuration.

```python
from terminado import uimodule
# ...

app = tornado.web.Application(...
    ui_modules = {'Terminal': uimodule.Terminal},
)
```

--------------------------------

### Register TermSocket in Tornado Application

Source: https://terminado.readthedocs.io/en/stable/_sources/websocket.rst.txt

Add TermSocket to the Tornado application routing table with a configured terminal manager.

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

--------------------------------

### terminado.TermSocket

Source: https://terminado.readthedocs.io/en/stable/websocket.html

A Tornado WebSocket handler used to bridge a pseudoterminal with a frontend terminal client.

```APIDOC
## WebSocket Handler: terminado.TermSocket

### Description
TermSocket is a subclass of tornado.web.WebSocketHandler that facilitates communication between a pseudoterminal and a client-side terminal emulator. It must be registered in a Tornado application with a terminal manager instance.

### Usage
```python
app = tornado.web.Application([
    (r"/websocket", terminado.TermSocket, 
        {'term_manager': terminado.SingleTermManager(shell_command=['bash'])})
])
```
```

--------------------------------

### terminado.TermSocket

Source: https://terminado.readthedocs.io/en/stable/_sources/websocket.rst.txt

The TermSocket handler is used to establish a WebSocket connection to a pseudoterminal. It must be configured with a terminal manager instance.

```APIDOC
## WebSocket Connection

### Description
Connects a web client to a pseudoterminal session via WebSocket.

### Endpoint
ws://<host>/websocket

### Configuration
- **term_manager** (terminado.TermManagerBase) - Required - The terminal manager instance (e.g., SingleTermManager, UniqueTermManager, or NamedTermManager) responsible for managing terminal lifecycles.
```

--------------------------------

### Authenticate TermSocket Connection

Source: https://terminado.readthedocs.io/en/stable/_sources/websocket.rst.txt

Subclass TermSocket to implement custom authentication logic before allowing the connection.

```python
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

Source: https://terminado.readthedocs.io/en/stable/websocket.html

Classes that manage the lifecycle and sharing behavior of terminals connected via WebSockets.

```APIDOC
## Terminal Manager Classes

### SingleTermManager
All WebSocket connections share a single common terminal instance.

### UniqueTermManager
Each WebSocket connection is assigned a unique terminal instance.

### NamedTermManager
Terminals are shared between WebSockets connected to the same endpoint.

### TermManagerBase
Base class for implementing custom terminal management logic. Key methods include:
- `get_terminal(url_component)`: Returns a terminal for a new connection.
- `new_terminal(**kwargs)`: Creates and returns a new terminal instance.
- `start_reading(ptywclients)`: Connects the terminal to the event loop.
- `client_disconnected(websocket)`: Handles cleanup when a client disconnects.
```
Tokens:
Raw