Browser hot reload for Python ASGI web apps
Project description
arel
Browser hot reload for Python ASGI web apps.
Overview
What is this for?
arel can be used to implement development-only hot-reload for non-Python files that are not read from disk on each request. This may include HTML templates, GraphQL schemas, cached rendered Markdown content, etc.
How does it work?
arel watches changes over a set of files. When a file changes, arel notifies the browser (using WebSocket), and an injected client script triggers a page reload. You can register your own reload hooks for any extra server-side operations, such as reloading cached content or re-initializing other server-side resources.
Installation
pip install 'arel==0.4.*'
Quickstart
For a working example using Starlette, see the Example section.
Although the exact instructions to set up hot reload with arel depend on the specifics of your ASGI framework, there are three general steps to follow:
-
Create an
HotReloadinstance, passing one or more directories of files to watch, and optionally a list of callbacks to call before a reload is triggered:import arel async def reload_data(): print("Reloading server data...") hotreload = arel.HotReload( paths=[ arel.Path("./server/data", on_reload=[reload_data]), arel.Path("./server/static"), ], )
-
Mount the hot reload endpoint, and register its startup and shutdown event handlers. If using Starlette, this can be done like this:
from starlette.applications import Starlette from starlette.routing import WebSocketRoute app = Starlette( routes=[WebSocketRoute("/hot-reload", hotreload, name="hot-reload")], on_startup=[hotreload.startup], on_shutdown=[hotreload.shutdown], )
-
Add the JavaScript code to your website HTML. If using Starlette with Jinja templates, you can do this by updating the global environment, then injecting the script into your base template:
templates.env.globals["DEBUG"] = os.getenv("DEBUG") # Development flag. templates.env.globals["hotreload"] = hotreload
<body> <!-- Page content... --> <!-- Hot reload script --> {% if DEBUG %} {{ hotreload.script(url_for('hot-reload')) | safe }} {% endif %} </body>
Example
The example directory contains an example Markdown-powered website that uses arel to refresh the browser when Markdown content or HTML templates change.
License
MIT
Changelog
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog.
0.4.0 - 2025-09-22
Removed
- Drop support for Python 3.7 and 3.8 (EOL versions). (Pull #39)
Added
- Add support for Python 3.13. (Pull #39)
Fixed
- Update watchfiles dependency to support modern versions (>=0.18,<2.0). (Pull #39)
0.3.0 - 2023-12-29
Changed
- Use
watchfilesinstead ofwatchgod. This unlocks Python 3.12 support. (Pull #34)
Added
- Add support for Python 3.12. (Pull #35)
0.2.0 - 2020-07-08
Added
- Add support for watching multiple directories, each with its own reload callbacks. (Pull #15)
Changed
arel.HotReload("./directory", on_reload=[...])should now be written asarel.HotReload(paths=[arel.Path("./directory", on_reload=[...])]). (Pull #15)
0.1.0 - 2020-04-11
Initial release.
Added
- Add
HotReloadASGI application class. (Pull #1)
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file arel-0.4.0.tar.gz.
File metadata
- Download URL: arel-0.4.0.tar.gz
- Upload date:
- Size: 14.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.12.11
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
08b2f72f767a84825a649891eb30f20f89c0de6aa67134939691ee0012aafc73
|
|
| MD5 |
1c1ffe6c1718980ab16ed35830ec679c
|
|
| BLAKE2b-256 |
4e46a1a8634e7e6b8f0cd86021cc428127671c71457dc051da703b55ea8d90ec
|
File details
Details for the file arel-0.4.0-py3-none-any.whl.
File metadata
- Download URL: arel-0.4.0-py3-none-any.whl
- Upload date:
- Size: 8.3 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.12.11
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
7b1fe5d10c06a6f231cfeec79e48888176931b86f0ae6e432196845edf818109
|
|
| MD5 |
d404034e8c56239d779221d3c2299322
|
|
| BLAKE2b-256 |
86a3a70c2c3bcb50254522f997298f90a44ba698a60a47efb40d9cceab31a4f5
|
