envread 0.2.0__tar.gz

envread-0.2.0/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

envread-0.2.0/.github/FUNDING.yml

@@ -0,0 +1 @@
+buy_me_a_coffee: jlianesglrs

envread-0.2.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/

envread-0.2.0/CHANGELOG.md

@@ -0,0 +1,65 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+- Renamed the distribution, import package and command to `envread` (the old name is not available on PyPI).
+
+## [0.2.0]
+
+### Added
+
+- `load(cls, source=None)` fills a plain dataclass from the environment: field name
+  upper-cased as the variable name, the annotation as the parser, a default,
+  `default_factory` or `X | None` making it optional. Every field is read first and all
+  failures are raised together as `EnvValidationError` (its `errors` tuple holds each one).
+- `var(name, default=, default_factory=, separator=, secret=)`, a `field()` replacement
+  for fields that need a different name, a list separator or masking.
+- Settings fields may be `str`, `int`, `float`, `bool`, `Decimal`, `Path`, `timedelta`,
+  `Secret`, any `Enum`, `Literal[...]` of strings, `dict[...]` (a JSON object), and
+  `list[X]` / `tuple[X, ...]` of a scalar type.
+- New getters, each with the same typed overloads as the 0.1 ones: `decimal` (finite
+  only), `path`, `duration` (`90`, `250ms`, `1h30m`, `1.5h` into `timedelta`), `enum`
+  (member name in any case, or value) and `secret`.
+- `secret=True` on every getter keeps the value out of the error message, its `value`
+  attribute and the exception chain. `Secret` masks itself in `str`, `repr` and
+  f-strings, compares in constant time and refuses pickling.
+- `Env(prefix=...)` and `Env.prefixed()` scope names; errors name the full variable.
+- `Env(empty_is_unset=True)` treats `KEY=` as unset; `Env.raw()`, `Env.is_set()`,
+  `in`, `Env.source`, `Env.full_name()` and a repr that never shows values.
+- `.env` support as a documented subset of python-dotenv 1.x: `parse_dotenv`,
+  `read_dotenv` and `load_dotenv(path, override=False)`, raising `DotenvError` (file and
+  line, never the value) for anything outside the subset. On Windows, `load_dotenv`
+  refuses entries longer than the 32,767 characters the process environment accepts.
+- `envread` command (also `python -m envread`): `check` validates a spec file or a
+  `module:Class` dataclass against the environment with text or JSON output, and `get`
+  prints one parsed value. Both take `--prefix`, `--env-file` and `--empty-is-unset`.
+- `InvalidEnvError` gains `reason`, `secret`, `detail` and `masked()`.
+
+### Changed
+
+- `bool` also accepts `enable`/`enabled` and `disable`/`disabled`, matching boolish.
+- Very long values are trimmed in error messages; the `value` attribute keeps them whole.
+- JSON errors report the line and column.
+
+### Fixed
+
+- `str(MissingEnvError(...))` no longer wraps the message in an extra pair of quotes.
+
+## [0.1.0]
+
+### Added
+
+- `Env` reader and a module-level `env` default, backed by `os.environ` or any mapping
+  you pass to `Env(source=...)`.
+- Typed getters `str`, `int`, `float`, `bool`, `list` and `json`, each overloaded so the
+  return type follows the call: non-optional when required, `T | None` with a `None`
+  default or `required=False`.
+- `bool` accepts `true/false`, `yes/no`, `on/off` and `1/0` in any case; `list` splits on
+  a configurable separator; `json` parses with the standard library.
+- `MissingEnvError` (also a `KeyError`) and `InvalidEnvError` (also a `ValueError`), both
+  naming the offending variable.
+- Ships `py.typed`, no runtime dependencies.

envread-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,23 @@
+# Contributing
+
+Thanks for taking the time. This project keeps a small, predictable shape.
+
+## Setup
+
+```
+pip install -r requirements-dev.txt
+```
+
+## Before you open a pull request
+
+- Keep public API in `src/envread/__init__.py`; internals live in `_`-prefixed modules.
+- Add a test for the behaviour you change, and extend `tests/test_contract.py` when the
+  public API changes. Behaviour that depends on the operating system is tested in real
+  child processes with a crafted `env=` (see `tests/procs.py`), not with mocks.
+- Run `scripts/check.ps1` (format, lint, types, tests) and make sure it passes. The end
+  to end test builds a wheel and installs it into a throwaway virtual environment; skip
+  it while iterating with `pytest -m "not e2e"`.
+- Keep every source file at 200 lines or fewer.
+- One logical change per commit, imperative subject line.
+
+Open an issue first if the change is large or shifts the public API.

