envbool 0.2.0__tar.gz → 0.3.0__tar.gz

{envbool-0.2.0 → envbool-0.3.0}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: envbool
-Version: 0.2.0
+Version: 0.3.0
 Summary: A small Python library and CLI tool for coercing environment variables (and arbitrary strings) into boolean values.
 Keywords: environment variables,boolean,configuration,env,coerce
 Author: Kyle O'Malley
 Author-email: Kyle O'Malley <j.kyle.omalley@gmail.com>
 License-Expression: MIT
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Utilities
@@ -242,11 +242,13 @@ Set `ENVBOOL_NO_CONFIG=1` to skip config discovery entirely.
 | `envbool(var, **opts)` | Read an environment variable and return `bool`. |
 | `to_bool(value, **opts)` | Coerce a string to `bool`. |
 | `load_config()` | Load and return the active `EnvBoolConfig` (cached). |
+| `reload_config()` | Discard the cache, re-read the config file, and return the fresh `EnvBoolConfig`. |
 | `EnvBoolConfig` | Frozen dataclass: `strict`, `warn`, `effective_truthy`, `effective_falsy`, `source_path`. |
 | `DEFAULT_TRUTHY` | `frozenset` of the built-in truthy strings. |
 | `DEFAULT_FALSY` | `frozenset` of the built-in falsy strings. |
 | `EnvBoolError` | Base class for every exception the library raises. |
 | `InvalidBoolValueError` | Raised in strict mode for unrecognized values. Also a `ValueError`. |
+| `MissingEnvVarError` | Raised by `envbool(required=True)` when the variable is unset. Also a `KeyError`. |
 | `ConfigError` | Raised when a config file is malformed. |
 
 `envbool()` and `to_bool()` share the same keyword-only options:
@@ -259,6 +261,10 @@ Set `ENVBOOL_NO_CONFIG=1` to skip config discovery entirely.
 | `truthy` / `falsy` | `Iterable[str] \| None` | `None` | **Replace** the effective set. |
 | `extend_truthy` / `extend_falsy` | `Iterable[str] \| None` | `None` | **Extend** the effective set. |
 
+`envbool()` also accepts `required` (`bool`, default `False`): when `True`, a
+variable that is unset raises `MissingEnvVarError` before `default` is applied. A
+variable set to an empty string counts as present and still uses `default`.
+
 ## Advanced topics
 
 ### Exception handling

{envbool-0.2.0 → envbool-0.3.0}/README.md

@@ -214,11 +214,13 @@ Set `ENVBOOL_NO_CONFIG=1` to skip config discovery entirely.
 | `envbool(var, **opts)` | Read an environment variable and return `bool`. |
 | `to_bool(value, **opts)` | Coerce a string to `bool`. |
 | `load_config()` | Load and return the active `EnvBoolConfig` (cached). |
+| `reload_config()` | Discard the cache, re-read the config file, and return the fresh `EnvBoolConfig`. |
 | `EnvBoolConfig` | Frozen dataclass: `strict`, `warn`, `effective_truthy`, `effective_falsy`, `source_path`. |
 | `DEFAULT_TRUTHY` | `frozenset` of the built-in truthy strings. |
 | `DEFAULT_FALSY` | `frozenset` of the built-in falsy strings. |
 | `EnvBoolError` | Base class for every exception the library raises. |
 | `InvalidBoolValueError` | Raised in strict mode for unrecognized values. Also a `ValueError`. |
+| `MissingEnvVarError` | Raised by `envbool(required=True)` when the variable is unset. Also a `KeyError`. |
 | `ConfigError` | Raised when a config file is malformed. |
 
 `envbool()` and `to_bool()` share the same keyword-only options:
@@ -231,6 +233,10 @@ Set `ENVBOOL_NO_CONFIG=1` to skip config discovery entirely.
 | `truthy` / `falsy` | `Iterable[str] \| None` | `None` | **Replace** the effective set. |
 | `extend_truthy` / `extend_falsy` | `Iterable[str] \| None` | `None` | **Extend** the effective set. |
 
+`envbool()` also accepts `required` (`bool`, default `False`): when `True`, a
+variable that is unset raises `MissingEnvVarError` before `default` is applied. A
+variable set to an empty string counts as present and still uses `default`.
+
 ## Advanced topics
 
 ### Exception handling

