fix: corrected envflag behavior

 * envflag: removed default parameter.
 * envflag: behavior now matches click.BoolParamType.
 * envflag: raises an error if none of the conditions are met.
 * tests(envflag): updated tests and applied monkeypatch.

Author: 7576457

litestar/cli/commands/core.py

@@ -8,6 +8,8 @@
 from contextlib import AbstractContextManager, ExitStack, contextmanager
 from typing import TYPE_CHECKING, Any
 
+from litestar.utils.helpers import envflag
+
 try:
     import rich_click as click
 except ImportError:
@@ -119,7 +121,14 @@ class CommaSplittedPath(click.Path):
 
 
 @click.command(name="version")
-@click.option("-s", "--short", help="Exclude release level and serial information", is_flag=True, default=False)
+@click.option(
+    "-s",
+    "--short",
+    help="Exclude release level and serial information",
+    type=click.BOOL,
+    default=False,
+    is_flag=True,
+)
 def version_command(short: bool) -> None:
     """Show the currently installed Litestar version."""
     from litestar import __version__
@@ -135,7 +144,15 @@ def info_command(app: Litestar) -> None:
 
 
 @click.command(name="run")
-@click.option("-r", "--reload", help="Reload server on changes", default=False, is_flag=True, envvar="LITESTAR_RELOAD")
+@click.option(
+    "-r",
+    "--reload",
+    help="Reload server on changes",
+    envvar="LITESTAR_RELOAD",
+    type=click.BOOL,
+    default=False,
+    is_flag=True,
+)
 @click.option(
     "-R",
     "--reload-dir",
@@ -195,23 +212,39 @@ def info_command(app: Litestar) -> None:
     show_default=True,
     envvar="LITESTAR_UNIX_DOMAIN_SOCKET",
 )
