envproof 0.1.0__tar.gz

envproof-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install pytest hatchling
+      - run: pip install -e .
+      - run: pytest

envproof-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+*.pyc

envproof-0.1.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: envproof
+Version: 0.1.0
+Summary: Validate environment variables at startup with typed, clear error messages. Zero dependencies.
+Project-URL: Homepage, https://github.com/CoderSufiyan/envguard
+Project-URL: Repository, https://github.com/CoderSufiyan/envguard
+Project-URL: Issues, https://github.com/CoderSufiyan/envguard/issues
+License: MIT
+Keywords: config,dotenv,env,environment,settings,validation
+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.8
+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
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# envguard
+
+Validate environment variables at startup with typed, clear error messages. Zero dependencies.
+
+```python
+from envguard import EnvGuard
+
+class Env(EnvGuard):
+    DATABASE_URL: str
+    PORT: int = 8080
+    DEBUG: bool = False
+    ALLOWED_HOSTS: list = []
+
+env = Env()
+print(env.PORT)  # 8080 (int, not string)
+```
+
+If `DATABASE_URL` is missing, you get this instead of a cryptic `KeyError` somewhere deep in your app:
+
+```
+EnvGuardError:
+Missing required environment variables:
+  - DATABASE_URL (str): not set
+```
+
+## Install
+
+```bash
+pip install envguard
+```
+
+## Usage
+
+### Subclass style (recommended)
+
+```python
+from envguard import EnvGuard
+
+class Env(EnvGuard):
+    # Required — raises if not set
+    DATABASE_URL: str
+    API_KEY: str
+
+    # Optional — uses default if not set
+    PORT: int = 8080
+    DEBUG: bool = False
+    LOG_LEVEL: str = "INFO"
+    ALLOWED_HOSTS: list = []
+
+env = Env()
+```
+
+### One-liner style
+
+```python
+from envguard import guard
+
+env = guard(DATABASE_URL=str, PORT=int, DEBUG=bool)
+print(env.DATABASE_URL)
+```
+
+## Supported types
+
+| Type    | Example env value         | Python value             |
+|---------|---------------------------|--------------------------|
+| `str`   | `"hello"`                 | `"hello"`                |
+| `int`   | `"8080"`                  | `8080`                   |
+| `float` | `"3.14"`                  | `3.14`                   |
+| `bool`  | `"true"`, `"1"`, `"yes"`  | `True`                   |
+| `bool`  | `"false"`, `"0"`, `"no"`  | `False`                  |
+| `list`  | `"a,b,c"`                 | `["a", "b", "c"]`        |
+
+## Error messages
+
+All errors are collected and reported together — you won't fix one missing var only to discover another:
+
+```
+EnvGuardError:
+Missing required environment variables:
+  - DATABASE_URL (str): not set
+  - API_KEY (str): not set
+
+Invalid environment variable values:
+  - PORT: expected int, got 'abc'
+  - DEBUG: expected bool, got 'maybe'
+```
+
+## Why not pydantic-settings?
+
+`pydantic-settings` is great but pulls in Pydantic as a dependency (~2MB). `envguard` is a single file with zero dependencies — useful when you want validation without adding weight to your project.
+
+## License
+
+MIT

envproof-0.1.0/README.md

@@ -0,0 +1,94 @@
+# envguard
+
+Validate environment variables at startup with typed, clear error messages. Zero dependencies.
+
+```python
+from envguard import EnvGuard
+
+class Env(EnvGuard):
+    DATABASE_URL: str
+    PORT: int = 8080
+    DEBUG: bool = False
+    ALLOWED_HOSTS: list = []
+
+env = Env()
+print(env.PORT)  # 8080 (int, not string)
+```
+
+If `DATABASE_URL` is missing, you get this instead of a cryptic `KeyError` somewhere deep in your app:
+
+```
+EnvGuardError:
+Missing required environment variables:
+  - DATABASE_URL (str): not set
+```
+
+## Install
+
+```bash
+pip install envguard
+```
+
+## Usage
+
+### Subclass style (recommended)
+
+```python
+from envguard import EnvGuard
+
+class Env(EnvGuard):
+    # Required — raises if not set
+    DATABASE_URL: str
+    API_KEY: str
+
+    # Optional — uses default if not set
+    PORT: int = 8080
+    DEBUG: bool = False
+    LOG_LEVEL: str = "INFO"
+    ALLOWED_HOSTS: list = []
+
+env = Env()
+```
+
+### One-liner style
+
+```python
+from envguard import guard
+
+env = guard(DATABASE_URL=str, PORT=int, DEBUG=bool)
+print(env.DATABASE_URL)
+```
+
+## Supported types
+
+| Type    | Example env value         | Python value             |
+|---------|---------------------------|--------------------------|
+| `str`   | `"hello"`                 | `"hello"`                |
+| `int`   | `"8080"`                  | `8080`                   |
+| `float` | `"3.14"`                  | `3.14`                   |
+| `bool`  | `"true"`, `"1"`, `"yes"`  | `True`                   |
+| `bool`  | `"false"`, `"0"`, `"no"`  | `False`                  |
+| `list`  | `"a,b,c"`                 | `["a", "b", "c"]`        |
+
+## Error messages
+
+All errors are collected and reported together — you won't fix one missing var only to discover another:
+
+```
+EnvGuardError:
+Missing required environment variables:
+  - DATABASE_URL (str): not set
+  - API_KEY (str): not set
+
+Invalid environment variable values:
+  - PORT: expected int, got 'abc'
+  - DEBUG: expected bool, got 'maybe'
+```
+
+## Why not pydantic-settings?
+
+`pydantic-settings` is great but pulls in Pydantic as a dependency (~2MB). `envguard` is a single file with zero dependencies — useful when you want validation without adding weight to your project.
+
+## License
+
+MIT

