tidyenv 0.1.0__py3-none-any.whl

tidyenv/__init__.py

@@ -0,0 +1,13 @@
+"""Typed environment variables with friendly errors and built-in .env support."""
+
+from tidyenv._dotenv import parse_dotenv
+from tidyenv._env import Env, EnvError, Problem
+
+__all__ = ["Env", "EnvError", "Problem", "env", "parse_dotenv"]
+__version__ = "0.1.0"
+
+# Show errors as tidyenv.EnvError, not tidyenv._env.EnvError.
+for _cls in (Env, EnvError, Problem):
+    _cls.__module__ = __name__
+
+env = Env()

tidyenv/_dotenv.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import re
+
+# The value keeps its leading whitespace: `A= # note` is an empty value plus a comment.
+_LINE = re.compile(r"^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_.]*)\s*=(.*?)\s*$")
+_ESCAPES = {"n": "\n", "r": "\r", "t": "\t", '"': '"', "\\": "\\"}
+
+
+def parse_dotenv(text: str) -> dict[str, str]:
+    """Parse the contents of a ``.env`` file into a dict.
+
+    Supports ``KEY=value``, ``export KEY=value``, ``#`` comments, blank lines,
+    'single quotes' (taken literally) and "double quotes" (with ``\\n``, ``\\t``,
+    ``\\"`` and ``\\\\`` escapes). Values must fit on one line.
+    Raises ``ValueError`` naming the bad line.
+    """
+    values: dict[str, str] = {}
+    for lineno, line in enumerate(text.splitlines(), start=1):
+        if not line.strip() or line.lstrip().startswith("#"):
+            continue
+        match = _LINE.match(line)
+        if match is None:
+            raise ValueError(f"line {lineno}: expected KEY=VALUE")
+        key, raw = match.groups()
+        try:
+            values[key] = _value(raw)
+        except ValueError as exc:
+            raise ValueError(f"line {lineno}: {exc}") from None
+    return values
+
+
+def _value(raw: str) -> str:
+    value = raw.lstrip()
+    if value[:1] in ("'", '"'):
+        quote = value[0]
+        end = _closing_quote(value, quote)
+        rest = value[end + 1 :].strip()
+        if rest and not rest.startswith("#"):
+            raise ValueError(f"unexpected text after closing quote: {rest!r}")
+        body = value[1:end]
+        if quote == "'":
+            return body
+        return re.sub(r"\\(.)", lambda m: _ESCAPES.get(m.group(1), m.group(0)), body)
+    # Unquoted: an inline comment needs whitespace before the '#'; the space after
+    # '=' counts, so `A= # note` is empty while `A=#x` is the literal '#x'.
+    return re.split(r"\s+#", raw, maxsplit=1)[0].strip()
+
+
+def _closing_quote(raw: str, quote: str) -> int:
+    i = 1
+    while i < len(raw):
+        if raw[i] == "\\" and quote == '"':
+            i += 2
+            continue
+        if raw[i] == quote:
+            return i
+        i += 1
+    raise ValueError(f"missing closing {quote}")

tidyenv/_env.py

