pureenv 0.1.1__tar.gz

pureenv-0.1.1/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: pureenv
+Version: 0.1.1
+Summary: Typed environment variable parsing for Python. Zero dependencies. Pure stdlib.
+License: MIT
+Project-URL: Homepage, https://github.com/abiget/pureenv
+Project-URL: Repository, https://github.com/abiget/pureenv
+Project-URL: Issues, https://github.com/abiget/pureenv/issues
+Keywords: environment,env,config,settings,typed
+Requires-Python: >=3.8

pureenv-0.1.1/README.md

@@ -0,0 +1,59 @@
+# pureenv
+
+Typed environment variable parsing for Python. Zero dependencies. Pure stdlib.
+
+---
+
+## The Problem
+
+Every Python project ends up writing this:
+```python
+PORT   = int(os.environ.get("PORT", 8080))
+DEBUG  = os.environ.get("DEBUG", "false").lower() == "true"
+DB_URL = os.environ["DATABASE_URL"] # KeyError with no helpful message
+```
+
+Manual casting. No validation. Cryptic error. Every. Single. Project.
+
+## The solution
+```python
+from pureenv import env
+PORT   = env.int("PORT",            default=8080)
+DEBUG  = env.bool("DEBUG",          default=False)
+DB_URL = env.str("DATABASE_URL",    required=True)
+```
+
+Typed. Validated. Clear errors when something is wrong.
+
+
+## Install
+```bash
+pip install pureenv
+```
+
+## Usage
+```python
+from pureenv import env
+
+# strings
+NAME = env.str("APP_NAME", default="myapp")
+
+# numbers
+PORT  = env.int("PORT",    default=8080)
+RATIO = env.float("RATIO", default=0.5)
+
+# booleans - accepts "true/false", "1/0", "yes/no", "y/n", "on/off"
+DEBUG = env.bool("DEBUG", default=False)
+
+# required - raises a clear error if missing
+DB_URL = env.str("DATABASE_URL", required=True)
+```
+
+## Why not `environs` or `python-dotenv`?
+
+| | pureenv | python-dotenv | environs |
+|---|---|---|---|
+| Typed casting       | ✅ | ❌ | ✅ |
+| Zero dependencies   | ✅ | ✅ | ❌ |
+| Required validation | ✅ | ❌ | ✅ |
+| Loads .env file     | ❌ | ✅ | ✅ |

pureenv-0.1.1/pureenv/__init__.py

@@ -0,0 +1,148 @@
+import os
+import sys
+
+# Store references to the original int and float functions to avoid issues
+#  if they are overridden in the environment
+_int = int
+_float = float
+_bool = bool
+_str = str
+
+class Env:
+    def __init__(self, environ: dict = None):
+        self._environ = environ if environ is not None else os.environ
+    def str(self, key: str, default: str = None,
+            required: bool = False) -> str:
+        """
+        Get an environment variable as a string.
+
+        Args:
+            key: The name of the environment variable.
+            default: The default value to return if the variable is not set (default: None).
+            required: If True, raises an error if the variable is not set (default: False).
+
+        Returns:
+            The value of the environment variable as a string, or the default value if not set.
+        """
+        value = self._environ.get(key, None)
+
+        if value is None:
+            if required:
+                if sys.platform.startswith("win"):
+                    hint = f"set {key}=your_value"
+                else:
+                    hint = f"export {key}=your_value"
+
+                raise ValueError(
+                    f"Required env var '{key}' is not set.\n"
+                    f"→ To fix: {hint}"
+                )
+            return _str(default) if default is not None else None
+        return value
+    
+    def int(self, key: str, default: int = None, 
+            required: bool = False) -> int:
+        """
+        Get an environment variable as an integer.
+        Args:
+            key: The name of the environment variable.
+            default: The default value to return if the variable is not set (default: None).
+            required: If True, raises an error if the variable is not set (default: False).
+
+        Returns:
+            The value of the environment variable as an integer, or the default value if not set.
+        """
+        value = self.str(key, default=default, required=required)
+
+        if value is None:
+            return None
+        
+        try:
+            return _int(value)
+        except (ValueError, TypeError):
+            # did it come from an env var or the default value?
+            if os.environ.get(key):
+                raise ValueError(
+                    f"Env var '{key}' has value {value!r} which is not a valid integer."
+                )
+            else:
+                raise ValueError(
+                    f"Default value for '{key}' is {value!r} which is not a valid integer."
+                )
+        
+    def float(self, key: str, default: float = None,
+                required: bool = False) -> float:
+        """
+        Get an environment variable as a float.
+
+        Args:
+            key: The name of the environment variable.
+            default: The default value to return if the variable is not set (default: None).
+            required: If True, raises an error if the variable is not set (default: False).
+
+        Returns:
+            The value of the environment variable as a float, or the default value if not set.
+        """
+        value = self.str(key, default=default, required=required)
+
+        if value is None:
+            return None
+        try:
+            return _float(value)
+        except (ValueError, TypeError):
+            if os.environ.get(key):
+                raise ValueError(
+                    f"Env var '{key}' has value {value!r} which is not a valid float."
+                )
+            else:
+                raise ValueError(
+                    f"Default value for '{key}' is {value!r} which is not a valid float."
+                )
+        
+    def bool(self, key: str, default: bool = None,
+                required: bool = False) -> bool:
+        """
+        Get an environment variable as a boolean.
+
+        Accepted values (case-insensitive):
+        - Truthy: "true", "1", "yes", "y", "on"
+        - Falsy: "false", "0", "no", "n", "off"
+
+        Args:
+            key: The name of the environment variable.
+            default: The default value to return if the variable is not set (default: None).
+            required: If True, raises an error if the variable is not set (default: False).
+
+        Returns:
+            The value of the environment variable as a boolean, or the default value if not set.
+        """
+        value = self.str(key, default=default, required=required)
+
+        if value is None:
+            return None
+        
+        if isinstance(value, _bool):
+            return value
+        
+        if isinstance(value, (_int, _float)):
+            return _bool(value)
+        
+        value_lower = value.lower()
+        if value_lower in ("true", "1", "yes", "y", "on"):
+            return True
+        elif value_lower in ("false", "0", "no", "n", "off"):
+            return False
+        else:
+            if os.environ.get(key):
+                raise ValueError(
+                    f"Env var '{key}' has value {value!r} which is not a valid boolean.\n"
+                    f"→ Use: true/false, 1/0, yes/no, y/n, on/off (case-insensitive)"
+                )
+            else:
+                raise ValueError(
+                    f"The default value for '{key}' is {value!r} which is not a valid boolean.\n"
+                    f"→ Use: true/false, 1/0, yes/no, y/n, on/off (case-insensitive)"
+                )
+
+# module-level singleton instance of Env for convenience
+env = Env()

