fastapi-reloader 1.3.1__py2.py3-none-any.whl → 1.3.2__py2.py3-none-any.whl

fastapi_reloader/__init__.py

@@ -1,4 +1,4 @@
 from .core import send_reload_signal
-from .patcher import patch_for_auto_reloading
+from .patcher import auto_refresh_middleware, html_injection_middleware, patch_for_auto_reloading, reloader_route_middleware
 
-__all__ = ["patch_for_auto_reloading", "send_reload_signal"]
+__all__ = ["auto_refresh_middleware", "html_injection_middleware", "patch_for_auto_reloading", "reloader_route_middleware", "send_reload_signal"]

fastapi_reloader/core.py

@@ -13,6 +13,7 @@ requests: dict[int, list[Queue[Literal[0, 1]]]] = defaultdict(list)
 
 
 def send_reload_signal():
+    """Broadcast a reload signal to all connected clients and break their long-polling connections."""
     for subscribers in requests.values():
         for queue in subscribers:
             queue.put_nowait(1)

fastapi_reloader/patcher.py

@@ -2,7 +2,7 @@ from collections.abc import Awaitable, Callable
 from contextlib import asynccontextmanager
 from copy import copy
 from math import inf
-from typing import TypeGuard
+from typing import Generic, TypeGuard, TypeVar
 
 from asgi_lifespan import LifespanManager
 from fastapi import FastAPI, Request, Response
