Metadata-Version: 2.2
Name: decterm
Version: 1.0.1
Summary: Cross-platform terminal controllable via Python (and web)
Home-page: https://github.com/decrule/decterm
Author: decterm
Author-email: decrule@outlook.com
License: MIT
Keywords: terminal,shell,cross-platform,automation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Shells
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: author-email
Dynamic: home-page
Dynamic: requires-python

# decterm

Cross-platform terminal you can drive from Python. Run shell commands and get output, with or without a web UI.

- **Headless** (default): no window, ideal for scripts and servers.
- **Web GUI** (`gui=True`): DecPython-style browser terminal; optional HTTP server for remote `send()`.
- **Server** (`port=...`): bind host/port and optional `secret` so external clients can POST commands via the standalone `send()` function.

## Examples

All examples are in the `examples/` folder. Run from project root: `python examples/headless.py` etc.

| File | Covers |
|------|--------|
| `examples/headless.py` | `DecTerm()`, `send()`, `sends()`, `close()`, context manager |
| `examples/gui.py` | `DecTerm(gui=True)`, web terminal in browser |
| `examples/server.py` | `DecTerm(host, port, secret)`, `dt.port` |
| `examples/send_remote.py` | `send(command, host, port, secret)` — run `server.py` first |

## Quick start

```bash
pip install decterm
```

```python
from decterm import DecTerm, send

# Headless
dt = DecTerm()
print(dt.send("dir"))       # or "ls" on Unix
print(dt.sends("cd /tmp", "pwd"))
dt.close()

# Web GUI (opens browser)
dt = DecTerm(gui=True)
dt.send("echo Hello")
# Run commands in the browser; then:
dt.close()

# Server: accept remote commands (e.g. port=8765, secret="mykey")
dt = DecTerm(host="0.0.0.0", port=8765, secret="mykey")
# From another machine or script:
r = send("echo hi", host="server-ip", port=8765, secret="mykey")
# r == {'code': 200, 'data': 'hi\n', 'msg': ''}
dt.close()
```

## API (concise)

### DecTerm

| Parameter / Method | Description |
|--------------------|-------------|
| `DecTerm(gui=False, shell=None, cwd=None, env=None, host='localhost', port=None, secret=None)` | Start a shell. `gui=True` opens web terminal in browser. `host`/`port`/`secret` start HTTP server; only `host='0.0.0.0'` accepts non-local requests. |
| `dt.send(cmd, timeout=30)` | Run one command, return output string. |
| `dt.sends(*cmds, timeout=30)` | Run several commands in order; returns last command's output. |
| `dt.port` | Bound port (None if no server). |
| `dt.close()` | Stop the shell and server. |

Use `timeout=None` in `send()` to wait indefinitely.

### Standalone send (client)

| Function | Description |
|----------|-------------|
| `send(command, host='localhost', port=None, secret=None)` | POST command to a DecTerm server. `port` is required. Returns `{'code': 200, 'data': '<output>', 'msg': ''}` on success, or `{'code': -1, 'data': '', 'msg': '<error>'}` on failure. When `secret` is set, sends timestamp + HMAC for auth. |

## Requirements

- Python 3.7+
- Windows, macOS, or Linux
- No extra packages (standard library only; no tkinter required for web GUI).

## License

MIT