pureenv-0.1.1/pureenv.egg-info/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: pureenv
+Version: 0.1.1
+Summary: Typed environment variable parsing for Python. Zero dependencies. Pure stdlib.
+License: MIT
+Project-URL: Homepage, https://github.com/abiget/pureenv
+Project-URL: Repository, https://github.com/abiget/pureenv
+Project-URL: Issues, https://github.com/abiget/pureenv/issues
+Keywords: environment,env,config,settings,typed
+Requires-Python: >=3.8

pureenv-0.1.1/pureenv.egg-info/SOURCES.txt

@@ -0,0 +1,8 @@
+README.md
+pyproject.toml
+pureenv/__init__.py
+pureenv.egg-info/PKG-INFO
+pureenv.egg-info/SOURCES.txt
+pureenv.egg-info/dependency_links.txt
+pureenv.egg-info/top_level.txt
+tests/test_pureenv.py

pureenv-0.1.1/pureenv.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pureenv-0.1.1/pureenv.egg-info/top_level.txt

@@ -0,0 +1 @@
+pureenv

pureenv-0.1.1/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pureenv"
+version = "0.1.1"
+description = "Typed environment variable parsing for Python. Zero dependencies. Pure stdlib."
+requires-python = ">=3.8"
+dependencies = []
+keywords = ["environment", "env", "config", "settings", "typed"]
+license = {text = "MIT"}
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["pureenv*"]
+
+[project.urls]
+Homepage = "https://github.com/abiget/pureenv"
+Repository = "https://github.com/abiget/pureenv"
+Issues = "https://github.com/abiget/pureenv/issues"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

pureenv-0.1.1/setup.cfg

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

pureenv-0.1.1/tests/test_pureenv.py

@@ -0,0 +1,89 @@
+import pytest
+from pureenv import Env
+
+
+def test_str_returns_value():
+    env = Env(environ={"NAME": "alice"})
+    assert env.str("NAME") == "alice"
+
+def test_str_returns_default():
+    env = Env(environ={})
+    assert env.str("MISSING", default="fallback") == "fallback"
+
+def test_str_returns_none_when_no_default():
+    env = Env(environ={})
+    assert env.str("MISSING") is None
+
+def test_str_raises_when_required():
+    env = Env(environ={})
+
+    with pytest.raises(ValueError, match="MISSING"):
+        env.str("MISSING", required=True)
+
+
+def test_int_returns_value():
+    env = Env(environ={"PORT": "8080"})
+    assert env.int("PORT") == 8080
+
+def test_int_returns_default():
+    env = Env(environ={})
+    assert env.int("MISSING", default=3306) == 3306
+
+def test_int_raises_on_invalid_value():
+    env = Env(environ={"PORT": "not_a_number"})
+
+    with pytest.raises(ValueError, match="PORT"):
+        env.int("PORT")
+
+def test_int_raises_when_required():
+    env = Env(environ={})
+
+    with pytest.raises(ValueError, match="PORT"):
+        env.int("PORT", required=True)
+
+def test_float_returns_value():
+    env = Env(environ={"PI": "3.14"})
+    assert env.float("PI") == 3.14
+
+def test_float_returns_default():
+    env = Env(environ={})
+    assert env.float("MISSING", default=3.14) == 3.14
+
+def test_float_raises_on_invalid_value():
+    env = Env(environ={"PI": "not_a_number"})
+
+    with pytest.raises(ValueError, match="PI"):
+        env.float("PI")
+
+def test_float_raises_when_required():
+    env = Env(environ={})
+
+    with pytest.raises(ValueError, match="PI"):
+        env.float("PI", required=True)
+
+
+@pytest.mark.parametrize("value", ("true", "1", "yes", "y", "on"))
+def test_bool_truthy_values(value):
+    env = Env(environ={"DEBUG": value})
+    assert env.bool("DEBUG") is True
+
+@pytest.mark.parametrize("value", ("false", "0", "no", "n", "off"))
+def test_bool_falsy_values(value):
+    env = Env(environ={"DEBUG": value})
+    assert env.bool("DEBUG") is False
+
+def test_bool_returns_default():
+    env = Env(environ={})
+    assert env.bool("MISSING", default=False) is False
+
+def test_bool_raises_on_invalid_value():
+    env = Env(environ={"DEBUG": "maybe"})
+
+    with pytest.raises(ValueError, match="DEBUG"):
+        env.bool("DEBUG")
+
+def test_bool_raises_when_required():
+    env = Env(environ={})
+
+    with pytest.raises(ValueError, match="MISSING"):
+        env.bool("MISSING", required=True)