envproof-0.1.0/envguard/__init__.py

@@ -0,0 +1,4 @@
+from .core import EnvGuard, EnvGuardError, guard
+
+__all__ = ["EnvGuard", "EnvGuardError", "guard"]
+__version__ = "0.1.0"

envproof-0.1.0/envguard/core.py

@@ -0,0 +1,84 @@
+import os
+from typing import Any, get_type_hints
+
+_MISSING = object()
+
+
+class EnvGuardError(Exception):
+    pass
+
+
+class EnvGuard:
+    """
+    Subclass this and declare your env vars as type-annotated class attributes.
+
+    Required var:   DATABASE_URL: str
+    Optional var:   PORT: int = 8080
+    """
+
+    def __init__(self):
+        hints = get_type_hints(self.__class__)
+        missing = []
+        invalid = []
+
+        for name, type_ in hints.items():
+            if name.startswith("_"):
+                continue
+
+            raw = os.environ.get(name)
+            has_default = name in self.__class__.__dict__
+            default = self.__class__.__dict__.get(name, _MISSING)
+
+            if raw is None:
+                if not has_default:
+                    missing.append((name, type_))
+                else:
+                    setattr(self, name, default)
+                continue
+
+            try:
+                setattr(self, name, _coerce(raw, type_))
+            except (ValueError, TypeError):
+                invalid.append((name, type_.__name__, raw))
+
+        errors = []
+        if missing:
+            errors.append("Missing required environment variables:")
+            for name, type_ in missing:
+                errors.append(f"  - {name} ({type_.__name__}): not set")
+        if invalid:
+            if errors:
+                errors.append("")
+            errors.append("Invalid environment variable values:")
+            for name, type_name, raw in invalid:
+                errors.append(f"  - {name}: expected {type_name}, got '{raw}'")
+
+        if errors:
+            raise EnvGuardError("\n" + "\n".join(errors))
+
+
+def _coerce(value: str, type_: type) -> Any:
+    if type_ is bool:
+        if value.lower() in ("true", "1", "yes", "on"):
+            return True
+        if value.lower() in ("false", "0", "no", "off"):
+            return False
+        raise ValueError(f"Cannot convert to bool: {value!r}")
+    if type_ is list:
+        return [v.strip() for v in value.split(",") if v.strip()]
+    return type_(value)
+
+
+def guard(**schema) -> Any:
+    """
+    One-liner usage without subclassing:
+
+        env = guard(DATABASE_URL=str, PORT=int, DEBUG=bool)
+        print(env.DATABASE_URL)
+    """
+
+    class _Env(EnvGuard):
+        pass
+
+    _Env.__annotations__ = schema
+    return _Env()

