🐛 Avoid fancy logs for non-TTY output

Shortcake-Parent: 2026-07-03-fix-duplicate-uvicorn-logs-under-fastapi-cli

Author: patrick91

src/fastapi_cli/logging.py

@@ -1,22 +1,40 @@
 import logging
+import sys
+from typing import Any
 
 from rich.console import Console
 from rich.logging import RichHandler
 
 
-def setup_logging(terminal_width: int | None = None, level: int = logging.INFO) -> None:
+def _stream_is_tty(stream: Any) -> bool:
+    return bool(getattr(stream, "isatty", lambda: False)())
+
+
+def setup_logging(
+    terminal_width: int | None = None,
+    level: int = logging.INFO,
+    use_rich: bool | None = None,
+) -> None:
     logger = logging.getLogger("fastapi_cli")
-    console = Console(width=terminal_width) if terminal_width else None
-    rich_handler = RichHandler(
-        show_time=False,
-        rich_tracebacks=True,
-        tracebacks_show_locals=True,
-        markup=True,
-        show_path=False,
-        console=console,
-    )
-    rich_handler.setFormatter(logging.Formatter("%(message)s"))
-    logger.addHandler(rich_handler)
+    if use_rich is None:
+        use_rich = _stream_is_tty(sys.stderr)
+
+    if use_rich:
+        console = Console(width=terminal_width) if terminal_width else None
+        handler: logging.Handler = RichHandler(
+            show_time=False,
+            rich_tracebacks=True,
+            tracebacks_show_locals=True,
+            markup=True,
+            show_path=False,
+            console=console,
+        )
+        handler.setFormatter(logging.Formatter("%(message)s"))
+    else:
+        handler = logging.StreamHandler()
+        handler.setFormatter(logging.Formatter("%(levelname)s:%(name)s:%(message)s"))
+
+    logger.addHandler(handler)
 
     logger.setLevel(level)
     logger.propagate = False

src/fastapi_cli/utils/cli.py

@@ -1,9 +1,10 @@
 import logging
+import sys
 from typing import Any
 
 from rich_toolkit import RichToolkit, RichToolkitTheme
 from rich_toolkit.styles import TaggedStyle
-from uvicorn.logging import DefaultFormatter
+from uvicorn.logging import AccessFormatter, DefaultFormatter
 
 
 class CustomFormatter(DefaultFormatter):
@@ -20,20 +21,40 @@ def formatMessage(self, record: logging.LogRecord) -> str:
         return result
 
 
-def get_uvicorn_log_config() -> dict[str, Any]:
+def _stream_is_tty(stream: Any) -> bool:
+    return bool(getattr(stream, "isatty", lambda: False)())
+
+
+def get_uvicorn_log_config(use_rich: bool | None = None) -> dict[str, Any]:
+    if use_rich is None:
+        use_rich = _stream_is_tty(sys.stderr) and _stream_is_tty(sys.stdout)
+
+    default_formatter: dict[str, Any] = {
+        "()": DefaultFormatter,
+        "fmt": "%(levelprefix)s %(message)s",
+        "use_colors": None,
+    }
+    access_formatter: dict[str, Any] = {
+        "()": AccessFormatter,
+        "fmt": '%(levelprefix)s %(client_addr)s - "%(request_line)s" %(status_code)s',
+    }
+    if use_rich:
+        default_formatter = {
+            "()": CustomFormatter,
+            "fmt": "%(levelprefix)s %(message)s",
+            "use_colors": None,
+        }
+        access_formatter = {
+            "()": CustomFormatter,
+            "fmt": "%(levelprefix)s %(client_addr)s - '%(request_line)s' %(status_code)s",
+        }
+
     return {
         "version": 1,
         "disable_existing_loggers": False,
         "formatters": {
-            "default": {
-                "()": CustomFormatter,
-                "fmt": "%(levelprefix)s %(message)s",
-                "use_colors": None,
-            },
-            "access": {
-                "()": CustomFormatter,
-                "fmt": "%(levelprefix)s %(client_addr)s - '%(request_line)s' %(status_code)s",
-            },
+            "default": default_formatter,
+            "access": access_formatter,
         },
         "handlers": {
             "default": {

tests/test_logging.py

@@ -0,0 +1,54 @@
+import io
+import logging
+import sys
+
+from pytest import MonkeyPatch
+from rich.logging import RichHandler
+
+from fastapi_cli.logging import setup_logging
+
+
+def test_setup_logging_uses_rich_handler_when_requested() -> None:
+    logger = logging.getLogger("fastapi_cli")
+    original_handlers = logger.handlers[:]
+    original_level = logger.level
+    original_propagate = logger.propagate
+    try:
+        logger.handlers = []
+
+        setup_logging(use_rich=True)
+
+        assert len(logger.handlers) == 1
+        assert isinstance(logger.handlers[0], RichHandler)
+    finally:
+        for handler in logger.handlers:
+            if handler not in original_handlers:
+                handler.close()
+        logger.handlers = original_handlers
+        logger.setLevel(original_level)
+        logger.propagate = original_propagate
+
+
+def test_setup_logging_uses_stream_handler_without_tty(
+    monkeypatch: MonkeyPatch,
+) -> None:
+    logger = logging.getLogger("fastapi_cli")
+    original_handlers = logger.handlers[:]
+    original_level = logger.level
+    original_propagate = logger.propagate
+    try:
+        logger.handlers = []
+        monkeypatch.setattr(sys, "stderr", io.StringIO())
+
+        setup_logging()
+
+        assert len(logger.handlers) == 1
+        assert isinstance(logger.handlers[0], logging.StreamHandler)
+        assert not isinstance(logger.handlers[0], RichHandler)
+    finally:
+        for handler in logger.handlers:
+            if handler not in original_handlers:
+                handler.close()
+        logger.handlers = original_handlers
+        logger.setLevel(original_level)
+        logger.propagate = original_propagate

tests/test_utils_cli.py

@@ -1,19 +1,42 @@
+import io
 import logging
+import sys
 from logging.config import dictConfig
 
-from pytest import LogCaptureFixture
+from pytest import LogCaptureFixture, MonkeyPatch
+from uvicorn.logging import AccessFormatter, DefaultFormatter
 
 from fastapi_cli.utils.cli import CustomFormatter, get_uvicorn_log_config
 
 
 def test_get_uvicorn_config_uses_custom_formatter() -> None:
-    config = get_uvicorn_log_config()
+    config = get_uvicorn_log_config(use_rich=True)
 
     assert config["formatters"]["default"]["()"] is CustomFormatter
     assert config["formatters"]["access"]["()"] is CustomFormatter
     assert config["loggers"]["uvicorn"]["propagate"] is False
 
 
+def test_get_uvicorn_config_uses_plain_formatters_without_rich() -> None:
+    config = get_uvicorn_log_config(use_rich=False)
+
+    assert config["formatters"]["default"]["()"] is DefaultFormatter
+    assert config["formatters"]["access"]["()"] is AccessFormatter
+    assert config["loggers"]["uvicorn"]["propagate"] is False
+
+
+def test_get_uvicorn_config_uses_plain_formatters_without_tty(
+    monkeypatch: MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(sys, "stderr", io.StringIO())
+    monkeypatch.setattr(sys, "stdout", io.StringIO())
+
+    config = get_uvicorn_log_config()
+
+    assert config["formatters"]["default"]["()"] is DefaultFormatter
+    assert config["formatters"]["access"]["()"] is AccessFormatter
+
+
 def test_custom_formatter() -> None:
     formatter = CustomFormatter()