envbool 0.1.0__py3-none-any.whl

envbool/__init__.py

@@ -0,0 +1,42 @@
+"""envbool -- coerce environment variables and strings into booleans.
+
+Import everything you need directly from this package:
+
+    from envbool import envbool, to_bool, InvalidBoolValueError
+
+For except clauses, envbool.exceptions is also importable by name:
+
+    from envbool.exceptions import InvalidBoolValueError
+
+Available names:
+    envbool()             -- read an env var and coerce to bool (primary API)
+    to_bool()             -- coerce an arbitrary string to bool (no os.environ)
+    load_config()         -- inspect or preload the process-level config cache
+    EnvBoolConfig         -- frozen dataclass returned by load_config()
+    DEFAULT_TRUTHY        -- built-in truthy set (frozenset)
+    DEFAULT_FALSY         -- built-in falsy set (frozenset)
+    EnvBoolError          -- base exception for all envbool errors
+    InvalidBoolValueError -- raised in strict mode for unrecognized values
+    ConfigError           -- raised for malformed or unreadable config files
+"""
+# All implementation lives in private underscore-prefixed modules so the public
+# surface can be reshaped without breaking imports. Do not import from _core,
+# _env, _config, _cli, or _defaults directly.
+
+from envbool._config import EnvBoolConfig, load_config
+from envbool._core import to_bool
+from envbool._defaults import DEFAULT_FALSY, DEFAULT_TRUTHY
+from envbool._env import envbool
+from envbool.exceptions import ConfigError, EnvBoolError, InvalidBoolValueError
+
+__all__ = [
+    "DEFAULT_FALSY",
+    "DEFAULT_TRUTHY",
+    "ConfigError",
+    "EnvBoolConfig",
+    "EnvBoolError",
+    "InvalidBoolValueError",
+    "envbool",
+    "load_config",
+    "to_bool",
+]

envbool/_cli.py

@@ -0,0 +1,121 @@
+"""envbool CLI -- coerce an environment variable or string to a boolean.
+
+Usage: envbool [OPTIONS] [VAR_NAME]
+
+Input source (first match wins):
+  1. --value TEXT  -- coerce a literal string directly
+  2. VAR_NAME      -- read and coerce an environment variable
+  3. stdin pipe    -- read a single value from stdin (piped or redirected)
+  If none apply, prints usage and exits 2.
+
+Exit codes:
+  0  -- truthy
+  1  -- falsy or unset/empty
+  2  -- error (unrecognized value in strict mode, bad arguments, multi-line stdin)
+
+Omitting --strict defers to the config file setting (default: lenient).
+
+Public surface:
+    main()  -- entry point registered as the "envbool" command
+"""
+# --strict uses default=None rather than False so an absent flag passes None
+# through to envbool()/to_bool(), which then defers to the loaded config
+# instead of overriding a config-level strict = true with False.
+
+__all__ = ["main"]
+
+import argparse
+import sys
+
+from envbool._core import to_bool
+from envbool._env import envbool
+from envbool.exceptions import InvalidBoolValueError
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    """Build and return the argument parser."""
+    # Separated from main() so tests can call it directly without going through
+    # the full parse-and-exit cycle.
+    parser = argparse.ArgumentParser(
+        prog="envbool",
+        description="Coerce an environment variable or string to a boolean.",
+    )
+    parser.add_argument(
+        "var",
+        nargs="?",
+        metavar="VAR_NAME",
+        help="Environment variable name to check.",
+    )
+    parser.add_argument(
+        "--value",
+        "-v",
+        metavar="TEXT",
+        help="Check a literal string instead of an env var.",
+    )
+    parser.add_argument(
+        "--strict",
+        "-s",
+        action="store_true",
+        # None so an absent flag defers to config rather than overriding it with False.
+        # store_true with default=None gives: flag present -> True, absent -> None.
+        default=None,
+        help="Raise error on unrecognized values.",
+    )
+    parser.add_argument(
+        "--default",
+        "-d",
+        action="store_true",
+        default=False,
+        help="Default value if unset/empty (default: false).",
+    )
+    parser.add_argument(
+        "--print",
+        "-p",
+        dest="print_result",
+        action="store_true",
+        help='Print "true" or "false" instead of using exit codes.',
+    )
+    return parser
+
+
+def main() -> None:
+    """Parse arguments, resolve the input source, and exit with the appropriate code."""
+    # All coercion logic lives in _core.py; this function is pure I/O plumbing.
+    parser = _build_parser()
+    args = parser.parse_args()
+
+    # --value and VAR_NAME are mutually exclusive. Using argparse's built-in
+    # add_mutually_exclusive_group would place them in a separate usage section,
+    # which makes the help text harder to read, so we validate manually instead.
+    if args.value is not None and args.var is not None:
+        parser.error("VAR_NAME and --value are mutually exclusive")
+
+    try:
+        if args.value is not None:
+            result = to_bool(args.value, strict=args.strict, default=args.default)
+        elif args.var is not None:
+            result = envbool(args.var, strict=args.strict, default=args.default)
+        elif not sys.stdin.isatty():
+            # Non-TTY stdin means the user piped or redirected input. Strip surrounding
+            # whitespace (handles the trailing newline echo adds) then reject anything
+            # with an embedded newline -- only a single value is meaningful here.
+            raw = sys.stdin.read().strip()
+            if "\n" in raw:
+                print(
+                    "error: stdin must contain a single value, not multiple lines",
+                    file=sys.stderr,
+                )
+                sys.exit(2)
+            result = to_bool(raw, strict=args.strict, default=args.default)
+        else:
+            parser.print_usage(sys.stderr)
+            sys.exit(2)
+    except InvalidBoolValueError as e:
+        print(f"error: {e}", file=sys.stderr)
+        sys.exit(2)
+
+    if args.print_result:
+        print("true" if result else "false")
+        sys.exit(0)
+    else:
+        sys.exit(0 if result else 1)

