envcaster 0.1.0__py3-none-any.whl

envcaster/__init__.py

@@ -0,0 +1,29 @@
+"""envcaster — typed, dependency-free environment variable loading.
+
+Read environment variables as the type you actually want — ``int``, ``float``,
+``bool``, ``list``, ``json``, ``Path`` — with defaults, required-checks, and
+error messages that tell you exactly which variable was wrong and why. Plus a
+tiny ``.env`` loader. Zero dependencies, pure standard library.
+
+    from envcaster import env
+
+    PORT = env.int("PORT", default=8000)
+    DEBUG = env.bool("DEBUG", default=False)
+    HOSTS = env.list("ALLOWED_HOSTS", sep=",")
+    SECRET = env.str("SECRET_KEY", required=True)
+"""
+
+from envcaster.core import CastError, Env, EnvError, MissingEnvError, env
+from envcaster.dotenv import load_dotenv, read_dotenv
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "env",
+    "Env",
+    "EnvError",
+    "MissingEnvError",
+    "CastError",
+    "load_dotenv",
+    "read_dotenv",
+]

envcaster/core.py

@@ -0,0 +1,210 @@
+"""Typed reads from the environment with defaults, requirements, and clear errors."""
+
+from __future__ import annotations
+
+import builtins
+import json as _json
+import os
+from pathlib import Path
+from typing import Any, Callable, List, Mapping, Optional, TypeVar
+
+__all__ = [
+    "Env",
+    "EnvError",
+    "MissingEnvError",
+    "CastError",
+    "env",
+]
+
+T = TypeVar("T")
+
+
+class EnvError(Exception):
+    """Base class for all envcaster errors."""
+
+
+class MissingEnvError(EnvError, KeyError):
+    """A required environment variable was not set."""
+
+    def __init__(self, name: str) -> None:
+        self.name = name
+        super().__init__(f"Required environment variable {name!r} is not set.")
+
+
+class CastError(EnvError, ValueError):
+    """An environment variable could not be cast to the requested type."""
+
+    def __init__(self, name: str, value: str, type_name: str, hint: str = "") -> None:
+        self.name = name
+        self.value = value
+        self.type_name = type_name
+        msg = f"Environment variable {name!r}={value!r} is not a valid {type_name}."
+        if hint:
+            msg += f" {hint}"
+        super().__init__(msg)
+
+
+# Sentinels — distinct from any user value (including None).
+class _Unset:
+    def __repr__(self) -> str:  # pragma: no cover - cosmetic
+        return "<unset>"
+
+
+_UNSET: Any = _Unset()
+_USE_DEFAULT: Any = object()
+
+_TRUE = {"1", "true", "t", "yes", "y", "on"}
+_FALSE = {"0", "false", "f", "no", "n", "off"}
+
+
+class Env:
+    """A typed reader over a mapping of environment variables.
+
+    By default it reads the live process environment (``os.environ``). Pass a
+    ``source`` mapping (e.g. a plain ``dict``) to read from somewhere else —
+    handy in tests. A ``prefix`` is prepended to every name you look up, so
+    ``Env(prefix="APP_").int("PORT")`` reads ``APP_PORT``.
+
+    A variable is **required unless you pass a ``default``**. Missing required
+    variables raise :class:`MissingEnvError`; bad values raise :class:`CastError`.
+    Both subclass :class:`EnvError` (and the matching builtin), so you can catch
+    broadly or narrowly.
+    """
+
+    def __init__(
+        self,
+        source: Optional[Mapping[str, str]] = None,
+        *,
+        prefix: str = "",
+    ) -> None:
+        self._source = source
+        self._prefix = prefix
+
+    # -- internals ---------------------------------------------------------
+
+    def _mapping(self) -> Mapping[str, str]:
+        # Read os.environ lazily so changes after construction are seen.
+        return os.environ if self._source is None else self._source
+
+    def _raw(self, name: str, default: Any, required: bool) -> str:
+        key = self._prefix + name
+        value = self._mapping().get(key)
+        if value is None:
+            if required or default is _UNSET:
+                raise MissingEnvError(key)
+            return _USE_DEFAULT
+        return value
+
+    # -- typed getters -----------------------------------------------------
+
+    def str(self, name: str, default: Any = _UNSET, *, required: bool = False) -> str:
+        """Return the variable as a string (the raw value, unchanged)."""
+        raw = self._raw(name, default, required)
+        return default if raw is _USE_DEFAULT else raw
+
+    def int(self, name: str, default: Any = _UNSET, *, required: bool = False) -> int:
+        """Return the variable parsed as an ``int`` (base-10, whitespace ignored)."""
+        raw = self._raw(name, default, required)
+        if raw is _USE_DEFAULT:
+            return default
+        try:
+            return int(raw.strip())
+        except ValueError:
+            raise CastError(self._prefix + name, raw, "integer") from None
+
+    def float(self, name: str, default: Any = _UNSET, *, required: bool = False) -> float:
+        """Return the variable parsed as a ``float``."""
+        raw = self._raw(name, default, required)
+        if raw is _USE_DEFAULT:
+            return default
+        try:
+            return float(raw.strip())
+        except ValueError:
+            raise CastError(self._prefix + name, raw, "float") from None
+
+    def bool(self, name: str, default: Any = _UNSET, *, required: bool = False) -> bool:
+        """Return the variable as a ``bool``.
+
+        Truthy: ``1 true t yes y on``. Falsy: ``0 false f no n off``
+        (case-insensitive). Anything else raises :class:`CastError`.
+        """
+        raw = self._raw(name, default, required)
+        if raw is _USE_DEFAULT:
+            return default
+        token = raw.strip().lower()
+        if token in _TRUE:
+            return True
+        if token in _FALSE:
+            return False
+        raise CastError(
+            self._prefix + name,
+            raw,
+            "boolean",
+            hint=f"Use one of: {', '.join(sorted(_TRUE | _FALSE))}.",
+        )
+
+    def list(
+        self,
+        name: str,
+        default: Any = _UNSET,
+        *,
+        sep: str = ",",
+        cast: Callable[[str], T] = builtins.str,  # type: ignore[assignment]
+        required: bool = False,
+    ) -> List[T]:
+        """Split the variable on ``sep`` into a list.
+
+        Items are stripped of surrounding whitespace and empty items dropped.
+        Pass ``cast`` to convert each item (e.g. ``cast=int``).
+        """
+        raw = self._raw(name, default, required)
+        if raw is _USE_DEFAULT:
+            return default
+        items = [piece.strip() for piece in raw.split(sep)]
+        items = [piece for piece in items if piece]
+        try:
+            return [cast(piece) for piece in items]
+        except (ValueError, TypeError):
+            raise CastError(self._prefix + name, raw, "list", hint="An item failed to cast.") from None
+
+    def json(self, name: str, default: Any = _UNSET, *, required: bool = False) -> Any:
+        """Parse the variable as JSON and return the resulting object."""
+        raw = self._raw(name, default, required)
+        if raw is _USE_DEFAULT:
+            return default
+        try:
+            return _json.loads(raw)
+        except _json.JSONDecodeError:
+            raise CastError(self._prefix + name, raw, "JSON") from None
+
+    def path(self, name: str, default: Any = _UNSET, *, required: bool = False) -> Path:
+        """Return the variable as a :class:`pathlib.Path` (not resolved/validated)."""
+        raw = self._raw(name, default, required)
+        if raw is _USE_DEFAULT:
+            return default
+        return Path(raw)
+
+    def cast(
+        self,
+        name: str,
+        func: Callable[[str], T],
+        default: Any = _UNSET,
+        *,
+        required: bool = False,
+    ) -> T:
+        """Apply an arbitrary ``func`` to the raw string value.
+
+        Any exception from ``func`` is wrapped in :class:`CastError`.
+        """
+        raw = self._raw(name, default, required)
+        if raw is _USE_DEFAULT:
+            return default
+        try:
+            return func(raw)
+        except Exception as exc:  # noqa: BLE001 - re-raised as CastError
+            type_name = getattr(func, "__name__", "value")
+            raise CastError(self._prefix + name, raw, type_name, hint=str(exc)) from None
+
+
+# A ready-to-use instance bound to the live process environment.
+env = Env()

