Merge pull request #32 from msamsami/docs/improve-examples-and-clarity

📝 Improve documentation examples and clarity

Author: msamsami

README.md

@@ -71,7 +71,7 @@ app = FastAPI()
 app.add_middleware(MaintenanceModeMiddleware)
 
 @app.get("/")
-def root():
+async def root():
     return {"message": "Hello World"}
 ```
 

docs/contributing.md

@@ -2,7 +2,7 @@
 
 We welcome contributions from the community to help improve FastAPI Maintenance.
 
-First, you might want to see the basic ways to [help FastAPI Maintenance package and get help](help.md).
+First, you might want to see the basic ways to [help FastAPI Maintenance project and get help](help.md).
 
 ## Developing
 
@@ -49,7 +49,7 @@ We use pytest for testing. To run the tests and generate coverage reports:
 bash scripts/test.sh
 ```
 
-This command generates a directory `./htmlcov/`, if you open the file `./htmlcov/index.html` in your browser, you can explore interactively the regions of code that are covered by the tests, and notice if there is any region missing.
+This command generates a directory `./htmlcov/`. Open the file `./htmlcov/index.html` in your browser to interactively explore which regions of code are covered by tests and identify any missing coverage.
 
 ## Docs
 

docs/help.md

@@ -1,6 +1,6 @@
 # Help
 
-This section provides information on how to get help with FastAPI Maintenance and how you can contribute to the project.
+This section provides information on how to get help with FastAPI Maintenance and how you can support the project.
 
 ## Getting Help
 

docs/index.md

@@ -71,7 +71,7 @@ app = FastAPI()
 app.add_middleware(MaintenanceModeMiddleware)
 
 @app.get("/")
-def root():
+async def root():
     return {"message": "Hello World"}
 ```
 

docs/tutorial/advanced-usage.md

@@ -1,13 +1,13 @@
 # Advanced Usage
 
-This section covers advanced usage patterns and integration scenarios for the FastAPI Maintenance package. These advanced usage patterns demonstrate how FastAPI Maintenance can be integrated into complex systems and workflows.
+This section covers advanced usage patterns and integration scenarios, demonstrating how FastAPI Maintenance can be integrated into complex systems and workflows.
 
 ## Combining Multiple Features
 
 You can combine various features of FastAPI Maintenance for sophisticated maintenance scenarios:
 
 ```python