envproof-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "envproof"
+version = "0.1.0"
+description = "Validate environment variables at startup with typed, clear error messages. Zero dependencies."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+keywords = ["environment", "config", "validation", "env", "dotenv", "settings"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/CoderSufiyan/envguard"
+Repository = "https://github.com/CoderSufiyan/envguard"
+Issues = "https://github.com/CoderSufiyan/envguard/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["envguard"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

envproof-0.1.0/tests/test_core.py

@@ -0,0 +1,203 @@
+import os
+import pytest
+from envguard import EnvGuard, EnvGuardError, guard
+
+
+def set_env(**kwargs):
+    for k, v in kwargs.items():
+        os.environ[k] = str(v)
+
+
+def clear_env(*keys):
+    for k in keys:
+        os.environ.pop(k, None)
+
+
+# --- EnvGuard subclass style ---
+
+class TestRequired:
+    def test_loads_required_str(self):
+        set_env(APP_NAME="myapp")
+
+        class Env(EnvGuard):
+            APP_NAME: str
+
+        env = Env()
+        assert env.APP_NAME == "myapp"
+        clear_env("APP_NAME")
+
+    def test_loads_required_int(self):
+        set_env(PORT="9000")
+
+        class Env(EnvGuard):
+            PORT: int
+
+        env = Env()
+        assert env.PORT == 9000
+        clear_env("PORT")
+
+    def test_loads_required_float(self):
+        set_env(RATE="3.14")
+
+        class Env(EnvGuard):
+            RATE: float
+
+        env = Env()
+        assert env.RATE == 3.14
+        clear_env("RATE")
+
+    def test_raises_on_missing_required(self):
+        clear_env("DATABASE_URL")
+
+        class Env(EnvGuard):
+            DATABASE_URL: str
+
+        with pytest.raises(EnvGuardError) as exc:
+            Env()
+        assert "DATABASE_URL" in str(exc.value)
+        assert "Missing" in str(exc.value)
+
+    def test_raises_on_multiple_missing(self):
+        clear_env("DB_URL", "API_KEY")
+
+        class Env(EnvGuard):
+            DB_URL: str
+            API_KEY: str
+
+        with pytest.raises(EnvGuardError) as exc:
+            Env()
+        assert "DB_URL" in str(exc.value)
+        assert "API_KEY" in str(exc.value)
+
+
+class TestOptional:
+    def test_uses_default_when_not_set(self):
+        clear_env("PORT")
+
+        class Env(EnvGuard):
+            PORT: int = 8080
+
+        env = Env()
+        assert env.PORT == 8080
+
+    def test_overrides_default_when_set(self):
+        set_env(PORT="9000")
+
+        class Env(EnvGuard):
+            PORT: int = 8080
+
+        env = Env()
+        assert env.PORT == 9000
+        clear_env("PORT")
+
+    def test_optional_str_default(self):
+        clear_env("LOG_LEVEL")
+
+        class Env(EnvGuard):
+            LOG_LEVEL: str = "INFO"
+
+        env = Env()
+        assert env.LOG_LEVEL == "INFO"
+
+
+class TestBoolCoercion:
+    @pytest.mark.parametrize("value", ["true", "True", "TRUE", "1", "yes", "on"])
+    def test_truthy_values(self, value):
+        set_env(DEBUG=value)
+
+        class Env(EnvGuard):
+            DEBUG: bool
+
+        assert Env().DEBUG is True
+        clear_env("DEBUG")
+
+    @pytest.mark.parametrize("value", ["false", "False", "FALSE", "0", "no", "off"])
+    def test_falsy_values(self, value):
+        set_env(DEBUG=value)
+
+        class Env(EnvGuard):
+            DEBUG: bool
+
+        assert Env().DEBUG is False
+        clear_env("DEBUG")
+
+    def test_invalid_bool_raises(self):
+        set_env(DEBUG="maybe")
+
+        class Env(EnvGuard):
+            DEBUG: bool
+
+        with pytest.raises(EnvGuardError) as exc:
+            Env()
+        assert "DEBUG" in str(exc.value)
+        clear_env("DEBUG")
+
+
+class TestListCoercion:
+    def test_comma_separated_list(self):
+        set_env(ALLOWED_HOSTS="localhost,example.com,api.example.com")
+
+        class Env(EnvGuard):
+            ALLOWED_HOSTS: list
+
+        env = Env()
+        assert env.ALLOWED_HOSTS == ["localhost", "example.com", "api.example.com"]
+        clear_env("ALLOWED_HOSTS")
+
+    def test_list_strips_whitespace(self):
+        set_env(HOSTS=" a , b , c ")
+
+        class Env(EnvGuard):
+            HOSTS: list
+
+        env = Env()
+        assert env.HOSTS == ["a", "b", "c"]
+        clear_env("HOSTS")
+
+
+class TestInvalidType:
+    def test_invalid_int_raises(self):
+        set_env(PORT="not-a-number")
+
+        class Env(EnvGuard):
+            PORT: int
+
+        with pytest.raises(EnvGuardError) as exc:
+            Env()
+        assert "PORT" in str(exc.value)
+        assert "int" in str(exc.value)
+        clear_env("PORT")
+
+    def test_reports_all_invalid_at_once(self):
+        set_env(PORT="bad", WORKERS="also-bad")
+
+        class Env(EnvGuard):
+            PORT: int
+            WORKERS: int
+
+        with pytest.raises(EnvGuardError) as exc:
+            Env()
+        assert "PORT" in str(exc.value)
+        assert "WORKERS" in str(exc.value)
+        clear_env("PORT", "WORKERS")
+
+
+# --- guard() one-liner style ---
+
+class TestGuard:
+    def test_guard_basic(self):
+        set_env(HOST="localhost")
+        env = guard(HOST=str)
+        assert env.HOST == "localhost"
+        clear_env("HOST")
+
+    def test_guard_raises_on_missing(self):
+        clear_env("SECRET_KEY")
+        with pytest.raises(EnvGuardError):
+            guard(SECRET_KEY=str)
+
+    def test_guard_int(self):
+        set_env(TIMEOUT="30")
+        env = guard(TIMEOUT=int)
+        assert env.TIMEOUT == 30
+        clear_env("TIMEOUT")