frozenenv 0.1.0__tar.gz

frozenenv-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+# Virtual environment
+.venv/
+venv/
+env/
+
+# Build output
+dist/
+build/
+*.egg-info/
+
+# Python cache
+__pycache__/bytecode cache
+*.py[cod]
+*.pyo
+.pytest_cache/
+.mypy_cache/
+
+# Environment / secrets
+.envcontains 
+.env.*
+.pypirccontains 
+
+# IDE files
+.vscode/optional 
+.idea/
+
+# OS junk
+.DS_StoremacOS 
+Thumbs.db

frozenenv-0.1.0/LICENSE

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

frozenenv-0.1.0/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: frozenenv
+Version: 0.1.0
+Summary: Typed environment variables as a frozen dataclass — zero dependencies
+Project-URL: Homepage, https://github.com/hudihi/frozenenv
+Project-URL: Repository, https://github.com/hudihi/frozenenv
+Project-URL: Issues, https://github.com/hudihi/frozenenv/issues
+Author-email: Abdillah Issa <hudihudiabdillah@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Your Name
+        
+        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.
+License-File: LICENSE
+Keywords: config,dotenv,environment,settings,typed
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10

frozenenv-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "frozenenv"
+version = "0.1.0"
+description = "Typed environment variables as a frozen dataclass — zero dependencies"
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [{ name = "Abdillah Issa", email = "hudihudiabdillah@gmail.com" }]
+keywords = ["environment", "config", "dotenv", "settings", "typed"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed",
+]
+requires-python = ">=3.10"
+dependencies = []   # ← zero deps, intentional
+
+[project.urls]
+Homepage = "https://github.com/hudihi/frozenenv"
+Repository = "https://github.com/hudihi/frozenenv"
+Issues = "https://github.com/hudihi/frozenenv/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/envclass"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

frozenenv-0.1.0/src/envclass/__init__.py

