envbool 0.4.2__tar.gz → 0.6.0__tar.gz

{envbool-0.4.2 → envbool-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: envbool
-Version: 0.4.2
+Version: 0.6.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
@@ -33,6 +33,7 @@ Description-Content-Type: text/markdown
 **Coerce environment variables and strings into booleans — sensibly.**
 
 [![PyPI version](https://img.shields.io/pypi/v/envbool)](https://pypi.org/project/envbool/)
+[![Snap Store](https://snapcraft.io/envbool/badge.svg)](https://snapcraft.io/envbool)
 [![Python versions](https://img.shields.io/pypi/pyversions/envbool)](https://pypi.org/project/envbool/)
 [![License: MIT](https://img.shields.io/github/license/jkomalley/envbool)](LICENSE)
 [![CI](https://github.com/jkomalley/envbool/actions/workflows/ci.yml/badge.svg)](https://github.com/jkomalley/envbool/actions/workflows/ci.yml)
@@ -67,8 +68,6 @@ CACHE = envbool("CACHE")
 - **Always returns `bool`.** No `None`, no surprises in your type signatures.
 - **Customizable value sets.** Replace or extend the truthy/falsy words your
   environment uses.
-- **Process-level defaults.** Call `set_defaults()` once at startup instead
-  of threading options through every call site.
 - **A CLI for shell scripts.** Exit codes map to truthiness, so it drops
   straight into `&&` / `||` chains.
 - **Zero ceremony.** Zero dependencies, fully typed, Python 3.11+.
@@ -91,6 +90,18 @@ pip install envbool
 uv add envbool
 ```
 
+### Snap
+
+On Linux, the CLI is also available as a snap:
+
+```bash
+sudo snap install envbool
+```
+
+The snap is CLI-only; use `pip` or `uv` to `import envbool`. snapd overrides
+`HOME`, `PATH`, `TMPDIR`, `XDG_RUNTIME_DIR`, and `SNAP_*`, so the CLI sees
+snapd's values for those.
+
 ## Usage
 
 ### The basics
@@ -113,6 +124,9 @@ surrounding whitespace.
 
 Pass `strict=True` to raise `InvalidBoolValueError` on anything outside the
 truthy/falsy sets — ideal for failing fast on a misconfigured deployment.
+Strict mode also raises `ConflictingValuesError` if the effective truthy and
+falsy sets overlap (e.g. `extend_falsy={"on"}`), on every call, whatever the
+value. Lenient mode instead logs a warning and lets truthy win.
 
 ```python
 import sys
@@ -137,6 +151,16 @@ FEATURE = envbool("FEATURE_FLAG", extend_truthy={"enabled", "y"})
 LOCALE = envbool("USE_METRIC", truthy={"metric"}, falsy={"imperial"})
 ```
 
+Each set is built in order: start from the built-in set, swap it out if
+`truthy`/`falsy` is given, then add anything in `extend_truthy`/
+`extend_falsy`. Passing both `truthy` and `extend_truthy` therefore gives you
+exactly their union:
+
+```python
+to_bool("y", truthy={"yes"}, extend_truthy={"y"})  # True
+to_bool("true", truthy={"yes"}, extend_truthy={"y"})  # False: built-ins replaced
+```
+
 ### Coercing arbitrary strings
 
 Use `to_bool` for values that don't come from the environment. It accepts the
@@ -150,36 +174,45 @@ to_bool("0")  # False
 to_bool("maybe", strict=True)  # raises InvalidBoolValueError
 ```
 
-### Process-level defaults
+### Loading application settings
 
-Set policy once at startup instead of threading `strict=`/`extend_truthy=`
-through every call site:
+In a real application, read every flag once at startup into a single settings
+object. With strict mode on, a typo like
+`DEBUG=ture` stops startup instead of quietly reading as `False`:
 
 ```python
-import envbool
+import sys
+from dataclasses import dataclass
 
-envbool.set_defaults(strict=True, extend_truthy=["enabled"])
+from envbool import EnvBoolError, envbool
 
-envbool.envbool("DEBUG")  # now raises on unrecognized values by default
-```
 
-`set_defaults()` replaces the process-level defaults **from the built-ins**,
-not from whatever a previous `set_defaults()` call left in place — call it
-once. Call-site arguments (`envbool("X", strict=False)`) still override
-whatever `set_defaults()` configured:
+@dataclass(frozen=True)
+class Settings:
+    debug: bool
+    use_cache: bool
+    new_checkout: bool
+    send_emails: bool
 
-```
-built-in defaults  →  set_defaults()  →  function arguments / CLI flags
-```
 
-`get_defaults()` returns the active `Defaults` (a frozen dataclass: `strict`,
-`warn`, `effective_truthy`, `effective_falsy`) for inspection.
-`reset_defaults()` restores the built-ins — call it in a test fixture (see
-[Testing code that uses envbool](#testing-code-that-uses-envbool)).
+def load_settings() -> Settings:
+    return Settings(
+        debug=envbool("DEBUG", strict=True),  # off unless set
+        use_cache=envbool("USE_CACHE", default=True, strict=True),  # on unless set
+        new_checkout=envbool("FEATURE_NEW_CHECKOUT", strict=True),
+        send_emails=envbool("SEND_EMAILS", required=True, strict=True),  # must be set
+    )
+
+
+try:
+    SETTINGS = load_settings()
+except EnvBoolError as e:
+    sys.exit(f"Invalid configuration: {e}")
+```
 
-> Through 0.3.x, envbool read TOML config files (`envbool.toml`,
-> `[tool.envbool]`). 0.4.0 removed them in favor of `set_defaults()` — see
-> `CHANGELOG.md` for the rationale and migration note.
+Catching `EnvBoolError` covers every failure: a bad value, a missing
+`required` variable, or overlapping value sets. The rest of the application
+reads `SETTINGS.debug` and never touches `os.environ` again.
 
 ## Command-line interface
 
@@ -227,35 +260,55 @@ options:
   --truthy VALUE        Replace the truthy set with VALUE (repeatable).
   --falsy VALUE         Replace the falsy set with VALUE (repeatable).
   --extend-truthy VALUE
-                        Add VALUE to the truthy set (repeatable).
-  --extend-falsy VALUE  Add VALUE to the falsy set (repeatable).
+                        Add VALUE to the truthy set, after any --truthy
+                        (repeatable).
+  --extend-falsy VALUE  Add VALUE to the falsy set, after any --falsy
+                        (repeatable).
 ```
 
 A few rules worth knowing:
 
-- Omitting `--strict` / `--warn` uses the built-in defaults (lenient, no
-  warnings). `set_defaults()` is a library-level concern — the one-shot CLI
-  process doesn't read it.
+- Without `--strict` / `--warn`, coercion is lenient and logs no warnings.
 - `VAR_NAME` and `--value` are mutually exclusive.
 - `--required` only applies to `VAR_NAME`; combining it with `--value` or
   giving it no `VAR_NAME` at all is a usage error.
 - With no `VAR_NAME`, `--value`, or non-empty piped stdin, the CLI prints
   usage and exits `2`.
 
+### Scripts using `set -e`
+
+Under `set -e` (errexit), a falsy result is a failing command: a bare
+`envbool FLAG` on its own line aborts the script when the flag is off. Check
+the status inside a condition instead, where errexit doesn't apply, or use
+`--print` to get the answer as text:
+
+```bash
+set -e
+
+envbool FLAG                  # aborts the script when FLAG is falsy
+
+if envbool FLAG; then         # safe: the status is the condition
+  echo "on"
+fi
+
+flag=$(envbool --print FLAG)  # safe: always exits 0 unless there's an error
+```
+
+`--print` still exits `2` on an error, so `set -e` catches a missing
+`--required` variable or a bad value under `--strict`, while a falsy value
+doesn't stop the script.
+
 ## API reference
 
 | Symbol | Description |
 | --- | --- |
 | `envbool(var, **opts)` | Read an environment variable and return `bool`. |
 | `to_bool(value, **opts)` | Coerce a string to `bool`. |
-| `set_defaults(**opts)` | Set process-level strict/warn/truthy/falsy defaults, replacing the built-ins. |
-| `get_defaults()` | Return the active `Defaults`. |
-| `reset_defaults()` | Restore built-in defaults. |
-| `Defaults` | Frozen dataclass: `strict`, `warn`, `effective_truthy`, `effective_falsy`. |
 | `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`. |
+| `ConflictingValuesError` | Raised in strict mode when the truthy and falsy sets overlap. Also a `ValueError`. |
 | `MissingEnvVarError` | Raised by `envbool(required=True)` when the variable is unset. Also a `KeyError`. |
 
 `envbool()` and `to_bool()` share the same keyword-only options:
@@ -263,10 +316,10 @@ A few rules worth knowing:
 | Option | Type | Default | Meaning |
 | --- | --- | --- | --- |
 | `default` | `bool` | `False` | Returned for unset/empty input. |
-| `strict` | `bool \| None` | `None` | Raise on unrecognized values (`None` defers to `set_defaults()`). |
-| `warn` | `bool \| None` | `None` | Log a warning on unrecognized values (`None` defers to `set_defaults()`). |
+| `strict` | `bool` | `False` | Raise on unrecognized values. |
+| `warn` | `bool` | `False` | Log a warning on unrecognized values. |
 | `truthy` / `falsy` | `Iterable[str] \| None` | `None` | **Replace** the effective set. |
-| `extend_truthy` / `extend_falsy` | `Iterable[str] \| None` | `None` | **Extend** the effective set. |
+| `extend_truthy` / `extend_falsy` | `Iterable[str] \| None` | `None` | **Extend** the effective set, after any replacement. |
 
 `envbool()` also accepts `required` (`bool`, default `False`): when `True`, a
 variable that is unset raises `MissingEnvVarError` before `default` is applied. A
@@ -317,7 +370,7 @@ logging.getLogger("envbool").addHandler(logging.StreamHandler())
 | Level | When |
 | --- | --- |
 | `WARNING` | An unrecognized value fell through in lenient mode (only when `warn=True`). |
-| `WARNING` | The truthy and falsy sets overlap (truthy wins). |
+| `WARNING` | The truthy and falsy sets overlap in lenient mode (truthy wins; strict mode raises `ConflictingValuesError` instead). |
 
 ### The unset-vs-empty distinction
 
@@ -336,23 +389,6 @@ else:
     result = envbool("MY_VAR")
 ```
 
-### Testing code that uses envbool
-
-If your tests call `set_defaults()`, reset it between tests with an autouse
-fixture so overrides don't leak across the suite:
-
-```python
-# conftest.py
-import pytest
-from envbool import reset_defaults
-
-
-@pytest.fixture(autouse=True)
-def _reset_envbool_defaults():
-    yield
-    reset_defaults()
-```
-
 ## Contributing
 
 Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for development

{envbool-0.4.2 → envbool-0.6.0}/README.md

@@ -5,6 +5,7 @@
 **Coerce environment variables and strings into booleans — sensibly.**
 
 [![PyPI version](https://img.shields.io/pypi/v/envbool)](https://pypi.org/project/envbool/)
+[![Snap Store](https://snapcraft.io/envbool/badge.svg)](https://snapcraft.io/envbool)
 [![Python versions](https://img.shields.io/pypi/pyversions/envbool)](https://pypi.org/project/envbool/)
 [![License: MIT](https://img.shields.io/github/license/jkomalley/envbool)](LICENSE)
 [![CI](https://github.com/jkomalley/envbool/actions/workflows/ci.yml/badge.svg)](https://github.com/jkomalley/envbool/actions/workflows/ci.yml)
@@ -39,8 +40,6 @@ CACHE = envbool("CACHE")
 - **Always returns `bool`.** No `None`, no surprises in your type signatures.
 - **Customizable value sets.** Replace or extend the truthy/falsy words your
   environment uses.
-- **Process-level defaults.** Call `set_defaults()` once at startup instead
-  of threading options through every call site.
 - **A CLI for shell scripts.** Exit codes map to truthiness, so it drops
   straight into `&&` / `||` chains.
 - **Zero ceremony.** Zero dependencies, fully typed, Python 3.11+.
@@ -63,6 +62,18 @@ pip install envbool
 uv add envbool
 ```
 
+### Snap
+
+On Linux, the CLI is also available as a snap:
+
+```bash
+sudo snap install envbool
+```
+
+The snap is CLI-only; use `pip` or `uv` to `import envbool`. snapd overrides
+`HOME`, `PATH`, `TMPDIR`, `XDG_RUNTIME_DIR`, and `SNAP_*`, so the CLI sees
+snapd's values for those.
+
 ## Usage
 
 ### The basics
@@ -85,6 +96,9 @@ surrounding whitespace.
 
 Pass `strict=True` to raise `InvalidBoolValueError` on anything outside the
 truthy/falsy sets — ideal for failing fast on a misconfigured deployment.
+Strict mode also raises `ConflictingValuesError` if the effective truthy and
+falsy sets overlap (e.g. `extend_falsy={"on"}`), on every call, whatever the
+value. Lenient mode instead logs a warning and lets truthy win.
 
 ```python
 import sys
@@ -109,6 +123,16 @@ FEATURE = envbool("FEATURE_FLAG", extend_truthy={"enabled", "y"})
 LOCALE = envbool("USE_METRIC", truthy={"metric"}, falsy={"imperial"})
 ```
 
+Each set is built in order: start from the built-in set, swap it out if
+`truthy`/`falsy` is given, then add anything in `extend_truthy`/
+`extend_falsy`. Passing both `truthy` and `extend_truthy` therefore gives you
+exactly their union:
+
+```python
+to_bool("y", truthy={"yes"}, extend_truthy={"y"})  # True
+to_bool("true", truthy={"yes"}, extend_truthy={"y"})  # False: built-ins replaced
+```
+
 ### Coercing arbitrary strings
 
 Use `to_bool` for values that don't come from the environment. It accepts the
@@ -122,36 +146,45 @@ to_bool("0")  # False
 to_bool("maybe", strict=True)  # raises InvalidBoolValueError
 ```
 
-### Process-level defaults
+### Loading application settings
 
-Set policy once at startup instead of threading `strict=`/`extend_truthy=`
-through every call site:
+In a real application, read every flag once at startup into a single settings
+object. With strict mode on, a typo like
+`DEBUG=ture` stops startup instead of quietly reading as `False`:
 
 ```python
-import envbool
+import sys
+from dataclasses import dataclass
 
-envbool.set_defaults(strict=True, extend_truthy=["enabled"])
+from envbool import EnvBoolError, envbool
 
-envbool.envbool("DEBUG")  # now raises on unrecognized values by default
-```
 
-`set_defaults()` replaces the process-level defaults **from the built-ins**,
-not from whatever a previous `set_defaults()` call left in place — call it
-once. Call-site arguments (`envbool("X", strict=False)`) still override
-whatever `set_defaults()` configured:
+@dataclass(frozen=True)
+class Settings:
+    debug: bool
+    use_cache: bool
+    new_checkout: bool
+    send_emails: bool
 
-```
-built-in defaults  →  set_defaults()  →  function arguments / CLI flags
-```
 
-`get_defaults()` returns the active `Defaults` (a frozen dataclass: `strict`,
-`warn`, `effective_truthy`, `effective_falsy`) for inspection.
-`reset_defaults()` restores the built-ins — call it in a test fixture (see
-[Testing code that uses envbool](#testing-code-that-uses-envbool)).
+def load_settings() -> Settings:
+    return Settings(
+        debug=envbool("DEBUG", strict=True),  # off unless set
+        use_cache=envbool("USE_CACHE", default=True, strict=True),  # on unless set
+        new_checkout=envbool("FEATURE_NEW_CHECKOUT", strict=True),
+        send_emails=envbool("SEND_EMAILS", required=True, strict=True),  # must be set
+    )
+
+
+try:
+    SETTINGS = load_settings()
+except EnvBoolError as e:
+    sys.exit(f"Invalid configuration: {e}")
+```
 
-> Through 0.3.x, envbool read TOML config files (`envbool.toml`,
-> `[tool.envbool]`). 0.4.0 removed them in favor of `set_defaults()` — see
-> `CHANGELOG.md` for the rationale and migration note.
+Catching `EnvBoolError` covers every failure: a bad value, a missing
+`required` variable, or overlapping value sets. The rest of the application
+reads `SETTINGS.debug` and never touches `os.environ` again.
 
 ## Command-line interface
 
@@ -199,35 +232,55 @@ options:
   --truthy VALUE        Replace the truthy set with VALUE (repeatable).
   --falsy VALUE         Replace the falsy set with VALUE (repeatable).
   --extend-truthy VALUE
-                        Add VALUE to the truthy set (repeatable).
-  --extend-falsy VALUE  Add VALUE to the falsy set (repeatable).
+                        Add VALUE to the truthy set, after any --truthy
+                        (repeatable).
+  --extend-falsy VALUE  Add VALUE to the falsy set, after any --falsy
+                        (repeatable).
 ```
 
 A few rules worth knowing:
 
-- Omitting `--strict` / `--warn` uses the built-in defaults (lenient, no
-  warnings). `set_defaults()` is a library-level concern — the one-shot CLI
-  process doesn't read it.
+- Without `--strict` / `--warn`, coercion is lenient and logs no warnings.
 - `VAR_NAME` and `--value` are mutually exclusive.
 - `--required` only applies to `VAR_NAME`; combining it with `--value` or
   giving it no `VAR_NAME` at all is a usage error.
 - With no `VAR_NAME`, `--value`, or non-empty piped stdin, the CLI prints
   usage and exits `2`.
 
+### Scripts using `set -e`
+
+Under `set -e` (errexit), a falsy result is a failing command: a bare
+`envbool FLAG` on its own line aborts the script when the flag is off. Check
+the status inside a condition instead, where errexit doesn't apply, or use
+`--print` to get the answer as text:
+
+```bash
+set -e
+
+envbool FLAG                  # aborts the script when FLAG is falsy
+
+if envbool FLAG; then         # safe: the status is the condition
+  echo "on"
+fi
+
+flag=$(envbool --print FLAG)  # safe: always exits 0 unless there's an error
+```
+
+`--print` still exits `2` on an error, so `set -e` catches a missing
+`--required` variable or a bad value under `--strict`, while a falsy value
+doesn't stop the script.
+
 ## API reference
 
 | Symbol | Description |
 | --- | --- |
 | `envbool(var, **opts)` | Read an environment variable and return `bool`. |
 | `to_bool(value, **opts)` | Coerce a string to `bool`. |
-| `set_defaults(**opts)` | Set process-level strict/warn/truthy/falsy defaults, replacing the built-ins. |
-| `get_defaults()` | Return the active `Defaults`. |
-| `reset_defaults()` | Restore built-in defaults. |
-| `Defaults` | Frozen dataclass: `strict`, `warn`, `effective_truthy`, `effective_falsy`. |
 | `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`. |
+| `ConflictingValuesError` | Raised in strict mode when the truthy and falsy sets overlap. Also a `ValueError`. |
 | `MissingEnvVarError` | Raised by `envbool(required=True)` when the variable is unset. Also a `KeyError`. |
 
 `envbool()` and `to_bool()` share the same keyword-only options:
@@ -235,10 +288,10 @@ A few rules worth knowing:
 | Option | Type | Default | Meaning |
 | --- | --- | --- | --- |
 | `default` | `bool` | `False` | Returned for unset/empty input. |
-| `strict` | `bool \| None` | `None` | Raise on unrecognized values (`None` defers to `set_defaults()`). |
-| `warn` | `bool \| None` | `None` | Log a warning on unrecognized values (`None` defers to `set_defaults()`). |
+| `strict` | `bool` | `False` | Raise on unrecognized values. |
+| `warn` | `bool` | `False` | Log a warning on unrecognized values. |
 | `truthy` / `falsy` | `Iterable[str] \| None` | `None` | **Replace** the effective set. |
-| `extend_truthy` / `extend_falsy` | `Iterable[str] \| None` | `None` | **Extend** the effective set. |
+| `extend_truthy` / `extend_falsy` | `Iterable[str] \| None` | `None` | **Extend** the effective set, after any replacement. |
 
 `envbool()` also accepts `required` (`bool`, default `False`): when `True`, a
 variable that is unset raises `MissingEnvVarError` before `default` is applied. A
@@ -289,7 +342,7 @@ logging.getLogger("envbool").addHandler(logging.StreamHandler())
 | Level | When |
 | --- | --- |
 | `WARNING` | An unrecognized value fell through in lenient mode (only when `warn=True`). |
-| `WARNING` | The truthy and falsy sets overlap (truthy wins). |
+| `WARNING` | The truthy and falsy sets overlap in lenient mode (truthy wins; strict mode raises `ConflictingValuesError` instead). |
 
 ### The unset-vs-empty distinction
 
@@ -308,23 +361,6 @@ else:
     result = envbool("MY_VAR")
 ```
 
-### Testing code that uses envbool
-
-If your tests call `set_defaults()`, reset it between tests with an autouse
-fixture so overrides don't leak across the suite:
-
-```python
-# conftest.py
-import pytest
-from envbool import reset_defaults
-
-
-@pytest.fixture(autouse=True)
-def _reset_envbool_defaults():
-    yield
-    reset_defaults()
-```
-
 ## Contributing
 
 Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for development

{envbool-0.4.2 → envbool-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "envbool"
-version = "0.4.2"
+version = "0.6.0"
 description = "A small Python library and CLI tool for coercing environment variables (and arbitrary strings) into boolean values."
 readme = "README.md"
 requires-python = ">=3.11"

{envbool-0.4.2 → envbool-0.6.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "envbool"
-version = "0.4.2"
+version = "0.6.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" }]

envbool-0.6.0/src/envbool/__init__.py

@@ -0,0 +1,43 @@
+"""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)
+    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
+    ConflictingValuesError -- raised in strict mode when truthy/falsy overlap
+    MissingEnvVarError     -- raised by envbool(required=True) when a var is unset
+"""
+# All implementation lives in private underscore-prefixed modules so the public
+# surface can be reshaped without breaking imports. Do not import from _core,
+# _env, or _cli directly.
+
+from envbool._core import DEFAULT_FALSY, DEFAULT_TRUTHY, to_bool
+from envbool._env import envbool
+from envbool.exceptions import (
+    ConflictingValuesError,
+    EnvBoolError,
+    InvalidBoolValueError,
+    MissingEnvVarError,
+)
+
+__all__ = [
+    "DEFAULT_FALSY",
+    "DEFAULT_TRUTHY",
+    "ConflictingValuesError",
+    "EnvBoolError",
+    "InvalidBoolValueError",
+    "MissingEnvVarError",
+    "envbool",
+    "to_bool",
+]

{envbool-0.4.2 → envbool-0.6.0}/src/envbool/_cli.py

@@ -14,20 +14,15 @@ Exit codes:
   2  -- error (unrecognized value in strict mode, unset VAR_NAME with --required,
         bad arguments, multi-line stdin)
 
-Omitting --strict or --warn defers to the process-level defaults
-(envbool.set_defaults(); default: lenient, no warnings).
+Without --strict or --warn, coercion is lenient and emits no warnings.
 
 Value sets: --truthy/--falsy (repeatable) replace the truthy/falsy set;
---extend-truthy/--extend-falsy (repeatable) add to it. Mirrors ruff's
-select/extend-select pattern.
+--extend-truthy/--extend-falsy (repeatable) add to it, after any
+replacement.
 
 Public surface:
     main()  -- entry point registered as the "envbool" command
 """
-# --strict and --warn use default=None rather than False so an absent flag
-# passes None through to envbool()/to_bool(), which then defers to the
-# process-level defaults instead of overriding a set_defaults(strict=True)/
-# warn=True with False.
 
 __all__ = ["main"]
 
@@ -36,7 +31,7 @@ import sys
 
 from envbool._core import to_bool
 from envbool._env import envbool
-from envbool.exceptions import InvalidBoolValueError, MissingEnvVarError
+from envbool.exceptions import EnvBoolError
 
 
 def _build_parser() -> argparse.ArgumentParser:
@@ -63,18 +58,11 @@ def _build_parser() -> argparse.ArgumentParser:
         "--strict",
         "-s",
         action="store_true",
-        # None so an absent flag defers to the process-level defaults rather
-        # than overriding them with False.
-        # store_true with default=None gives: flag present -> True, absent -> None.
-        default=None,
         help="Raise error on unrecognized values.",
     )
     parser.add_argument(
         "--warn",
         action="store_true",
-        # None so an absent flag defers to the process-level defaults rather
-        # than overriding them with False.
-        default=None,
         help="Log a warning on unrecognized values.",
     )
     parser.add_argument(
@@ -114,13 +102,13 @@ def _build_parser() -> argparse.ArgumentParser:
         "--extend-truthy",
         metavar="VALUE",
         action="append",
-        help="Add VALUE to the truthy set (repeatable).",
+        help="Add VALUE to the truthy set, after any --truthy (repeatable).",
     )
     parser.add_argument(
         "--extend-falsy",
         metavar="VALUE",
         action="append",
-        help="Add VALUE to the falsy set (repeatable).",
+        help="Add VALUE to the falsy set, after any --falsy (repeatable).",
     )
     return parser
 
@@ -213,7 +201,7 @@ def main() -> None:
     # SystemExit, which is not caught here and so propagates as intended.
     try:
         result = _coerce_from_source(parser, args)
-    except (InvalidBoolValueError, MissingEnvVarError) as e:
+    except EnvBoolError as e:
         print(f"error: {e}", file=sys.stderr)
         sys.exit(2)
 

{envbool-0.4.2 → envbool-0.6.0}/src/envbool/_core.py

@@ -1,35 +1,65 @@
 """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)
+    DEFAULT_TRUTHY  -- the built-in truthy set
+    DEFAULT_FALSY   -- the built-in falsy set
     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
+    _resolve()      -- compute effective truthy/falsy sets from call-site args
 """
-# This module has no knowledge of os.environ -- that lives in _env.py. It does
-# consult get_defaults() from _defaults.py so that strict=None/warn=None defer
-# to the process-level defaults (set_defaults()) rather than always defaulting
-# to False.
+# This module has no knowledge of os.environ -- that lives in _env.py. It also
+# holds no process-wide state: every setting comes from the call-site
+# arguments.
 
-__all__ = ["to_bool"]
+__all__ = ["DEFAULT_FALSY", "DEFAULT_TRUTHY", "to_bool"]
 
 import logging
 from collections.abc import Iterable
 
-from envbool._defaults import (
-    DEFAULT_FALSY,
-    DEFAULT_TRUTHY,
-    _apply_replace_or_extend,
-    get_defaults,
-)
-from envbool.exceptions import InvalidBoolValueError
+from envbool.exceptions import ConflictingValuesError, InvalidBoolValueError
 
 # Module-level logger -- attributed to "envbool._core" so callers can filter it
-# independently from "envbool.config" or the root "envbool" logger.
+# independently from the root "envbool" logger.
 _logger = logging.getLogger(__name__)
 
+DEFAULT_TRUTHY: frozenset[str] = frozenset({"true", "1", "yes", "on"})
+DEFAULT_FALSY: frozenset[str] = frozenset({"false", "0", "no", "off"})
+
+
+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 _apply_replace_then_extend(
+    base: frozenset[str],
+    replace: Iterable[str] | None,
+    extend: Iterable[str] | None,
+) -> frozenset[str]:
+    """Resolve a value set: replace the base (if given), then extend the result.
+
+    Used by _resolve() for each of the truthy and falsy sets:
+        replace -- swaps out base entirely; the caller owns the starting set
+        extend  -- additive; merged on top of whatever replace left
+        neither -- use base as-is
+    Passing both applies replace first, then extend, so neither argument is
+    silently dropped.
+
+    Args:
+        base: The starting set, used when replace is None.
+        replace: If not None, fully replaces base (normalized).
+        extend: If not None, merged on top of the (possibly replaced) set.
+
+    Returns:
+        The resolved, normalized frozenset.
+    """
+    result = _normalize_set(replace) if replace is not None else base
+    if extend is not None:
+        result |= _normalize_set(extend)
+    return result
+
+
 # Public API
 
 
@@ -37,8 +67,8 @@ def to_bool(
     value: str,
     *,
     default: bool = False,
-    strict: bool | None = None,
-    warn: bool | None = None,
+    strict: bool = False,
+    warn: bool = False,
     truthy: Iterable[str] | None = None,
     falsy: Iterable[str] | None = None,
     extend_truthy: Iterable[str] | None = None,
@@ -50,14 +80,14 @@ def to_bool(
     Args:
         value: The string to coerce.
         default: Returned when value is empty or unset.
-        strict: Raise on unrecognized values. None defers to process-level
-            defaults (set_defaults()) (default False).
-        warn: Log a warning on unrecognized values. None defers to
-            process-level defaults (set_defaults()) (default False).
+        strict: Raise on unrecognized values.
+        warn: Log a warning on unrecognized values.
         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.
+        extend_truthy: Extends the effective truthy set, after any truthy
+            replacement.
+        extend_falsy: Extends the effective falsy set, after any falsy
+            replacement.
         _var: Internal - env var name for error messages when called via envbool().
 
     Returns:
@@ -65,6 +95,8 @@ def to_bool(
 
     Raises:
         InvalidBoolValueError: In strict mode when value is unrecognized.
+        ConflictingValuesError: In strict mode when the effective truthy and
+            falsy sets overlap.
     """
     # Normalize first so all comparisons are case- and whitespace-insensitive.
     # Empty after normalization means "unset" -- return the caller's default
@@ -73,27 +105,30 @@ def to_bool(
     if not normalized:
         return default
 
-    # Read the process-level defaults (set once via set_defaults(), or the
-    # built-ins if never called). _resolve then applies the full three-level
-    # precedence chain:
-    #   hardcoded defaults (_defaults.py)
-    #   -> process-level defaults (effective_truthy/effective_falsy already
-    #      resolved there by set_defaults())
-    #   -> call-site args (truthy/extend_truthy/falsy/extend_falsy)
-    defaults = get_defaults()
+    # Precedence is two-level: the built-in sets, then the call-site args
+    # (truthy/extend_truthy/falsy/extend_falsy) layered on top by _resolve.
     effective_truthy, effective_falsy = _resolve(
-        config_truthy=defaults.effective_truthy,
-        config_falsy=defaults.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.
+    # Overlapping sets are a configuration mistake. Strict mode promises every
+    # accepted value is unambiguous, so it rejects the configuration outright --
+    # on every call, not just when the value lands in the overlap, so the
+    # mistake surfaces at the first strict read. Lenient mode warns so the
+    # problem is visible, then lets truthy win to stay predictable.
     overlap = effective_truthy & effective_falsy
     if overlap:
+        if strict:
+            err = ConflictingValuesError(
+                f"Truthy and falsy sets overlap: {', '.join(sorted(overlap))}"
+            )
+            err.overlap = overlap
+            err.truthy = effective_truthy
+            err.falsy = effective_falsy
+            raise err
         _logger.warning(
             "Overlapping truthy/falsy values (truthy wins): %s", sorted(overlap)
         )
@@ -101,16 +136,12 @@ def to_bool(
     if normalized in effective_truthy:
         return True
 
-    # Falsy is checked after truthy so the overlap rule above is enforced
-    # without any extra branching.
+    # Falsy is checked after truthy so the lenient overlap rule above (truthy
+    # wins) is enforced without any extra branching.
     if normalized in effective_falsy:
         return False
 
-    # Three-state logic: True/False at the call site override the process-level
-    # default; None defers to whatever set_defaults() last set (which defaults
-    # to False if set_defaults() was never called).
-    effective_strict = strict if strict is not None else defaults.strict
-    if effective_strict:
+    if 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
@@ -134,8 +165,7 @@ def to_bool(
         err.falsy = effective_falsy
         raise err
 
-    effective_warn = warn if warn is not None else defaults.warn
-    if effective_warn:
+    if warn:
         _logger.warning("Unrecognized boolean value: %r", normalized)
 
     # Lenient fallback: anything unrecognized is treated as falsy. This matches
@@ -148,16 +178,14 @@ def to_bool(
 
 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 -- see
-    # _apply_replace_or_extend() docstring for the full precedence rules.
-    effective_truthy = _apply_replace_or_extend(config_truthy, truthy, extend_truthy)
-    effective_falsy = _apply_replace_or_extend(config_falsy, falsy, extend_falsy)
+    # Replace-then-extend, per set -- see the _apply_replace_then_extend()
+    # docstring for the full precedence rules.
+    effective_truthy = _apply_replace_then_extend(DEFAULT_TRUTHY, truthy, extend_truthy)
+    effective_falsy = _apply_replace_then_extend(DEFAULT_FALSY, falsy, extend_falsy)
 
     return (effective_truthy, effective_falsy)

{envbool-0.4.2 → envbool-0.6.0}/src/envbool/_env.py

@@ -6,7 +6,7 @@ Public surface:
 # 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_defaults())
+# Delegation chain: envbool() -> to_bool() -> _resolve()
 
 __all__ = ["envbool"]
 
@@ -22,8 +22,8 @@ def envbool(
     *,
     default: bool = False,
     required: bool = False,
-    strict: bool | None = None,
-    warn: bool | None = None,
+    strict: bool = False,
+    warn: bool = False,
     truthy: Iterable[str] | None = None,
     falsy: Iterable[str] | None = None,
     extend_truthy: Iterable[str] | None = None,
@@ -37,20 +37,22 @@ def envbool(
         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 process-level
-            defaults (set_defaults()) (default False).
-        warn: Log a warning on unrecognized values. None defers to
-            process-level defaults (set_defaults()) (default False).
+        strict: Raise on unrecognized values.
+        warn: Log a warning on unrecognized values.
         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.
+        extend_truthy: Extends the effective truthy set, after any truthy
+            replacement.
+        extend_falsy: Extends the effective falsy set, after any falsy
+            replacement.
 
     Returns:
         True if the env var value is in the truthy set, False otherwise.
 
     Raises:
         InvalidBoolValueError: In strict mode when the value is unrecognized.
+        ConflictingValuesError: In strict mode when the effective truthy and
+            falsy sets overlap.
         MissingEnvVarError: When required=True and the variable is unset.
     """
     # `required` distinguishes "absent from the environment" from "set but empty"

{envbool-0.4.2 → envbool-0.6.0}/src/envbool/exceptions.py

@@ -8,6 +8,7 @@ which predates envbool adoption keeps working without changes.
 Hierarchy:
     EnvBoolError(Exception)
         InvalidBoolValueError(EnvBoolError, ValueError)
+        ConflictingValuesError(EnvBoolError, ValueError)
         MissingEnvVarError(EnvBoolError, KeyError)
 """
 
@@ -42,6 +43,28 @@ class InvalidBoolValueError(EnvBoolError, ValueError):
     falsy: frozenset[str]
 
 
+class ConflictingValuesError(EnvBoolError, ValueError):
+    """Raised in strict mode when the effective truthy and falsy sets overlap.
+
+    This is a configuration error, not a bad input value -- which is why it is
+    distinct from InvalidBoolValueError. It is raised on every strict call while
+    the conflict exists (not only when the value lands in the overlap), so a
+    misconfiguration fails immediately instead of waiting for a colliding token.
+    ValueError inheritance matches InvalidBoolValueError, so a single
+    ``except ValueError`` still covers every strict-mode failure.
+    """
+
+    # Set by the raising code after construction (see InvalidBoolValueError for
+    # why attributes live here rather than in __init__).
+
+    # Values present in both sets.
+    overlap: frozenset[str]
+
+    # The effective truthy and falsy sets that conflicted.
+    truthy: frozenset[str]
+    falsy: frozenset[str]
+
+
 class MissingEnvVarError(EnvBoolError, KeyError):
     """Raised by envbool(var, required=True) when var is not set in the environment.
 

envbool-0.4.2/src/envbool/__init__.py

@@ -1,56 +0,0 @@
-"""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)
-    set_defaults()        -- set process-level strict/warn/truthy/falsy defaults
-    get_defaults()        -- inspect the active process-level Defaults
-    reset_defaults()      -- restore built-in defaults (for test fixtures)
-    Defaults              -- frozen dataclass returned by get_defaults()
-    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
-"""
-# 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._core import to_bool
-from envbool._defaults import (
-    DEFAULT_FALSY,
-    DEFAULT_TRUTHY,
-    Defaults,
-    get_defaults,
-    reset_defaults,
-    set_defaults,
-)
-from envbool._env import envbool
-from envbool.exceptions import (
-    EnvBoolError,
-    InvalidBoolValueError,
-    MissingEnvVarError,
-)
-
-__all__ = [
-    "DEFAULT_FALSY",
-    "DEFAULT_TRUTHY",
-    "Defaults",
-    "EnvBoolError",
-    "InvalidBoolValueError",
-    "MissingEnvVarError",
-    "envbool",
-    "get_defaults",
-    "reset_defaults",
-    "set_defaults",
-    "to_bool",
-]

envbool-0.4.2/src/envbool/_defaults.py

@@ -1,189 +0,0 @@
-"""Built-in truthy/falsy sets, set-resolution helpers, and process-level defaults.
-
-The Defaults instance held here is consulted by to_bool()/envbool() whenever a
-call-site strict/warn argument is None or no truthy/falsy override is given.
-
-Public surface:
-    DEFAULT_TRUTHY   -- the built-in truthy set
-    DEFAULT_FALSY    -- the built-in falsy set
-    Defaults         -- frozen dataclass with resolved process-level settings
-    get_defaults()   -- returns the active Defaults
-    set_defaults()   -- replaces the active Defaults, built from the built-ins
-    reset_defaults() -- restores the built-in Defaults; for test fixtures
-
-This is a leaf module (no imports from elsewhere in envbool) so _core.py can
-import from it without a circular dependency.
-"""
-
-__all__ = [
-    "DEFAULT_FALSY",
-    "DEFAULT_TRUTHY",
-    "Defaults",
-    "get_defaults",
-    "reset_defaults",
-    "set_defaults",
-]
-
-import threading
-from collections.abc import Iterable
-from dataclasses import dataclass
-
-DEFAULT_TRUTHY: frozenset[str] = frozenset({"true", "1", "yes", "on"})
-DEFAULT_FALSY: frozenset[str] = frozenset({"false", "0", "no", "off"})
-
-
-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 _apply_replace_or_extend(
-    base: frozenset[str],
-    replace: Iterable[str] | None,
-    extend: Iterable[str] | None,
-) -> frozenset[str]:
-    """Resolve a value set using replace/extend/fall-back-to-base precedence.
-
-    Shared by _resolve() (call-site truthy/falsy args, in _core.py) and
-    set_defaults() (below) since both layer their inputs on top of a base set
-    using the same ruff select/extend-select pattern:
-        replace -- full replacement; caller owns the entire set
-        extend  -- additive; merges on top of base
-        neither -- use base as-is
-    replace takes precedence over extend; both cannot apply at once.
-
-    Args:
-        base: The starting set to fall back to or extend.
-        replace: If not None, fully replaces base (normalized).
-        extend: If not None and replace is None, merged on top of base.
-
-    Returns:
-        The resolved, normalized frozenset.
-    """
-    if replace is not None:
-        return _normalize_set(replace)
-    if extend is not None:
-        return base | _normalize_set(extend)
-    return base
-
-
-@dataclass(frozen=True)
-class Defaults:
-    """Process-level defaults consulted when a call-site argument is None.
-
-    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).
-    """
-
-    strict: bool = False
-    warn: bool = False
-    effective_truthy: frozenset[str] = DEFAULT_TRUTHY
-    effective_falsy: frozenset[str] = DEFAULT_FALSY
-
-
-class _DefaultsCache:
-    # Building a Defaults() is pure in-memory work (no disk I/O), so the cache
-    # starts pre-populated -- readers never need a "not built yet" branch. Only
-    # writers (set_defaults/reset_defaults) take the lock, so a concurrent
-    # writer can't produce a torn read.
-
-    value: Defaults = Defaults()
-    lock: threading.Lock = threading.Lock()
-
-
-_cache = _DefaultsCache()
-
-
-def get_defaults() -> Defaults:
-    """Return the active process-level defaults.
-
-    Returns:
-        The current Defaults -- built-ins, or whatever set_defaults() last set.
-    """
-    return _cache.value
-
-
-def _validated_tuple(name: str, values: Iterable[str] | None) -> tuple[str, ...] | None:
-    """Materialize an Iterable[str] argument once, validating every member.
-
-    Iterables (e.g. generators) can only be consumed once; materializing here
-    (rather than validating then re-passing the original iterable) avoids
-    silently resolving to an empty set on the second pass.
-
-    Raises:
-        TypeError: If any member is not a str.
-    """
-    if values is None:
-        return None
-    materialized = tuple(values)
-    for item in materialized:
-        if not isinstance(item, str):
-            raise TypeError(
-                f"{name} must be an iterable of strings, got {type(item).__name__!r}"
-            )
-    return materialized
-
-
-def set_defaults(
-    *,
-    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,
-) -> None:
-    """Set process-level defaults consulted when a call-site argument is None.
-
-    Each call replaces the defaults starting from the hardcoded built-ins --
-    it does not merge with a previous set_defaults() call. Call this once at
-    application startup rather than threading strict=/truthy=/etc. through
-    every envbool()/to_bool() call site.
-
-    Args:
-        strict: Raise on unrecognized values by default. None keeps the
-            built-in (False).
-        warn: Log a warning on unrecognized values by default. None keeps the
-            built-in (False).
-        truthy: Replaces the built-in truthy set.
-        falsy: Replaces the built-in falsy set.
-        extend_truthy: Extends the built-in truthy set.
-        extend_falsy: Extends the built-in falsy set.
-
-    Raises:
-        TypeError: If strict/warn are not bool, or truthy/falsy/extend_truthy/
-            extend_falsy contain a non-string member.
-    """
-    if strict is not None and not isinstance(strict, bool):
-        raise TypeError(f"strict must be a bool, got {type(strict).__name__!r}")
-    if warn is not None and not isinstance(warn, bool):
-        raise TypeError(f"warn must be a bool, got {type(warn).__name__!r}")
-
-    truthy = _validated_tuple("truthy", truthy)
-    falsy = _validated_tuple("falsy", falsy)
-    extend_truthy = _validated_tuple("extend_truthy", extend_truthy)
-    extend_falsy = _validated_tuple("extend_falsy", extend_falsy)
-
-    new_defaults = Defaults(
-        strict=strict if strict is not None else False,
-        warn=warn if warn is not None else False,
-        effective_truthy=_apply_replace_or_extend(
-            DEFAULT_TRUTHY, truthy, extend_truthy
-        ),
-        effective_falsy=_apply_replace_or_extend(DEFAULT_FALSY, falsy, extend_falsy),
-    )
-    with _cache.lock:
-        _cache.value = new_defaults
-
-
-def reset_defaults() -> None:
-    """Restore built-in defaults, discarding any set_defaults() override.
-
-    Intended for test fixtures: call in an autouse fixture teardown so a
-    set_defaults() call in one test doesn't leak into the next.
-    """
-    with _cache.lock:
-        _cache.value = Defaults()