fastapi-loopguard 0.6.0__tar.gz → 0.6.1__tar.gz

{fastapi_loopguard-0.6.0 → fastapi_loopguard-0.6.1}/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.6.1 (2026-08-12)
+
+- The console blocking banner is restyled: a slim rule frame instead of
+  the `=`/`!` walls, with ANSI color hierarchy (headline red, explanation
+  dim, fixes cyan) on real terminals. Redirected streams and `NO_COLOR`
+  environments get identical plain text, so log grep patterns keep
+  working. (#9)
+- The 503 page's BAD/GOOD code examples render each snippet on its own
+  line again: the blocks are now `<pre>` elements; the previous `<div>`s
+  collapsed the newlines. (#10)
+
 ## 0.6.0 (2026-08-12)
 
 Detection-core hardening plus the AI test harness. Fixes found by a

{fastapi_loopguard-0.6.0 → fastapi_loopguard-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fastapi-loopguard
-Version: 0.6.0
+Version: 0.6.1
 Summary: Detect event-loop blocking in FastAPI/Starlette with per-request attribution
 Project-URL: Homepage, https://github.com/parhamdavari/fastapi-loopguard
 Project-URL: Documentation, https://github.com/parhamdavari/fastapi-loopguard#readme

{fastapi_loopguard-0.6.0 → fastapi_loopguard-0.6.1}/assets/demo.tape

@@ -46,7 +46,7 @@ Sleep 4.5s
 Ctrl+L
 Type "# the server console explains what happened"
 Enter
-Type "grep -B 2 -A 18 'LOOPGUARD' /tmp/loopguard-demo.log"
+Type "grep -A 17 'LOOPGUARD' /tmp/loopguard-demo.log"
 Enter
 Sleep 2.5s
 Type "# pip install fastapi-loopguard  ->  app.add_middleware(LoopGuardMiddleware)"

{fastapi_loopguard-0.6.0 → fastapi_loopguard-0.6.1}/pyproject.toml

@@ -1,129 +1,129 @@
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
-
-[project]
-name = "fastapi-loopguard"
-version = "0.6.0"
-description = "Detect event-loop blocking in FastAPI/Starlette with per-request attribution"
-readme = "README.md"
-license = "MIT"
-requires-python = ">=3.12"
-authors = [
-    { name = "Parham" }
-]
-keywords = [
-    "fastapi",
-    "starlette",
-    "asyncio",
-    "middleware",
-    "monitoring",
-    "performance",
-    "blocking",
-    "event-loop",
-]
-classifiers = [
-    "Development Status :: 4 - Beta",
-    "Framework :: AsyncIO",
-    "Framework :: FastAPI",
-    "Intended Audience :: Developers",
-    "License :: OSI Approved :: MIT License",
-    "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.12",
-    "Programming Language :: Python :: 3.13",
-    "Topic :: Software Development :: Libraries :: Python Modules",
-    "Topic :: System :: Monitoring",
-    "Typing :: Typed",
-]
-dependencies = [
-    "starlette>=0.37.0,<2.0",
-]
-
-[project.optional-dependencies]
-prometheus = ["prometheus-client>=0.19.0"]
-structlog = ["structlog>=24.1.0"]
-all = [
-    "prometheus-client>=0.19.0",
-    "structlog>=24.1.0",
-]
-dev = [
-    "pytest>=8.0.0",
-    "pytest-asyncio>=0.23.0",
-    "httpx>=0.27.0",
-    "fastapi>=0.110.0",
-    # Without this, tests/test_metrics.py importorskip-skips silently and
-    # metrics.py sits at 0% coverage in CI
-    "prometheus-client>=0.19.0",
-    "mypy>=1.8.0",
-    "ruff>=0.3.0",
-    "coverage>=7.4.0",
-]
-stress = [
-    "locust>=2.20.0",
-    "uvicorn>=0.27.0",
-]
-
-[project.urls]
-Homepage = "https://github.com/parhamdavari/fastapi-loopguard"
-Documentation = "https://github.com/parhamdavari/fastapi-loopguard#readme"
-Repository = "https://github.com/parhamdavari/fastapi-loopguard"
-Issues = "https://github.com/parhamdavari/fastapi-loopguard/issues"
-
-[project.entry-points.pytest11]
-loopguard = "fastapi_loopguard.pytest_plugin"
-
-[tool.hatch.build.targets.wheel]
-packages = ["src/fastapi_loopguard"]
-
-[tool.hatch.build.targets.sdist]
-exclude = [
-    "/.claude",
-    "/stress_results*.csv",
-    "/.coverage",
-    "/.pytest_cache",
-    "/.mypy_cache",
-    "/.ruff_cache",
-]
-
-[tool.pytest.ini_options]
-asyncio_mode = "auto"
-asyncio_default_fixture_loop_scope = "function"
-testpaths = ["tests"]
-
-[tool.mypy]
-python_version = "3.12"
-strict = true
-warn_return_any = true
-warn_unused_configs = true
-
-[[tool.mypy.overrides]]
-module = "prometheus_client.*"
-ignore_missing_imports = true
-
-[[tool.mypy.overrides]]
-module = "locust.*"
-ignore_missing_imports = true
-
-[tool.ruff]
-target-version = "py312"
-line-length = 88
-src = ["src", "tests"]
-
-[tool.ruff.lint]
-select = ["E", "F", "I", "N", "W", "UP", "B", "C4", "SIM", "ANN"]
-ignore = ["ANN401"]
-
-[tool.ruff.format]
-quote-style = "double"
-indent-style = "space"
-
-[tool.coverage.run]
-source = ["src/fastapi_loopguard"]
-branch = true
-
-[tool.coverage.report]
-exclude_lines = [
-    "pragma: no cover",
-    "if TYPE_CHECKING:",
-    "raise NotImplementedError",
-]
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "fastapi-loopguard"
+version = "0.6.1"
+description = "Detect event-loop blocking in FastAPI/Starlette with per-request attribution"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.12"
+authors = [
+    { name = "Parham" }
+]
+keywords = [
+    "fastapi",
+    "starlette",
+    "asyncio",
+    "middleware",
+    "monitoring",
+    "performance",
+    "blocking",
+    "event-loop",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: AsyncIO",
+    "Framework :: FastAPI",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Monitoring",
+    "Typing :: Typed",
+]
+dependencies = [
+    "starlette>=0.37.0,<2.0",
+]
+
+[project.optional-dependencies]
+prometheus = ["prometheus-client>=0.19.0"]
+structlog = ["structlog>=24.1.0"]
+all = [
+    "prometheus-client>=0.19.0",
+    "structlog>=24.1.0",
+]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "httpx>=0.27.0",
+    "fastapi>=0.110.0",
+    # Without this, tests/test_metrics.py importorskip-skips silently and
+    # metrics.py sits at 0% coverage in CI
+    "prometheus-client>=0.19.0",
+    "mypy>=1.8.0",
+    "ruff>=0.3.0",
+    "coverage>=7.4.0",
+]
+stress = [
+    "locust>=2.20.0",
+    "uvicorn>=0.27.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/parhamdavari/fastapi-loopguard"
+Documentation = "https://github.com/parhamdavari/fastapi-loopguard#readme"
+Repository = "https://github.com/parhamdavari/fastapi-loopguard"
+Issues = "https://github.com/parhamdavari/fastapi-loopguard/issues"
+
+[project.entry-points.pytest11]
+loopguard = "fastapi_loopguard.pytest_plugin"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/fastapi_loopguard"]
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+    "/.claude",
+    "/stress_results*.csv",
+    "/.coverage",
+    "/.pytest_cache",
+    "/.mypy_cache",
+    "/.ruff_cache",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+
+[[tool.mypy.overrides]]
+module = "prometheus_client.*"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "locust.*"
+ignore_missing_imports = true
+
+[tool.ruff]
+target-version = "py312"
+line-length = 88
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP", "B", "C4", "SIM", "ANN"]
+ignore = ["ANN401"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.coverage.run]
+source = ["src/fastapi_loopguard"]
+branch = true
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+]

{fastapi_loopguard-0.6.0 → fastapi_loopguard-0.6.1}/src/fastapi_loopguard/middleware.py

@@ -8,6 +8,7 @@ from __future__ import annotations
 
 import asyncio
 import json
+import os
 import sys
 import uuid
 from typing import TYPE_CHECKING
@@ -25,6 +26,71 @@ from .monitor import SentinelMonitor
 if TYPE_CHECKING:
     from .config import LoopGuardConfig
 
+# ANSI styles for the console banner
+_RESET = "\x1b[0m"
+_BOLD_RED = "\x1b[1;31m"
+_DIM = "\x1b[2m"
+_CYAN = "\x1b[36m"
+
+_BANNER_WIDTH = 72
+
+
+def _console_supports_color() -> bool:
+    """Color only on a real terminal, and never against NO_COLOR.
+
+    Escape codes in a redirected stream would pollute log files and
+    aggregators, so anything that is not a TTY gets plain text.
+    """
+    try:
+        is_tty = sys.stderr.isatty()
+    except (AttributeError, ValueError):
+        is_tty = False
+    return is_tty and not os.environ.get("NO_COLOR")
+
+
+def _format_console_warning(ctx: RequestContext, use_color: bool) -> str:
+    """Render the blocking banner, with or without ANSI color.
+
+    The plain rendering is the colored one minus escape codes — same
+    lines, same order — so log output and terminal output stay greppable
+    with the same patterns.
+    """
+
+    def paint(code: str, text: str) -> str:
+        return f"{code}{text}{_RESET}" if use_color else text
+
+    title = "LOOPGUARD: Event Loop Blocked!"
+    top_rule = f"── {title} " + "─" * max(0, _BANNER_WIDTH - len(title) - 4)
+    lines = [
+        "",
+        paint(_BOLD_RED, top_rule),
+        "",
+        f"  In-flight request: {ctx.method} {ctx.path}",
+        f"  Request ID: {ctx.request_id}",
+        f"  Blocked: {ctx.blocking_count} time(s), {ctx.total_blocking_ms:.1f}ms total",
+        "",
+        paint(
+            _DIM,
+            "  Blocking was detected while this request was in flight. "
+            "The culprit\n  may be this request or any other concurrent "
+            "request.\n  ALL requests were frozen while the event loop "
+            "was blocked.",
+        ),
+        "",
+        "  Common fixes:",
+        paint(
+            _CYAN,
+            "    time.sleep(n)       -> await asyncio.sleep(n)\n"
+            "    requests.get(url)   -> await httpx.AsyncClient().get(url)\n"
+            "    open(f).read()      -> await aiofiles.open(f)\n"
+            "    subprocess.run(...) -> await asyncio.create_subprocess_exec(...)",
+        ),
+        "",
+        "  Docs: https://fastapi.tiangolo.com/async/",
+        paint(_BOLD_RED, "─" * _BANNER_WIDTH),
+    ]
+    return "\n".join(lines)
+
 
 class LoopGuardMiddleware:
     """Pure ASGI middleware that detects event loop blocking per-request.
@@ -297,30 +363,10 @@ class LoopGuardMiddleware:
 
     def _log_console_warning(self, ctx: RequestContext) -> None:
         """Print attention-grabbing console warning to stderr."""
-        warning = f"""
-{"=" * 72}
-{"!" * 72}
-  LOOPGUARD: Event Loop Blocked!
-{"!" * 72}
-
-  In-flight request: {ctx.method} {ctx.path}
-  Request ID: {ctx.request_id}
-  Blocked: {ctx.blocking_count} time(s), {ctx.total_blocking_ms:.1f}ms total
-
-  Blocking was detected while this request was in flight. The culprit
-  may be this request or any other concurrent request.
-  ALL requests were frozen while the event loop was blocked.
-
-  Common fixes:
-    time.sleep(n)       -> await asyncio.sleep(n)
-    requests.get(url)   -> await httpx.AsyncClient().get(url)
-    open(f).read()      -> await aiofiles.open(f)
-    subprocess.run(...) -> await asyncio.create_subprocess_exec(...)
-
-  Docs: https://fastapi.tiangolo.com/async/
-{"=" * 72}
-"""
-        print(warning, file=sys.stderr)
+        print(
+            _format_console_warning(ctx, _console_supports_color()),
+            file=sys.stderr,
+        )
 
     def _generate_error_html(self, ctx: RequestContext) -> str:
         """Generate educational HTML error page for strict mode."""
@@ -417,7 +463,7 @@ class LoopGuardMiddleware:
         <h2>Common Causes & Fixes</h2>
 
         <div class="bad-label">BAD - These block the event loop:</div>
-        <div class="code-block bad">
+        <pre class="code-block bad">
 <span class="comment"># Sleeping</span>
 time.sleep(1)
 
@@ -428,11 +474,10 @@ requests.get("https://api.example.com")
 open("data.json").read()
 
 <span class="comment"># Subprocess</span>
-subprocess.run(["ls", "-la"])
-        </div>
+subprocess.run(["ls", "-la"])</pre>
 
         <div class="good-label">GOOD - Use async alternatives:</div>
-        <div class="code-block good">
+        <pre class="code-block good">
 <span class="comment"># Sleeping</span>
 await asyncio.sleep(1)
 
@@ -446,8 +491,7 @@ async with aiofiles.open("data.json") as f:
 
 <span class="comment"># Subprocess</span>
 proc = await asyncio.create_subprocess_exec("ls", "-la")
-await proc.wait()
-        </div>
+await proc.wait()</pre>
 
         <h2>Quick Fixes</h2>
         <ul>