envbool/_config.py

@@ -0,0 +1,374 @@
+"""Config file discovery, loading, caching, and EnvBoolConfig dataclass.
+
+Discovery priority (first found wins):
+  1. Project-level: walk up from CWD looking for envbool.toml or [tool.envbool]
+     in pyproject.toml. Walk stops at boundary markers or pyproject.toml.
+  2. User-level: <platformdirs.user_config_dir("envbool")>/config.toml
+
+The config is loaded once and cached for the lifetime of the process (thread-safe).
+Call _reset_config() in test fixtures to clear it.
+
+Public surface:
+    EnvBoolConfig   -- frozen dataclass with resolved settings
+    load_config()   -- returns the cached (or freshly loaded) config
+    _reset_config() -- clears the cache; for test use only
+"""
+
+import logging
+import os
+import threading
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import platformdirs
+
+from envbool._defaults import DEFAULT_FALSY, DEFAULT_TRUTHY
+from envbool.exceptions import ConfigError
+
+__all__ = ["EnvBoolConfig", "load_config"]
+
+_logger = logging.getLogger(__name__)
+
+# Boundary markers that signal "you have reached the project root -- stop walking."
+# pyproject.toml is handled separately because it is both a boundary and a potential
+# config source (checked for [tool.envbool] before the walk stops).
+_BOUNDARY_MARKERS: frozenset[str] = frozenset({".git", ".hg", "setup.py", "setup.cfg"})
+
+# Safety cap: never walk more than this many directory levels from CWD. Prevents
+# runaway traversal in CI/CD environments or Docker containers without markers.
+_MAX_WALK_DEPTH: int = 10
+
+
+@dataclass(frozen=True)
+class EnvBoolConfig:
+    """Resolved configuration for this process, loaded from a config file or defaults.
+
+    Attributes:
+        strict: When True, unrecognized values raise InvalidBoolValueError.
+        warn: When True, unrecognized values in lenient mode emit a WARNING log.
+        effective_truthy: Fully resolved truthy set (after extend/replace logic).
+        effective_falsy: Fully resolved falsy set (after extend/replace logic).
+        source_path: Which file was loaded, or None if using hardcoded defaults.
+    """
+
+    strict: bool = False
+    warn: bool = False
+    # field() is required here because frozenset is not a primitive type -- Python's
+    # dataclass machinery rejects non-primitive mutable-looking defaults without it,
+    # even though frozenset is immutable.
+    effective_truthy: frozenset[str] = field(default_factory=lambda: DEFAULT_TRUTHY)
+    effective_falsy: frozenset[str] = field(default_factory=lambda: DEFAULT_FALSY)
+    source_path: Path | None = None
+
+
+class _ConfigCache:
+    # A class attribute instead of a bare module-level variable avoids the need
+    # for 'global' statements when updating the cached value. The lock lives here
+    # so all cache state travels together.
+
+    config: EnvBoolConfig | None = None
+    lock: threading.Lock = threading.Lock()
+
+
+_cache = _ConfigCache()
+
+
+def load_config() -> EnvBoolConfig:
+    """Return the active config, loading from disk on first call.
+
+    Subsequent calls return the cached instance with no disk I/O. Use this to
+    inspect or preload the config at application startup.
+
+    Returns:
+        The resolved EnvBoolConfig for this process.
+
+    Raises:
+        ConfigError: If a config file is found but malformed or has invalid values.
+    """
+    return _get_config()
+
+
+def _get_config() -> EnvBoolConfig:
+    # Double-checked locking: the outer check avoids lock contention on the hot
+    # path (all calls after first load); the inner check prevents duplicate disk
+    # I/O if two threads race on the very first call.
+    if _cache.config is not None:
+        return _cache.config
+    with _cache.lock:
+        if _cache.config is not None:  # another thread may have loaded while we waited
+            return _cache.config
+        _cache.config = _load_config_from_disk()
+        return _cache.config
+
+
+def _reset_config() -> None:
+    """Clear the cached config so the next call reloads from disk.
+
+    For test use only -- not part of the public API. Intended to be called in a
+    pytest autouse fixture so each test starts with a clean slate:
+
+        @pytest.fixture(autouse=True)
+        def _reset_envbool_config():
+            yield
+            envbool._reset_config()
+    """
+    with _cache.lock:
+        _cache.config = None
+
+
+def _load_config_from_disk() -> EnvBoolConfig:
+    """Discover and parse the config file, returning EnvBoolConfig.
+
+    Uses a raw os.environ.get() -- not envbool() itself -- to check
+    ENVBOOL_NO_CONFIG. Calling envbool() here would trigger _get_config() again
+    before _config is set, causing infinite recursion.
+    """
+    if os.environ.get("ENVBOOL_NO_CONFIG") == "1":
+        _logger.debug("ENVBOOL_NO_CONFIG=1 -- skipping config file discovery")
+        return EnvBoolConfig()
+
+    # Project-level: walk up from CWD
+    project_config = _find_project_config()
+    if project_config is not None:
+        return project_config
+
+    # User-level: platformdirs fallback
+    user_config = _find_user_config()
+    if user_config is not None:
+        return user_config
+
+    _logger.debug("No config file found -- using hardcoded defaults")
+    return EnvBoolConfig()
+
+
+def _find_project_config() -> EnvBoolConfig | None:
+    """Walk up the directory tree from CWD looking for a project-level config.
+
+    Returns the parsed EnvBoolConfig if a config is found, None otherwise.
+    Stops early at boundary markers or after _MAX_WALK_DEPTH levels.
+    """
+    current = Path.cwd()
+    for _ in range(_MAX_WALK_DEPTH):
+        # envbool.toml takes priority over pyproject.toml in the same directory.
+        envbool_toml = current / "envbool.toml"
+        if envbool_toml.is_file():
+            _logger.debug("Found config: %s", envbool_toml)
+            return _parse_toml_file(envbool_toml)
+
+        pyproject = current / "pyproject.toml"
+        if pyproject.is_file():
+            # pyproject.toml is both a potential config source AND a boundary marker.
+            # We check for [tool.envbool] first; if present, use it. Either way, stop
+            # walking -- a pyproject.toml signals "you've reached the project root."
+            config = _try_pyproject(pyproject)
+            if config is not None:
+                _logger.debug("Found config in [tool.envbool]: %s", pyproject)
+            else:
+                _logger.debug(
+                    "pyproject.toml has no [tool.envbool] -- stopping walk at %s",
+                    current,
+                )
+            return config  # may be None -- caller treats None as "not found"
+
+        # Standard boundary markers (not config sources, just stop signals).
+        if any((current / marker).exists() for marker in _BOUNDARY_MARKERS):
+            _logger.debug("Boundary marker found at %s -- stopping walk", current)
+            return None
+
+        parent = current.parent
+        if parent == current:
+            # Reached filesystem root
+            return None
+        current = parent
+
+    _logger.debug("Depth cap (%d) reached -- stopping walk", _MAX_WALK_DEPTH)
+    return None
+
+
+def _find_user_config() -> EnvBoolConfig | None:
+    """Check the platformdirs user config directory for config.toml.
+
+    Returns the parsed EnvBoolConfig if found, None if the file does not exist.
+    If platformdirs cannot determine the config dir (very rare), returns None
+    rather than crashing.
+    """
+    try:
+        config_dir = Path(platformdirs.user_config_dir("envbool"))
+    except Exception:  # noqa: BLE001 -- platformdirs failure is non-fatal
+        _logger.debug("platformdirs could not determine user config dir -- skipping")
+        return None
+
+    config_file = config_dir / "config.toml"
+    if not config_file.is_file():
+        return None
+
+    _logger.debug("Found user config: %s", config_file)
+    return _parse_toml_file(config_file)
+
+
+def _try_pyproject(path: Path) -> EnvBoolConfig | None:
+    """Parse path as a pyproject.toml and return config from [tool.envbool].
+
+    Returns None (not an error) if the section is absent -- the caller
+    interprets that as "stop walking but no config found."
+
+    Raises:
+        ConfigError: If the TOML is malformed or [tool.envbool] has invalid values.
+    """
+    try:
+        with path.open("rb") as f:
+            data = tomllib.load(f)
+    except tomllib.TOMLDecodeError as exc:
+        err = ConfigError(f"Malformed TOML in {path}: {exc}")
+        err.path = path
+        raise err from exc
+
+    section = data.get("tool", {}).get("envbool")
+    if section is None:
+        return None
+    if not isinstance(section, dict):
+        err = ConfigError(f"[tool.envbool] must be a table in {path}")
+        err.path = path
+        raise err
+    return _parse_config(section, path)
+
+
+def _parse_toml_file(path: Path) -> EnvBoolConfig:
+    """Read and parse a standalone TOML config file (envbool.toml or user config.toml).
+
+    Args:
+        path: Path to the TOML file.
+
+    Returns:
+        Parsed and validated EnvBoolConfig.
+
+    Raises:
+        ConfigError: If the file is malformed TOML or contains invalid values.
+    """
+    try:
+        with path.open("rb") as f:
+            data = tomllib.load(f)
+    except tomllib.TOMLDecodeError as exc:
+        err = ConfigError(f"Malformed TOML in {path}: {exc}")
+        err.path = path
+        raise err from exc
+
+    return _parse_config(data, path)
+
+
+def _parse_config(data: dict, path: Path) -> EnvBoolConfig:
+    """Validate a raw TOML dict and resolve it into an EnvBoolConfig.
+
+    Unknown keys are silently ignored so config files stay forward-compatible as
+    new options are added. Known keys are type-checked strictly -- wrong types
+    (e.g. strict = "yes" instead of strict = true) raise ConfigError with a message
+    that names the expected type, since a type mismatch is almost certainly a typo.
+
+    The extend/replace logic here mirrors _resolve() in core.py:
+      - "truthy" replaces DEFAULT_TRUTHY entirely
+      - "extend_truthy" adds to DEFAULT_TRUTHY
+      - "truthy" takes priority when both present (ruff's select/extend-select pattern)
+
+    Args:
+        data: Parsed TOML key/value pairs (the [tool.envbool] section or top-level).
+        path: Source file path, attached to any ConfigError for diagnostics.
+
+    Returns:
+        Resolved EnvBoolConfig with effective_truthy/effective_falsy fully computed.
+
+    Raises:
+        ConfigError: For type mismatches or malformed list elements.
+    """
+    # --- bool fields ---
+    strict = _get_bool_field(data, "strict", path)
+    warn = _get_bool_field(data, "warn", path)
+
+    # --- set fields: apply extend/replace logic ---
+    # truthy replaces DEFAULT_TRUTHY; extend_truthy adds to it; truthy wins if both.
+    raw_truthy = _get_str_list_field(data, "truthy", path)
+    raw_extend_truthy = _get_str_list_field(data, "extend_truthy", path)
+    if raw_truthy is not None:
+        effective_truthy = _normalize_set(raw_truthy)
+    elif raw_extend_truthy is not None:
+        effective_truthy = DEFAULT_TRUTHY | _normalize_set(raw_extend_truthy)
+    else:
+        effective_truthy = DEFAULT_TRUTHY
+
+    # Same extend/replace logic for the falsy side, independent of truthy.
+    raw_falsy = _get_str_list_field(data, "falsy", path)
+    raw_extend_falsy = _get_str_list_field(data, "extend_falsy", path)
+    if raw_falsy is not None:
+        effective_falsy = _normalize_set(raw_falsy)
+    elif raw_extend_falsy is not None:
+        effective_falsy = DEFAULT_FALSY | _normalize_set(raw_extend_falsy)
+    else:
+        effective_falsy = DEFAULT_FALSY
+
+    _logger.debug(
+        "Config loaded from %s: strict=%s warn=%s truthy=%s falsy=%s",
+        path,
+        strict,
+        warn,
+        sorted(effective_truthy),
+        sorted(effective_falsy),
+    )
+
+    return EnvBoolConfig(
+        strict=strict if strict is not None else False,
+        warn=warn if warn is not None else False,
+        effective_truthy=effective_truthy,
+        effective_falsy=effective_falsy,
+        source_path=path,
+    )
+
+
+def _normalize_set(values: list[str]) -> frozenset[str]:
+    """Strip and lowercase values so they match to_bool()'s normalized input."""
+    return frozenset(v.strip().lower() for v in values)
+
+
+def _get_bool_field(data: dict, key: str, path: Path) -> bool | None:
+    """Extract a bool field from data, returning None if absent.
+
+    Raises:
+        ConfigError: If the key is present but not a Python bool (TOML boolean).
+    """
+    if key not in data:
+        return None
+    value = data[key]
+    if not isinstance(value, bool):
+        err = ConfigError(
+            f"Config error in {path}: '{key}' must be a boolean (true or false),"
+            f" got {type(value).__name__!r}"
+        )
+        err.path = path
+        raise err
+    return value
+
+
+def _get_str_list_field(data: dict, key: str, path: Path) -> list[str] | None:
+    """Extract a list-of-strings field from data, returning None if absent.
+
+    Raises:
+        ConfigError: If the key is present but not a list, or contains non-strings.
+    """
+    if key not in data:
+        return None
+    value = data[key]
+    if not isinstance(value, list):
+        err = ConfigError(
+            f"Config error in {path}: '{key}' must be an array of strings,"
+            f" got {type(value).__name__!r}"
+        )
+        err.path = path
+        raise err
+    for i, item in enumerate(value):
+        if not isinstance(item, str):
+            err = ConfigError(
+                f"Config error in {path}: '{key}[{i}]' must be a string,"
+                f" got {type(item).__name__!r}"
+            )
+            err.path = path
+            raise err
+    return value

