feat: make environment flag parsing consistent with click

litestar/app.py

@@ -4,7 +4,6 @@
 import inspect
 import itertools
 import logging
-import os
 import pdb  # noqa: T100
 import warnings
 from collections import defaultdict
@@ -53,7 +52,7 @@
 from litestar.stores.registry import StoreRegistry
 from litestar.types import Empty, TypeDecodersSequence
 from litestar.types.internal_types import PathParameterDefinition, RouteHandlerMapItem, TemplateConfigType
-from litestar.utils import ensure_async_callable, join_paths, unique
+from litestar.utils import ensure_async_callable, envflag, join_paths, unique
 from litestar.utils.dataclass import extract_dataclass_items
 from litestar.utils.predicates import is_async_callable, is_class_and_subclass
 from litestar.utils.warnings import warn_pdb_on_exception
@@ -334,10 +333,10 @@ def __init__(
             logging_config = LoggingConfig()
 
         if debug is None:
-            debug = os.getenv("LITESTAR_DEBUG", "0") == "1"
+            debug = envflag("LITESTAR_DEBUG")
 
         if pdb_on_exception is None:
-            pdb_on_exception = os.getenv("LITESTAR_PDB", "0") == "1"
+            pdb_on_exception = envflag("LITESTAR_PDB")
 
         config = AppConfig(
             after_exception=list(after_exception or []),

litestar/cli/_utils.py

@@ -30,7 +30,7 @@
 
 from litestar import Litestar, __version__
 from litestar.middleware import DefineMiddleware
-from litestar.utils import get_name
+from litestar.utils import envflag, get_name
 
 if sys.version_info >= (3, 10):
     from importlib.metadata import entry_points
@@ -113,7 +113,7 @@ def from_env(cls, app_path: str | None, app_dir: Path | None = None) -> Litestar
             dotenv.load_dotenv()
         app_path = app_path or getenv("LITESTAR_APP")
         app_name = getenv("LITESTAR_APP_NAME") or "Litestar"
-        quiet_console = getenv("LITESTAR_QUIET_CONSOLE") or False
+        quiet_console = envflag("LITESTAR_QUIET_CONSOLE")
         if app_path and getenv("LITESTAR_APP") is None:
             os.environ["LITESTAR_APP"] = app_path
         if app_path:
@@ -345,7 +345,7 @@ def _autodiscovery_paths(base_dir: Path, arbitrary: bool = True) -> Generator[Pa
 
 def _autodiscover_app(cwd: Path) -> LoadedApp:
     app_name = getenv("LITESTAR_APP_NAME") or "Litestar"
-    quiet_console = getenv("LITESTAR_QUIET_CONSOLE") or False
+    quiet_console = envflag("LITESTAR_QUIET_CONSOLE")
     for file_path in _autodiscovery_paths(cwd):
         import_path = _path_to_dotted_path(file_path.relative_to(cwd))
         module = importlib.import_module(import_path)

litestar/cli/commands/core.py

@@ -205,6 +205,14 @@ def info_command(app: Litestar) -> None:
     is_flag=True,
     envvar="LITESTAR_CREATE_SELF_SIGNED_CERT",
 )
+@click.option(
+    "-q",
+    "--quiet-console",
+    envvar="LITESTAR_QUIET_CONSOLE",
+    help="Suppress formatted console output (useful for non-TTY environments, logs, and CI/CD",
+    is_flag=True,
+    default=False,
+)
 def run_command(
     reload: bool,
     port: int,
@@ -220,6 +228,7 @@ def run_command(
     ssl_certfile: str | None,
     ssl_keyfile: str | None,
     create_self_signed_cert: bool,
+    quiet_console: bool,
     ctx: click.Context,
 ) -> None:
     """Run a Litestar app. (requires 'uvicorn' to be installed).
@@ -234,7 +243,7 @@ def run_command(
 
     if pdb:
         os.environ["LITESTAR_PDB"] = "1"
-    quiet_console = os.getenv("LITESTAR_QUIET_CONSOLE") or False
+
     if not UVICORN_INSTALLED:
         console.print(
             r"uvicorn is not installed. Please install the standard group, litestar\[standard], to use this command."

litestar/utils/__init__.py

@@ -1,6 +1,6 @@
 from litestar.utils.deprecation import deprecated, warn_deprecation
 
-from .helpers import get_enum_string_value, get_name, unique_name_for_scope, url_quote
+from .helpers import envflag, get_enum_string_value, get_name, unique_name_for_scope, url_quote
 from .path import join_paths, normalize_path
 from .predicates import (
     is_annotated_type,
@@ -29,6 +29,7 @@
     "AsyncIteratorWrapper",
     "deprecated",
     "ensure_async_callable",
+    "envflag",
     "find_index",
     "get_enum_string_value",
     "get_name",

litestar/utils/helpers.py

@@ -2,6 +2,7 @@
 
 from enum import Enum
 from functools import partial
+from os import getenv
 from typing import TYPE_CHECKING, TypeVar, cast
 from urllib.parse import quote
 
@@ -102,3 +103,25 @@ def get_exception_group() -> type[BaseException]:
         from exceptiongroup import ExceptionGroup as _ExceptionGroup  # pyright: ignore
 
         return cast("type[BaseException]", _ExceptionGroup)
+
+
+def envflag(varname: str, default: bool = False) -> bool:
+    """Get the boolean value of an environment variable.
+
+    Determines whether an environment variable is set to a truthy value.
+    Returns True if the variable exists and its value matches one of:
+    "1", "true", "t", "yes", "on", "y" (case-insensitive).
+    Otherwise, including when the variable is not set, returns False.
+
+    Args:
+        varname (str): The name of the environment variable to check.
+        default (bool): Value to return if the variable is not set OR empty.
+
+    Returns:
+        bool: True if the environment variable is set to a truthy value,
+        otherwise False.
+    """
+    envvar = getenv(varname)
+    if not envvar:
+        return default
+    return envvar.lower() in ("1", "true", "t", "yes", "on", "y")

litestar/utils/warnings.py

@@ -1,10 +1,10 @@
 from __future__ import annotations
 
-import os
 import warnings
 from typing import TYPE_CHECKING
 
 from litestar.exceptions import LitestarWarning
+from litestar.utils import envflag
 
 if TYPE_CHECKING:
     import re
@@ -13,7 +13,7 @@
 
 
 def warn_implicit_sync_to_thread(source: AnyCallable, stacklevel: int = 2) -> None:
-    if os.getenv("LITESTAR_WARN_IMPLICIT_SYNC_TO_THREAD") == "0":
+    if not envflag("LITESTAR_WARN_IMPLICIT_SYNC_TO_THREAD", default=True):
         return
 
     warnings.warn(
@@ -29,7 +29,7 @@ def warn_implicit_sync_to_thread(source: AnyCallable, stacklevel: int = 2) -> No
 
 
 def warn_sync_to_thread_with_async_callable(source: AnyCallable, stacklevel: int = 2) -> None:
-    if os.getenv("LITESTAR_WARN_SYNC_TO_THREAD_WITH_ASYNC") == "0":
+    if not envflag("LITESTAR_WARN_SYNC_TO_THREAD_WITH_ASYNC", default=True):
         return
 
     warnings.warn(
@@ -42,7 +42,7 @@ def warn_sync_to_thread_with_async_callable(source: AnyCallable, stacklevel: int
 
 
 def warn_sync_to_thread_with_generator(source: AnyGenerator, stacklevel: int = 2) -> None:
-    if os.getenv("LITESTAR_WARN_SYNC_TO_THREAD_WITH_GENERATOR") == "0":
+    if not envflag("LITESTAR_WARN_SYNC_TO_THREAD_WITH_GENERATOR", default=True):
         return
 
     warnings.warn(
@@ -73,7 +73,7 @@ def warn_middleware_excluded_on_all_routes(
 
 
 def warn_signature_namespace_override(signature_key: str, stacklevel: int = 2) -> None:
-    if os.getenv("LITESTAR_WARN_SIGNATURE_NAMESPACE_OVERRIDE") == "0":
+    if not envflag("LITESTAR_WARN_SIGNATURE_NAMESPACE_OVERRIDE", default=True):
         return
 
     warnings.warn(

tests/unit/test_utils/test_helpers.py

@@ -1,9 +1,10 @@
+import os
 from functools import partial
 from typing import Any, Generic, TypeVar
 
 import pytest
 
-from litestar.utils.helpers import get_name, unique_name_for_scope, unwrap_partial
+from litestar.utils.helpers import envflag, get_name, unique_name_for_scope, unwrap_partial
 
 T = TypeVar("T")
 
@@ -45,3 +46,40 @@ def test_unique_name_for_scope() -> None:
     assert unique_name_for_scope("a", ["a", "a_0", "b"]) == "a_1"
 
     assert unique_name_for_scope("b", ["a", "a_0", "b"]) == "b_0"
+
+
+def test_envflag_truthy_values() -> None:
+    for value in ("1", "true", "TRUE", "t", "T", "yes", "YES", "on", "ON", "y", "Y"):
+        os.environ["TEST_FLAG"] = value
+        assert envflag("TEST_FLAG") is True
+        del os.environ["TEST_FLAG"]
+
+
+def test_envflag_falsy_values() -> None:
+    for value in ("0", "false", "no", "off", ""):
+        os.environ["TEST_FLAG"] = value
+        assert envflag("TEST_FLAG") is False
+        del os.environ["TEST_FLAG"]
+
+
+def test_envflag_missing() -> None:
+    assert envflag("NONEXISTENT_VAR") is False
+    assert envflag("NONEXISTENT_VAR_123", default=True) is True
+    assert envflag("NONEXISTENT_VAR_456", default=False) is False
+
+
+def test_envflag_overrides_default() -> None:
+    os.environ["TEST_FLAG"] = "true"
+    assert envflag("TEST_FLAG", default=False) is True
+    del os.environ["TEST_FLAG"]
+
+    os.environ["TEST_FLAG"] = "0"
+    assert envflag("TEST_FLAG", default=True) is False
+    del os.environ["TEST_FLAG"]
+
+
+def test_envflag_empty_string_uses_default() -> None:
+    os.environ["TEST_FLAG"] = ""
+    assert envflag("TEST_FLAG", default=True) is True
+    assert envflag("TEST_FLAG", default=False) is False
+    del os.environ["TEST_FLAG"]

tools/sphinx_ext/run_examples.py

@@ -22,6 +22,7 @@
 from sphinx.addnodes import highlightlang
 
 from litestar import Litestar
+from litestar.utils import envflag
 
 if TYPE_CHECKING:
     from collections.abc import Generator
@@ -34,7 +35,7 @@
 
 logger = logging.getLogger("sphinx")
 
-ignore_missing_output = os.getenv("LITESTAR_DOCS_IGNORE_MISSING_EXAMPLE_OUTPUT", "") == "1"
+ignore_missing_output = envflag("LITESTAR_DOCS_IGNORE_MISSING_EXAMPLE_OUTPUT")
 
 
 class StartupError(RuntimeError):