envcaster/dotenv.py

@@ -0,0 +1,67 @@
+"""A tiny, dependency-free ``.env`` reader.
+
+Just enough to load a local ``.env`` in development. For complex needs
+(variable interpolation, multiline values) reach for python-dotenv.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Dict, Union
+
+__all__ = ["read_dotenv", "load_dotenv"]
+
+_PathLike = Union[str, "os.PathLike[str]"]
+
+
+def _unquote(value: str) -> str:
+    value = value.strip()
+    if len(value) >= 2 and value[0] == value[-1] and value[0] in ("'", '"'):
+        return value[1:-1]
+    return value
+
+
+def read_dotenv(path: _PathLike = ".env") -> Dict[str, str]:
+    """Parse a ``.env`` file into a dict. Returns ``{}`` if the file is absent.
+
+    Supports ``KEY=value``, ``export KEY=value``, ``#`` comments, blank lines,
+    and single/double-quoted values. Does **not** touch ``os.environ``.
+    """
+    file = Path(path)
+    if not file.is_file():
+        return {}
+
+    result: Dict[str, str] = {}
+    for raw_line in file.read_text(encoding="utf-8").splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line.startswith("export "):
+            line = line[len("export ") :].lstrip()
+        if "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        key = key.strip()
+        if not key:
+            continue
+        # Strip an inline comment only when the value is not quoted.
+        stripped = value.strip()
+        if stripped[:1] not in ("'", '"') and " #" in value:
+            value = value.split(" #", 1)[0]
+        result[key] = _unquote(value)
+    return result
+
+
+def load_dotenv(path: _PathLike = ".env", *, override: bool = False) -> Dict[str, str]:
+    """Read a ``.env`` file and inject its values into ``os.environ``.
+
+    By default existing environment variables win (``override=False``), so real
+    environment configuration is never clobbered by the file. Returns the dict
+    that was parsed from the file.
+    """
+    values = read_dotenv(path)
+    for key, value in values.items():
+        if override or key not in os.environ:
+            os.environ[key] = value
+    return values

envcaster-0.1.0.dist-info/METADATA

@@ -0,0 +1,207 @@
+Metadata-Version: 2.4
+Name: envcaster
+Version: 0.1.0
+Summary: Typed, dependency-free environment variable loading: read env vars as int/bool/list/json/Path with defaults, required-checks, and clear errors.
+Author: YoungAlpaccino
+License: MIT
+Project-URL: Homepage, https://github.com/YoungAlpaccino/envcast
+Project-URL: Repository, https://github.com/YoungAlpaccino/envcast
+Project-URL: Issues, https://github.com/YoungAlpaccino/envcast/issues
+Keywords: env,environment,config,dotenv,settings,12factor,typed,configuration
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# envcaster ⚙️
+
+> Read environment variables as the **type you actually want** — `int`, `bool`, `list`, `json`, `Path` — with defaults, required-checks, and errors that name the offending variable. Zero dependencies, pure standard library.
+
+[![CI](https://github.com/YoungAlpaccino/envcast/actions/workflows/ci.yml/badge.svg)](https://github.com/YoungAlpaccino/envcast/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/envcaster.svg)](https://pypi.org/project/envcaster/)
+[![Python](https://img.shields.io/pypi/pyversions/envcaster.svg)](https://pypi.org/project/envcaster/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+`os.environ` only ever gives you strings. So every project grows the same little
+pile of `int(os.environ.get("PORT", "8000"))` and hand-rolled truthy checks that
+quietly treat `"False"` as `True`. **envcaster** is that pile, done once and done right.
+
+- 🪶 **Zero required dependencies** — pure standard library.
+- 🎯 **Typed getters** — `str · int · float · bool · list · json · path` (+ custom `cast`).
+- 🧯 **Loud, precise errors** — missing or malformed values tell you *which* variable and *why*.
+- 🧪 **Fully tested** across Python 3.9–3.12.
+- 🧩 **Drop-in `.env` loader** that never clobbers real environment config.
+
+---
+
+## Install
+
+```bash
+pip install envcaster
+```
+
+---
+
+## Quick start
+
+```python
+from envcaster import env
+
+PORT    = env.int("PORT", default=8000)
+DEBUG   = env.bool("DEBUG", default=False)
+HOSTS   = env.list("ALLOWED_HOSTS", sep=",")          # ["a", "b"] from "a,b"
+TIMEOUT = env.float("TIMEOUT", default=1.5)
+SECRET  = env.str("SECRET_KEY", required=True)         # raises if not set
+DATA    = env.path("DATA_DIR", default="/var/data")   # -> pathlib.Path
+FLAGS   = env.json("FEATURE_FLAGS", default={})        # parsed JSON
+```
+
+> **A variable is required unless you give it a `default`.** Missing required
+> variables raise `MissingEnvError`; bad values raise `CastError`. Both subclass
+> `EnvError` — catch broadly or narrowly.
+
+---
+
+## Usage
+
+### Booleans that actually behave
+
+```python
+env.bool("DEBUG")     # 1 true t yes y on  -> True   (case-insensitive)
+                      # 0 false f no n off -> False
+                      # anything else      -> CastError
+```
+
+No more `bool("False") == True` bugs.
+
+### Lists (and lists of other types)
+
+```python
+env.list("ALLOWED_HOSTS")                 # "a, b ,, c" -> ["a", "b", "c"]  (trims, drops empties)
+env.list("PORTS", sep=":", cast=int)      # "80:443"    -> [80, 443]
+env.list("TAGS", default=[])              # missing     -> []
+```
+
+### JSON and paths
+
+```python
+env.json("LIMITS")          # '{"rpm": 60}' -> {"rpm": 60}
+env.path("LOG_DIR")         # "/var/log"    -> PosixPath("/var/log")
+```
+
+### Anything else — bring your own cast
+
+```python
+from decimal import Decimal
+
+env.cast("PRICE", Decimal)                 # "9.99" -> Decimal("9.99")
+env.cast("COLOR", lambda v: int(v, 16))    # "ff0000" -> 16711680
+# exceptions from your function are wrapped in CastError, naming the variable
+```
+
+### Scoped readers with a prefix
+
+```python
+from envcaster import Env
+
+app = Env(prefix="APP_")
+app.int("PORT")        # reads APP_PORT
+app.bool("DEBUG")      # reads APP_DEBUG
+```
+
+### Read from somewhere other than `os.environ`
+
+```python
+cfg = Env(source={"PORT": "9000"})   # great for tests — no global state
+cfg.int("PORT")                       # 9000
+```
+
+### Load a `.env` file (no dependency)
+
+```python
+from envcaster import load_dotenv, env
+
+load_dotenv()                  # reads ./.env into os.environ (won't override real env vars)
+load_dotenv(".env.local", override=True)
+
+PORT = env.int("PORT")
+
+# Or parse without touching the environment:
+from envcaster import read_dotenv
+values = read_dotenv(".env")   # -> {"PORT": "8000", ...}
+```
+
+Handles `KEY=value`, `export KEY=value`, `# comments`, and quoted values. For
+interpolation or multiline values, use [python-dotenv](https://github.com/theskumar/python-dotenv).
+
+---
+
+## API reference
+
+| Call | Returns | Notes |
+|---|---|---|
+| `env.str(name, default=…, required=False)` | `str` | The raw value, unchanged |
+| `env.int(name, …)` | `int` | Base-10, whitespace stripped |
+| `env.float(name, …)` | `float` | |
+| `env.bool(name, …)` | `bool` | `1/true/t/yes/y/on` ↔ `0/false/f/no/n/off` |
+| `env.list(name, …, sep=",", cast=str)` | `list` | Trims items, drops empties, per-item `cast` |
+| `env.json(name, …)` | `Any` | `json.loads` of the value |
+| `env.path(name, …)` | `pathlib.Path` | Not resolved/validated |
+| `env.cast(name, func, …)` | `Any` | Apply any callable; errors wrapped in `CastError` |
+| `Env(source=None, prefix="")` | `Env` | Custom mapping and/or name prefix |
+| `read_dotenv(path=".env")` | `dict` | Parse a `.env` file; `{}` if absent |
+| `load_dotenv(path=".env", override=False)` | `dict` | Inject into `os.environ` |
+
+**Errors:** `EnvError` (base) · `MissingEnvError` (also `KeyError`) · `CastError` (also `ValueError`).
+
+---
+
+## Why not just `os.environ`?
+
+```python
+# Before
+import os
+PORT  = int(os.environ.get("PORT", "8000"))
+DEBUG = os.environ.get("DEBUG", "false").lower() in ("1", "true", "yes")
+HOSTS = [h.strip() for h in os.environ.get("ALLOWED_HOSTS", "").split(",") if h.strip()]
+
+# After
+from envcaster import env
+PORT  = env.int("PORT", default=8000)
+DEBUG = env.bool("DEBUG", default=False)
+HOSTS = env.list("ALLOWED_HOSTS", default=[])
+```
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/YoungAlpaccino/envcast
+cd envcast
+pip install -e ".[dev]"
+pytest          # run tests
+ruff check .    # lint
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](./LICENSE). Use it anywhere, including commercially.

envcaster-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+envcaster/__init__.py,sha256=L2yif83QketIcGkbhtAr7s2DC4kGLvttCDWCeH_oqVo,875
+envcaster/core.py,sha256=gyL46ehOyABaa86suU_yLeIfflosOSBxNGwlYe13D9s,7168
+envcaster/dotenv.py,sha256=IvFRxXRkx7e9-DIg87n9KF1nlIlMBuloX24-U6o9hIA,2173
+envcaster/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+envcaster-0.1.0.dist-info/licenses/LICENSE,sha256=I6OFRouQilM7XAjOq3RJp8glXpwdnQZZBsrJ5L6Ctso,1071
+envcaster-0.1.0.dist-info/METADATA,sha256=bDAUzE8gDkb2nYvikLQ121U3Ixoam-_-2CeNm6PjZSI,7282
+envcaster-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+envcaster-0.1.0.dist-info/top_level.txt,sha256=0UJS2e59c1eyhYh2jJzyl2fmmR22GHvpJrArXPD64nI,10
+envcaster-0.1.0.dist-info/RECORD,,

envcaster-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

envcaster-0.1.0.dist-info/licenses/LICENSE

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

envcaster-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+envcaster