envbool 0.4.1__tar.gz → 0.5.0__tar.gz

envbool-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kyle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{envbool-0.4.1 → envbool-0.5.0}/PKG-INFO

@@ -1,11 +1,12 @@
 Metadata-Version: 2.4
 Name: envbool
-Version: 0.4.1
+Version: 0.5.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
+License-File: LICENSE
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
@@ -44,9 +45,9 @@ Reading a boolean out of the environment is the kind of thing every project
 reinvents, slightly differently, in slightly buggy ways:
 
 ```python
-DEBUG   = os.environ.get("DEBUG",   "").lower() in ("1", "true", "yes")
+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")
+CACHE = os.environ.get("CACHE", "").lower() in ("1", "true", "yes")
 ```
 
 `envbool` is that snippet, done once and done properly:
@@ -54,9 +55,9 @@ CACHE   = os.environ.get("CACHE",   "").lower() in ("1", "true", "yes")
 ```python
 from envbool import envbool
 
-DEBUG   = envbool("DEBUG")
+DEBUG = envbool("DEBUG")
 VERBOSE = envbool("VERBOSE")
-CACHE   = envbool("CACHE")
+CACHE = envbool("CACHE")
 ```
 
 ## Features
@@ -90,6 +91,22 @@ pip install envbool
 uv add envbool
 ```
 
+### Snap
+
+On Linux, the `envbool` command is also available as a strictly confined
+[snap](https://snapcraft.io/):
+
+```bash
+sudo snap install envbool
+```
+
+The snap ships the CLI only; to `import envbool` from your own code, install it
+with `pip` or `uv`. It reads ordinary environment variables unchanged, but
+snapd sets a few variables for every snap, so the CLI sees snapd's values for
+`HOME`, `PATH`, `TMPDIR`, `XDG_RUNTIME_DIR`, and `SNAP_*` rather than yours. If
+both the snap and a pip install are present, whichever of `/snap/bin` or your
+pip `bin` directory comes first on `PATH` wins.
+
 ## Usage
 
 ### The basics
@@ -100,8 +117,8 @@ uv add envbool
 ```python
 from envbool import envbool
 
-DEBUG = envbool("DEBUG")                 # False if unset or empty
-CACHE = envbool("CACHE", default=True)   # True if unset or empty
+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`; the falsy values are
@@ -112,6 +129,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
@@ -136,6 +156,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 base set (the built-ins, or
+whatever `set_defaults()` configured), 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
@@ -144,8 +174,8 @@ same keyword arguments as `envbool`.
 ```python
 from envbool import to_bool
 
-to_bool("yes")                 # True
-to_bool("0")                   # False
+to_bool("yes")  # True
+to_bool("0")  # False
 to_bool("maybe", strict=True)  # raises InvalidBoolValueError
 ```
 
@@ -176,6 +206,52 @@ built-in defaults  →  set_defaults()  →  function arguments / CLI flags
 `reset_defaults()` restores the built-ins — call it in a test fixture (see
 [Testing code that uses envbool](#testing-code-that-uses-envbool)).
 
+### Loading application settings
+
+In a real application, read every flag once at startup into a single settings
+object, with the policy set up front. With strict mode on, a typo like
+`DEBUG=ture` stops startup instead of quietly reading as `False`:
+
+```python
+import sys
+from dataclasses import dataclass
+
+import envbool
+from envbool import EnvBoolError
+
+
+@dataclass(frozen=True)
+class Settings:
+    debug: bool
+    use_cache: bool
+    new_checkout: bool
+    send_emails: bool
+
+
+def load_settings() -> Settings:
+    envbool.set_defaults(
+        strict=True,
+        extend_truthy=["enabled"],
+        extend_falsy=["disabled"],
+    )
+    return Settings(
+        debug=envbool.envbool("DEBUG"),  # off unless set
+        use_cache=envbool.envbool("USE_CACHE", default=True),  # on unless set
+        new_checkout=envbool.envbool("FEATURE_NEW_CHECKOUT"),
+        send_emails=envbool.envbool("SEND_EMAILS", required=True),  # must be set
+    )
+
+
+try:
+    SETTINGS = load_settings()
+except EnvBoolError as e:
+    sys.exit(f"Invalid configuration: {e}")
+```
+
+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.
+
 > 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.
@@ -226,8 +302,10 @@ 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:
@@ -241,6 +319,29 @@ A few rules worth knowing:
 - 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 |
@@ -255,6 +356,7 @@ A few rules worth knowing:
 | `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:
@@ -265,7 +367,7 @@ A few rules worth knowing:
 | `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()`). |
 | `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
@@ -284,9 +386,9 @@ from envbool import envbool, InvalidBoolValueError
 try:
     result = envbool("MY_VAR", strict=True)
 except InvalidBoolValueError as e:
-    print(e.var)    # "MY_VAR" — env var name, or None when raised from to_bool()
+    print(e.var)  # "MY_VAR" — env var name, or None when raised from to_bool()
     print(e.value)  # "maybe" — the normalized (stripped, lowercased) value
-    print(e.truthy) # frozenset({"true", "1", "yes", "on"}) — effective truthy set
+    print(e.truthy)  # frozenset({"true", "1", "yes", "on"}) — effective truthy set
     print(e.falsy)  # frozenset({"false", "0", "no", "off"}) — effective falsy set
 ```
 
@@ -316,7 +418,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
 
@@ -345,6 +447,7 @@ fixture so overrides don't leak across the suite:
 import pytest
 from envbool import reset_defaults
 
+
 @pytest.fixture(autouse=True)
 def _reset_envbool_defaults():
     yield

{envbool-0.4.1 → envbool-0.5.0}/README.md

@@ -17,9 +17,9 @@ Reading a boolean out of the environment is the kind of thing every project
 reinvents, slightly differently, in slightly buggy ways:
 
 ```python
-DEBUG   = os.environ.get("DEBUG",   "").lower() in ("1", "true", "yes")
+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")
+CACHE = os.environ.get("CACHE", "").lower() in ("1", "true", "yes")
 ```
 
 `envbool` is that snippet, done once and done properly:
@@ -27,9 +27,9 @@ CACHE   = os.environ.get("CACHE",   "").lower() in ("1", "true", "yes")
 ```python
 from envbool import envbool
 
-DEBUG   = envbool("DEBUG")
+DEBUG = envbool("DEBUG")
 VERBOSE = envbool("VERBOSE")
-CACHE   = envbool("CACHE")
+CACHE = envbool("CACHE")
 ```
 
 ## Features
@@ -63,6 +63,22 @@ pip install envbool
 uv add envbool
 ```
 
+### Snap
+
+On Linux, the `envbool` command is also available as a strictly confined
+[snap](https://snapcraft.io/):
+
+```bash
+sudo snap install envbool
+```
+
+The snap ships the CLI only; to `import envbool` from your own code, install it
+with `pip` or `uv`. It reads ordinary environment variables unchanged, but
+snapd sets a few variables for every snap, so the CLI sees snapd's values for
+`HOME`, `PATH`, `TMPDIR`, `XDG_RUNTIME_DIR`, and `SNAP_*` rather than yours. If
+both the snap and a pip install are present, whichever of `/snap/bin` or your
+pip `bin` directory comes first on `PATH` wins.
+
 ## Usage
 
 ### The basics
@@ -73,8 +89,8 @@ uv add envbool
 ```python
 from envbool import envbool
 
-DEBUG = envbool("DEBUG")                 # False if unset or empty
-CACHE = envbool("CACHE", default=True)   # True if unset or empty
+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`; the falsy values are
@@ -85,6 +101,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 +128,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 base set (the built-ins, or
+whatever `set_defaults()` configured), 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
@@ -117,8 +146,8 @@ same keyword arguments as `envbool`.
 ```python
 from envbool import to_bool
 