envbool/_core.py

@@ -0,0 +1,177 @@
+"""Pure string-to-bool coercion with configurable truthy/falsy sets.
+
+Public surface:
+    DEFAULT_TRUTHY  -- the built-in truthy set (from _defaults)
+    DEFAULT_FALSY   -- the built-in falsy set (from _defaults)
+    to_bool()       -- coerce a single string to bool
+
+Private surface (used by _env.py and tests):
+    _resolve()      -- compute effective truthy/falsy sets from layered inputs
+"""
+# This module has no knowledge of os.environ -- that lives in _env.py. It does
+# consult the config cache (_get_config) so that strict=None/warn=None defer to
+# the loaded config file rather than always defaulting to False.
+# Import order matters: _config.py imports _defaults (not _core), so _core.py
+# can safely import from _config.py without creating a circular dependency.
+
+__all__ = ["to_bool"]
+
+import logging
+from collections.abc import Iterable
+
+from envbool._config import _get_config
+from envbool._defaults import DEFAULT_FALSY, DEFAULT_TRUTHY
+from envbool.exceptions import InvalidBoolValueError
+
+# Module-level logger -- attributed to "envbool._core" so callers can filter it
+# independently from "envbool.config" or the root "envbool" logger.
+_logger = logging.getLogger(__name__)
+
+# Public API
+
+
+def to_bool(
+    value: str,
+    *,
+    default: bool = False,
+    strict: bool | None = None,
+    warn: bool | None = None,
+    truthy: Iterable[str] | None = None,
+    falsy: Iterable[str] | None = None,
+    extend_truthy: Iterable[str] | None = None,
+    extend_falsy: Iterable[str] | None = None,
+    _var: str | None = None,
+) -> bool:
+    """Coerce a string to bool.
+
+    Args:
+        value: The string to coerce.
+        default: Returned when value is empty or unset.
+        strict: Raise on unrecognized values. None defers to config (default False).
+        warn: Log a warning on unrecognized values. None defers to config
+            (default False).
+        truthy: Replaces the effective truthy set.
+        falsy: Replaces the effective falsy set.
+        extend_truthy: Extends the effective truthy set.
+        extend_falsy: Extends the effective falsy set.
+        _var: Internal - env var name for error messages when called via envbool().
+
+    Returns:
+        True if value is in the truthy set, False otherwise.
+
+    Raises:
+        InvalidBoolValueError: In strict mode when value is unrecognized.
+    """
+    # Normalize first so all comparisons are case- and whitespace-insensitive.
+    # Empty after normalization means "unset" -- return the caller's default
+    # rather than treating it as an unrecognized value.
+    normalized = value.strip().lower()
+    if not normalized:
+        return default
+
+    # Load config once per process (cached after first call -- no per-call disk I/O).
+    # _resolve then applies the full three-level precedence chain:
+    #   hardcoded defaults (_defaults.py)
+    #   -> config file (effective_truthy/effective_falsy already resolved there)
+    #   -> call-site args (truthy/extend_truthy/falsy/extend_falsy)
+    config = _get_config()
+    effective_truthy, effective_falsy = _resolve(
+        config_truthy=config.effective_truthy,
+        config_falsy=config.effective_falsy,
+        truthy=truthy,
+        falsy=falsy,
+        extend_truthy=extend_truthy,
+        extend_falsy=extend_falsy,
+    )
+
+    # Overlapping sets are a caller mistake, not a runtime error. Warn so the
+    # problem is visible, then let truthy win to stay consistent and predictable.
+    overlap = effective_truthy & effective_falsy
+    if overlap:
+        _logger.warning(
+            "Overlapping truthy/falsy values (truthy wins): %s", sorted(overlap)
+        )
+
+    if normalized in effective_truthy:
+        return True
+
+    # Falsy is checked after truthy so the overlap rule above is enforced
+    # without any extra branching.
+    if normalized in effective_falsy:
+        return False
+
+    # Three-state logic: True/False at the call site override the config value;
+    # None defers to whatever the config file says (which defaults to False if no
+    # config file exists).
+    effective_strict = strict if strict is not None else config.strict
+    if effective_strict:
+        truthy_list = ", ".join(sorted(effective_truthy))
+        falsy_list = ", ".join(sorted(effective_falsy))
+        # _var is threaded in by envbool() so the error message names the env
+        # var; it's a private param to keep it out of the public to_bool() API.
+        if _var is not None:
+            msg = (
+                f"Invalid boolean value for {_var}: {normalized!r}\n"
+                f"  Expected truthy: {truthy_list}\n"
+                f"  Expected falsy:  {falsy_list}"
+            )
+        else:
+            msg = (
+                f"Invalid boolean value: {normalized!r}\n"
+                f"  Expected truthy: {truthy_list}\n"
+                f"  Expected falsy:  {falsy_list}"
+            )
+        err = InvalidBoolValueError(msg)
+        err.var = _var
+        err.value = normalized
+        err.truthy = effective_truthy
+        err.falsy = effective_falsy
+        raise err
+
+    effective_warn = warn if warn is not None else config.warn
+    if effective_warn:
+        _logger.warning("Unrecognized boolean value: %r", normalized)
+
+    # Lenient fallback: anything unrecognized is treated as falsy. This matches
+    # the "off by default" mental model of environment variable feature flags.
+    return False
+
+
+# Private API
+
+
+def _normalize_set(values: Iterable[str]) -> frozenset[str]:
+    """Strip and lowercase values so they match to_bool()'s normalized input."""
+    return frozenset(v.strip().lower() for v in values)
+
+
+def _resolve(
+    *,
+    config_truthy: frozenset[str] = DEFAULT_TRUTHY,
+    config_falsy: frozenset[str] = DEFAULT_FALSY,
+    truthy: Iterable[str] | None = None,
+    falsy: Iterable[str] | None = None,
+    extend_truthy: Iterable[str] | None = None,
+    extend_falsy: Iterable[str] | None = None,
+) -> tuple[frozenset[str], frozenset[str]]:
+    # Priority mirrors ruff's select/extend-select pattern:
+    #   truthy        -- full replacement; caller owns the entire set
+    #   extend_truthy -- additive; merges on top of config_truthy
+    #   (neither)     -- use config_truthy as-is (defaults when no config file)
+    # truthy takes precedence over extend_truthy; both cannot apply at once.
+    if truthy is not None:
+        effective_truthy = _normalize_set(truthy)
+    elif extend_truthy is not None:
+        effective_truthy = config_truthy | _normalize_set(extend_truthy)
+    else:
+        effective_truthy = config_truthy
+
+    # Same three-level logic for the falsy side, independent of truthy.
+    if falsy is not None:
+        effective_falsy = _normalize_set(falsy)
+    elif extend_falsy is not None:
+        effective_falsy = config_falsy | _normalize_set(extend_falsy)
+    else:
+        effective_falsy = config_falsy
+
+    return (effective_truthy, effective_falsy)