@@ -0,0 +1,322 @@
+from __future__ import annotations
+
+import json as _json
+import math
+import os
+from collections.abc import Callable, Iterator, Mapping, Sequence
+from contextlib import contextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, TypeVar, overload
+
+from tidyenv._dotenv import parse_dotenv
+
+T = TypeVar("T")
+U = TypeVar("U")
+
+# Env has methods named str/int/list/...; these aliases keep the builtins reachable.
+_str = str
+_int = int
+_float = float
+_bool = bool
+_list = list
+
+_MISSING: Any = object()
+_TRUE = {"1", "true", "yes", "y", "on"}
+_FALSE = {"0", "false", "no", "n", "off"}
+
+
+@dataclass(frozen=True)
+class Problem:
+    """One thing that is wrong with the environment."""
+
+    name: str
+    message: str
+
+    def __str__(self) -> str:
+        return f"{self.name}: {self.message}"
+
+
+class EnvError(Exception):
+    """Raised when one or more environment variables are missing or invalid."""
+
+    def __init__(self, problems: Sequence[Problem]) -> None:
+        self.problems = list(problems)
+        lines = "\n".join(f"  - {p}" for p in self.problems)
+        noun = "problem" if len(self.problems) == 1 else "problems"
+        super().__init__(f"{len(self.problems)} environment {noun}:\n{lines}")
+
+
+class Env:
+    """Reads typed values from the environment.
+
+    Each reader raises :class:`EnvError` right away, unless it runs inside
+    :meth:`collect`, which gathers every problem and raises once at the end.
+    """
+
+    def __init__(self, environ: Mapping[_str, _str] | None = None, prefix: _str = "") -> None:
+        self._environ = environ
+        self.prefix = prefix
+        self._dotenv: dict[_str, _str] = {}
+        # Per thread / async task, so a collect() in one never swallows another's errors.
+        self._pending: ContextVar[_list[Problem] | None] = ContextVar(
+            "tidyenv_pending", default=None
+        )
+
+    @property
+    def environ(self) -> Mapping[_str, _str]:
+        return os.environ if self._environ is None else self._environ
+
+    def read_dotenv(
+        self, path: _str | os.PathLike[_str] = ".env", *, required: _bool = False
+    ) -> Env:
+        """Use values from a ``.env`` file for variables the environment doesn't set.
+
+        Real environment variables always win. A missing file is skipped unless
+        ``required=True``. When several files are read, later ones override
+        earlier ones. Nothing is written to ``os.environ``.
+        Returns ``self``, so ``env = Env().read_dotenv()`` works.
+        """
+        file = Path(path)
+        if not file.exists():
+            if required:
+                raise EnvError([Problem(_str(file), "file not found")])
+            return self
+        if not file.is_file():
+            raise EnvError([Problem(_str(file), "not a file")])
+        try:
+            # utf-8-sig drops the BOM that some Windows editors add.
+            text = file.read_text(encoding="utf-8-sig")
+        except UnicodeDecodeError:
+            raise EnvError([Problem(_str(file), "not valid UTF-8")]) from None
+        except OSError as exc:
+            raise EnvError([Problem(_str(file), exc.strerror or _str(exc))]) from None
+        try:
+            self._dotenv.update(parse_dotenv(text))
+        except ValueError as exc:
+            raise EnvError([Problem(_str(file), _str(exc))]) from None
+        return self
+
+    @contextmanager
+    def collect(self) -> Iterator[Env]:
+        """Gather problems from every read inside the block, then raise them together.
+
+        Failed reads return ``None`` inside the block, so don't use those
+        values until the block has exited cleanly.
+        """
+        token = self._pending.set([])
+        try:
+            yield self
+            problems = self._pending.get()
+        finally:
+            self._pending.reset(token)
+        if problems:
+            raise EnvError(problems)
+
+    # -- readers ---------------------------------------------------------
+    # Each reader returns its type, or the type of `default` when one is given.
+
+    @overload
+    def str(self, name: _str, *, secret: _bool = ...) -> _str: ...
+    @overload
+    def str(self, name: _str, default: T, *, secret: _bool = ...) -> _str | T: ...
+    def str(self, name: _str, default: Any = _MISSING, *, secret: _bool = False) -> Any:
+        """Read a string. Values are stripped; an empty value counts as missing."""
+        return self._read(name, default, lambda raw: raw, secret=secret)
+
+    @overload
+    def int(self, name: _str, *, secret: _bool = ...) -> _int: ...
+    @overload
+    def int(self, name: _str, default: T, *, secret: _bool = ...) -> _int | T: ...
+    def int(self, name: _str, default: Any = _MISSING, *, secret: _bool = False) -> Any:
+        """Read an integer, e.g. ``8000`` or ``1_000``."""
+        return self._read(name, default, _parse_int, secret=secret)
+
+    @overload
+    def float(self, name: _str, *, secret: _bool = ...) -> _float: ...
+    @overload
+    def float(self, name: _str, default: T, *, secret: _bool = ...) -> _float | T: ...
+    def float(self, name: _str, default: Any = _MISSING, *, secret: _bool = False) -> Any:
+        """Read a number, e.g. ``0.25``."""
+        return self._read(name, default, _parse_float, secret=secret)
+
+    @overload
+    def bool(self, name: _str) -> _bool: ...
+    @overload
+    def bool(self, name: _str, default: T) -> _bool | T: ...
+    def bool(self, name: _str, default: Any = _MISSING) -> Any:
+        """Read a boolean: 1/true/yes/y/on or 0/false/no/n/off, in any case."""
+        return self._read(name, default, _parse_bool)
+
+    @overload
+    def list(self, name: _str, *, sep: _str = ..., secret: _bool = ...) -> _list[_str]: ...
+    @overload
+    def list(
+        self, name: _str, default: T, *, sep: _str = ..., secret: _bool = ...
+    ) -> _list[_str] | T: ...
+    @overload
+    def list(
+        self, name: _str, *, sep: _str = ..., of: Callable[[_str], U], secret: _bool = ...
+    ) -> _list[U]: ...
+    @overload
+    def list(
+        self,
+        name: _str,
+        default: T,
+        *,
+        sep: _str = ...,
+        of: Callable[[_str], U],
+        secret: _bool = ...,
+    ) -> _list[U] | T: ...
+    def list(
+        self,
+        name: _str,
+        default: Any = _MISSING,
+        *,
+        sep: _str = ",",
+        of: Callable[[_str], Any] = _str,
+        secret: _bool = False,
+    ) -> Any:
+        """Read a separated list, e.g. ``a, b, c``. Items are stripped; blanks dropped.
+
+        ``of`` converts each item, e.g. ``of=int``. ``int``, ``float`` and ``bool``
+        use the same rules as the matching readers, so ``of=bool`` understands ``no``.
+        """
+        known = of in _ITEM_PARSERS
+        convert = _ITEM_PARSERS.get(of, of)
+
+        def parse(raw: _str) -> _list[Any]:
+            items = [item.strip() for item in raw.split(sep)]
+            values = []
+            for number, item in enumerate((item for item in items if item), start=1):
+                try:
+                    values.append(convert(item))
+                except Exception as exc:
+                    label = f"item {number}" if secret else f"item {number} ({item!r})"
+                    raise ValueError(f"{label}: {_item_error(exc, known, secret)}") from None
+            return values
+
+        return self._read(name, default, parse, secret=secret)
+
+    @overload
+    def choice(self, name: _str, choices: Sequence[_str]) -> _str: ...
+    @overload
+    def choice(self, name: _str, choices: Sequence[_str], default: T) -> _str | T: ...
+    def choice(self, name: _str, choices: Sequence[_str], default: Any = _MISSING) -> Any:
+        """Read a string that must be one of ``choices``."""
+
+        def parse(raw: _str) -> _str:
+            if raw not in choices:
+                raise ValueError(f"expected one of {', '.join(choices)}")
+            return raw
+
+        return self._read(name, default, parse)
+
+    @overload
+    def path(self, name: _str, *, must_exist: _bool = ...) -> Path: ...
+    @overload
+    def path(self, name: _str, default: T, *, must_exist: _bool = ...) -> Path | T: ...
+    def path(self, name: _str, default: Any = _MISSING, *, must_exist: _bool = False) -> Any:
+        """Read a filesystem path, with ``~`` expanded."""
+
+        def parse(raw: _str) -> Path:
+            p = Path(raw).expanduser()
+            if must_exist and not p.exists():
+                raise ValueError("path does not exist")
+            return p
+
+        return self._read(name, default, parse)
+
+    def json(self, name: _str, default: Any = _MISSING, *, secret: _bool = False) -> Any:
+        """Read a JSON value, e.g. ``{"a": 1}``."""
+        return self._read(name, default, _parse_json, secret=secret)
+
+    # -- internals -------------------------------------------------------
+
+    def _read(
+        self,
+        name: _str,
+        default: Any,
+        parse: Callable[[_str], Any],
+        *,
+        secret: _bool = False,
+    ) -> Any:
+        key = self.prefix + name
+        raw = self.environ.get(key)
+        if raw is None:
+            raw = self._dotenv.get(key)
+        if raw is None or raw.strip() == "":
+            if default is not _MISSING:
+                return default
+            return self._fail(key, "is not set")
+        try:
+            return parse(raw.strip())
+        except (ValueError, TypeError) as exc:
+            shown = "***" if secret else repr(raw)
+            return self._fail(key, f"{exc} (got {shown})")
+
+    def _fail(self, key: _str, message: _str) -> None:
+        problem = Problem(key, message)
+        pending = self._pending.get()
+        if pending is None:
+            raise EnvError([problem])
+        pending.append(problem)
+        return None
+
+
+def _parse_int(raw: str) -> int:
+    try:
+        return int(raw)  # int() already accepts 1_000 but rejects 1__0 and _1
+    except ValueError:
+        raise ValueError("expected an integer") from None
+
+
+def _parse_float(raw: str) -> float:
+    try:
+        value = float(raw)
+    except ValueError:
+        raise ValueError("expected a number") from None
+    if not math.isfinite(value):
+        raise ValueError("expected a finite number")
+    return value
+
+
+def _parse_bool(raw: str) -> bool:
+    value = raw.lower()
+    if value in _TRUE:
+        return True
+    if value in _FALSE:
+        return False
+    raise ValueError("expected true/false, yes/no, on/off or 1/0")
+
+
+def _parse_json(raw: str) -> Any:
+    try:
+        return _json.loads(raw)
+    except _json.JSONDecodeError as exc:
+        raise ValueError(f"invalid JSON: {exc.msg}") from None
+
+
+def _parse_str(raw: str) -> str:
+    return raw
+
+
+# Converters for env.list(of=...) that get the readers' rules and friendly messages.
+_ITEM_PARSERS: dict[Callable[[str], Any], Callable[[str], Any]] = {
+    str: _parse_str,
+    int: _parse_int,
+    float: _parse_float,
+    bool: _parse_bool,
+}
+
+
+def _item_error(exc: Exception, known: bool, secret: bool) -> str:
+    """Describe why ``of`` rejected a list item without leaking a secret value."""
+    if known:
+        return str(exc)  # our own messages never contain the value
+    if secret:
+        return "invalid value"
+    if isinstance(exc, (ValueError, TypeError)):
+        return str(exc)
+    return f"{type(exc).__name__}: {exc}"