-to_bool("yes")                 # True
-to_bool("0")                   # False
+to_bool("yes")  # True
+to_bool("0")  # False
 to_bool("maybe", strict=True)  # raises InvalidBoolValueError
 ```
 
@@ -149,6 +178,52 @@ built-in defaults  →  set_defaults()  →  function arguments / CLI flags
 `reset_defaults()` restores the built-ins — call it in a test fixture (see
 [Testing code that uses envbool](#testing-code-that-uses-envbool)).
 
+### Loading application settings
+
+In a real application, read every flag once at startup into a single settings
+object, with the policy set up front. With strict mode on, a typo like
+`DEBUG=ture` stops startup instead of quietly reading as `False`:
+
+```python
+import sys
+from dataclasses import dataclass
+
+import envbool
+from envbool import EnvBoolError
+
+
+@dataclass(frozen=True)
+class Settings:
+    debug: bool
+    use_cache: bool
+    new_checkout: bool
+    send_emails: bool
+
+
+def load_settings() -> Settings:
+    envbool.set_defaults(
+        strict=True,
+        extend_truthy=["enabled"],
+        extend_falsy=["disabled"],
+    )
+    return Settings(
+        debug=envbool.envbool("DEBUG"),  # off unless set
+        use_cache=envbool.envbool("USE_CACHE", default=True),  # on unless set
+        new_checkout=envbool.envbool("FEATURE_NEW_CHECKOUT"),
+        send_emails=envbool.envbool("SEND_EMAILS", required=True),  # must be set
+    )
+
+
+try:
+    SETTINGS = load_settings()
+except EnvBoolError as e:
+    sys.exit(f"Invalid configuration: {e}")
+```
+
+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.
+
 > 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.
@@ -199,8 +274,10 @@ 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:
@@ -214,6 +291,29 @@ A few rules worth knowing:
 - 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 |
@@ -228,6 +328,7 @@ A few rules worth knowing:
 | `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:
@@ -238,7 +339,7 @@ A few rules worth knowing:
 | `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()`). |
 | `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
@@ -257,9 +358,9 @@ from envbool import envbool, InvalidBoolValueError
 try:
     result = envbool("MY_VAR", strict=True)
 except InvalidBoolValueError as e:
-    print(e.var)    # "MY_VAR" — env var name, or None when raised from to_bool()
+    print(e.var)  # "MY_VAR" — env var name, or None when raised from to_bool()
     print(e.value)  # "maybe" — the normalized (stripped, lowercased) value
-    print(e.truthy) # frozenset({"true", "1", "yes", "on"}) — effective truthy set
+    print(e.truthy)  # frozenset({"true", "1", "yes", "on"}) — effective truthy set
     print(e.falsy)  # frozenset({"false", "0", "no", "off"}) — effective falsy set
 ```
 
@@ -289,7 +390,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
 
@@ -318,6 +419,7 @@ fixture so overrides don't leak across the suite:
 import pytest
 from envbool import reset_defaults
 
+
 @pytest.fixture(autouse=True)
 def _reset_envbool_defaults():
     yield

{envbool-0.4.1 → envbool-0.5.0}/pyproject.toml

@@ -1,10 +1,11 @@
 [project]
 name = "envbool"
-version = "0.4.1"
+version = "0.5.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"
 license = "MIT"
+license-files = ["LICENSE"]
 keywords = [
     "environment variables",
     "boolean",

{envbool-0.4.1 → envbool-0.5.0}/pyproject.toml.orig

@@ -1,11 +1,12 @@
 [project]
 name = "envbool"
-version = "0.4.1"
+version = "0.5.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" }]
 requires-python = ">=3.11"
 license = "MIT"