envbool/_defaults.py

@@ -0,0 +1,14 @@
+"""Built-in truthy/falsy value sets -- the baseline when no overrides are provided.
+
+These are intentionally small: common, unambiguous tokens only. Add project-specific
+values like "enabled", "disabled", "y", "n" via extend_truthy / extend_falsy rather
+than expecting them here.
+"""
+# Both _core.py and _config.py import these constants. Keeping them in a separate
+# module prevents the circular import that would arise if _config.py imported from
+# _core.py (which imports _get_config from _config.py).
+
+__all__ = ["DEFAULT_FALSY", "DEFAULT_TRUTHY"]
+
+DEFAULT_TRUTHY: frozenset[str] = frozenset({"true", "1", "yes", "on"})
+DEFAULT_FALSY: frozenset[str] = frozenset({"false", "0", "no", "off"})

envbool/_env.py

@@ -0,0 +1,65 @@
+"""envbool() -- read an environment variable and coerce it to bool.
+
+Public surface:
+    envbool()  -- the primary library API
+"""
+# This is the only layer in the package that touches os.environ. The split
+# between _env.py and _core.py keeps os.environ access isolated here so that
+# to_bool() can be tested without monkeypatching the environment.
+# Delegation chain: envbool() -> to_bool() -> _resolve() (+ _get_config())
+
+__all__ = ["envbool"]
+
+import os
+from collections.abc import Iterable
+
+from envbool._core import to_bool
+
+
+def envbool(
+    var: str,
+    *,
+    default: bool = False,
+    strict: bool | None = None,
+    warn: bool | None = None,
+    truthy: Iterable[str] | None = None,
+    falsy: Iterable[str] | None = None,
+    extend_truthy: Iterable[str] | None = None,
+    extend_falsy: Iterable[str] | None = None,
+) -> bool:
+    """Read an environment variable and coerce its value to bool.
+
+    Args:
+        var: Environment variable name.
+        default: Returned when the variable is unset or empty.
+        strict: Raise on unrecognized values. None defers to config (default False).
+        warn: Log a warning on unrecognized values. None defers to config
+            (default False).
+        truthy: Replaces the effective truthy set.
+        falsy: Replaces the effective falsy set.
+        extend_truthy: Extends the effective truthy set.
+        extend_falsy: Extends the effective falsy set.
+
+    Returns:
+        True if the env var value is in the truthy set, False otherwise.
+
+    Raises:
+        InvalidBoolValueError: In strict mode when the value is unrecognized.
+    """
+    # Missing var becomes "" so to_bool treats it the same as an empty value,
+    # returning `default` rather than raising or treating absence as a distinct state.
+    value = os.environ.get(var, "")
+    # _var=var threads the env var name into any InvalidBoolValueError so the message
+    # reads "Invalid boolean value for DEBUG: 'maybe'" instead of just the value.
+    # It is a private parameter to keep it out of to_bool()'s public signature.
+    return to_bool(
+        value,
+        default=default,
+        strict=strict,
+        warn=warn,
+        truthy=truthy,
+        falsy=falsy,
+        extend_truthy=extend_truthy,
+        extend_falsy=extend_falsy,
+        _var=var,
+    )

