Metadata-Version: 2.3
Name: textual-serve
Version: 1.1.2
Summary: Turn your Textual TUIs in to web applications
Author-email: Will McGugan <will@textualize.io>
License: MIT License
        
        Copyright (c) 2024 Textualize
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Requires-Python: >=3.9
Requires-Dist: aiohttp-jinja2>=1.6
Requires-Dist: aiohttp>=3.9.5
Requires-Dist: jinja2>=3.1.4
Requires-Dist: rich
Requires-Dist: textual>=0.66.0
Description-Content-Type: text/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.
