envcaster 0.1.0__tar.gz

envcaster-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,176 @@
+# 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/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "envcaster"
+version = "0.1.0"
+description = "Typed, dependency-free environment variable loading: read env vars as int/bool/list/json/Path with defaults, required-checks, and clear errors."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "YoungAlpaccino" }]
+keywords = ["env", "environment", "config", "dotenv", "settings", "12factor", "typed", "configuration"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "ruff", "build", "twine"]
+
+[project.urls]
+Homepage = "https://github.com/YoungAlpaccino/envcast"
+Repository = "https://github.com/YoungAlpaccino/envcast"
+Issues = "https://github.com/YoungAlpaccino/envcast/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+envcaster = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100

envcaster-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

envcaster-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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/src/envcaster.egg-info/PKG-INFO

@@ -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/src/envcaster.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+src/envcaster/__init__.py
+src/envcaster/core.py
+src/envcaster/dotenv.py
+src/envcaster/py.typed
+src/envcaster.egg-info/PKG-INFO
+src/envcaster.egg-info/SOURCES.txt
+src/envcaster.egg-info/dependency_links.txt
+src/envcaster.egg-info/requires.txt
+src/envcaster.egg-info/top_level.txt
+tests/test_core.py
+tests/test_dotenv.py

envcaster-0.1.0/src/envcaster.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

envcaster-0.1.0/src/envcaster.egg-info/requires.txt

@@ -0,0 +1,6 @@
+
+[dev]
+pytest>=7
+ruff
+build
+twine

envcaster-0.1.0/src/envcaster.egg-info/top_level.txt

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

envcaster-0.1.0/tests/test_core.py

@@ -0,0 +1,151 @@
+import json
+
+import pytest
+
+from envcaster import CastError, Env, MissingEnvError
+
+
+def make(**values):
+    return Env(source=dict(values))
+
+
+# -- str ------------------------------------------------------------------
+
+
+def test_str_present_and_default():
+    e = make(NAME="alice")
+    assert e.str("NAME") == "alice"
+    assert e.str("MISSING", default="fallback") == "fallback"
+
+
+def test_empty_string_is_a_value_not_missing():
+    e = make(NAME="")
+    assert e.str("NAME") == ""
+
+
+# -- int / float ----------------------------------------------------------
+
+
+def test_int_parses_and_strips_whitespace():
+    assert make(PORT="  8000 ").int("PORT") == 8000
+
+
+def test_int_bad_value_raises_casterror_with_name():
+    with pytest.raises(CastError) as exc:
+        make(PORT="abc").int("PORT")
+    assert exc.value.name == "PORT"
+
+
+def test_float_parses():
+    assert make(RATE="1.5").float("RATE") == 1.5
+
+
+# -- bool -----------------------------------------------------------------
+
+
+@pytest.mark.parametrize("raw", ["1", "true", "TRUE", "t", "yes", "Y", "on"])
+def test_bool_truthy(raw):
+    assert make(FLAG=raw).bool("FLAG") is True
+
+
+@pytest.mark.parametrize("raw", ["0", "false", "F", "no", "n", "OFF"])
+def test_bool_falsy(raw):
+    assert make(FLAG=raw).bool("FLAG") is False
+
+
+def test_bool_invalid_raises():
+    with pytest.raises(CastError):
+        make(FLAG="maybe").bool("FLAG")
+
+
+def test_bool_default():
+    assert make().bool("FLAG", default=False) is False
+
+
+# -- list -----------------------------------------------------------------
+
+
+def test_list_splits_strips_and_drops_empty():
+    e = make(HOSTS="a, b ,, c")
+    assert e.list("HOSTS") == ["a", "b", "c"]
+
+
+def test_list_custom_sep_and_cast():
+    e = make(NUMS="1|2|3")
+    assert e.list("NUMS", sep="|", cast=int) == [1, 2, 3]
+
+
+def test_list_cast_failure_raises():
+    with pytest.raises(CastError):
+        make(NUMS="1,x,3").list("NUMS", cast=int)
+
+
+def test_list_default():
+    assert make().list("HOSTS", default=[]) == []
+
+
+# -- json -----------------------------------------------------------------
+
+
+def test_json_parses_object():
+    e = make(CONF=json.dumps({"a": 1, "b": [2, 3]}))
+    assert e.json("CONF") == {"a": 1, "b": [2, 3]}
+
+
+def test_json_invalid_raises():
+    with pytest.raises(CastError):
+        make(CONF="{not json}").json("CONF")
+
+
+# -- path -----------------------------------------------------------------
+
+
+def test_path_returns_pathlib():
+    from pathlib import Path
+
+    assert make(DIR="/tmp/x").path("DIR") == Path("/tmp/x")
+
+
+# -- cast -----------------------------------------------------------------
+
+
+def test_custom_cast():
+    e = make(COLOR="ff0000")
+    assert e.cast("COLOR", lambda v: int(v, 16)) == 0xFF0000
+
+
+def test_custom_cast_wraps_errors():
+    with pytest.raises(CastError):
+        make(COLOR="zzz").cast("COLOR", lambda v: int(v, 16))
+
+
+# -- required / missing ---------------------------------------------------
+
+
+def test_missing_without_default_raises():
+    with pytest.raises(MissingEnvError):
+        make().str("SECRET")
+
+
+def test_required_true_raises_even_with_default():
+    with pytest.raises(MissingEnvError):
+        make().str("SECRET", default="x", required=True)
+
+
+def test_missing_error_is_keyerror_subclass():
+    assert issubclass(MissingEnvError, KeyError)
+
+
+# -- prefix & live os.environ --------------------------------------------
+
+
+def test_prefix():
+    e = Env(source={"APP_PORT": "9000"}, prefix="APP_")
+    assert e.int("PORT") == 9000
+
+
+def test_default_env_reads_live_os_environ(monkeypatch):
+    from envcaster import env
+
+    monkeypatch.setenv("ENVCAST_TEST_X", "42")
+    assert env.int("ENVCAST_TEST_X") == 42

