Metadata-Version: 2.4
Name: pysx-framework
Version: 0.7.0
Summary: Server-side reactive renderer for Python, templated with PEP 750 t-strings
Author: JMS Apps
Author-email: JMS Apps <jmsapps@outlook.com>
License-Expression: MIT
License-File: LICENSE
Requires-Dist: cryptography==50.0.2
Requires-Dist: websockets==17.1
Requires-Dist: uvicorn==0.54.0 ; extra == 'asgi'
Requires-Dist: ruff==0.16.10 ; extra == 'dev'
Requires-Dist: typer==0.27.2 ; extra == 'examples'
Requires-Dist: lsprotocol==2025.0.0 ; extra == 'lsp'
Requires-Dist: pygls==2.1.1 ; extra == 'lsp'
Requires-Dist: pyright==1.1.414 ; extra == 'lsp'
Requires-Dist: ruff==0.16.10 ; extra == 'lsp'
Requires-Python: >=3.14
Provides-Extra: asgi
Provides-Extra: dev
Provides-Extra: examples
Provides-Extra: lsp
Description-Content-Type: text/markdown

<p align="center">
  <img src="assets/pysx-logo.png" alt="PYSX" width="260">
</p>

**Reactive interfaces, written in Python.**

PYSX brings the feel of a reactive web app to Python. Write your interface with
readable, indentation-based templates, keep state in signals, and let the page
update as that state changes.

Python runs on the server. A small JavaScript client connects the browser to your
application, sends user events, and applies the updates it receives.

## Install

Use Python 3.14 or newer and install
[pysx-framework from PyPI](https://pypi.org/project/pysx-framework/):

```sh
python -m pip install 'pysx-framework==0.7.0'
```

Or add it to a uv project with `uv add 'pysx-framework==0.7.0'`.
The Python import remains `pysx`. Follow the [quickstart](docs/QUICKSTART.md)
to run your first application.

## How it works

The initial HTTP response contains the rendered page. The browser attaches to that
same graph, preserving edits made before attachment. Each session gets its own
reactive state. Signals hold values, derived
signals compute from them, and effects track dependencies automatically. When a
user clicks a button or edits a field, Python handles the event and sends changes
back to the page.

Templates use Python 3.14+ t-strings to keep markup and live values together:

<img src="assets/pysx-counter.svg" alt="Python counter example with PYSX template syntax highlighting" width="1048">


Changing `count` updates the displayed value. The browser applies targeted patches,
and keyed lists preserve unchanged rows so focus, selection, and scroll survive
updates.

## Build with PYSX

- **Reactive state:** signals, derived values, batched updates, and writable views into structured data.
- **Readable interfaces:** t-string templates and composable, typed native elements.
- **Live forms:** two-way bindings, native validation, reset and submit handling, and caret-preserving server corrections.
- **Async applications:** owned resources, timers and server push update pages without another browser event.
- **Document continuity:** open pages restore compatible UI state after server loss. See [recovery](docs/RECOVERY.md).
- **Hosting:** shared standalone and optional ASGI serving, request context, static assets and lifecycle hooks. See [hosting](docs/HOSTING.md).
- **Scoped styling:** typed styled bases, inherited rules, live CSS variables and isolated
  themes. See the [styling guide](docs/STYLING.md).
- **Editor support:** VSCode syntax highlighting and advisory template diagnostics.

## Playgrounds

Copy runnable starter applications into your own project, then run them the ordinary way:

```sh
pysx-playground                        # all of them, into ./playgrounds
pysx-playground counter                # just one
pysx --app playgrounds.counter         # run it
pysx --app playgrounds.counter --watch # edit the file and watch it reload
```

`counter` is the smallest useful live application, `recovery` a draft that survives a restart
with the tab open, and `durable` declared state reconstructed through a fresh application
graph.
Re-running `pysx-playground <name>` restores that playground to its shipped source and
clears its state, so it is also the reset.

## Supported platforms

Python 3.14 or newer. The quality matrix has passed on Linux, macOS and Windows.
See [compatibility and support](docs/COMPATIBILITY.md) for tested versions,
deployment requirements and maintenance windows.

PYSX is available under the [MIT license](LICENSE).

## Explore

Start with the [quickstart](docs/QUICKSTART.md), work through the
[interactive tutorial](docs/TUTORIAL.md), or browse the [API index](docs/API.md).

- [Examples](examples/README.md) — run the demos and explore reactive state and live forms.
- [Tests](tests/README.md) — run the test suite and quality checks.
- [Editor support](editor/README.md) — install the VSCode extension.

For the technical details, see the [template grammar](docs/GRAMMAR.md),
[native elements and bindings](docs/ELEMENTS.md), and [wire protocol](docs/PROTOCOL.md).