+license-files = ["LICENSE"]
 keywords = ["environment variables", "boolean", "configuration", "env", "coerce"]
 dependencies = []
 classifiers = [

{envbool-0.4.1 → envbool-0.5.0}/src/envbool/__init__.py

@@ -9,17 +9,18 @@ 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
+    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
+    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,
@@ -36,6 +37,7 @@ from envbool._defaults import (
 )
 from envbool._env import envbool
 from envbool.exceptions import (
+    ConflictingValuesError,
     EnvBoolError,
     InvalidBoolValueError,
     MissingEnvVarError,
@@ -44,6 +46,7 @@ from envbool.exceptions import (
 __all__ = [
     "DEFAULT_FALSY",
     "DEFAULT_TRUTHY",
+    "ConflictingValuesError",
     "Defaults",
     "EnvBoolError",
     "InvalidBoolValueError",

{envbool-0.4.1 → envbool-0.5.0}/src/envbool/_cli.py

@@ -18,8 +18,8 @@ Omitting --strict or --warn defers to the process-level defaults
 (envbool.set_defaults(); default: lenient, 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
@@ -36,7 +36,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:
@@ -114,13 +114,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 +213,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.1 → envbool-0.5.0}/src/envbool/_core.py

@@ -21,10 +21,10 @@ from collections.abc import Iterable
 from envbool._defaults import (
     DEFAULT_FALSY,
     DEFAULT_TRUTHY,
-    _apply_replace_or_extend,
+    _apply_replace_then_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.
@@ -56,8 +56,10 @@ def to_bool(
             process-level defaults (set_defaults()) (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.
+        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 +67,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
@@ -90,10 +94,27 @@ def to_bool(
         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.
+    # 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). Resolved before the lookup
+    # because the overlap check below also depends on it.
+    effective_strict = strict if strict is not None else defaults.strict
+
+    # 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 effective_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,15 +122,11 @@ 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:
         truthy_list = ", ".join(sorted(effective_truthy))
         falsy_list = ", ".join(sorted(effective_falsy))
@@ -155,9 +172,9 @@ def _resolve(
     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(config_truthy, truthy, extend_truthy)
+    effective_falsy = _apply_replace_then_extend(config_falsy, falsy, extend_falsy)
 
     return (effective_truthy, effective_falsy)

{envbool-0.4.1 → envbool-0.5.0}/src/envbool/_defaults.py

@@ -37,34 +37,34 @@ def _normalize_set(values: Iterable[str]) -> frozenset[str]:
     return frozenset(v.strip().lower() for v in values)
 
 
-def _apply_replace_or_extend(
+def _apply_replace_then_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.
+    """Resolve a value set: replace the base (if given), then extend the result.
 
     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
+    the same way:
+        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
-    replace takes precedence over extend; both cannot apply at once.
+    Passing both applies replace first, then extend, so neither argument is
+    silently dropped.
 
     Args:
-        base: The starting set to fall back to or extend.
+        base: The starting set, used when replace is None.
         replace: If not None, fully replaces base (normalized).
-        extend: If not None and replace is None, merged on top of base.
+        extend: If not None, merged on top of the (possibly replaced) set.
 
     Returns:
         The resolved, normalized frozenset.
     """
-    if replace is not None:
-        return _normalize_set(replace)
+    result = _normalize_set(replace) if replace is not None else base
     if extend is not None:
-        return base | _normalize_set(extend)
-    return base
+        result |= _normalize_set(extend)
+    return result
 
 
 @dataclass(frozen=True)
@@ -150,8 +150,8 @@ def set_defaults(
             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.
+        extend_truthy: Extends the truthy set (built-in, or truthy if given).
+        extend_falsy: Extends the falsy set (built-in, or falsy if given).
 
     Raises:
         TypeError: If strict/warn are not bool, or truthy/falsy/extend_truthy/
@@ -170,10 +170,10 @@ def set_defaults(
     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(
+        effective_truthy=_apply_replace_then_extend(
             DEFAULT_TRUTHY, truthy, extend_truthy
         ),
-        effective_falsy=_apply_replace_or_extend(DEFAULT_FALSY, falsy, extend_falsy),
+        effective_falsy=_apply_replace_then_extend(DEFAULT_FALSY, falsy, extend_falsy),
     )
     with _cache.lock:
         _cache.value = new_defaults

{envbool-0.4.1 → envbool-0.5.0}/src/envbool/_env.py

@@ -43,14 +43,18 @@ def envbool(
             process-level defaults (set_defaults()) (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.
+        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.1 → envbool-0.5.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.