@@ -0,0 +1,163 @@
+from __future__ import annotations
+
+import dataclasses
+import os
+import pathlib
+import types
+import typing
+from typing import Any, get_type_hints
+
+__all__ = ["envclass", "EnvError"]
+__version__ = "0.1.0"
+
+__BOOL_TRUE = {"1", "true", "yes", "on", "enabled"}
+__BOOL_FALSE = {"0", "false", "no", "off", "disabled"}
+
+
+
+class EnvError(Exception):
+    """Raised when a required env var is missing or cannot be cast to the expected type."""
+    
+    
+def _parse_dotenv(path: str | os.PathLike) -> dict[str, str]:
+    """Parse KEY=VALUE lines from a .env file. Returns empty dict if not found."""
+    result: dict[str, str] = {}
+    p = pathlib.Path(path)
+    
+    if not p.exists():
+        return result
+    
+    for raw in p.read_text(encoding="utf-8").splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line.startswith("export "):
+            line = line[7:].lstrip()
+        if "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        key = key.strip()
+        value = value.strip()
+        
+        #strip surrounding quotes if present
+        if len(value) >= 2 and value[0] == value[-1] and value[0] in ('"', "'"):
+            value = value[1:-1]
+        if key:
+            result[key] = value
+    return result
+
+
+def _coerce(value: str, annotation: Any, name: str) -> Any:
+    """Cast string value to the given type annontation."""
+    origin = typing.get_origin(annotation)
+    args = typing.get_args(annotation)
+
+
+    # Optional[X] or X | None
+    if origin is typing.Union or origin is types.UnionType:
+        non_none = [a for a in args if a is not type(None)]
+        if not value and type(None) in args:
+            return None
+        return _coerce(value, non_none[0], name) if non_none else value
+
+    # bool - must come before int (bool is a subclass of int!)
+    if annotation is bool:
+        val = value.lower()
+        if val in __BOOL_TRUE:
+            return True
+        if val in __BOOL_FALSE:
+            return False
+        opts = ", ".join(sorted(__BOOL_TRUE | __BOOL_FALSE))
+        raise EnvError(f"{name}: '{value}' is not a valid bool. Use: {opts}")
+
+    # int, float, str
+    if annotation in (int, float, str):
+        try:
+            return annotation(value)
+        except (ValueError, TypeError) as exc:
+            raise EnvError(f"{name}: cannot cast '{value} to {annotation.__name__} ") from exc
+    # list[X] - comma-separated
+    if origin is list:
+        if not value:
+            return []
+        item_type = args[0] if args else str
+        return [_coerce(v.strip(), item_type, name) for v in value.split(",")]
+        
+    # Fallback: return as string
+    return value
+
+def envclass(cls=None, *, env_file: str | os.PathLike | None = ".env",override: bool = False):
+    """Decorator that turns a class into a typed, frozen env-var config object.
+    
+    Args:
+    env_file: Path to a .env file to load. Defaults to '.env' in cwd.
+              Set to None to skip .env loading entirely.
+    override: If True, .env values overwrite real environment variables.
+    """
+    
+    def wrap(klass):
+        # 1. Make it a frozen dataclass so config can't be mutated
+        dc = dataclasses.dataclass(klass, frozen=True)
+        
+        
+        # 2. Grab the resolved type hints (handles forward refs)
+        hints = get_type_hints(dc)
+        
+        # 3. Collect defaults from the dataclass fields
+        defaults: dict[str, Any] = {}
+        for f in dataclasses.fields(dc):
+            if f.default is not dataclasses.MISSING:
+                defaults[f.name] = f.default
+            elif f.default_factory is not dataclasses.MISSING:
+                defaults[f.name] = f.default_factory()
+            
+        # 4. Build a custom __init__ that reads from env
+        original_init = dc.__init__
+        
+        def __init__(self, *, _env: dict[str, str] | None = None):
+            # Load .env file first
+            dotenv_vals: dict[str, str] = {}
+            
+            if env_file is not None:
+                dotenv_vals = _parse_dotenv(env_file)
+                
+            # Merge: real env wins unless override=True
+            source = dict(dotenv_vals)
+            if override:
+                source.update(os.environ)
+            else:
+                for k, v in os.environ.items():
+                    source[k] = v
+                    
+            # Allow test injection via _env parameter
+            if _env is not None:
+                source.update(_env)
+                
+            # Resolve each field
+            kwargs: dict[str, Any] = {}
+            missing = []
+            
+            for field_name, annotation in hints.items():
+                raw = source.get(field_name)
+                if raw is not None:
+                    kwargs[field_name] = _coerce(raw, annotation, field_name)
+                elif field_name in defaults:
+                    kwargs[field_name] = defaults[field_name]
+                else:
+                    missing.append(field_name)
+                    
+            if missing:
+                raise EnvError(f"Missing required env vars: {', '.join(missing)}")
+        
+            # Call the frozen dataclass __init__ via object.__setattr__
+            for k, v in kwargs.items():
+                object.__setattr__(self, k, v)
+        
+        dc.__init__ = __init__
+        return dc
+    
+    if cls is None:
+        return wrap
+    return wrap(cls)
+    
+    

frozenenv-0.1.0/src/envclass/py.typed

@@ -0,0 +1 @@
+# marks package as typed

frozenenv-0.1.0/tests/test_envclass.py