envread-0.2.0/IMPROVEMENTS-round.md

@@ -0,0 +1,87 @@
+# envread improvement round
+
+A ranked list of substantial, coherent improvements for this round. Every item is
+additive: the 0.1 API (`Env`, `env`, the `str`/`int`/`float`/`bool`/`list`/`json`
+getters, `EnvError`, `MissingEnvError`, `InvalidEnvError`) keeps its signatures, and
+code written against 0.1 keeps working.
+
+## Starting point
+
+0.1 read one variable at a time with six overloaded getters, so `env.int("PORT")` was
+`int` and `env.int("PORT", None)` was `int | None`. It stopped at the first problem,
+quoted every bad value in its errors (secrets included), had no way to scope names,
+no richer types, no settings object, no `.env` support and nothing to run from a
+deployment script.
+
+## Ranked improvements
+
+1. **Collect every error at once.** Deployments fail one variable at a time when a
+   reader stops at the first problem. `load()` reads every field first and raises one
+   `EnvValidationError` whose `errors` tuple and message list every missing and invalid
+   variable together.
+
+2. **A declarative settings class without metaclass magic.** `load(Settings)` fills a
+   plain (optionally frozen) dataclass: the field name upper-cased is the variable name,
+   the annotation picks the parser, a default or `X | None` makes it optional.
+   `var(name, default=, default_factory=, separator=, secret=)` is a drop-in for
+   `field()` when a field needs more. No base class, no decorator, no metaclass.
+
+3. **Secrets never leak.** A `secret=True` keyword on every getter keeps the value out
+   of the message, the `value` attribute and the exception chain (no `__cause__` or
+   `__context__` that would print it in a traceback). A `Secret` type, returned by
+   `env.secret()` and usable as a field annotation, masks itself in `str`, `repr`,
+   f-strings and dataclass reprs, compares in constant time, and refuses pickling.
+
+4. **Richer typed getters with precise overloads.** `decimal` (exact, finite only),
+   `path`, `duration` (`90`, `250ms`, `1h30m`, `1.5h` into `timedelta`), `enum` (member
+   by name in any case, or by value) and `secret`, each with the same five overloads as
+   the 0.1 getters so the static type follows the default and `required=`.
+
+5. **Settings field types beyond scalars.** `list[X]` and `tuple[X, ...]` with a
+   per-field separator and typed items, `Literal["a", "b"]` choices, `Enum`
+   subclasses, `dict[...]` as a JSON object, `Secret`, plus every scalar getter type.
+   An annotation that cannot come from a string fails fast with `TypeError`.
+
+6. **Prefix scoping.** `Env(prefix="APP_")` and `env.prefixed("DB_")` read
+   `APP_DB_HOST` from `host`; errors name the full variable, and `load()` honours the
+   reader's prefix.
+
+7. **A deployment checker CLI.** `envread check env.spec` (or `module:Class` for a
+   dataclass) validates the current environment and prints one line per variable,
+   exits 0 or 1, supports `--format json`, `--prefix`, `--env-file`,
+   `--empty-is-unset`, `--quiet` and `--show-values` (secrets stay masked).
+   `envread get NAME --type int --default 8080` prints one canonical value for shell
+   scripts. Errors go to stderr with exit code 1.
+
+8. **`.env` loading as a documented subset.** `parse_dotenv`, `read_dotenv` and
+   `load_dotenv` implement a subset of python-dotenv 1.x syntax and are tested line by
+   line against python-dotenv itself. Constructs the two common references
+   (python-dotenv and docker compose `env_file`) read differently, and anything outside
+   the subset, raise `DotenvError` naming the line instead of being guessed at.
+
+9. **Platform facts made explicit.** Empty versus unset is now a choice
+   (`empty_is_unset=True`), `raw()` and `is_set()` expose presence, case sensitivity
+   follows the platform (documented and tested in real child processes), and
+   `load_dotenv` refuses an entry Windows cannot store (`NAME=value` over 32,767
+   characters) before writing anything.
+
+10. **Boolean vocabulary aligned with boolish.** `bool` now also accepts
+    `enable`/`enabled` and `disable`/`disabled`, matching the default vocabulary of the
+    sibling library without depending on it.
+
+11. **Error quality.** `MissingEnvError` no longer prints with doubled quotes, very
+    long values are trimmed in messages (the attribute keeps them whole), JSON errors
+    report line and column, and enum errors list the valid members.
+
+12. **Ground-truth tests.** A contract test pins the complete promise of every public
+    name; real-process tests run child interpreters with a crafted `env=`; an end to end
+    test builds the wheel, installs it into a throwaway virtual environment and drives
+    the installed `envread` script.
+
+## Deliberately left out
+
+- Interpolation forms beyond `${NAME}` and `${NAME:-default}`, and multi-line quoted
+  `.env` values: the references disagree or the cost outweighs the use.
+- ISO 8601 durations: the unit form covers configuration values without a parser for
+  a second grammar.
+- `~` and variable expansion in paths: a config path should mean exactly what it says.