tidyenv-0.1.0.dist-info/METADATA

@@ -0,0 +1,156 @@
+Metadata-Version: 2.5
+Name: tidyenv
+Version: 0.1.0
+Summary: Typed environment variables with friendly errors and built-in .env support.
+Project-URL: Homepage, https://github.com/LenaBarretta/tidyenv
+Project-URL: Issues, https://github.com/LenaBarretta/tidyenv/issues
+Author-email: Elena Raikova <lenabarretta@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: 12-factor,config,env,environment,settings
+Classifier: Development Status :: 3 - Alpha
+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.9
+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: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/LenaBarretta/tidyenv/main/docs/logo.png" alt="tidyenv logo" width="160">
+</p>
+
+# tidyenv
+
+[![PyPI](https://img.shields.io/pypi/v/tidyenv)](https://pypi.org/project/tidyenv/)
+[![Python](https://img.shields.io/pypi/pyversions/tidyenv)](https://pypi.org/project/tidyenv/)
+[![CI](https://github.com/LenaBarretta/tidyenv/actions/workflows/ci.yml/badge.svg)](https://github.com/LenaBarretta/tidyenv/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**Typed environment variables with friendly errors.** Built-in `.env` support. Zero dependencies.
+
+```python
+from tidyenv import env
+
+PORT = env.int("PORT", default=8000)
+DEBUG = env.bool("DEBUG", default=False)
+HOSTS = env.list("ALLOWED_HOSTS", default=["localhost"])
+DATABASE_URL = env.str("DATABASE_URL")
+```
+
+Each line converts the type, applies the default, and if something is wrong, says exactly what:
+
+```text
+tidyenv.EnvError: 1 environment problem:
+  - PORT: expected an integer (got 'eighty')
+```
+
+## Why
+
+| | Plain `os.environ` | tidyenv |
+| --- | --- | --- |
+| Number with a default | `int(os.environ.get("PORT", "8000"))` | `env.int("PORT", default=8000)` |
+| Bad number | `ValueError: invalid literal for int() with base 10: 'eighty'` (which variable?) | `PORT: expected an integer (got 'eighty')` |
+| Missing variable | `KeyError: 'DB_URL'` | `DB_URL: is not set` |
+| Empty value `DB_URL=` | silently `""` | treated as not set |
+| Boolean | `os.environ.get("DEBUG", "").lower() in ("1", "true", "yes")`, and a typo like `ture` silently means `False` | `env.bool("DEBUG", default=False)`, and `ture` is an error |
+| List | `[h.strip() for h in os.environ.get("HOSTS", "").split(",") if h.strip()]` | `env.list("HOSTS")` |
+| List of numbers | the same, plus `int()` on every item | `env.list("PORTS", of=int)` |
+| One of several values | `if mode not in ("dev", "prod"): raise ...` | `env.choice("MODE", ["dev", "prod"])` |
+| Secrets in errors | the value ends up in your logs | `secret=True` shows `***` |
+| `.env` file | `pip install python-dotenv` + `load_dotenv()` | `env.read_dotenv()`, nothing to install |
+| Types for mypy / IDE | `str \| None`, cast it yourself | `env.int` returns `int` |
+| Several broken variables | crash, fix, redeploy, crash on the next one | `env.collect()` lists them all at once |
+
+One line per variable, and every error names the variable and says what is wrong with it.
+
+## Install
+
+```bash
+pip install tidyenv
+```
+
+Python 3.9+.
+
+## Usage
+
+| Reader | Example value | Returns |
+| --- | --- | --- |
+| `env.str(name)` | `hello` | `str` (stripped) |
+| `env.int(name)` | `8000`, `1_000` | `int` |
+| `env.float(name)` | `0.25` | `float` (`nan` and `inf` are rejected) |
+| `env.bool(name)` | `true/false`, `yes/no`, `on/off`, `1/0`, any case | `bool` |
+| `env.list(name, sep=",", of=str)` | `a, b, c` | `list` (use `of=int` to convert items; `int`, `float` and `bool` follow the rules above) |
+| `env.choice(name, choices)` | `prod` | `str` that must be in `choices` |
+| `env.path(name, must_exist=False)` | `~/data` | `pathlib.Path` with `~` expanded |
+| `env.json(name)` | `{"a": 1}` | parsed JSON |
+
+Every reader takes an optional `default`. Without one, a missing or empty variable is
+an error. With one, the default is returned instead, and type checkers know the result
+is `int | <type of default>`.
+
+### `.env` files
+
+No need for `python-dotenv`:
+
+```python
+env.read_dotenv()  # reads ./.env if it exists
+env.read_dotenv("config/dev.env", required=True)
+```
+
+Real environment variables always win over the file, and nothing is written to
+`os.environ`. When you read several files, later ones override earlier ones.
+Supported syntax: `KEY=value`, `export KEY=value`, `# comments`,
+`'single quotes'` (literal) and `"double quotes"` (with `\n`, `\t`, `\"` escapes).
+Each value must fit on one line; for a multi-line value such as a PEM key, write
+`\n` inside double quotes.
+Need just the parser? `tidyenv.parse_dotenv(text)` returns a `dict`.
+
+### All errors at once (optional)
+
+By default the first bad variable raises `EnvError`. If you'd rather see every
+problem in one go, wrap your reads in `env.collect()`:
+
+```python
+with env.collect():
+    PORT = env.int("PORT", default=8000)
+    DATABASE_URL = env.str("DATABASE_URL")
+    API_KEY = env.str("API_KEY", secret=True)
+```
+
+```text
+tidyenv.EnvError: 3 environment problems:
+  - PORT: expected an integer (got 'eighty')
+  - DATABASE_URL: is not set
+  - API_KEY: is not set
+```
+
+Failed reads return `None` inside the block, so only use the values after it exits.
+
+### More
+
+**Secrets.** Pass `secret=True` and the raw value is shown as `***` in error messages,
+including errors about single `env.list` items.
+
+**Prefixes and custom sources.** Build your own reader:
+
+```python
+from tidyenv import Env
+
+env = Env(prefix="MYAPP_")  # reads MYAPP_PORT for env.int("PORT")
+test_env = Env(environ={"PORT": "1"})  # any mapping, handy in tests
+```
+
+**Handling errors.** `EnvError.problems` is a list of `Problem(name, message)`, so you
+can print them your own way.
+
+## License
+
+MIT

tidyenv-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+tidyenv/__init__.py,sha256=1EGuoTp0hMJdIZv9bllA7jzphFl0JiU9-kq_sfRn7Mc,404
+tidyenv/_dotenv.py,sha256=qqOUfLt4BX8OQ5HMi3UiiioSBKaSkl-usmnMfCCZd9c,2158
+tidyenv/_env.py,sha256=oeGQKjrADXefMhuxQTt3RgO4jXFoFwCdcOLTOoDxBUI,11256
+tidyenv/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tidyenv-0.1.0.dist-info/METADATA,sha256=G-fp19rTU9Ah-84idpOV-e3Uk7wIKwzi_n-J_3HkrLs,6192
+tidyenv-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+tidyenv-0.1.0.dist-info/licenses/LICENSE,sha256=KHfqCKAIyFnUFdMWTerpafhQcS240iaDuPMq3w_J67M,1070
+tidyenv-0.1.0.dist-info/RECORD,,

tidyenv-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

tidyenv-0.1.0.dist-info/licenses/LICENSE

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