envbool/exceptions.py

@@ -0,0 +1,55 @@
+"""Exception hierarchy for envbool.
+
+All exceptions inherit from EnvBoolError so callers can catch the entire
+library with a single except clause. Where it makes sense, exceptions also
+inherit from a standard Python exception (ValueError, etc.) so that code
+which predates envbool adoption keeps working without changes.
+
+Hierarchy:
+    EnvBoolError(Exception)
+        InvalidBoolValueError(EnvBoolError, ValueError)
+        ConfigError(EnvBoolError)
+"""
+
+from pathlib import Path
+
+
+class EnvBoolError(Exception):
+    """Base exception for all envbool errors.
+
+    Catch this to handle any error from the library in one place.
+    """
+
+
+class InvalidBoolValueError(EnvBoolError, ValueError):
+    """Raised in strict mode when a value is not in the truthy or falsy sets.
+
+    Dual inheritance lets existing except ValueError handlers keep working
+    after a codebase adopts envbool, with no migration required.
+    """
+
+    # Attributes are set by the raising code after construction rather than in
+    # __init__ to keep the signature simple and avoid pickling/subclassing issues.
+
+    # Name of the environment variable, if the error originated from envbool().
+    # None when raised directly from to_bool() with no env var context.
+    var: str | None
+
+    # The normalized (stripped, lowercased) value that was not recognized.
+    value: str
+
+    # The effective truthy and falsy sets at the time of the error. Attached
+    # so callers can inspect exactly what was expected without re-running resolution.
+    truthy: frozenset[str]
+    falsy: frozenset[str]
+
+
+class ConfigError(EnvBoolError):
+    """Raised when a config file is malformed or contains invalid values.
+
+    Not a ValueError -- config problems are distinct from bad boolean values
+    and should not be caught by generic except ValueError handlers.
+    """
+
+    # Path to the config file that caused the error, for diagnostic messages.
+    path: Path