envread-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Javier Lianes
+
+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.

envread-0.2.0/PKG-INFO

@@ -0,0 +1,269 @@
+Metadata-Version: 2.5
+Name: envread
+Version: 0.2.0
+Summary: Typed reader for environment variables: inferred return types, settings dataclasses, .env files and a checker CLI, zero dependencies
+Project-URL: Homepage, https://lianes8studio.com
+Project-URL: Repository, https://github.com/JaviLianes8/typedenv
+Project-URL: Issues, https://github.com/JaviLianes8/typedenv/issues
+Project-URL: Changelog, https://github.com/JaviLianes8/typedenv/blob/main/CHANGELOG.md
+Project-URL: LinkedIn, https://www.linkedin.com/in/jlianes/
+Project-URL: Funding, https://buymeacoffee.com/jlianesglrs
+Author-email: Javier Lianes <javier@lianes8studio.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: 12factor,config,dotenv,env,environment,environment-variables,settings,typed
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Systems Administration
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: python-dotenv; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Requires-Dist: typing-extensions; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# envread
+
+Typed reader for environment variables with mypy-inferred return types, settings
+dataclasses, `.env` files and a checker CLI. Zero dependencies.
+
+## Install
+
+```
+pip install envread
+```
+
+## Read one variable
+
+```python
+from envread import env
+
+database_url = env.str("DATABASE_URL")  # str, raises MissingEnvError if unset
+port = env.int("PORT", 8080)  # int, the default when unset
+workers = env.int("WORKERS", None)  # int | None
+debug = env.bool("DEBUG", False)  # true/false, yes/no, on/off, 1/0, ...
+hosts = env.list("ALLOWED_HOSTS")  # split on "," and trimmed
+timeout = env.duration("TIMEOUT", None)  # "90", "250ms", "1h30m" -> timedelta
+api_key = env.secret("API_KEY")  # Secret: prints as ***
+```
+
+Every getter takes the same arguments and the static type follows the call:
+
+| call | type | when unset |
+| --- | --- | --- |
+| `env.int("X")` | `int` | raises `MissingEnvError` |
+| `env.int("X", required=True)` | `int` | raises `MissingEnvError` |
+| `env.int("X", 8080)` | `int` | `8080` |
+| `env.int("X", None)` | `int \| None` | `None` |
+| `env.int("X", required=False)` | `int \| None` | `None` |
+
+| getter | returns | accepts |
+| --- | --- | --- |
+| `str` | `str` | anything, returned as is (`""` stays `""`) |
+| `int` | `int` | base-10 integer, surrounding whitespace ignored |
+| `float` | `float` | anything `float()` accepts |
+| `bool` | `bool` | `true/false`, `yes/no`, `on/off`, `1/0`, `y/n`, `t/f`, `enable(d)/disable(d)`, any case |
+| `decimal` | `Decimal` | exact decimal; `NaN` and infinities are rejected |
+| `path` | `Path` | non-empty path, taken literally (no `~` expansion) |
+| `duration` | `timedelta` | seconds (`90`, `1.5`) or units `w d h m s ms` from largest to smallest (`1h30m`) |
+| `enum` | your `Enum` | member name in any case, or the member value as text |
+| `list` | `list[str]` | split on `separator=` (default `,`), items trimmed, `""` is `[]` |
+| `json` | `Any` | JSON, parsed by the standard library |
+| `secret` | `Secret` | anything, wrapped so it never prints |
+
+The boolean words match the default vocabulary of
+[boolish](https://pypi.org/project/boolish/), without depending on it.
+
+## Load a settings dataclass
+
+```python
+from dataclasses import dataclass, field
+from datetime import timedelta
+from typing import Literal
+
+from envread import Env, Secret, load, var
+
+
+@dataclass(frozen=True)
+class Settings:
+    database_url: Secret  # DATABASE_URL, required
+    port: int = 8080  # PORT
+    workers: int | None = None  # WORKERS, optional
+    hosts: list[str] = field(default_factory=list)
+    timeout: timedelta = timedelta(seconds=5)
+    mode: Literal["dev", "prod"] = "dev"
+    token: str = var("SERVICE_TOKEN", default="", secret=True)
+    ports: tuple[int, ...] = var(default=(), separator=";")
+
+
+settings = load(Settings)  # from os.environ
+settings = load(Settings, Env(prefix="APP_"))  # APP_DATABASE_URL, APP_PORT, ...
+```
+
+There is no base class and no metaclass: `load` reads `dataclasses.fields()` and the
+annotations. The variable name is the field name upper-cased, or `var(name=...)`. A
+field with a default, a `default_factory` or an `X | None` annotation is optional.
+Supported annotations: `str`, `int`, `float`, `bool`, `Decimal`, `Path`, `timedelta`,
+`Secret`, any `Enum`, `Literal["a", "b"]`, `dict[...]` (a JSON object), and `list[X]` or
+`tuple[X, ...]` of a scalar type. Anything else raises `TypeError` when `load` runs.
+
+`load` reads every field before raising, so one run reports every problem:
+
+```
+EnvValidationError: 3 environment variables failed validation:
+  - required environment variable 'DATABASE_URL' is not set
+  - environment variable 'PORT' is not a valid integer: 'eighty'
+  - environment variable 'MODE' is not a valid choice: 'staging': expected one of dev, prod
+```
+
+The individual errors are in `error.errors`. If you lint with ruff, add
+`extend-immutable-calls = ["envread.var"]` under `[tool.ruff.lint.flake8-bugbear]`
+so `var()` is treated like `field()`.
+
+## Secrets
+
+`secret=True` on any getter, `var(secret=True)`, or a `Secret` annotation keeps the
+value out of error messages, the error's `value` attribute (`"***"`) and the exception
+chain, so even an uncaught traceback does not show it. A `Secret` prints as `***` in
+`str`, `repr`, f-strings and dataclass reprs; call `.reveal()` where the real value is
+needed. It compares in constant time and refuses to be pickled. `secret=True` alone only
+protects errors; annotate the field as `Secret` to keep it out of the dataclass repr too.
+
+## Prefixes, empty values and presence
+
+```python
+app = Env(prefix="APP_")  # app.int("PORT") reads APP_PORT
+db = app.prefixed("DB_")  # db.str("HOST") reads APP_DB_HOST
+strict = Env(empty_is_unset=True)  # KEY= counts as unset
+env.raw("PORT")  # the unparsed string, or None
+env.is_set("PORT"), "PORT" in env  # presence
+cfg = Env({"PORT": "9090"})  # any mapping instead of os.environ
+```
+
+## Platform facts
+
+- **Names**: `os.environ` is case-insensitive on Windows (keys are stored upper-case)
+  and case-sensitive on POSIX, so `env.str("path")` finds `PATH` on Windows only. A
+  plain `dict` source is always exact.
+- **Values** are always strings; there is no `None` in the environment. A variable can
+  be set to `""`, which is different from unset unless you pass `empty_is_unset=True`.
+- **Length**: on Windows `os.environ` refuses an entry whose `NAME=value` is longer
+  than 32,767 characters, although a child process can receive longer values through
+  `subprocess` `env=`. `load_dotenv` checks this up front and raises `DotenvError`.
+
+## `.env` files
+
+```python
+from envread import load_dotenv, parse_dotenv, read_dotenv
+
+load_dotenv(".env")  # set what is not already set; returns what it set
+load_dotenv(".env", override=True)  # the file wins
+values = read_dotenv(".env")  # dict, environment untouched
+```
+
+The supported syntax is a subset of python-dotenv 1.x, tested line by line against
+python-dotenv itself:
+
+| syntax | result |
+| --- | --- |
+| blank lines, `# comment` lines | ignored |
+| `export KEY=value`, `KEY = value` | `export` and spaces around `=` are allowed |
+| `KEY=plain value  # note` | `plain value` (an inline `#` needs a space before it) |
+| `KEY='literal \n $X'` | taken literally; only `\'` and `\\` are escapes |
+| `KEY="a\tb ${X}"` | escapes `\\ \' \" \a \b \f \n \r \t \v`, then expansion |
+| `${NAME}`, `${NAME:-default}` | earlier keys, then the environment; unknown is `""` |
+| `KEY` (no `=`) | skipped |
+| `KEY=` | `""` |
+
+Expansion order follows python-dotenv: `read_dotenv` and `parse_dotenv` prefer earlier
+keys in the file, `load_dotenv` prefers the existing environment unless `override=True`.
+The default in `${NAME:-default}` applies only when `NAME` is unset. Unquoted `$NAME`
+without braces is literal.
+
+Anything else raises `DotenvError` with the file and line, never the value:
+multi-line quoted values, other `${...}` forms (`${X-d}`, `${X:?err}`, nesting), text
+after a closing quote, and `${` inside single quotes (python-dotenv expands it, docker
+compose keeps it literal). Docker compose `env_file` also expands unbraced `$NAME`
+and treats `${NAME:-default}` as "unset or empty", so files that rely on those
+compose-only behaviours read differently there.
+
+## Command line
+
+```
+envread check env.spec                     validate every variable in a spec file
+envread check myapp.settings:Settings      validate the fields of a dataclass
+envread check env.spec --env-file .env     layer a .env file under the environment
+envread check env.spec --format json       machine-readable report
+envread get PORT --type int --default 8080 print one parsed value
+envread get DEBUG --type bool              prints true or false
+```
+
+A spec file lists one variable per line as `NAME TYPE [optional] [secret]`, with types
+`str int float bool decimal path duration json secret`, `list[:SEP]` and
+`choice:A,B,C`:
+
+```
+# deployment contract
+DATABASE_URL  secret
+PORT          int       optional
+LOG_LEVEL     choice:debug,info,warning
+HOSTS         list:;
+```
+
+```
+$ envread check env.spec
+ok       DATABASE_URL  secret
+invalid  PORT          int, optional: not a valid integer: 'eighty'
+missing  LOG_LEVEL     choice: not set
+ok       HOSTS         list
+envread: 2 of 4 variables failed
+```
+
+`check` exits 0 when every variable is valid and 1 otherwise, so it gates a deploy
+script directly. Values are printed only with `--show-values`, and secrets never are.
+`--prefix`, `--env-file` and `--empty-is-unset` work on both commands; `--quiet` gives
+an exit code only. Errors go to stderr with exit code 1. `python -m envread` works the same
+as the `envread` script.
+
+## Errors
+
+`MissingEnvError` is also a `KeyError`; `InvalidEnvError`, `EnvValidationError` and
+`DotenvError` are also `ValueError`s; all of them derive from `EnvError`.
+
+## Why
+
+Reading config from the environment is a one-liner until you want the value typed, a
+missing variable to fail loudly, every failure reported in one go, secrets kept out of
+logs, and your type checker to agree with all of it. The existing options each give up
+one of those or pull in dependencies: `environs` needs `marshmallow` and
+`python-dotenv`, `environ-config` is built on `attrs`, `pydantic-settings` pulls in
+`pydantic-core`, and `typenv` depends on `python-dotenv` and has not shipped since 2021.
+
+`envread` has no runtime dependencies, ships `py.typed`, and uses `@overload` so
+`env.int("X")` is `int` and `env.int("X", None)` is `int | None` with no casts. Reach
+for it when you want typed environment access and a deploy-time check without adding a
+settings framework to the project.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Links
+
+- Website: https://lianes8studio.com
+- GitHub: https://github.com/JaviLianes8
+- LinkedIn: https://www.linkedin.com/in/jlianes/