-@click.option("-d", "--debug", help="Run app in debug mode", is_flag=True, envvar="LITESTAR_DEBUG")
-@click.option("-P", "--pdb", "--use-pdb", help="Drop into PDB on an exception", is_flag=True, envvar="LITESTAR_PDB")
+@click.option(
+    "-d",
+    "--debug",
+    help="Run app in debug mode",
+    envvar="LITESTAR_DEBUG",
+    type=click.BOOL,
+    is_flag=True,
+)
+@click.option(
+    "-P",
+    "--pdb",
+    "--use-pdb",
+    help="Drop into PDB on an exception",
+    envvar="LITESTAR_PDB",
+    type=click.BOOL,
+    is_flag=True,
+)
 @click.option("--ssl-certfile", help="Location of the SSL cert file", default=None, envvar="LITESTAR_SSL_CERT_PATH")
 @click.option("--ssl-keyfile", help="Location of the SSL key file", default=None, envvar="LITESTAR_SSL_KEY_PATH")
 @click.option(
     "--create-self-signed-cert",
     help="If certificate and key are not found at specified locations, create a self-signed certificate and a key",
-    is_flag=True,
     envvar="LITESTAR_CREATE_SELF_SIGNED_CERT",
+    type=click.BOOL,
+    is_flag=True,
 )
 @click.option(
     "-q",
     "--quiet-console",
     envvar="LITESTAR_QUIET_CONSOLE",
     help="Suppress formatted console output (useful for non-TTY environments, logs, and CI/CD",
+    type=click.BOOL,
     is_flag=True,
-    default=False,
 )
 def run_command(
     reload: bool,
@@ -244,6 +277,8 @@ def run_command(
     if pdb:
         os.environ["LITESTAR_PDB"] = "1"
 
+    quiet_console = bool(envflag("LITESTAR_QUIET_CONSOLE"))
+
     if not UVICORN_INSTALLED:
         console.print(
             r"uvicorn is not installed. Please install the standard group, litestar\[standard], to use this command."
@@ -316,7 +351,7 @@ def run_command(
 
 
 @click.command(name="routes")
-@click.option("--schema", help="Include schema routes", is_flag=True, default=False)
+@click.option("--schema", help="Include schema routes", is_flag=True, default=False, type=click.BOOL)
 @click.option("--exclude", help="routes to exclude via regex", type=str, is_flag=False, multiple=True)
 def routes_command(app: Litestar, exclude: tuple[str, ...], schema: bool) -> None:  # pragma: no cover
     """Display information about the application's routes."""

litestar/utils/helpers.py

@@ -1,11 +1,12 @@
 from __future__ import annotations
 
+import os
 from enum import Enum
 from functools import partial
-from os import getenv
 from typing import TYPE_CHECKING, TypeVar, cast
 from urllib.parse import quote
 
+from litestar.exceptions import LitestarException
 from litestar.utils.typing import get_origin_or_inner_type
 
 if TYPE_CHECKING:
@@ -105,23 +106,31 @@ def get_exception_group() -> type[BaseException]:
         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.
+def envflag(varname: str) -> bool | None:
+    """Parse an environment variable as a boolean flag.
 
     Args:
-        varname (str): The name of the environment variable to check.
-        default (bool): Value to return if the variable is not set OR empty.
+        varname: The name of the environment variable to check.
 
     Returns:
-        bool: True if the environment variable is set to a truthy value,
-        otherwise False.
+        True for truthy values (1, true, t, yes, y, on),
+        False for falsy values (0, false, f, no, n, off),
+        or empty string, None if not set.
+
+    Raises:
+        LitestarException: If the value is not a recognized boolean.
     """
-    envvar = getenv(varname)
+    if varname not in os.environ:
+        return None
+
+    envvar = os.environ.get(varname)
     if not envvar:
-        return default
-    return envvar.lower() in ("1", "true", "t", "yes", "on", "y")
+        return False
+
+    norm = envvar.strip().lower()
+    if norm in {"1", "true", "t", "yes", "y", "on"}:
+        return True
+    if norm in {"0", "false", "f", "no", "n", "off"}:
+        return False
+
+    raise LitestarException(f"Invalid value for {varname}: '{norm}' is not a valid boolean.")

litestar/utils/warnings.py

@@ -13,7 +13,7 @@
 
 
 def warn_implicit_sync_to_thread(source: AnyCallable, stacklevel: int = 2) -> None:
-    if not envflag("LITESTAR_WARN_IMPLICIT_SYNC_TO_THREAD", default=True):
+    if not envflag("LITESTAR_WARN_IMPLICIT_SYNC_TO_THREAD"):
         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 not envflag("LITESTAR_WARN_SYNC_TO_THREAD_WITH_ASYNC", default=True):
+    if not envflag("LITESTAR_WARN_SYNC_TO_THREAD_WITH_ASYNC"):
         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 not envflag("LITESTAR_WARN_SYNC_TO_THREAD_WITH_GENERATOR", default=True):
+    if not envflag("LITESTAR_WARN_SYNC_TO_THREAD_WITH_GENERATOR"):
         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 not envflag("LITESTAR_WARN_SIGNATURE_NAMESPACE_OVERRIDE", default=True):
+    if not envflag("LITESTAR_WARN_SIGNATURE_NAMESPACE_OVERRIDE"):
         return
 
     warnings.warn(

tests/unit/test_utils/test_helpers.py

@@ -1,9 +1,9 @@
-import os
 from functools import partial
 from typing import Any, Generic, TypeVar
 
 import pytest
 
+from litestar.exceptions import LitestarException
 from litestar.utils.helpers import envflag, get_name, unique_name_for_scope, unwrap_partial
 
 T = TypeVar("T")
@@ -48,38 +48,42 @@ def test_unique_name_for_scope() -> None:
     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
+def test_envflag_truthy_values(monkeypatch: pytest.MonkeyPatch) -> None:
+    for value in ("1", "true", "t", "yes", "y", "on", "YeS", "oN", "TRUE", "T"):
+        monkeypatch.setenv("TEST_FLAG", value)
         assert envflag("TEST_FLAG") is True
-        del os.environ["TEST_FLAG"]
+        monkeypatch.delenv("TEST_FLAG")
 
 
-def test_envflag_falsy_values() -> None:
-    for value in ("0", "false", "no", "off", ""):
-        os.environ["TEST_FLAG"] = value
+def test_envflag_falsy_values(monkeypatch: pytest.MonkeyPatch) -> None:
+    for value in ("0", "false", "f", "no", "n", "off", "", "OfF", "fAlSe", "NO"):
+        monkeypatch.setenv("TEST_FLAG", value)
         assert envflag("TEST_FLAG") is False
-        del os.environ["TEST_FLAG"]
+        monkeypatch.delenv("TEST_FLAG")
+
+
+def test_envflag_invalid_value(monkeypatch: pytest.MonkeyPatch) -> None:
+    for value in ("2", "Tru", "Fals", "maybe", "invalid", "O"):
+        monkeypatch.setenv("TEST_FLAG", value)
+        with pytest.raises(LitestarException):
+            envflag("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
+    assert envflag("NONEXISTENT_VAR") is None
 
 
-def test_envflag_overrides_default() -> None:
-    os.environ["TEST_FLAG"] = "true"
-    assert envflag("TEST_FLAG", default=False) is True
-    del os.environ["TEST_FLAG"]
+def test_envflag_overrides(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("TEST_FLAG", "true")
+    assert envflag("TEST_FLAG") is True
+    monkeypatch.delenv("TEST_FLAG")
 
-    os.environ["TEST_FLAG"] = "0"
-    assert envflag("TEST_FLAG", default=True) is False
-    del os.environ["TEST_FLAG"]
+    monkeypatch.setenv("TEST_FLAG", "0")
+    assert envflag("TEST_FLAG") is False
+    monkeypatch.delenv("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"]
+def test_envflag_empty_string(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("TEST_FLAG", "")
+    assert envflag("TEST_FLAG") is False
+    monkeypatch.delenv("TEST_FLAG")