fastapi-reloader 1.3__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

@@ -1,11 +1,13 @@
 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
 from fastapi.responses import StreamingResponse
+from starlette.applications import Starlette
 from starlette.middleware import Middleware
 from starlette.middleware.base import BaseHTTPMiddleware
 from starlette.types import ASGIApp
@@ -14,11 +16,49 @@ from .core import reload_router
 
 
 def is_streaming_response(response: Response) -> TypeGuard[StreamingResponse]:
-    # In fact, it may not be a fastapi's StreamingResponse, but a starlette's one with the same interface
+    # In fact, it may not be a Starlette's StreamingResponse, but an internal one with the same interface
     return hasattr(response, "body_iterator")
 
 
-def patch_for_auto_reloading(app: ASGIApp):
+async def _injection_http_middleware(request: Request, call_next: Callable[[Request], Awaitable[Response]]):
+    res = await call_next(request)
+
+    if request.method != "GET" or "html" not in (res.headers.get("content-type", "")) or res.headers.get("content-encoding", "identity") != "identity":
+        return res
+
+    async def response():
+        if is_streaming_response(res):
+            async for chunk in res.body_iterator:
+                yield chunk
+        else:
+            yield res.body
+
+        yield b'\n\n <script src="/---fastapi-reloader---/poller.js"></script>'
+
+    headers = {k: v for k, v in res.headers.items() if k.lower() not in {"content-length", "transfer-encoding"}}
+
+    return StreamingResponse(response(), res.status_code, headers, res.media_type)
+
+
+T = TypeVar("T", bound=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):
@@ -28,25 +68,24 @@ def patch_for_auto_reloading(app: ASGIApp):
     new_app.include_router(reload_router)
     new_app.mount("/", app)
 
-    async def hmr_middleware(request: Request, call_next: Callable[[Request], Awaitable[Response]]):
-        res = await call_next(request)
-
-        if request.method != "GET" or "html" not in (res.headers.get("content-type", "")):
-            return res
+    return new_app
 
-        async def response():
-            if is_streaming_response(res):
-                async for chunk in res.body_iterator:
-                    yield chunk
-            else:
-                yield res.body
 
-            yield b'\n\n <script src="/---fastapi-reloader---/poller.js"></script>'
+reloader_route_middleware = UniversalMiddleware(_wrap_asgi_app)
+"""This middleware wraps the app with a FastAPI app that handles reload signals."""
 
-        headers = {k: v for k, v in res.headers.items() if k.lower() not in {"content-length", "content-encoding", "transfer-encoding"}}
 
-        return StreamingResponse(response(), res.status_code, headers, res.media_type)
+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, html_injection_middleware]  # before compression middlewares
+        return _wrap_asgi_app(new_app)
 
-    new_app.user_middleware.append(Middleware(BaseHTTPMiddleware, dispatch=hmr_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/runtime.js

@@ -1,4 +1,17 @@
-(async function () {
+async function poll() {
+  while (true) {
+    try {
+      const res = await fetch("/---fastapi-reloader---", { method: "HEAD" });
+      if (res.ok) {
+        break;
+      } else if (res.status !== 502) {
+        return;
+      }
+    } catch (error) {}
+  }
+}
+
+async function main() {
   const response = await fetch("/---fastapi-reloader---/0");
   const reader = response.body.getReader();
   const decoder = new TextDecoder();
@@ -10,20 +23,11 @@
     if (value) {
       const chunk = decoder.decode(value, { stream: true });
       if (chunk.includes("1")) {
-        while (true) {
-          try {
-            const res = await fetch("/---fastapi-reloader---", {
-              method: "HEAD",
-            });
-            if (res.ok) {
-              break;
-            } else if (res.status !== 502) {
-              return;
-            }
-          } catch (error) {}
-        }
+        await poll();
         location.reload();
       }
     }
   }
-})();
+}
+
+main();

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.dist-info/METADATA

@@ -1,84 +0,0 @@
-Metadata-Version: 2.1
-Name: fastapi-reloader
-Version: 1.3
-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.dist-info/RECORD

@@ -1,8 +0,0 @@
-fastapi_reloader-1.3.dist-info/METADATA,sha256=QrT6bBHmbNP3BbLMDtW7M2nskhCK_AsXgZcELTC5oCk,2268
-fastapi_reloader-1.3.dist-info/WHEEL,sha256=pz1FfwQ2kf9tI4G8U2ObRTKdvsTSmrreuBTtdnO8pJw,94
-fastapi_reloader-1.3.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=NOLTYVkbaZxRN6BSRRbsC0gUtdxn7OdARLZppcZ12jY,1921
-fastapi_reloader/runtime.js,sha256=H9SCpyGpBUmfvcdlzpU4RXnIBCYSQwIqXZ7jd1bdtSo,743
-fastapi_reloader-1.3.dist-info/RECORD,,