-from fastapi import FastAPI, Request, Depends
+from fastapi import FastAPI, Request
 from fastapi.responses import JSONResponse
 from fastapi_maintenance import (
     MaintenanceModeMiddleware,
@@ -62,6 +62,8 @@ async def update_system():
 You can use FastAPI's events to configure maintenance mode during application startup and shutdown:
 
 ```python
+from contextlib import asynccontextmanager
+
 from fastapi import FastAPI
 from fastapi_maintenance import (
     MaintenanceModeMiddleware,
@@ -72,18 +74,16 @@ from fastapi_maintenance import (
 # Configure backend
 configure_backend("file", file_path="maintenance_mode.txt")
 
-app = FastAPI()
-app.add_middleware(MaintenanceModeMiddleware)
-
-@app.on_event("startup")
-async def startup_event():
-    # Clear any maintenance mode from previous crashes on startup
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Startup: Clear any maintenance mode from previous crashes
     await set_maintenance_mode(False)
-
-@app.on_event("shutdown")
-async def shutdown_event():
-    # Enable maintenance mode during shutdown
+    yield
+    # Shutdown: Enable maintenance mode
     await set_maintenance_mode(True)
+
+app = FastAPI(lifespan=lifespan)
+app.add_middleware(MaintenanceModeMiddleware)
 ```
 
 ## Integration with Other Middleware

docs/tutorial/backends.md

@@ -1,12 +1,12 @@
 # Backend Options
 
-FastAPI Maintenance provides flexible backend storage options for managing the maintenance mode state. This allows you to store the maintenance mode state in different ways depending on your application's needs.
+FastAPI Maintenance provides flexible backend storage options for managing the maintenance mode state. This allows you to store and read the maintenance mode state in different ways depending on your application's needs.
 
 ## Available Backends
 
 The package currently includes two built-in backend options:
 
-1. **Environment Variable Backend** (default): Uses environment variables to store the maintenance mode state
+1. **Environment Variable Backend** (default): Reads the maintenance mode state from environment variables
 2. **Local File Backend**: Uses a local file to store the maintenance mode state
 
 ## Environment Variable Backend
@@ -41,7 +41,7 @@ The environment variable backend is **read-only** at runtime. This means:
 
 - You can only set the maintenance mode state *before* starting your application.
 - Direct calls to `set_maintenance_mode()` will log a warning and have no effect.
-- However, context manager `maintenance_mode_on()` **will work as expected for the duration of the context block**. They achieve this by using a temporary, in-memory override of the maintenance state. The actual environment variable is not changed. This allows you to temporarily simulate maintenance mode changes even with the environment variable backend.
+- However, context manager `maintenance_mode_on()` **will work as expected for the duration of the context block**. It achieves this by using a temporary, in-memory override of the maintenance state. The actual environment variable is not changed. This allows you to temporarily simulate maintenance mode changes even with the environment variable backend.
 
 Use this backend when you primarily manage maintenance mode state externally (e.g., via deployment scripts or orchestration tools) but still want the flexibility of temporary overrides within your code using context managers.
 

docs/tutorial/cli.md

@@ -110,6 +110,7 @@ Use the CLI in monitoring scripts:
 #!/bin/bash
 
 # Check maintenance status and act accordingly
+# Note: This script relies on the CLI output containing "ON" for active maintenance
 if fastapi-maintenance status --backend env --var-name PROD_MAINTENANCE_MODE | grep -q "ON"; then
     echo "Application is in maintenance mode"
     exit 1
@@ -128,14 +129,11 @@ Integrate with deployment automation:
 
 # Check if maintenance mode is active before deployment
 echo "Checking maintenance mode status..."
-fastapi-maintenance status --backend file --file-path /app/maintenance.txt
 
-# The exit code can be used in conditional logic
-if [ $? -eq 0 ]; then
-    echo "Status check completed successfully"
-else
-    echo "Failed to check maintenance status"
-    exit 1
+STATUS=$(fastapi-maintenance status --backend file --file-path /app/maintenance.txt)
+
+if echo "$STATUS" | grep -q "ON"; then
+    echo "Warning: Application is in maintenance mode"
 fi
 ```
 

docs/tutorial/context-manager.md

@@ -6,9 +6,7 @@ FastAPI Maintenance provides an async context manager that temporarily enables m
 - Application deployments
 - Data imports or exports
 - Content synchronization and updates
-- System updates
 - User permission and role updates
-- Rolling out new features
 - Temporarily disabling services during critical operations
 
 ## Basic Usage
@@ -115,9 +113,11 @@ async def custom_maintenance_operation():
 
 ## Nesting Context Managers
 
-You can nest the `maintenance_mode_on` context manager. When nesting, the innermost context will maintain the state established by the outer context:
+You can nest the `maintenance_mode_on` context manager. When nesting, maintenance mode remains ON throughout all nested contexts until the outermost context exits:
 
 ```python
+from fastapi_maintenance import maintenance_mode_on, get_maintenance_mode
+
 async def complex_operation():
     # Start with maintenance OFF
     assert not await get_maintenance_mode()

docs/tutorial/custom-exemptions.md

@@ -63,12 +63,12 @@ The handler function must:
 # Synchronous handler
 def is_exempt(request: Request) -> bool:
     # Logic here
-    return True/False
+    return True  # or False
 
 # Asynchronous handler
 async def is_exempt(request: Request) -> bool:
     # Async logic here
-    return True/False
+    return True  # or False
 ```
 
 ### Return Value
@@ -79,7 +79,7 @@ The return value determines how the request is handled:
 
 ### Execution Context
 
-The handler runs for every request when maintenance middleware is in place, so:
+The handler is evaluated for every request that reaches the maintenance middleware, so:
 - Keep it lightweight to avoid performance issues
 - Handle all exceptions internally
 - Avoid side effects that could impact other requests
@@ -112,7 +112,10 @@ def is_exempt(request: Request) -> bool:
     client_host = request.client.host if request.client else None
 
     # Exempt localhost and internal network
-    if client_host in ["127.0.0.1", "::1"] or client_host.startswith("10."):
+    if client_host and (
+        client_host in ["127.0.0.1", "::1"]
+        or client_host.startswith("10.")
+    ):
         return True
 
     return False

docs/tutorial/custom-responses.md

@@ -56,7 +56,7 @@ from fastapi_maintenance import MaintenanceModeMiddleware
 
 app = FastAPI()
 
-async def custom_maintenance_response(request: Request) -> JSONResponse:
+def custom_maintenance_response(request: Request) -> JSONResponse:
     return JSONResponse(
         status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
         content={
@@ -86,7 +86,7 @@ from fastapi_maintenance import MaintenanceModeMiddleware
 
 app = FastAPI()
 
-async def html_maintenance_page(request: Request) -> HTMLResponse:
+def html_maintenance_page(request: Request) -> HTMLResponse:
     html_content = """
     <!DOCTYPE html>
     <html>
@@ -153,7 +153,7 @@ from fastapi_maintenance import MaintenanceModeMiddleware
 
 app = FastAPI()
 
-async def content_negotiated_response(request: Request) -> Response:
+def content_negotiated_response(request: Request) -> Response:
     accept = request.headers.get("accept", "")
 
     # Return HTML for browser requests
@@ -191,11 +191,15 @@ app = FastAPI()
 # Set up templates
 templates = Jinja2Templates(directory="templates")
 
-async def template_maintenance_page(request: Request) -> Response:
+def template_maintenance_page(request: Request) -> Response:
     # Pass data to the template
     return templates.TemplateResponse(
         "maintenance.html",
-        {"request": request, "site_name": "My API", "estimated_time": "2 hours"},
+        {
+            "request": request,
+            "site_name": "My API",
+            "estimated_time": "2 hours",
+        },
         status_code=503
     )
 
@@ -238,7 +242,7 @@ from fastapi_maintenance import MaintenanceModeMiddleware
 
 app = FastAPI()
 
-async def path_aware_response(request: Request) -> JSONResponse:
+def path_aware_response(request: Request) -> JSONResponse:
     # Customize message based on path
     path = request.url.path
 
@@ -259,3 +263,41 @@ app.add_middleware(
     response_handler=path_aware_response
 )
 ```
+
+### Async Response Handler
+
+When you need to fetch maintenance information from a database or external service, you can use an async response handler:
+
+```python
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+from fastapi_maintenance import MaintenanceModeMiddleware
+import httpx
+
+app = FastAPI()
+
+async def async_maintenance_response(request: Request) -> JSONResponse:
+    # Fetch maintenance status from external status page API
+    async with httpx.AsyncClient() as client:
+        try:
+            response = await client.get("https://status.example.com/api/maintenance")
+            status_data = response.json()
+            estimated_end = status_data.get("estimated_end", "unknown")
+        except:
+            estimated_end = "unknown"
+
+    return JSONResponse(
+        content={
+            "status": "maintenance",
+            "message": "Service temporarily unavailable",
+            "estimated_completion": estimated_end
+        },
+        status_code=503,
+        headers={"Retry-After": "1800"}
+    )
+
+app.add_middleware(
+    MaintenanceModeMiddleware,
+    response_handler=async_maintenance_response
+)
+```