envbool 0.2.0__tar.gz → 0.4.0__tar.gz

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

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: envbool
-Version: 0.2.0
+Version: 0.4.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
@@ -18,7 +18,6 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Typing :: Typed
-Requires-Dist: platformdirs>=4.9.6
 Requires-Python: >=3.11
 Project-URL: Homepage, https://github.com/jkomalley/envbool
 Project-URL: Repository, https://github.com/jkomalley/envbool
@@ -67,18 +66,17 @@ 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.
-- **Config files.** Share defaults across a project via `envbool.toml` or
-  `[tool.envbool]` in `pyproject.toml`.
+- **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.** One dependency, fully typed, Python 3.11+.
+- **Zero ceremony.** Zero dependencies, fully typed, Python 3.11+.
 
 ## Contents
 
 - [Installation](#installation)
 - [Usage](#usage)
 - [Command-line interface](#command-line-interface)
-- [Configuration](#configuration)
 - [API reference](#api-reference)
 - [Advanced topics](#advanced-topics)
 - [Contributing](#contributing)
@@ -151,6 +149,37 @@ to_bool("0")                   # False
 to_bool("maybe", strict=True)  # raises InvalidBoolValueError
 ```
 
+### Process-level defaults
+
+Set policy once at startup instead of threading `strict=`/`extend_truthy=`
+through every call site:
+
+```python
+import envbool
+
+envbool.set_defaults(strict=True, extend_truthy=["enabled"])
+
+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:
+
+```
+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)).
+
+> 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.
+
 ## Command-line interface
 
 The `envbool` command exits `0` for truthy, `1` for falsy, and `2` on error, so
@@ -176,9 +205,9 @@ in that order of priority.
 
 ```console
 $ envbool --help
-usage: envbool [-h] [--value TEXT] [--strict] [--warn] [--default] [--print]
-               [--truthy VALUE] [--falsy VALUE] [--extend-truthy VALUE]
-               [--extend-falsy VALUE] [--show-config]
+usage: envbool [-h] [--value TEXT] [--strict] [--warn] [--default]
+               [--required] [--print] [--truthy VALUE] [--falsy VALUE]
+               [--extend-truthy VALUE] [--extend-falsy VALUE]
                [VAR_NAME]
 
 Coerce an environment variable or string to a boolean.
@@ -192,48 +221,25 @@ options:
   --strict, -s          Raise error on unrecognized values.
   --warn                Log a warning on unrecognized values.
   --default, -d         Default value if unset/empty (default: false).
+  --required, -r        Exit 2 if VAR_NAME is not set in the environment.
   --print, -p           Print "true" or "false" instead of using exit codes.
   --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).
-  --show-config         Print the effective configuration and exit.
 ```
 
 A few rules worth knowing:
 
-- Omitting `--strict` / `--warn` defers to the config file setting.
+- 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.
 - `VAR_NAME` and `--value` are mutually exclusive.
-- `--show-config` prints the effective configuration and exits. It cannot be
-  combined with `VAR_NAME`, `--value`, `--print`, or `--default`, but it *can*
-  take the value-set flags to preview overrides.
-- With no `VAR_NAME`, `--value`, or piped stdin, the CLI prints usage and exits `2`.
-
-## Configuration
-
-Share defaults across a project by dropping an `envbool.toml` at its root (or a
-`[tool.envbool]` table in `pyproject.toml`):
-
-```toml
-# envbool.toml
-strict = true
-extend_truthy = ["enabled"]
-extend_falsy  = ["disabled"]
-```
-
-`envbool` walks up from the current directory to find the nearest project config,
-then falls back to a user-level `config.toml` in the platform's standard config
-directory (`~/.config/envbool/` on Linux, `~/Library/Application Support/envbool/`
-on macOS), resolved via [platformdirs](https://pypi.org/project/platformdirs/).
-
-Values resolve in three layers, each overriding the last:
-
-```
-built-in defaults  →  config file  →  function arguments / CLI flags
-```
-
-Set `ENVBOOL_NO_CONFIG=1` to skip config discovery entirely.
+- `--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`.
 
 ## API reference
 
@@ -241,24 +247,30 @@ 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). |
-| `EnvBoolConfig` | Frozen dataclass: `strict`, `warn`, `effective_truthy`, `effective_falsy`, `source_path`. |
+| `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`. |
-| `ConfigError` | Raised when a config file is malformed. |
+| `MissingEnvVarError` | Raised by `envbool(required=True)` when the variable is unset. Also a `KeyError`. |
 
 `envbool()` and `to_bool()` share the same keyword-only options:
 
 | Option | Type | Default | Meaning |
 | --- | --- | --- | --- |
 | `default` | `bool` | `False` | Returned for unset/empty input. |
-| `strict` | `bool \| None` | `None` | Raise on unrecognized values (`None` defers to config). |
-| `warn` | `bool \| None` | `None` | Log a warning on unrecognized values (`None` defers to config). |
+| `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. |
 
+`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
@@ -288,10 +300,6 @@ InvalidBoolValueError: Invalid boolean value for MY_VAR: 'maybe'
   Expected falsy:  0, false, no, off
 ```
 
-`ConfigError` is raised when a config file is found but malformed (for example,
-`strict = "yes"` instead of `strict = true`). It carries the offending path on
-`e.path`.
-
 ### Logging
 
 `envbool` logs through the standard `logging` module under the `"envbool"`
@@ -307,7 +315,6 @@ logging.getLogger("envbool").addHandler(logging.StreamHandler())
 
 | Level | When |
 | --- | --- |
-| `DEBUG` | A config file was discovered and loaded, or none was found. |
 | `WARNING` | An unrecognized value fell through in lenient mode (only when `warn=True`). |
 | `WARNING` | The truthy and falsy sets overlap (truthy wins). |
 
@@ -330,24 +337,20 @@ else:
 
 ### Testing code that uses envbool
 
-`envbool` loads its config file once and caches it for the process lifetime. If
-your tests create temporary config files, clear that cache between them with an
-autouse fixture:
+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._config import _reset_config
+from envbool import reset_defaults
 
 @pytest.fixture(autouse=True)
-def _reset_envbool_config():
+def _reset_envbool_defaults():
     yield
-    _reset_config()
+    reset_defaults()
 ```
 
-`_reset_config()` is private but stable and exists for exactly this purpose; it
-clears the cache under a lock, so it is safe to call from any thread.
-
 ## Contributing
 
 Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for development

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

@@ -39,18 +39,17 @@ 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.
-- **Config files.** Share defaults across a project via `envbool.toml` or
-  `[tool.envbool]` in `pyproject.toml`.
+- **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.** One dependency, fully typed, Python 3.11+.
+- **Zero ceremony.** Zero dependencies, fully typed, Python 3.11+.
 
 ## Contents
 
 - [Installation](#installation)
 - [Usage](#usage)
 - [Command-line interface](#command-line-interface)
-- [Configuration](#configuration)
 - [API reference](#api-reference)
 - [Advanced topics](#advanced-topics)
 - [Contributing](#contributing)
@@ -123,6 +122,37 @@ to_bool("0")                   # False
 to_bool("maybe", strict=True)  # raises InvalidBoolValueError
 ```
 
+### Process-level defaults
+
+Set policy once at startup instead of threading `strict=`/`extend_truthy=`
+through every call site:
+
+```python
+import envbool
+
+envbool.set_defaults(strict=True, extend_truthy=["enabled"])
+
+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:
+
+```
+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)).
+
+> 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.
+
 ## Command-line interface
 
 The `envbool` command exits `0` for truthy, `1` for falsy, and `2` on error, so
@@ -148,9 +178,9 @@ in that order of priority.
 
 ```console
 $ envbool --help
-usage: envbool [-h] [--value TEXT] [--strict] [--warn] [--default] [--print]
-               [--truthy VALUE] [--falsy VALUE] [--extend-truthy VALUE]
-               [--extend-falsy VALUE] [--show-config]
+usage: envbool [-h] [--value TEXT] [--strict] [--warn] [--default]
+               [--required] [--print] [--truthy VALUE] [--falsy VALUE]
+               [--extend-truthy VALUE] [--extend-falsy VALUE]
                [VAR_NAME]
 
 Coerce an environment variable or string to a boolean.
@@ -164,48 +194,25 @@ options:
   --strict, -s          Raise error on unrecognized values.
   --warn                Log a warning on unrecognized values.
   --default, -d         Default value if unset/empty (default: false).
+  --required, -r        Exit 2 if VAR_NAME is not set in the environment.
   --print, -p           Print "true" or "false" instead of using exit codes.
   --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).
-  --show-config         Print the effective configuration and exit.
 ```
 
 A few rules worth knowing:
 
-- Omitting `--strict` / `--warn` defers to the config file setting.
+- 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.
 - `VAR_NAME` and `--value` are mutually exclusive.
-- `--show-config` prints the effective configuration and exits. It cannot be
-  combined with `VAR_NAME`, `--value`, `--print`, or `--default`, but it *can*
-  take the value-set flags to preview overrides.
-- With no `VAR_NAME`, `--value`, or piped stdin, the CLI prints usage and exits `2`.
-
-## Configuration
-
-Share defaults across a project by dropping an `envbool.toml` at its root (or a
-`[tool.envbool]` table in `pyproject.toml`):
-
-```toml
-# envbool.toml
-strict = true
-extend_truthy = ["enabled"]
-extend_falsy  = ["disabled"]
-```
-
-`envbool` walks up from the current directory to find the nearest project config,
-then falls back to a user-level `config.toml` in the platform's standard config
-directory (`~/.config/envbool/` on Linux, `~/Library/Application Support/envbool/`
-on macOS), resolved via [platformdirs](https://pypi.org/project/platformdirs/).
-
-Values resolve in three layers, each overriding the last:
-
-```
-built-in defaults  →  config file  →  function arguments / CLI flags
-```
-
-Set `ENVBOOL_NO_CONFIG=1` to skip config discovery entirely.
+- `--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`.
 
 ## API reference
 
@@ -213,24 +220,30 @@ 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). |
-| `EnvBoolConfig` | Frozen dataclass: `strict`, `warn`, `effective_truthy`, `effective_falsy`, `source_path`. |
+| `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`. |
-| `ConfigError` | Raised when a config file is malformed. |
+| `MissingEnvVarError` | Raised by `envbool(required=True)` when the variable is unset. Also a `KeyError`. |
 
 `envbool()` and `to_bool()` share the same keyword-only options:
 
 | Option | Type | Default | Meaning |
 | --- | --- | --- | --- |
 | `default` | `bool` | `False` | Returned for unset/empty input. |
-| `strict` | `bool \| None` | `None` | Raise on unrecognized values (`None` defers to config). |
-| `warn` | `bool \| None` | `None` | Log a warning on unrecognized values (`None` defers to config). |
+| `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. |
 
+`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
@@ -260,10 +273,6 @@ InvalidBoolValueError: Invalid boolean value for MY_VAR: 'maybe'
   Expected falsy:  0, false, no, off
 ```
 
-`ConfigError` is raised when a config file is found but malformed (for example,
-`strict = "yes"` instead of `strict = true`). It carries the offending path on
-`e.path`.
-
 ### Logging
 
 `envbool` logs through the standard `logging` module under the `"envbool"`
@@ -279,7 +288,6 @@ logging.getLogger("envbool").addHandler(logging.StreamHandler())
 
 | Level | When |
 | --- | --- |
-| `DEBUG` | A config file was discovered and loaded, or none was found. |
 | `WARNING` | An unrecognized value fell through in lenient mode (only when `warn=True`). |
 | `WARNING` | The truthy and falsy sets overlap (truthy wins). |
 
@@ -302,24 +310,20 @@ else:
 
 ### Testing code that uses envbool
 
-`envbool` loads its config file once and caches it for the process lifetime. If
-your tests create temporary config files, clear that cache between them with an
-autouse fixture:
+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._config import _reset_config
+from envbool import reset_defaults
 
 @pytest.fixture(autouse=True)
-def _reset_envbool_config():
+def _reset_envbool_defaults():
     yield
-    _reset_config()
+    reset_defaults()
 ```
 
-`_reset_config()` is private but stable and exists for exactly this purpose; it
-clears the cache under a lock, so it is safe to call from any thread.
-
 ## Contributing
 
 Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for development

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

@@ -1,17 +1,15 @@
 [project]
 name = "envbool"
-version = "0.2.0"
+version = "0.4.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"
 keywords = ["environment variables", "boolean", "configuration", "env", "coerce"]
-dependencies = [
-    "platformdirs>=4.9.6",
-]
+dependencies = []
 classifiers = [
-    "Development Status :: 3 - Alpha",
+    "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Topic :: Utilities",
@@ -40,6 +38,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.4.0}/src/envbool/__init__.py

@@ -11,32 +11,46 @@ For except clauses, envbool.exceptions is also importable by name:
 Available names:
     envbool()             -- read an env var and coerce to bool (primary API)
     to_bool()             -- coerce an arbitrary string to bool (no os.environ)
-    load_config()         -- inspect or preload the process-level config cache
-    EnvBoolConfig         -- frozen dataclass returned by load_config()
+    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
-    ConfigError           -- raised for malformed or unreadable config files
+    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._config import EnvBoolConfig, load_config
 from envbool._core import to_bool
-from envbool._defaults import DEFAULT_FALSY, DEFAULT_TRUTHY
+from envbool._defaults import (
+    DEFAULT_FALSY,
+    DEFAULT_TRUTHY,
+    Defaults,
+    get_defaults,
+    reset_defaults,
+    set_defaults,
+)
 from envbool._env import envbool
-from envbool.exceptions import ConfigError, EnvBoolError, InvalidBoolValueError
+from envbool.exceptions import (
+    EnvBoolError,
+    InvalidBoolValueError,
+    MissingEnvVarError,
+)
 
 __all__ = [
     "DEFAULT_FALSY",
     "DEFAULT_TRUTHY",
-    "ConfigError",
-    "EnvBoolConfig",
+    "Defaults",
     "EnvBoolError",
     "InvalidBoolValueError",
+    "MissingEnvVarError",
     "envbool",
-    "load_config",
+    "get_defaults",
+    "reset_defaults",
+    "set_defaults",
     "to_bool",
 ]

envbool-0.4.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()