mirror of
https://github.com/Textualize/textual-serve.git
synced 2025-10-17 02:50:37 +03:00
110 lines
3.4 KiB
Markdown
110 lines
3.4 KiB
Markdown
# textual-serve
|
|
|
|
Every [Textual](https://github.com/textualize/textual) application is now a web application.
|
|
|
|
With 3 lines of code, any Textual app can run in the browser.
|
|
|
|
|
|
|
|
|
|
<table>
|
|
<tr>
|
|
<td>
|
|
<p>This is <a href="https://github.com/darrenburns/posting">Posting</a> running in the terminal.</p>
|
|
</td>
|
|
<td>
|
|
<img src="https://github.com/Textualize/textual-serve/assets/554369/14120e6e-bd8c-4620-a9fc-7cf41e3e994b" width="100%"/>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<p>This is <a href="https://github.com/darrenburns/posting">Posting</a> running in the <em>browser</em>.</p>
|
|
</td>
|
|
<td>
|
|
<img src="https://github.com/Textualize/textual-serve/assets/554369/cfa66f9b-02a0-4335-a127-e5a75c6f859d" width="100%"/>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
---
|
|
|
|
## Getting Started
|
|
|
|
First, [install (or upgrade) Textual](https://textual.textualize.io/getting_started/#installation).
|
|
|
|
Then install `textual-serve` from PyPI:
|
|
|
|
|
|
```
|
|
pip install textual-serve
|
|
```
|
|
|
|
## Creating a server
|
|
|
|
First import the Server class:
|
|
|
|
```python
|
|
from textual_serve.server import Server
|
|
```
|
|
|
|
Then create a `Server` instance and pass the command that launches your Textual app:
|
|
|
|
```python
|
|
server = Server("python -m textual")
|
|
```
|
|
|
|
The command can be anything you would enter in the shell, as long as it results in a Textual app running.
|
|
|
|
Finally, call the `serve` method:
|
|
|
|
```python
|
|
server.serve()
|
|
```
|
|
|
|
You will now be able to click on the link in the terminal to run your app in a browser.
|
|
|
|
### Summary
|
|
|
|
Run this code, visit http://localhost:8000
|
|
|
|
```python
|
|
from textual_serve.server import Server
|
|
|
|
server = Server("python -m textual")
|
|
server.serve()
|
|
```
|
|
|
|
## Configuration
|
|
|
|
The `Server` class has the following parameters:
|
|
|
|
| parameter | description |
|
|
| -------------- | ---------------------------------------------------------------------------------- |
|
|
| command | A shell command to launch a Textual app. |
|
|
| host | The host of the web application (defaults to "localhost"). |
|
|
| port | The port for the web application (defaults to 8000). |
|
|
| title | The title show in the web app on load, leave as `None` to use the command. |
|
|
| public_url | The public URL, if the server is behind a proxy. `None` for the local URL. |
|
|
| statics_path | Path to statics folder, relative to server.py. Default uses directory in module. |
|
|
| templates_path | Path to templates folder, relative to server.py. Default uses directory in module. |
|
|
|
|
The `Server.serve` method accepts a `debug` parameter.
|
|
When set to `True`, this will enable [textual devtools](https://textual.textualize.io/guide/devtools/).
|
|
|
|
## How does it work?
|
|
|
|
When you visit the app URL, the server launches an instance of your app in a subprocess, and communicates with it via a websocket.
|
|
|
|
This means that you can serve multiple Textual apps across all the CPUs on your system.
|
|
|
|
|
|
Note that Textual-serve uses a custom protocol to communicate with Textual apps.
|
|
It *does not* simply expose a shell in your browser.
|
|
There is no way for a malicious user to do anything the app-author didn't intend.
|
|
|
|
## See also
|
|
|
|
See also [textual-web](https://github.com/Textualize/textual-web) which serves Textual apps on a public URL.
|
|
|
|
You can consider this project to essentially be a self-hosted equivalent of Textual-web.
|