pyreaction 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (38) hide show
  1. pyreaction-0.1.0/LICENSE +21 -0
  2. pyreaction-0.1.0/PKG-INFO +346 -0
  3. pyreaction-0.1.0/README.md +305 -0
  4. pyreaction-0.1.0/pyproject.toml +99 -0
  5. pyreaction-0.1.0/pyproject.toml.orig +96 -0
  6. pyreaction-0.1.0/src/reaction/__init__.py +220 -0
  7. pyreaction-0.1.0/src/reaction/cli/__init__.py +80 -0
  8. pyreaction-0.1.0/src/reaction/cli/__main__.py +3 -0
  9. pyreaction-0.1.0/src/reaction/cli/scaffold.py +121 -0
  10. pyreaction-0.1.0/src/reaction/cli/serve.py +123 -0
  11. pyreaction-0.1.0/src/reaction/cli/templates/default/README.md.tmpl +14 -0
  12. pyreaction-0.1.0/src/reaction/cli/templates/default/_gitignore +4 -0
  13. pyreaction-0.1.0/src/reaction/cli/templates/default/app.py +12 -0
  14. pyreaction-0.1.0/src/reaction/cli/templates/default/components/__init__.py +0 -0
  15. pyreaction-0.1.0/src/reaction/cli/templates/default/components/counter.py +12 -0
  16. pyreaction-0.1.0/src/reaction/cli/templates/default/public/style.css +26 -0
  17. pyreaction-0.1.0/src/reaction/cli/templates/default/pyproject.toml.tmpl +29 -0
  18. pyreaction-0.1.0/src/reaction/client/client.js +1087 -0
  19. pyreaction-0.1.0/src/reaction/client/index.html +15 -0
  20. pyreaction-0.1.0/src/reaction/client/style.css +54 -0
  21. pyreaction-0.1.0/src/reaction/core/__init__.py +0 -0
  22. pyreaction-0.1.0/src/reaction/core/_html_types.py +3768 -0
  23. pyreaction-0.1.0/src/reaction/core/boundary.py +46 -0
  24. pyreaction-0.1.0/src/reaction/core/components.py +322 -0
  25. pyreaction-0.1.0/src/reaction/core/element.py +880 -0
  26. pyreaction-0.1.0/src/reaction/core/hooks.py +989 -0
  27. pyreaction-0.1.0/src/reaction/core/parse.py +112 -0
  28. pyreaction-0.1.0/src/reaction/core/resources.py +96 -0
  29. pyreaction-0.1.0/src/reaction/core/router.py +76 -0
  30. pyreaction-0.1.0/src/reaction/core/ssr.py +372 -0
  31. pyreaction-0.1.0/src/reaction/core/store.py +336 -0
  32. pyreaction-0.1.0/src/reaction/core/vdom.py +2558 -0
  33. pyreaction-0.1.0/src/reaction/py.typed +0 -0
  34. pyreaction-0.1.0/src/reaction/server/__init__.py +3 -0
  35. pyreaction-0.1.0/src/reaction/server/app.py +1435 -0
  36. pyreaction-0.1.0/src/reaction/server/encoding.py +85 -0
  37. pyreaction-0.1.0/src/reaction/server/settings.py +76 -0
  38. pyreaction-0.1.0/src/reaction/testing.py +586 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 jeomon
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,346 @@
1
+ Metadata-Version: 2.4
2
+ Name: pyreaction
3
+ Version: 0.1.0
4
+ Summary: React-style UI components in pure Python, rendered on the server and patched into the browser over a WebSocket.
5
+ Keywords: react,ui,components,hooks,asgi,websocket
6
+ Author: jeomon
7
+ Author-email: jeomon <jeogeoalukka@gmail.com>
8
+ License-Expression: MIT
9
+ License-File: LICENSE
10
+ Classifier: Development Status :: 3 - Alpha
11
+ Classifier: Intended Audience :: Developers
12
+ Classifier: Operating System :: OS Independent
13
+ Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
14
+ Classifier: Topic :: Software Development :: User Interfaces
15
+ Classifier: Typing :: Typed
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Programming Language :: Python :: 3.14
21
+ Classifier: Framework :: AsyncIO
22
+ Requires-Dist: starlette>=0.37
23
+ Requires-Dist: uvicorn>=0.30
24
+ Requires-Dist: websockets>=12
25
+ Requires-Dist: orjson>=3.9
26
+ Requires-Dist: playwright>=1.50 ; extra == 'browser'
27
+ Requires-Dist: jinja2>=3.1 ; extra == 'jinja'
28
+ Requires-Dist: redis>=5 ; extra == 'redis'
29
+ Requires-Dist: a2wsgi>=1.10 ; extra == 'wsgi'
30
+ Requires-Python: >=3.11
31
+ Project-URL: Homepage, https://github.com/Jeomon/pyreaction
32
+ Project-URL: Documentation, https://github.com/Jeomon/pyreaction/tree/main/docs
33
+ Project-URL: Repository, https://github.com/Jeomon/pyreaction
34
+ Project-URL: Issues, https://github.com/Jeomon/pyreaction/issues
35
+ Project-URL: Changelog, https://github.com/Jeomon/pyreaction/blob/main/CHANGELOG.md
36
+ Provides-Extra: browser
37
+ Provides-Extra: jinja
38
+ Provides-Extra: redis
39
+ Provides-Extra: wsgi
40
+ Description-Content-Type: text/markdown
41
+
42
+ <div align="center">
43
+ <h1>⚛️ pyreaction</h1>
44
+
45
+ <img src="https://img.shields.io/badge/license-MIT-green" alt="License: MIT">
46
+ <img src="https://img.shields.io/badge/python-3.11%2B-blue" alt="Python 3.11+">
47
+ <img src="https://img.shields.io/badge/typing-mypy%20checked-informational" alt="Typed with mypy">
48
+ <img src="https://img.shields.io/badge/status-pre--release%200.1-orange" alt="Status: pre-release 0.1">
49
+ </div>
50
+
51
+ **pyreaction** brings React's component model to Python. Components run on the
52
+ server; the browser gets server-rendered HTML for the first paint, then small DOM
53
+ updates over a WebSocket. No JavaScript to write, no build step, no Node.
54
+
55
+ ```python
56
+ from reaction import component, html, run, use_state
57
+
58
+ @component
59
+ def Counter():
60
+ count, set_count = use_state(0)
61
+ return html.button(f"Clicked {count} times", on_click=lambda: set_count(count + 1))
62
+
63
+ run(Counter) # http://127.0.0.1:8000
64
+ ```
65
+
66
+ The package is `pyreaction`, the import is `reaction`, and the command is
67
+ `reaction` (`pyreaction` works too).
68
+
69
+ ## ✨ Key Features
70
+
71
+ - **The React model in Python**
72
+ Components, `use_state`, `use_effect`, context, keys, error boundaries, Suspense,
73
+ portals, refs, the rules of hooks, `StrictMode`, and React 19's form actions,
74
+ `use_optimistic` and `ViewTransition`.
75
+
76
+ - **Server-rendered first**
77
+ Every URL returns real HTML with its data in it, good for search engines and slow
78
+ devices. Suspense content streams into the same response, and the live page
79
+ adopts the HTML instead of redrawing it.
80
+
81
+ - **Small updates**
82
+ The server diffs the tree and sends only DOM operations, such as "set the text of
83
+ node 12". A click on a small page is a round trip of about a third of a
84
+ millisecond on the server.
85
+
86
+ - **Resilient connections**
87
+ Pages reconnect by themselves and resume with their state, and typing is never
88
+ undone by a slow round trip.
89
+
90
+ - **Large pages stay fast**
91
+ `VirtualList` renders only the rows in view, and per-page stores with selectors
92
+ re-render only the components whose part changed.
93
+
94
+ - **Fits your stack**
95
+ Run it alone, mount it in FastAPI (with `Depends`), put it in front of Django or
96
+ Flask, or drop components into Jinja templates.
97
+
98
+ - **Escape hatches**
99
+ Wrap any JavaScript or React widget, run code in the browser with `js()`, call
100
+ element methods from Python, and read any event property on demand.
101
+
102
+ - **Testable and typed**
103
+ A fake browser for unit tests, a live server helper for Playwright, and typed
104
+ HTML tags that editors autocomplete.
105
+
106
+ ## 🛠️ Installation
107
+
108
+ ### Prerequisites
109
+
110
+ - Python 3.11 or newer
111
+ - [uv](https://docs.astral.sh/uv/) (recommended) or pip
112
+
113
+ ```shell
114
+ uv add pyreaction
115
+ # or
116
+ pip install pyreaction
117
+ ```
118
+
119
+ Optional extras are added the same way, as in `pyreaction[redis,jinja]`:
120
+
121
+ | Extra | For |
122
+ | --- | --- |
123
+ | `redis` | stores shared between worker processes (`RedisBackend`) |
124
+ | `wsgi` | putting pages in front of a WSGI app such as Flask |
125
+ | `jinja` | the `{% component %}` template tag |
126
+ | `browser` | Playwright, for tests in a real browser |
127
+
128
+ ### Start a project
129
+
130
+ ```shell
131
+ uvx pyreaction init my-app
132
+ cd my-app
133
+ uv run dev # http://127.0.0.1:8000, restarts on every save
134
+ ```
135
+
136
+ ```
137
+ my-app/
138
+ pyproject.toml settings under [tool.pyreaction]
139
+ app.py the App component
140
+ components/ your components
141
+ public/ served at /static; style.css is linked from the page
142
+ ```
143
+
144
+ ### Use it with your framework
145
+
146
+ <details>
147
+ <summary>FastAPI</summary>
148
+
149
+ Serve the pages next to your API with `mount`, or turn a route into a page with
150
+ `page`, whose function can use `Depends`:
151
+
152
+ ```python
153
+ from fastapi import Depends, FastAPI
154
+ from reaction import mount, page
155
+
156
+ api = FastAPI()
157
+ mount(api, App, "/ui") # a whole app under /ui
158
+
159
+ @page(api, "/orders/{order_id}", title="Order")
160
+ def order(order_id: int, user=Depends(current_user)):
161
+ return OrderPage(order_id=order_id, user=user)
162
+ ```
163
+
164
+ Run it as usual with `uvicorn main:api`. See [Integrations](https://github.com/Jeomon/pyreaction/blob/main/docs/integrations.md#fastapi).
165
+ </details>
166
+
167
+ <details>
168
+ <summary>Django</summary>
169
+
170
+ Put the pages in front of Django's ASGI app, in `asgi.py`:
171
+
172
+ ```python
173
+ from django.core.asgi import get_asgi_application
174
+ from reaction import wrap
175
+
176
+ application = wrap(get_asgi_application(), Dashboard, "/dashboard")
177
+ ```
178
+
179
+ Run it with `uvicorn mysite.asgi:application`. See [Integrations](https://github.com/Jeomon/pyreaction/blob/main/docs/integrations.md#django-flask-and-other-frameworks).
180
+ </details>
181
+
182
+ <details>
183
+ <summary>Flask</summary>
184
+
185
+ Install the `wsgi` extra, then wrap the Flask app:
186
+
187
+ ```python
188
+ from reaction import wrap
189
+
190
+ app = wrap(flask_app, Dashboard, "/dashboard")
191
+ ```
192
+
193
+ Run it with `uvicorn main:app`. See [Integrations](https://github.com/Jeomon/pyreaction/blob/main/docs/integrations.md#django-flask-and-other-frameworks).
194
+ </details>
195
+
196
+ <details>
197
+ <summary>Jinja templates</summary>
198
+
199
+ Install the `jinja` extra, then add a `{% component %}` tag to your templates:
200
+
201
+ ```python
202
+ from reaction import jinja_components
203
+
204
+ api.mount("/components", jinja_components(templates.env, [Counter, Chart], secret=SECRET))
205
+ ```
206
+
207
+ ```jinja
208
+ {% component "myapp.widgets.Counter" %}
209
+ {% component "myapp.widgets.Chart", values=[1, 2, 3] %}
210
+ ```
211
+
212
+ See [Integrations](https://github.com/Jeomon/pyreaction/blob/main/docs/integrations.md#jinja-templates).
213
+ </details>
214
+
215
+ ## 🖥️ Running pyreaction
216
+
217
+ | Command | |
218
+ | --- | --- |
219
+ | `python app.py` | a single file that calls `run(App)` |
220
+ | `uv run dev` | a project, with reload on save and errors shown in the page |
221
+ | `uv run pro` | a project, for production |
222
+ | `uvicorn main:app` | any app built with `create_app`, `mount` or `wrap` |
223
+
224
+ `reaction run` and `reaction dev` take `--host` and `--port`, which default to
225
+ `PYREACTION_HOST`/`127.0.0.1` and `PYREACTION_PORT`/`PORT`/`8000`. Behind a proxy,
226
+ pass the WebSocket upgrade through; [Deployment](https://github.com/Jeomon/pyreaction/blob/main/docs/deployment.md) has an Nginx
227
+ example and notes on workers and sticky sessions.
228
+
229
+ ## ⚙️ Configuration
230
+
231
+ Options go to `create_app` (and `run`, `mount`, `page`, `wrap`), into a project's
232
+ `[tool.pyreaction]` table, or into `PYREACTION_*` environment variables. The ones
233
+ most often changed:
234
+
235
+ | Option | Default | Environment variable | |
236
+ | --- | --- | --- | --- |
237
+ | `debug` | `False` | `PYREACTION_DEBUG` | errors and warnings shown in the page |
238
+ | `allowed_origins` | `()` | `PYREACTION_ALLOWED_ORIGINS` | extra origins allowed to open the WebSocket |
239
+ | `compress` | `True` | `PYREACTION_COMPRESS` | gzip pages; turn off when a proxy compresses |
240
+ | `resume_timeout` | `30.0` | `PYREACTION_RESUME_TIMEOUT` | seconds a dropped page's state is kept |
241
+ | `max_upload_size` | 10 MiB | `PYREACTION_MAX_UPLOAD_SIZE` | bytes per uploaded file |
242
+ | `reconnect_attempts` | `0` (no limit) | `PYREACTION_RECONNECT_ATTEMPTS` | failed attempts before a page gives up |
243
+
244
+ [Configuration](https://github.com/Jeomon/pyreaction/blob/main/docs/configuration.md) lists all of them.
245
+
246
+ ## 📚 Documentation
247
+
248
+ | | |
249
+ | --- | --- |
250
+ | [Getting started](https://github.com/Jeomon/pyreaction/blob/main/docs/getting-started.md) | install, a single-file app, a project |
251
+ | [Elements and events](https://github.com/Jeomon/pyreaction/blob/main/docs/elements-and-events.md) | describing the page, handlers, file uploads |
252
+ | [Hooks](https://github.com/Jeomon/pyreaction/blob/main/docs/hooks.md) | state, effects and the rest |
253
+ | [Data, forms and pending state](https://github.com/Jeomon/pyreaction/blob/main/docs/data-and-forms.md) | loading data, Suspense, form actions, optimistic updates |
254
+ | [Routing and the page head](https://github.com/Jeomon/pyreaction/blob/main/docs/routing.md) | URLs, links, redirects, `<title>` and `<meta>` |
255
+ | [Built-in components and the DOM](https://github.com/Jeomon/pyreaction/blob/main/docs/components.md) | refs, portals, long lists, error boundaries, JavaScript widgets |
256
+ | [Shared state](https://github.com/Jeomon/pyreaction/blob/main/docs/state.md) | stores shared between pages, processes, or within one page |
257
+ | [Integrations](https://github.com/Jeomon/pyreaction/blob/main/docs/integrations.md) | FastAPI, Django, Flask, Jinja templates, static pages |
258
+ | [Testing](https://github.com/Jeomon/pyreaction/blob/main/docs/testing.md) | a fake browser for unit tests, a live server for Playwright |
259
+ | [Configuration](https://github.com/Jeomon/pyreaction/blob/main/docs/configuration.md) | every option, in code, `pyproject.toml` or the environment |
260
+ | [Deployment and security](https://github.com/Jeomon/pyreaction/blob/main/docs/deployment.md) | workers, proxies, compression, origins, limits |
261
+ | [API reference](https://github.com/Jeomon/pyreaction/blob/main/docs/api.md) | everything `reaction` exports |
262
+ | [How it works](https://github.com/Jeomon/pyreaction/blob/main/docs/how-it-works.md) | the request, the live connection, and the update protocol |
263
+
264
+ Runnable apps are in [`examples/`](https://github.com/Jeomon/pyreaction/tree/main/examples): a todo list, routed pages, a login
265
+ flow, JavaScript widgets, and a FastAPI app.
266
+
267
+ ## 🔒 Security
268
+
269
+ - WebSockets are accepted only from the page's own origin, plus `allowed_origins`.
270
+ - Log in with ordinary HTTP routes that set an `HttpOnly` cookie; a WebSocket cannot
271
+ set cookies. `examples/login.py` is a complete version.
272
+ - Text is always escaped. `dangerously_set_inner_html`, `js()` code and
273
+ `js_component_from_string` are sent as written: never build them from user input.
274
+ - Uploads, queued events and pending updates are capped per page.
275
+
276
+ [Deployment and security](https://github.com/Jeomon/pyreaction/blob/main/docs/deployment.md#security) has the details. To report a
277
+ vulnerability, see [SECURITY.md](https://github.com/Jeomon/pyreaction/blob/main/SECURITY.md); please do not open a public issue.
278
+
279
+ ## 📝 Limitations
280
+
281
+ - **Every interaction is a round trip.** Handlers run on the server, so latency
282
+ follows the network; use `js()` for what must react instantly, such as selecting
283
+ an input's text.
284
+ - **Each open page holds state on the server.** Memory grows with open tabs, and a
285
+ 10,000-row page holds about 20 MB. Long lists should use `VirtualList`.
286
+ - **Rendering runs on the server's event loop.** A very large page (10,000 rows)
287
+ takes about 80 ms to serve, during which other pages on that process wait.
288
+ - **Resuming after a drop needs the same process.** With several workers, route a
289
+ page's connections to the worker that served it (sticky sessions).
290
+ - **Before 1.0**, the API may still change between minor versions; see the
291
+ [changelog](https://github.com/Jeomon/pyreaction/blob/main/CHANGELOG.md).
292
+ - **The import name is `reaction`**, which an unrelated, unmaintained PyPI package
293
+ (`reaction`, 2020) also uses. Do not install both in one environment.
294
+
295
+ ## 🤝 Contributing
296
+
297
+ Bug reports and pull requests are welcome. [CONTRIBUTING.md](https://github.com/Jeomon/pyreaction/blob/main/CONTRIBUTING.md)
298
+ explains the setup, the tests and type checks, and what a change needs.
299
+ [CHANGELOG.md](https://github.com/Jeomon/pyreaction/blob/main/CHANGELOG.md) lists what changed in each version.
300
+
301
+ ## 🙏 References
302
+
303
+ pyreaction follows the design of these projects; their documentation is the best
304
+ explanation of the ideas it borrows.
305
+
306
+ - **[React](https://react.dev)** ([source](https://github.com/facebook/react)):
307
+ the component model, hooks and their rules, keys and reconciliation, Suspense,
308
+ error boundaries, portals, and React 19's form actions, `use_optimistic`, `use`,
309
+ `cache`, resource hints and `ViewTransition`. Where pyreaction has a React API,
310
+ it follows React's behaviour, checked against React 19.3's source.
311
+ - **[ReactPy](https://reactpy.dev)** ([source](https://github.com/reactive-python/reactpy)):
312
+ React's model in Python, rendered over a WebSocket. pyreaction's hook names,
313
+ `html` element factories, `to_vdom` key names and JavaScript component interop
314
+ follow ReactPy's lead; it differs in diffing on the server and sending DOM
315
+ operations rather than VDOM trees, and in rendering every page as HTML first.
316
+
317
+ It is built on [Starlette](https://www.starlette.io), [uvicorn](https://www.uvicorn.org)
318
+ and [orjson](https://github.com/ijl/orjson).
319
+
320
+ pyreaction is an independent project. It is not affiliated with, endorsed by or
321
+ sponsored by Meta, the React project or the ReactPy project. React is a trademark of
322
+ Meta Platforms, Inc.; the name is used only to describe what pyreaction follows.
323
+
324
+ ## 🪪 License
325
+
326
+ pyreaction is free and open-source software, released under the
327
+ [MIT License](https://github.com/Jeomon/pyreaction/blob/main/LICENSE). You may use, copy, modify, merge, publish, distribute,
328
+ sublicense and sell it, in personal and commercial projects alike, provided the
329
+ copyright notice and the license text are included in all copies or substantial
330
+ portions of the software.
331
+
332
+ The software is provided "as is", without warranty of any kind; the authors are
333
+ not liable for any claim or damages arising from its use. Contributions to
334
+ pyreaction are accepted under the same license (see [CONTRIBUTING.md](https://github.com/Jeomon/pyreaction/blob/main/CONTRIBUTING.md)).
335
+
336
+ ## 📄 Citation
337
+
338
+ ```bibtex
339
+ @software{pyreaction,
340
+ author = {jeomon},
341
+ title = {pyreaction: React-style UI components in pure Python},
342
+ year = {2026},
343
+ publisher = {GitHub},
344
+ url = {https://github.com/Jeomon/pyreaction}
345
+ }
346
+ ```
@@ -0,0 +1,305 @@
1
+ <div align="center">
2
+ <h1>⚛️ pyreaction</h1>
3
+
4
+ <img src="https://img.shields.io/badge/license-MIT-green" alt="License: MIT">
5
+ <img src="https://img.shields.io/badge/python-3.11%2B-blue" alt="Python 3.11+">
6
+ <img src="https://img.shields.io/badge/typing-mypy%20checked-informational" alt="Typed with mypy">
7
+ <img src="https://img.shields.io/badge/status-pre--release%200.1-orange" alt="Status: pre-release 0.1">
8
+ </div>
9
+
10
+ **pyreaction** brings React's component model to Python. Components run on the
11
+ server; the browser gets server-rendered HTML for the first paint, then small DOM
12
+ updates over a WebSocket. No JavaScript to write, no build step, no Node.
13
+
14
+ ```python
15
+ from reaction import component, html, run, use_state
16
+
17
+ @component
18
+ def Counter():
19
+ count, set_count = use_state(0)
20
+ return html.button(f"Clicked {count} times", on_click=lambda: set_count(count + 1))
21
+
22
+ run(Counter) # http://127.0.0.1:8000
23
+ ```
24
+
25
+ The package is `pyreaction`, the import is `reaction`, and the command is
26
+ `reaction` (`pyreaction` works too).
27
+
28
+ ## ✨ Key Features
29
+
30
+ - **The React model in Python**
31
+ Components, `use_state`, `use_effect`, context, keys, error boundaries, Suspense,
32
+ portals, refs, the rules of hooks, `StrictMode`, and React 19's form actions,
33
+ `use_optimistic` and `ViewTransition`.
34
+
35
+ - **Server-rendered first**
36
+ Every URL returns real HTML with its data in it, good for search engines and slow
37
+ devices. Suspense content streams into the same response, and the live page
38
+ adopts the HTML instead of redrawing it.
39
+
40
+ - **Small updates**
41
+ The server diffs the tree and sends only DOM operations, such as "set the text of
42
+ node 12". A click on a small page is a round trip of about a third of a
43
+ millisecond on the server.
44
+
45
+ - **Resilient connections**
46
+ Pages reconnect by themselves and resume with their state, and typing is never
47
+ undone by a slow round trip.
48
+
49
+ - **Large pages stay fast**
50
+ `VirtualList` renders only the rows in view, and per-page stores with selectors
51
+ re-render only the components whose part changed.
52
+
53
+ - **Fits your stack**
54
+ Run it alone, mount it in FastAPI (with `Depends`), put it in front of Django or
55
+ Flask, or drop components into Jinja templates.
56
+
57
+ - **Escape hatches**
58
+ Wrap any JavaScript or React widget, run code in the browser with `js()`, call
59
+ element methods from Python, and read any event property on demand.
60
+
61
+ - **Testable and typed**
62
+ A fake browser for unit tests, a live server helper for Playwright, and typed
63
+ HTML tags that editors autocomplete.
64
+
65
+ ## 🛠️ Installation
66
+
67
+ ### Prerequisites
68
+
69
+ - Python 3.11 or newer
70
+ - [uv](https://docs.astral.sh/uv/) (recommended) or pip
71
+
72
+ ```shell
73
+ uv add pyreaction
74
+ # or
75
+ pip install pyreaction
76
+ ```
77
+
78
+ Optional extras are added the same way, as in `pyreaction[redis,jinja]`:
79
+
80
+ | Extra | For |
81
+ | --- | --- |
82
+ | `redis` | stores shared between worker processes (`RedisBackend`) |
83
+ | `wsgi` | putting pages in front of a WSGI app such as Flask |
84
+ | `jinja` | the `{% component %}` template tag |
85
+ | `browser` | Playwright, for tests in a real browser |
86
+
87
+ ### Start a project
88
+
89
+ ```shell
90
+ uvx pyreaction init my-app
91
+ cd my-app
92
+ uv run dev # http://127.0.0.1:8000, restarts on every save
93
+ ```
94
+
95
+ ```
96
+ my-app/
97
+ pyproject.toml settings under [tool.pyreaction]
98
+ app.py the App component
99
+ components/ your components
100
+ public/ served at /static; style.css is linked from the page
101
+ ```
102
+
103
+ ### Use it with your framework
104
+
105
+ <details>
106
+ <summary>FastAPI</summary>
107
+
108
+ Serve the pages next to your API with `mount`, or turn a route into a page with
109
+ `page`, whose function can use `Depends`:
110
+
111
+ ```python
112
+ from fastapi import Depends, FastAPI
113
+ from reaction import mount, page
114
+
115
+ api = FastAPI()
116
+ mount(api, App, "/ui") # a whole app under /ui
117
+
118
+ @page(api, "/orders/{order_id}", title="Order")
119
+ def order(order_id: int, user=Depends(current_user)):
120
+ return OrderPage(order_id=order_id, user=user)
121
+ ```
122
+
123
+ Run it as usual with `uvicorn main:api`. See [Integrations](https://github.com/Jeomon/pyreaction/blob/main/docs/integrations.md#fastapi).
124
+ </details>
125
+
126
+ <details>
127
+ <summary>Django</summary>
128
+
129
+ Put the pages in front of Django's ASGI app, in `asgi.py`:
130
+
131
+ ```python
132
+ from django.core.asgi import get_asgi_application
133
+ from reaction import wrap
134
+
135
+ application = wrap(get_asgi_application(), Dashboard, "/dashboard")
136
+ ```
137
+
138
+ Run it with `uvicorn mysite.asgi:application`. See [Integrations](https://github.com/Jeomon/pyreaction/blob/main/docs/integrations.md#django-flask-and-other-frameworks).
139
+ </details>
140
+
141
+ <details>
142
+ <summary>Flask</summary>
143
+
144
+ Install the `wsgi` extra, then wrap the Flask app:
145
+
146
+ ```python
147
+ from reaction import wrap
148
+
149
+ app = wrap(flask_app, Dashboard, "/dashboard")
150
+ ```
151
+
152
+ Run it with `uvicorn main:app`. See [Integrations](https://github.com/Jeomon/pyreaction/blob/main/docs/integrations.md#django-flask-and-other-frameworks).
153
+ </details>
154
+
155
+ <details>
156
+ <summary>Jinja templates</summary>
157
+
158
+ Install the `jinja` extra, then add a `{% component %}` tag to your templates:
159
+
160
+ ```python
161
+ from reaction import jinja_components
162
+
163
+ api.mount("/components", jinja_components(templates.env, [Counter, Chart], secret=SECRET))
164
+ ```
165
+
166
+ ```jinja
167
+ {% component "myapp.widgets.Counter" %}
168
+ {% component "myapp.widgets.Chart", values=[1, 2, 3] %}
169
+ ```
170
+
171
+ See [Integrations](https://github.com/Jeomon/pyreaction/blob/main/docs/integrations.md#jinja-templates).
172
+ </details>
173
+
174
+ ## 🖥️ Running pyreaction
175
+
176
+ | Command | |
177
+ | --- | --- |
178
+ | `python app.py` | a single file that calls `run(App)` |
179
+ | `uv run dev` | a project, with reload on save and errors shown in the page |
180
+ | `uv run pro` | a project, for production |
181
+ | `uvicorn main:app` | any app built with `create_app`, `mount` or `wrap` |
182
+
183
+ `reaction run` and `reaction dev` take `--host` and `--port`, which default to
184
+ `PYREACTION_HOST`/`127.0.0.1` and `PYREACTION_PORT`/`PORT`/`8000`. Behind a proxy,
185
+ pass the WebSocket upgrade through; [Deployment](https://github.com/Jeomon/pyreaction/blob/main/docs/deployment.md) has an Nginx
186
+ example and notes on workers and sticky sessions.
187
+
188
+ ## ⚙️ Configuration
189
+
190
+ Options go to `create_app` (and `run`, `mount`, `page`, `wrap`), into a project's
191
+ `[tool.pyreaction]` table, or into `PYREACTION_*` environment variables. The ones
192
+ most often changed:
193
+
194
+ | Option | Default | Environment variable | |
195
+ | --- | --- | --- | --- |
196
+ | `debug` | `False` | `PYREACTION_DEBUG` | errors and warnings shown in the page |
197
+ | `allowed_origins` | `()` | `PYREACTION_ALLOWED_ORIGINS` | extra origins allowed to open the WebSocket |
198
+ | `compress` | `True` | `PYREACTION_COMPRESS` | gzip pages; turn off when a proxy compresses |
199
+ | `resume_timeout` | `30.0` | `PYREACTION_RESUME_TIMEOUT` | seconds a dropped page's state is kept |
200
+ | `max_upload_size` | 10 MiB | `PYREACTION_MAX_UPLOAD_SIZE` | bytes per uploaded file |
201
+ | `reconnect_attempts` | `0` (no limit) | `PYREACTION_RECONNECT_ATTEMPTS` | failed attempts before a page gives up |
202
+
203
+ [Configuration](https://github.com/Jeomon/pyreaction/blob/main/docs/configuration.md) lists all of them.
204
+
205
+ ## 📚 Documentation
206
+
207
+ | | |
208
+ | --- | --- |
209
+ | [Getting started](https://github.com/Jeomon/pyreaction/blob/main/docs/getting-started.md) | install, a single-file app, a project |
210
+ | [Elements and events](https://github.com/Jeomon/pyreaction/blob/main/docs/elements-and-events.md) | describing the page, handlers, file uploads |
211
+ | [Hooks](https://github.com/Jeomon/pyreaction/blob/main/docs/hooks.md) | state, effects and the rest |
212
+ | [Data, forms and pending state](https://github.com/Jeomon/pyreaction/blob/main/docs/data-and-forms.md) | loading data, Suspense, form actions, optimistic updates |
213
+ | [Routing and the page head](https://github.com/Jeomon/pyreaction/blob/main/docs/routing.md) | URLs, links, redirects, `<title>` and `<meta>` |
214
+ | [Built-in components and the DOM](https://github.com/Jeomon/pyreaction/blob/main/docs/components.md) | refs, portals, long lists, error boundaries, JavaScript widgets |
215
+ | [Shared state](https://github.com/Jeomon/pyreaction/blob/main/docs/state.md) | stores shared between pages, processes, or within one page |
216
+ | [Integrations](https://github.com/Jeomon/pyreaction/blob/main/docs/integrations.md) | FastAPI, Django, Flask, Jinja templates, static pages |
217
+ | [Testing](https://github.com/Jeomon/pyreaction/blob/main/docs/testing.md) | a fake browser for unit tests, a live server for Playwright |
218
+ | [Configuration](https://github.com/Jeomon/pyreaction/blob/main/docs/configuration.md) | every option, in code, `pyproject.toml` or the environment |
219
+ | [Deployment and security](https://github.com/Jeomon/pyreaction/blob/main/docs/deployment.md) | workers, proxies, compression, origins, limits |
220
+ | [API reference](https://github.com/Jeomon/pyreaction/blob/main/docs/api.md) | everything `reaction` exports |
221
+ | [How it works](https://github.com/Jeomon/pyreaction/blob/main/docs/how-it-works.md) | the request, the live connection, and the update protocol |
222
+
223
+ Runnable apps are in [`examples/`](https://github.com/Jeomon/pyreaction/tree/main/examples): a todo list, routed pages, a login
224
+ flow, JavaScript widgets, and a FastAPI app.
225
+
226
+ ## 🔒 Security
227
+
228
+ - WebSockets are accepted only from the page's own origin, plus `allowed_origins`.
229
+ - Log in with ordinary HTTP routes that set an `HttpOnly` cookie; a WebSocket cannot
230
+ set cookies. `examples/login.py` is a complete version.
231
+ - Text is always escaped. `dangerously_set_inner_html`, `js()` code and
232
+ `js_component_from_string` are sent as written: never build them from user input.
233
+ - Uploads, queued events and pending updates are capped per page.
234
+
235
+ [Deployment and security](https://github.com/Jeomon/pyreaction/blob/main/docs/deployment.md#security) has the details. To report a
236
+ vulnerability, see [SECURITY.md](https://github.com/Jeomon/pyreaction/blob/main/SECURITY.md); please do not open a public issue.
237
+
238
+ ## 📝 Limitations
239
+
240
+ - **Every interaction is a round trip.** Handlers run on the server, so latency
241
+ follows the network; use `js()` for what must react instantly, such as selecting
242
+ an input's text.
243
+ - **Each open page holds state on the server.** Memory grows with open tabs, and a
244
+ 10,000-row page holds about 20 MB. Long lists should use `VirtualList`.
245
+ - **Rendering runs on the server's event loop.** A very large page (10,000 rows)
246
+ takes about 80 ms to serve, during which other pages on that process wait.
247
+ - **Resuming after a drop needs the same process.** With several workers, route a
248
+ page's connections to the worker that served it (sticky sessions).
249
+ - **Before 1.0**, the API may still change between minor versions; see the
250
+ [changelog](https://github.com/Jeomon/pyreaction/blob/main/CHANGELOG.md).
251
+ - **The import name is `reaction`**, which an unrelated, unmaintained PyPI package
252
+ (`reaction`, 2020) also uses. Do not install both in one environment.
253
+
254
+ ## 🤝 Contributing
255
+
256
+ Bug reports and pull requests are welcome. [CONTRIBUTING.md](https://github.com/Jeomon/pyreaction/blob/main/CONTRIBUTING.md)
257
+ explains the setup, the tests and type checks, and what a change needs.
258
+ [CHANGELOG.md](https://github.com/Jeomon/pyreaction/blob/main/CHANGELOG.md) lists what changed in each version.
259
+
260
+ ## 🙏 References
261
+
262
+ pyreaction follows the design of these projects; their documentation is the best
263
+ explanation of the ideas it borrows.
264
+
265
+ - **[React](https://react.dev)** ([source](https://github.com/facebook/react)):
266
+ the component model, hooks and their rules, keys and reconciliation, Suspense,
267
+ error boundaries, portals, and React 19's form actions, `use_optimistic`, `use`,
268
+ `cache`, resource hints and `ViewTransition`. Where pyreaction has a React API,
269
+ it follows React's behaviour, checked against React 19.3's source.
270
+ - **[ReactPy](https://reactpy.dev)** ([source](https://github.com/reactive-python/reactpy)):
271
+ React's model in Python, rendered over a WebSocket. pyreaction's hook names,
272
+ `html` element factories, `to_vdom` key names and JavaScript component interop
273
+ follow ReactPy's lead; it differs in diffing on the server and sending DOM
274
+ operations rather than VDOM trees, and in rendering every page as HTML first.
275
+
276
+ It is built on [Starlette](https://www.starlette.io), [uvicorn](https://www.uvicorn.org)
277
+ and [orjson](https://github.com/ijl/orjson).
278
+
279
+ pyreaction is an independent project. It is not affiliated with, endorsed by or
280
+ sponsored by Meta, the React project or the ReactPy project. React is a trademark of
281
+ Meta Platforms, Inc.; the name is used only to describe what pyreaction follows.
282
+
283
+ ## 🪪 License
284
+
285
+ pyreaction is free and open-source software, released under the
286
+ [MIT License](https://github.com/Jeomon/pyreaction/blob/main/LICENSE). You may use, copy, modify, merge, publish, distribute,
287
+ sublicense and sell it, in personal and commercial projects alike, provided the
288
+ copyright notice and the license text are included in all copies or substantial
289
+ portions of the software.
290
+
291
+ The software is provided "as is", without warranty of any kind; the authors are
292
+ not liable for any claim or damages arising from its use. Contributions to
293
+ pyreaction are accepted under the same license (see [CONTRIBUTING.md](https://github.com/Jeomon/pyreaction/blob/main/CONTRIBUTING.md)).
294
+
295
+ ## 📄 Citation
296
+
297
+ ```bibtex
298
+ @software{pyreaction,
299
+ author = {jeomon},
300
+ title = {pyreaction: React-style UI components in pure Python},
301
+ year = {2026},
302
+ publisher = {GitHub},
303
+ url = {https://github.com/Jeomon/pyreaction}
304
+ }
305
+ ```