@@ -0,0 +1,155 @@
+# tests file for envclass.py
+import pytest
+from envclass import envclass, EnvError
+
+
+def test_reads_string(monkeypatch):
+    monkeypatch.setenv("HOST", "localhost")
+
+    @envclass(env_file=None)
+    class Config:
+        HOST: str
+
+    assert Config().HOST == "localhost"
+    
+def test_reads_int(monkeypatch):
+    monkeypatch.setenv("PORT", "9000")
+
+    @envclass(env_file=None)
+    class Config:
+        PORT: int
+
+    assert Config().PORT == 9000
+    assert isinstance(Config().PORT, int)
+    
+def test_reads_float(monkeypatch):
+    monkeypatch.setenv("RATE", "3.14")
+
+    @envclass(env_file=None)
+    class Config:
+        RATE: float
+
+    assert Config().RATE == 3.14
+    
+
+@pytest.mark.parametrize("val", ["true", "True", "1", "yes", "on", "enabled"])
+def test_bool_true(monkeypatch, val):
+    monkeypatch.setenv("FLAG", val)
+    
+    @envclass(env_file=None)
+    class Config:
+        FLAG: bool
+        
+    assert Config().FLAG is True
+    
+
+@pytest.mark.parametrize("val", ["false", "False", "0", "no", "off", "disabled"])
+def test_bool_false(monkeypatch, val):
+    monkeypatch.setenv("FLAG", val)
+    
+    @envclass(env_file=None)
+    class Config:
+        FLAG: bool
+        
+    assert Config().FLAG is False
+    
+def test_bool_invalid(monkeypatch):
+    monkeypatch.setenv("FLAG", "notabool")
+    
+    @envclass(env_file=None)
+    class Config:
+        FLAG: bool
+        
+    with pytest.raises(EnvError, match="FLAG"):
+        Config()
+        
+        
+def test_list_of_strings(monkeypatch):
+    monkeypatch.setenv("ITEMS", "apple,banana, cherry")
+
+    @envclass(env_file=None)
+    class Config:
+        ITEMS: list[str]
+
+    assert Config().ITEMS == ["apple", "banana", "cherry"]
+    
+def test_list_of_ints(monkeypatch):
+    monkeypatch.setenv("PORTS", "8000, 9000, 10000")
+    
+    @envclass(env_file=None)
+    class Config:
+        PORTS: list[int]
+        
+    assert Config().PORTS == [8000, 9000, 10000]
+    
+def test_list_empty_string_gives_empty_list(monkeypatch):
+    monkeypatch.setenv("ITEMS", "")
+    
+    @envclass(env_file=None)
+    class Config:
+        ITEMS: list[str]
+        
+    assert Config().ITEMS == []
+    
+    
+def test_default_used_when_var_missing(monkeypatch):
+    monkeypatch.delenv("PORT", raising=False)
+
+    @envclass(env_file=None)
+    class Config:
+        PORT: int = 8000
+
+    assert Config().PORT == 8000
+    
+    
+
+def test_env_overrides_default(monkeypatch):
+    monkeypatch.setenv("PORT", "9000")
+    
+    @envclass(env_file=None)
+    class Config:
+        PORT: int = 8000
+        
+    assert Config().PORT == 9000
+    
+    
+def test_missing_required_raises(monkeypatch):
+    monkeypatch.delenv("DATABASE_URL", raising=False)
+
+    @envclass(env_file=None)
+    class Config:
+        DATABASE_URL: str
+
+    with pytest.raises(EnvError, match="DATABASE_URL"):
+        Config()
+        
+def test_config_is_frozen(monkeypatch):
+    monkeypatch.setenv("PORT", "8000")
+    
+    @envclass(env_file=None)
+    class Config:
+        PORT: int
+        
+    cfg = Config()
+    with pytest.raises(Exception):   # FrozenInstanceError
+        cfg.PORT = 9999              # type: ignore
+        
+        
+def test_optional_present(monkeypatch):
+    monkeypatch.setenv("TOKEN", "abc123")
+
+    @envclass(env_file=None)
+    class Config:
+        TOKEN: str | None = None
+
+    assert Config().TOKEN == "abc123"
+    
+    
+def test_optional_missing_gives_none(monkeypatch):
+    monkeypatch.delenv("TOKEN", raising=False)
+    
+    @envclass(env_file=None)
+    class Config:
+        TOKEN: str | None = None
+    
+    assert Config().TOKEN is None