@@ -40,10 +40,25 @@ async def _injection_http_middleware(request: Request, call_next: Callable[[Requ
     return StreamingResponse(response(), res.status_code, headers, res.media_type)
 
 
-injection_middleware = Middleware(BaseHTTPMiddleware, dispatch=_injection_http_middleware)
+T = TypeVar("T", bound=ASGIApp)
 
 
-def _reloader_middleware(app: ASGIApp):
+class UniversalMiddleware(Middleware, Generic[T]):
+    """Adapt an ASGI middleware so it can serve both Starlette/FastAPI middleware slots and plain ASGI usage."""
+
+    def __init__(self, asgi_middleware: Callable[[ASGIApp], T]):
+        self.fn = asgi_middleware
+        super().__init__(self)
+
+    def __call__(self, app):
+        return self.fn(app)
+
+
+html_injection_middleware = UniversalMiddleware(lambda app: BaseHTTPMiddleware(app, _injection_http_middleware))
+"""This middleware injects the HMR client script into HTML responses."""
+
+
+def _wrap_asgi_app(app: ASGIApp):
     @asynccontextmanager
     async def lifespan(_):
         async with LifespanManager(app, inf, inf):
@@ -56,13 +71,21 @@ def _reloader_middleware(app: ASGIApp):
     return new_app
 
 
-def patch_for_auto_reloading(app: ASGIApp):
+reloader_route_middleware = UniversalMiddleware(_wrap_asgi_app)
+"""This middleware wraps the app with a FastAPI app that handles reload signals."""
+
+
+def patch_for_auto_reloading(app: ASGIApp):  # this function is preserved for backward compatibility
     if isinstance(app, Starlette):  # both FastAPI and Starlette have user_middleware attribute
         new_app = copy(app)
-        new_app.user_middleware = [*app.user_middleware, injection_middleware]  # before compression middlewares
-        return _reloader_middleware(new_app)
+        new_app.user_middleware = [*app.user_middleware, html_injection_middleware]  # before compression middlewares
+        return _wrap_asgi_app(new_app)
 
-    new_app = _reloader_middleware(app)
-    new_app.user_middleware.append(injection_middleware)  # the last middleware is the first one to be called
+    new_app = _wrap_asgi_app(app)
+    new_app.user_middleware.append(html_injection_middleware)  # the last middleware is the first one to be called
 
     return new_app
+
+
+auto_refresh_middleware = UniversalMiddleware(patch_for_auto_reloading)
+"""This middleware combines the two middlewares above to enable the full functionality of this package."""

fastapi_reloader-1.3.2.dist-info/METADATA

@@ -0,0 +1,160 @@
+Metadata-Version: 2.1
+Name: fastapi-reloader
+Version: 1.3.2
+Project-URL: Homepage, https://github.com/promplate/hmr
+Requires-Dist: asgi-lifespan~=2.0
+Requires-Dist: fastapi~=0.115
+Description-Content-Type: text/markdown
+
+# FastAPI Reloader
+
+[![PyPI - Version](https://img.shields.io/pypi/v/fastapi-reloader)](https://pypi.org/project/fastapi-reloader/)
+[![PyPI - Downloads](https://img.shields.io/pypi/dw/fastapi-reloader)](https://pepy.tech/projects/fastapi-reloader/)
+
+A lightweight middleware ASGI applications that enables automatic browser page reloading during development.
+
+## Features
+
+- 🔄 Automatic browser refresh when server restarts
+- 🚀 Works with any ASGI application and any event loop
+- 🔌 Simple integration with just two steps
+
+## Installation
+
+```sh
+pip install fastapi-reloader
+```
+
+For a more comprehensive development experience, consider using `uvicorn-hmr` which includes this package:
+
+```sh
+pip install uvicorn-hmr[all]
+```
+
+Then run your app with:
+
+```sh
+uvicorn-hmr main:app --refresh
+```
+
+## Standalone Usage
+
+You can also use `fastapi-reloader` as a standalone package without `uvicorn-hmr`. However, there are a few things to keep in mind.
+
+It's important to understand the roles of the different packages:
+
+- `uvicorn-hmr` Provides server-side hot module reloading (as a drop-in replacement for `uvicorn --reload`).
+- `fastapi-reloader` Triggers a [browser page refresh](https://developer.mozilla.org/docs/Web/API/Location/reload "window.reload") when the server restarts.
+
+If you configure `fastapi-reloader` manually and run your ASGI app with a standard reloader like `uvicorn --reload`, the behavior will be similar to `uvicorn-hmr --refresh` but with "cold" (process-restarting) server reloads instead of "hot" (in-process) reloads provided by [`hmr`](https://pyth-on-line.promplate.dev/hmr).
+
+The manual integration steps are quite straightforward:
+
+### Step 1: Add Middleware
+
+`fastapi-reloader` works by injecting a `<script>` tag into HTML responses.
+
+```python
+from fastapi import FastAPI
+from fastapi_reloader import auto_refresh_middleware
+
+app = FastAPI()
+app.add_middleware(auto_refresh_middleware)
+```
+
+Note that this middleware must be placed **before** any compression middleware (like Starlette's `GZipMiddleware`).
+
+If you can't place it as early as possible in the middleware stack, you can use the following ways:
+
+```python
+# Approach 1: wrap your app with it (works with any ASGI app)
+app = html_injection_middleware(app)
+
+# Approach 2: manually add it to the user_middleware list (supported FastAPI, Starlette etc.)
+app.user_middleware.append(html_injection_middleware)
+```
+
+The `auto_refresh_middleware` is a convenient wrapper that applies both `reloader_route_middleware` and `html_injection_middleware`. However, you can add them separately for more control:
+
+- **Fine-grained control**: If a sub-router in your application uses compression, you must add `html_injection_middleware` before the compression middleware on that router.
+- **Scoped reloading**: If you only want to enable auto-reloading for a specific part of your app, you can apply `html_injection_middleware` only to that sub-router.
+
+> The `reloader_route_middleware` mounts the necessary endpoints and should typically be added to the main application instance.
+
+```python
+from fastapi import FastAPI
+from starlette.middleware.gzip import GZipMiddleware
+from fastapi_reloader import html_injection_middleware, reloader_route_middleware
+
+app = FastAPI()
+# Apply the reloader routes to the main app
+app.add_middleware(reloader_route_middleware)
+
+# Apply HTML injection middleware before compression ones
+app.add_middleware(html_injection_middleware)
+app.add_middleware(GZipMiddleware)  # or BrotliMiddleware, ZstMiddleware, etc.
+```
+
+FastAPI routers needs further configuration like this (because [`fastapi.APIRouter`](https://fastapi.tiangolo.com/reference/apirouter/) doesn't support middlewares directly):
+
+```python
+app.mount(router.prefix, html_injection_middleware(router))  # place this first to shadows the next line
+app.include_router(router)  # this can't be removed because FastAPI needs it to generate OpenAPI schema
+```
+
+### Step 2: Manually Triggering Reloads
+
+When used standalone, you **have to** add a few lines into your code to manually *trigger the reload signal* (aka. call `send_reload_signal()`) before your ASGI server shuts down (I mean, when a server receives a shutdown signal like SIGINT/SIGTERM or it want to restart because of code changes etc.). `fastapi-reloader` works with any ASGI server, but most of them wait for open connections to close before shutting down. The long-polling connection internally used by `uvicorn-hmr` won't close on its own (because we have no idea of when it will happen), preventing the server from shutting down gracefully (behaving like a deadlock).
+
+So you need to hook into your ASGI server's shutdown process to call `send_reload_signal()`. This can be done through subclassing, monkey-patching, or using a library like [`dowhen`](https://github.com/gaogaotiantian/dowhen).
+
+Here is an example for `uvicorn`:
+
+```python
+from fastapi_reloader import send_reload_signal
+import uvicorn
+
+_shutdown = uvicorn.Server.shutdown
+
+def shutdown(self, *args, **kwargs):
+    send_reload_signal()
+    return _shutdown(self, *args, **kwargs)
+
+uvicorn.Server.shutdown = shutdown
+```
+
+and start the server as normal
+
+```sh
+uvicorn main:app --reload
+```
+
+or this way:
+
+```python
+if __name__ == "__main__":
+    uvicorn.run("main:app", reload=True)
+```
+
+## How It Works
+
+The package injects a small JavaScript snippet into your HTML responses that:
+
+1. Opens a long-lived connection to the server
+2. Listens for reload signals
+3. Starts polling for heartbeat when `send_reload_signal` is called
+4. Reloads the page when heartbeat from new server is received
+
+## Configuration
+
+The package works out-of-the-box with default settings. No additional configuration is required.
+
+## Limitations
+
+- Unlike `uvicorn-hmr`, which does on-demand fine-grained reloading on the server side, this package simply reloads all the pages in the browser.
+- Designed for development use only (not for production)
+- Requires JavaScript to be enabled in the browser
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.

fastapi_reloader-1.3.2.dist-info/RECORD

@@ -0,0 +1,8 @@
+fastapi_reloader-1.3.2.dist-info/METADATA,sha256=D7-0CWUurSwKz-MdsPAQL-Tm4SE6Lg0X5V_3q3I2qSQ,6314
+fastapi_reloader-1.3.2.dist-info/WHEEL,sha256=pz1FfwQ2kf9tI4G8U2ObRTKdvsTSmrreuBTtdnO8pJw,94
+fastapi_reloader-1.3.2.dist-info/entry_points.txt,sha256=6OYgBcLyFCUgeqLgnvMyOJxPCWzgy7se4rLPKtNonMs,34
+fastapi_reloader/__init__.py,sha256=qWjX076aoLEZxZoOIvtmg84khic2FBXpAWuRWVbouTY,309
+fastapi_reloader/core.py,sha256=pug78QfiDLaX7uBj9zbjAwphMlsFGlam0qEpUnHOhfo,1779
+fastapi_reloader/patcher.py,sha256=MXZjva7zIdSYN4j5RGxBMy2UtJ34pSj3ylwzcKfoAKU,3318
+fastapi_reloader/runtime.js,sha256=pUPeMnMuKGHhBTudp6bFuNTTyZhGSvrvvWy_lWVN8nA,713
+fastapi_reloader-1.3.2.dist-info/RECORD,,

fastapi_reloader-1.3.1.dist-info/METADATA

@@ -1,84 +0,0 @@
-Metadata-Version: 2.1
-Name: fastapi-reloader
-Version: 1.3.1
-Project-URL: Homepage, https://github.com/promplate/hmr
-Requires-Dist: asgi-lifespan~=2.0
-Requires-Dist: fastapi~=0.115
-Description-Content-Type: text/markdown
-
-# FastAPI Reloader
-
-[![PyPI - Version](https://img.shields.io/pypi/v/fastapi-reloader)](https://pypi.org/project/fastapi-reloader/)
-[![PyPI - Downloads](https://img.shields.io/pypi/dw/fastapi-reloader)](https://pepy.tech/projects/fastapi-reloader/)
-
-A lightweight middleware ASGI applications that enables automatic browser page reloading during development.
-
-## Features
-
-- 🔄 Automatic browser refresh when code changes (work with `uvicorn-hmr`)
-- 🚀 Works with any ASGI application
-- 🔌 Simple integration with just two function calls
-
-## Installation
-
-```sh
-pip install fastapi-reloader
-```
-
-For a more comprehensive development experience, consider using `uvicorn-hmr` which includes this package:
-
-```sh
-pip install uvicorn-hmr[all]
-```
-
-Then run your app with:
-
-```sh
-uvicorn-hmr main:app --reload
-```
-
-## Advanced Usage
-
-### Manual Integration
-
-```python
-from fastapi import FastAPI
-from fastapi_reloader import patch_for_auto_reloading
-
-app = FastAPI()  # or some other ASGI app
-
-app = patch_for_auto_reloading(app)  # this will return a new FastAPI app
-```
-
-### Manual Trigger
-
-You can manually trigger a reload from your code:
-
-```python
-from fastapi_reloader import send_reload_signal
-
-send_reload_signal()  # When you need to trigger a reload
-```
-
-## How It Works
-
-The package injects a small JavaScript snippet into your HTML responses that:
-
-1. Opens a long-lived connection to the server
-2. Listens for reload signals
-3. Start polling for heartbeat when `send_reload_signal` is called
-4. Reloads the page when heartbeat from new server is received
-
-## Configuration
-
-The package works out-of-the-box with default settings. No additional configuration is required.
-
-## Limitations
-
-- Unlike `uvicorn-hmr`, which does on-demand fine-grained reloading on the server side, this package simply reloads all the pages in the browser.
-- Designed for development use only (not for production)
-- Requires JavaScript to be enabled in the browser
-
-## Contributing
-
-Contributions are welcome! Please open an issue or submit a pull request.

fastapi_reloader-1.3.1.dist-info/RECORD

@@ -1,8 +0,0 @@
-fastapi_reloader-1.3.1.dist-info/METADATA,sha256=xKLO2Z0ZWciUVgTReqnzDklb611n6zA5PEthLU59ODA,2270
-fastapi_reloader-1.3.1.dist-info/WHEEL,sha256=pz1FfwQ2kf9tI4G8U2ObRTKdvsTSmrreuBTtdnO8pJw,94
-fastapi_reloader-1.3.1.dist-info/entry_points.txt,sha256=6OYgBcLyFCUgeqLgnvMyOJxPCWzgy7se4rLPKtNonMs,34
-fastapi_reloader/__init__.py,sha256=VE5m-0M92Weme8COqLs0LwIx5g6FHhqyOLGAgY6Zkzs,145
-fastapi_reloader/core.py,sha256=eAyPhBZaFiKepy5NcU966adAJwqFTpHlK_uXn1cJQU8,1676
-fastapi_reloader/patcher.py,sha256=nwn9sJW8KsXUr7dSPClWuPCanP453ymazfetVtuPaDA,2436
-fastapi_reloader/runtime.js,sha256=pUPeMnMuKGHhBTudp6bFuNTTyZhGSvrvvWy_lWVN8nA,713
-fastapi_reloader-1.3.1.dist-info/RECORD,,