envbool-0.1.0.dist-info/METADATA

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: envbool
+Version: 0.1.0
+Summary: A small Python library and CLI tool for coercing environment variables (and arbitrary strings) into boolean values.
+Author: Kyle O'Malley
+Author-email: Kyle O'Malley <j.kyle.omalley@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Classifier: Environment :: Console
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Dist: platformdirs>=4.9.6
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# envbool
+
+Coerce environment variables to booleans.
+
+[![PyPI version](https://img.shields.io/pypi/v/envbool)](https://pypi.org/project/envbool/)
+[![Python versions](https://img.shields.io/pypi/pyversions/envbool)](https://pypi.org/project/envbool/)
+[![License: MIT](https://img.shields.io/pypi/l/envbool)](https://pypi.org/project/envbool/)
+[![CI](https://github.com/jkomalley/envbool/actions/workflows/ci.yml/badge.svg)](https://github.com/jkomalley/envbool/actions/workflows/ci.yml)
+
+---
+
+Every project ends up with some version of this:
+
+```python
+DEBUG   = os.environ.get("DEBUG",   "").lower() in ("1", "true", "yes")
+VERBOSE = os.environ.get("VERBOSE", "").lower() in ("1", "true", "yes")
+CACHE   = os.environ.get("CACHE",   "").lower() in ("1", "true", "yes")
+```
+
+`envbool` replaces that:
+
+```python
+from envbool import envbool
+
+DEBUG   = envbool("DEBUG")
+VERBOSE = envbool("VERBOSE")
+CACHE   = envbool("CACHE")
+```
+
+It also handles strict mode, warnings, custom value sets, config files, and a CLI for shell scripts.
+
+---
+
+## Installation
+
+```bash
+pip install envbool
+# or
+uv add envbool
+```
+
+## Usage
+
+**Lenient by default.** Anything not recognized as truthy returns `False`. Unset and empty variables return the default.
+
+```python
+from envbool import envbool
+
+DEBUG = envbool("DEBUG")                    # False if unset or empty
+CACHE = envbool("CACHE", default=True)      # True if unset or empty
+```
+
+The built-in truthy values are `true`, `1`, `yes`, `on`. Comparison is case-insensitive.
+
+**Strict mode** raises `InvalidBoolValueError` for unrecognized values — useful for catching typos in production config.
+
+```python
+from envbool import envbool, InvalidBoolValueError
+
+try:
+    USE_SSL = envbool("USE_SSL", strict=True)
+except InvalidBoolValueError as e:
+    print(f"Bad value for USE_SSL: {e.value!r}")
+    sys.exit(1)
+```
+
+**Extend the value sets** when your environment uses non-standard strings.
+
+```python
+FEATURE = envbool("FEATURE_FLAG", extend_truthy={"enabled", "y"})
+```
+
+**Coerce an arbitrary string** (not from `os.environ`) with `to_bool`:
+
+```python
+from envbool import to_bool
+
+to_bool("yes")                  # True
+to_bool("0")                    # False
+to_bool("maybe", strict=True)   # raises InvalidBoolValueError
+```
+
+## CLI
+
+The `envbool` command exits `0` for truthy and `1` for falsy, so it works naturally in shell scripts.
+
+```bash
+# Control flow via exit code
+envbool DEBUG && echo "debug is on"
+
+# Print the resolved value
+echo "Verbose: $(envbool --print VERBOSE)"
+
+# Pipe a string
+echo "yes" | envbool && echo "truthy"
+
+# Strict mode
+envbool --strict ENABLE_CACHE || echo "cache is off or misconfigured"
+```
+
+## Configuration
+
+Put shared defaults in `envbool.toml` (or `[tool.envbool]` in `pyproject.toml`) at your project root:
+
+```toml
+strict = true
+extend_truthy = ["enabled"]
+extend_falsy  = ["disabled"]
+```
+
+`envbool` walks up from the current directory to find the nearest config file, then falls back to a user-level config (`~/.config/envbool/config.toml` on Linux/macOS). Function arguments always override the config.
+
+Set `ENVBOOL_NO_CONFIG=1` to skip config discovery entirely.
+
+## API
+
+| Symbol | Description |
+|---|---|
+| `envbool(var, ...)` | Read an env var and return `bool` |
+| `to_bool(value, ...)` | Coerce a string to `bool` |
+| `load_config()` | Inspect the loaded config |
+| `DEFAULT_TRUTHY` | `frozenset` of built-in truthy strings |
+| `DEFAULT_FALSY` | `frozenset` of built-in falsy strings |
+| `InvalidBoolValueError` | Raised in strict mode on unrecognized values |
+| `ConfigError` | Raised when a config file is malformed |
+
+Both `envbool()` and `to_bool()` accept the same keyword arguments: `default`, `strict`, `warn`, `truthy`, `falsy`, `extend_truthy`, `extend_falsy`. `truthy`/`falsy` replace the effective set; `extend_truthy`/`extend_falsy` add to it.

envbool-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+envbool/__init__.py,sha256=Liw1zzfhLJDkWcDZo8YwU2x50eoNBSAxKS-sX4PeW6U,1651
+envbool/_cli.py,sha256=wct1z5OLw3wzoV8Cv-dOitbecV7zvpQAdT0xbqZZTV4,4261
+envbool/_config.py,sha256=ir6Ev6j-UbEgDDa0oQxk1o9QsaqPu_X3KkwNxJflwNk,13606
+envbool/_core.py,sha256=D6OgA8SyQoYZLTsuArmBo2ZWtF5Hvd408IgDVdLRd0I,6871
+envbool/_defaults.py,sha256=2SQs08zrTXeNJ5jDTlD2E1sH4-we5nlzao_S7Y0lf6I,695
+envbool/_env.py,sha256=UpHS-iFU92oa6Ij4ooknSUNlhHIehIbLtrBcgt4gyVQ,2299
+envbool/exceptions.py,sha256=UTTbnsimjebr-91UrgUyipi8TK_WanS04s9fD7Mxrjw,1920
+envbool/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+envbool-0.1.0.dist-info/WHEEL,sha256=WvwXFgRajeoYkfRVmDhkP4Qlqo31Mk687zIO2QQoFmw,80
+envbool-0.1.0.dist-info/entry_points.txt,sha256=HlbOED6ApEXVINGBXP7iPQt6q1N-_2UUSJUVu83Y5tQ,47
+envbool-0.1.0.dist-info/METADATA,sha256=UxVvXhSDR-_EUuL_mF4nL0dnAVV9D_hA73EA-Du60bE,4776
+envbool-0.1.0.dist-info/RECORD,,

envbool-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.7
+Root-Is-Purelib: true
+Tag: py3-none-any

envbool-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+envbool = envbool._cli:main
+