{envbool-0.2.0 → envbool-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "envbool"
-version = "0.2.0"
+version = "0.3.0"
 description = "A small Python library and CLI tool for coercing environment variables (and arbitrary strings) into boolean values."
 readme = "README.md"
 authors = [{ name = "Kyle O'Malley", email = "j.kyle.omalley@gmail.com" }]
@@ -11,7 +11,7 @@ dependencies = [
     "platformdirs>=4.9.6",
 ]
 classifiers = [
-    "Development Status :: 3 - Alpha",
+    "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Topic :: Utilities",
@@ -40,6 +40,7 @@ build-backend = "uv_build"
 
 [dependency-groups]
 dev = [
+    "hypothesis>=6.155.5",
     "pre-commit>=4.5.1",
     "pytest>=9.0.3",
     "pytest-cov>=7.1.0",

{envbool-0.2.0 → envbool-0.3.0}/src/envbool/__init__.py

@@ -12,22 +12,29 @@ 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
+    reload_config()       -- discard the cache and re-read the config file
     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
+    MissingEnvVarError    -- raised by envbool(required=True) when a var is unset
     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._config import EnvBoolConfig, load_config, reload_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
+from envbool.exceptions import (
+    ConfigError,
+    EnvBoolError,
+    InvalidBoolValueError,
+    MissingEnvVarError,
+)
 
 __all__ = [
     "DEFAULT_FALSY",
@@ -36,7 +43,9 @@ __all__ = [
     "EnvBoolConfig",
     "EnvBoolError",
     "InvalidBoolValueError",
+    "MissingEnvVarError",
     "envbool",
     "load_config",
+    "reload_config",
     "to_bool",
 ]

envbool-0.3.0/src/envbool/__main__.py

@@ -0,0 +1,6 @@
+"""Enable ``python -m envbool`` as an alias for the installed ``envbool`` command."""
+
+from envbool._cli import main
+
+if __name__ == "__main__":
+    main()

{envbool-0.2.0 → envbool-0.3.0}/src/envbool/_cli.py

@@ -11,7 +11,8 @@ Input source (first match wins):
 Exit codes:
   0  -- truthy
   1  -- falsy or unset/empty
-  2  -- error (unrecognized value in strict mode, bad arguments, multi-line stdin)
+  2  -- error (unrecognized value in strict mode, unset VAR_NAME with --required,
+        bad arguments, multi-line stdin)
 
 Omitting --strict or --warn defers to the config file setting (default:
 lenient, no warnings).
@@ -40,7 +41,7 @@ import sys
 from envbool._config import load_config
 from envbool._core import _resolve, to_bool
 from envbool._env import envbool
-from envbool.exceptions import ConfigError, InvalidBoolValueError
+from envbool.exceptions import ConfigError, InvalidBoolValueError, MissingEnvVarError
 
 
 def _build_parser() -> argparse.ArgumentParser:
@@ -86,6 +87,13 @@ def _build_parser() -> argparse.ArgumentParser:
         default=False,
         help="Default value if unset/empty (default: false).",
     )
+    parser.add_argument(
+        "--required",
+        "-r",
+        action="store_true",
+        default=False,
+        help="Exit 2 if VAR_NAME is not set in the environment.",
+    )
     parser.add_argument(
         "--print",
         "-p",
@@ -146,12 +154,15 @@ def _print_config(args: argparse.Namespace) -> None:
     print(f"falsy:       {', '.join(sorted(effective_falsy))}")
 
 
-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()
+def _coerce_from_source(
+    parser: argparse.ArgumentParser, args: argparse.Namespace
+) -> bool:
+    """Resolve the input source (--value, VAR_NAME, or stdin) and coerce it to bool.
 
+    Validates the mutually exclusive source flags, then dispatches to the matching
+    coercion call. Exits via parser.error()/sys.exit() for usage errors; the
+    coercion exceptions propagate to main()'s single error boundary.
+    """
     value_set_kwargs = {
         "truthy": args.truthy,
         "falsy": args.falsy,
@@ -159,6 +170,63 @@ def main() -> None:
         "extend_falsy": args.extend_falsy,
     }
 
+    # --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")
+
+    # --required only governs the env-var lookup; a literal --value always
+    # has a value, so combining them is a usage error rather than a no-op.
+    if args.required and args.value is not None:
+        parser.error("--required and --value are mutually exclusive")
+
+    if args.value is not None:
+        return to_bool(
+            args.value,
+            strict=args.strict,
+            warn=args.warn,
+            default=args.default,
+            **value_set_kwargs,
+        )
+    if args.var is not None:
+        return envbool(
+            args.var,
+            strict=args.strict,
+            warn=args.warn,
+            default=args.default,
+            required=args.required,
+            **value_set_kwargs,
+        )
+    if 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)
+        return to_bool(
+            raw,
+            strict=args.strict,
+            warn=args.warn,
+            default=args.default,
+            **value_set_kwargs,
+        )
+
+    parser.print_usage(sys.stderr)
+    sys.exit(2)
+
+
+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()
+
     # Both --show-config and the coercion calls below trigger config-file loading,
     # so a malformed config can raise ConfigError from either path. A single error
     # boundary around both keeps that failure a clean "error: ..." exit rather than
@@ -180,50 +248,8 @@ def main() -> None:
             _print_config(args)
             sys.exit(0)
 
-        # --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")
-
-        if args.value is not None:
-            result = to_bool(
-                args.value,
-                strict=args.strict,
-                warn=args.warn,
-                default=args.default,
-                **value_set_kwargs,
-            )
-        elif args.var is not None:
-            result = envbool(
-                args.var,
-                strict=args.strict,
-                warn=args.warn,
-                default=args.default,
-                **value_set_kwargs,
-            )
-        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,
-                warn=args.warn,
-                default=args.default,
-                **value_set_kwargs,
-            )
-        else:
-            parser.print_usage(sys.stderr)
-            sys.exit(2)
-    except (InvalidBoolValueError, ConfigError) as e:
+        result = _coerce_from_source(parser, args)
+    except (InvalidBoolValueError, ConfigError, MissingEnvVarError) as e:
         print(f"error: {e}", file=sys.stderr)
         sys.exit(2)
 

{envbool-0.2.0 → envbool-0.3.0}/src/envbool/_config.py

@@ -26,7 +26,7 @@ import platformdirs
 from envbool._defaults import DEFAULT_FALSY, DEFAULT_TRUTHY
 from envbool.exceptions import ConfigError
 
-__all__ = ["EnvBoolConfig", "load_config"]
+__all__ = ["EnvBoolConfig", "load_config", "reload_config"]
 
 _logger = logging.getLogger(__name__)
 
@@ -89,6 +89,28 @@ def load_config() -> EnvBoolConfig:
     return _get_config()
 
 
+def reload_config() -> EnvBoolConfig:
+    """Force a re-read of the config file, replacing the cached config.
+
+    ``load_config()`` caches for the lifetime of the process, so a config file
+    that is written or edited after the first lookup is never picked up. Call
+    this to discard the cache and reload from disk -- useful in long-running
+    processes (workers, servers, notebooks) that change config at runtime.
+
+    The clear-and-reload happens atomically under the cache lock so concurrent
+    readers never observe a momentarily empty cache.
+
+    Returns:
+        The freshly loaded EnvBoolConfig, now installed as the cached instance.
+
+    Raises:
+        ConfigError: If a config file is found but malformed or has invalid values.
+    """
+    with _cache.lock:
+        _cache.config = _load_config_from_disk()
+        return _cache.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

{envbool-0.2.0 → envbool-0.3.0}/src/envbool/_env.py

@@ -14,12 +14,14 @@ import os
 from collections.abc import Iterable
 
 from envbool._core import to_bool
+from envbool.exceptions import MissingEnvVarError
 
 
 def envbool(
     var: str,
     *,
     default: bool = False,
+    required: bool = False,
     strict: bool | None = None,
     warn: bool | None = None,
     truthy: Iterable[str] | None = None,
@@ -32,6 +34,9 @@ def envbool(
     Args:
         var: Environment variable name.
         default: Returned when the variable is unset or empty.
+        required: When True, raise if the variable is not set at all. A truly
+            unset var raises before `default` is considered; a var set to an
+            empty string is "present" and still coerces via `default`.
         strict: Raise on unrecognized values. None defers to config (default False).
         warn: Log a warning on unrecognized values. None defers to config
             (default False).
@@ -45,7 +50,17 @@ def envbool(
 
     Raises:
         InvalidBoolValueError: In strict mode when the value is unrecognized.
+        MissingEnvVarError: When required=True and the variable is unset.
     """
+    # `required` distinguishes "absent from the environment" from "set but empty"
+    # -- membership, not the value, so VAR= (empty) is treated as present. This
+    # check precedes the default-handling below so an unset required var raises
+    # instead of silently falling back to `default`.
+    if required and var not in os.environ:
+        err = MissingEnvVarError(f"Required environment variable {var} is not set")
+        err.var = var
+        raise err
+
     # 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, "")

{envbool-0.2.0 → envbool-0.3.0}/src/envbool/exceptions.py

@@ -8,6 +8,7 @@ which predates envbool adoption keeps working without changes.
 Hierarchy:
     EnvBoolError(Exception)
         InvalidBoolValueError(EnvBoolError, ValueError)
+        MissingEnvVarError(EnvBoolError, KeyError)
         ConfigError(EnvBoolError)
 """
 
@@ -44,6 +45,24 @@ class InvalidBoolValueError(EnvBoolError, ValueError):
     falsy: frozenset[str]
 
 
+class MissingEnvVarError(EnvBoolError, KeyError):
+    """Raised by envbool(var, required=True) when var is not set in the environment.
+
+    Dual inheritance with KeyError mirrors the InvalidBoolValueError(ValueError)
+    pattern: a missing os.environ lookup naturally raises KeyError, so existing
+    ``except KeyError`` handlers keep working after a codebase adopts envbool.
+
+    Only a truly-unset variable triggers this -- a variable set to an empty
+    string is "present" and coerces normally via the caller's default.
+    """
+
+    # Set by the raising code after construction (see InvalidBoolValueError for
+    # why attributes live here rather than in __init__).
+
+    # Name of the environment variable that was required but not set.
+    var: str
+
+
 class ConfigError(EnvBoolError):
     """Raised when a config file is malformed or contains invalid values.