envcaster-0.1.0/tests/test_dotenv.py

@@ -0,0 +1,57 @@
+from envcaster import load_dotenv, read_dotenv
+
+SAMPLE = """\
+# a comment
+NAME=alice
+export TOKEN=secret
+QUOTED="hello world"
+SINGLE='single quoted'
+WITH_COMMENT=value   # trailing comment
+EMPTY=
+
+  # indented comment
+PORT=8000
+"""
+
+
+def write(tmp_path, text=SAMPLE):
+    f = tmp_path / ".env"
+    f.write_text(text, encoding="utf-8")
+    return f
+
+
+def test_read_dotenv_parses_all_forms(tmp_path):
+    data = read_dotenv(write(tmp_path))
+    assert data["NAME"] == "alice"
+    assert data["TOKEN"] == "secret"          # export prefix stripped
+    assert data["QUOTED"] == "hello world"    # double quotes stripped
+    assert data["SINGLE"] == "single quoted"  # single quotes stripped
+    assert data["WITH_COMMENT"] == "value"    # inline comment dropped
+    assert data["EMPTY"] == ""
+    assert data["PORT"] == "8000"
+
+
+def test_read_dotenv_missing_file_returns_empty(tmp_path):
+    assert read_dotenv(tmp_path / "nope.env") == {}
+
+
+def test_quoted_value_keeps_hash(tmp_path):
+    f = write(tmp_path, 'URL="http://x/#frag"\n')
+    assert read_dotenv(f)["URL"] == "http://x/#frag"
+
+
+def test_load_dotenv_does_not_override_by_default(tmp_path, monkeypatch):
+    monkeypatch.setenv("NAME", "real")
+    load_dotenv(write(tmp_path))
+    import os
+
+    assert os.environ["NAME"] == "real"        # existing env wins
+    assert os.environ["TOKEN"] == "secret"     # new key injected
+
+
+def test_load_dotenv_override(tmp_path, monkeypatch):
+    monkeypatch.setenv("NAME", "real")
+    load_dotenv(write(tmp_path), override=True)
+    import os
+
+    assert os.environ["NAME"] == "alice"