duckenv 0.1.0__tar.gz

duckenv-0.1.0/.gitignore

@@ -0,0 +1,3 @@
+__pycache__/
+dist/
+.coverage

duckenv-0.1.0/.woodpecker/lint.yml

@@ -0,0 +1,13 @@
+steps:
+  lint:
+    image: python:3.13-slim
+    environment:
+      PIP_ROOT_USER_ACTION: ignore
+    commands:
+      - pip install .[dev]
+      - black . --check
+      - mypy .
+    when:
+      - event: pull_request
+      - event: push
+        branch: main

duckenv-0.1.0/.woodpecker/release.yml

@@ -0,0 +1,20 @@
+steps:
+  release:
+    image: python:3.11-slim
+    commands:
+      - pip install build twine
+      - python -m build
+      - twine upload --disable-progress-bar dist/*
+    environment:
+      TWINE_REPOSITORY:
+        from_secret: twine_repository
+      TWINE_USERNAME:
+        from_secret: twine_username
+      TWINE_PASSWORD:
+        from_secret: twine_password
+    when:
+      event: tag
+
+depends_on:
+  - lint
+  - tests

duckenv-0.1.0/.woodpecker/tests.yml

@@ -0,0 +1,20 @@
+matrix:
+  PY_VERSION:
+    - 3.11
+    - 3.12
+    - 3.13
+    - 3.14
+
+steps:
+  tests:
+    image: python:${PY_VERSION}-slim
+    environment:
+      PIP_ROOT_USER_ACTION: ignore
+    commands:
+      - pip install .[tests]
+      - coverage run -m unittest -v tests.py
+      - coverage report -m
+    when:
+      - event: pull_request
+      - event: push
+        branch: main

duckenv-0.1.0/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: duckenv
+Version: 0.1.0
+Summary: A minimalist .env loader
+Project-URL: Homepage, https://codeberg.org/canarduck/duckenv
+Project-URL: Issues, https://codeberg.org/canarduck/duckenv/issues
+Author-email: Renaud Canarduck <renaud@canarduck.com>
+License-Expression: MIT
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: black; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Provides-Extra: tests
+Requires-Dist: coverage; extra == 'tests'
+Description-Content-Type: text/markdown
+
+# duckenv
+
+A minimalist dotenv loader for Python, inspired by [environs](https://github.com/sloria/environs) but with fewer features and dependencies.
+
+## Installation
+
+```bash
+pip install duckenv
+```
+
+## Usage
+
+Create a `.env` file:
+```env
+DEBUG=on
+TTL=30
+NAME=Jean-Michel
+MY_LIST=apple,banana,orange
+```
+
+Load and parse environment variables:
+
+```python
+from duckenv import Env
+
+env = Env()  # reads `.env` by default
+
+env.str("NAME")                    # "Jean-Michel"
+env.int("AGE")                     # 30
+env.bool("DEBUG")                  # True
+env.list("MY_LIST")                # ["apple", "banana", "orange"]
+env.str("MISSING_VAR", "default")  # "default"
+env.str("MISSING_VAR")             # Raises KeyError
+env.int("NAME")                    # Raises ValueError
+```
+
+## Supported Methods
+
+- `str(name, default=...)`: Returns a string or `None`.
+- `int(name, default=...)`: Returns an integer or `None`.
+- `bool(name, default=...)`: Accepts `true/false`, `on/off`, `1/0`, returns `True/False` or `None`.
+- `list(name, default=...)`: Parses comma-separated strings into a list of stripped strings, or accepts a list directly.
+
+If a variable is not set and no default is provided, a `KeyError` is raised.
+
+## License
+
+MIT

duckenv-0.1.0/README.md

@@ -0,0 +1,48 @@
+# duckenv
+
+A minimalist dotenv loader for Python, inspired by [environs](https://github.com/sloria/environs) but with fewer features and dependencies.
+
+## Installation
+
+```bash
+pip install duckenv
+```
+
+## Usage
+
+Create a `.env` file:
+```env
+DEBUG=on
+TTL=30
+NAME=Jean-Michel
+MY_LIST=apple,banana,orange
+```
+
+Load and parse environment variables:
+
+```python
+from duckenv import Env
+
+env = Env()  # reads `.env` by default
+
+env.str("NAME")                    # "Jean-Michel"
+env.int("AGE")                     # 30
+env.bool("DEBUG")                  # True
+env.list("MY_LIST")                # ["apple", "banana", "orange"]
+env.str("MISSING_VAR", "default")  # "default"
+env.str("MISSING_VAR")             # Raises KeyError
+env.int("NAME")                    # Raises ValueError
+```
+
+## Supported Methods
+
+- `str(name, default=...)`: Returns a string or `None`.
+- `int(name, default=...)`: Returns an integer or `None`.
+- `bool(name, default=...)`: Accepts `true/false`, `on/off`, `1/0`, returns `True/False` or `None`.
+- `list(name, default=...)`: Parses comma-separated strings into a list of stripped strings, or accepts a list directly.
+
+If a variable is not set and no default is provided, a `KeyError` is raised.
+
+## License
+
+MIT

duckenv-0.1.0/duckenv.py

@@ -0,0 +1,158 @@
+"""duckenv."""
+
+import os
+from pathlib import Path
+from typing import Any
+
+DEFAULT = object()
+
+
+class Env:
+    """A Minimalist dotenv loader.
+
+    Inspired by [environs](https://github.com/sloria/environs) with less features and
+    dependencies.
+    """
+
+    implemented_methods = ["str", "int", "bool", "list", "bool"]
+
+    def __init__(self, env_file: Path = Path(".env")) -> None:
+        """Loads `env_file` in the environnement variables.
+
+        Args:
+            env_file: the dotenv file
+        """
+        if not env_file.is_file():
+            raise FileNotFoundError(f"{env_file} does not exist")
+        for idx, line in enumerate(env_file.read_text().splitlines(), 1):
+            try:
+                name, value = line.split("=", 1)
+            except ValueError:
+                raise ValueError(
+                    f"Unable to parse line {idx} of {env_file}, must be NAME=value"
+                )
+            os.environ[name] = value
+
+    def __getattr__(self, method: str) -> None:
+        """Aliases implemented methods to their `get_` equivalent.
+
+        To avoid using defining `str`, `int` methods (which makes mypy unhappy, we use
+        `get_str`, `get_int` and handle their `natural` aliases here.
+
+        Args:
+            method: A method name (str, list, ...)
+
+        Raises:
+            NotImplementedError: the method (for example `dict`) is not implemented
+        """
+        if method in self.implemented_methods:
+            return getattr(self, f"get_{method}")
+        else:
+            raise NotImplementedError(f"Method {method} is not supported")
+
+    def _get(self, name: str, default: Any) -> Any:
+        """Get the value of `name` from the env variables.
+
+        Args:
+            name: variable's name
+            default: default value
+
+        Returns:
+            `name`'s value or `default`
+
+        Raises:
+            KeyError: `name` is not defined in the env and no `default` to use
+        """
+        if default == DEFAULT and name not in os.environ:
+            raise KeyError(f"Env var {name} is required")
+        return os.environ.get(name, default)
+
+    def get_str(self, name: str, default: Any = DEFAULT) -> str | None:
+        """Cast `name` in a string.
+
+        Args:
+            name: variable's name
+            default: default value if `name` is not defined in the env
+
+        Returns:
+            A string or None
+
+        Raises:
+            KeyError: `name` is not defined in the env and no `default` to use
+        """
+        value = self._get(name, default)
+        if value is None:
+            return None
+        return str(value)
+
+    def get_list(self, name: str, default: Any = DEFAULT) -> list | None:
+        """Cast `name` in a list.
+
+        This only handles a list of strings.
+
+        Args:
+            name: variable's name
+            default: default value if `name` is not defined in the env
+
+        Returns:
+            A list or None
+
+        Raises:
+            ValueError: `name`'s value is nor a list nor a comma-separated string
+            KeyError: `name` is not defined in the env and no `default` to use
+        """
+        value = self._get(name, default)
+        if value is None or isinstance(value, list):
+            return value
+        if not isinstance(value, str):
+            raise ValueError(
+                f"{name} must be a list or a string of comma-separated values, not {value} ({type(value)})"
+            )
+        return [v.strip() for v in value.split(",")]
+
+    def get_int(self, name: str, default: Any = DEFAULT) -> int | None:
+        """Cast `name` in an integer.
+
+        Args:
+            name: variable's name
+            default: default value if `name` is not defined in the env
+
+        Returns:
+            An integer or None
+
+        Raises:
+            KeyError: `name` is not defined in the env and no `default` to use
+        """
+        value = self._get(name, default)
+        if value is None or isinstance(value, int):
+            return value
+        try:
+            return int(value)
+        except ValueError:
+            raise ValueError(f"{name} is not int-able, « {value} » ({type(value)})")
+
+    def get_bool(self, name: str, default: Any = DEFAULT) -> bool | None:
+        """Cast `name` in a bool.
+
+        Args:
+            name: variable's name
+            default: default value if `name` is not defined in the env
+
+        Returns:
+            A boolean value or None
+
+        Raises:
+            ValueError: `name`'s value is not bool-able
+            KeyError: `name` is not defined in the env and no `default` to use
+        """
+        value = self._get(name, default)
+        if value is None or isinstance(value, bool):
+            return value
+        if value in [0, 1]:
+            return bool(value)
+        possible_values = {"on": True, "off": False, "1": True, "0": False}
+        if isinstance(value, str) and value in possible_values:
+            return possible_values[value]
+        raise ValueError(
+            f"{name} must be a bool, 0/1 or one of {', '.join(possible_values.keys())}, not « {value} » ({type(value)})"
+        )

duckenv-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "duckenv"
+version = "0.1.0"
+authors = [
+  { name="Renaud Canarduck", email="renaud@canarduck.com" },
+]
+description = "A minimalist .env loader"
+readme = "README.md"
+requires-python = ">=3.11"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+license = "MIT"
+
+[project.urls]
+Homepage = "https://codeberg.org/canarduck/duckenv"
+Issues = "https://codeberg.org/canarduck/duckenv/issues"
+
+[project.optional-dependencies]
+tests = ["coverage"]
+dev = [
+  "black",
+  "mypy",
+]
+
+[build-system]
+requires = ["hatchling >= 1.26"]
+build-backend = "hatchling.build"
+
+[tool.coverage.report]
+fail_under = 90
+
+[tool.coverage.run]
+branch = true
+source = ["."]

duckenv-0.1.0/tests.py

@@ -0,0 +1,152 @@
+import os
+import tempfile
+import unittest
+from pathlib import Path
+
+from duckenv import Env, DEFAULT
+
+test_env = """\
+NAME=Jean-Michel
+TTL=30
+DJANGO_DEBUG=on
+THIEVES=Margaret,Brittany, Prudence
+EMPTY=
+"""
+
+
+class TestEnv(unittest.TestCase):
+    def setUp(self):
+        self.temp_env_file = Path(tempfile.mktemp())
+        self.temp_env_file.write_text(test_env)
+        os.environ.clear()
+        self.env = Env(self.temp_env_file)
+
+    def tearDown(self):
+        self.temp_env_file.unlink()
+
+
+class TestInit(TestEnv):
+    def test_env_file_loaded(self):
+        self.assertEqual(os.environ["NAME"], "Jean-Michel")
+        self.assertEqual(os.environ["TTL"], "30")
+
+    def test_file_does_not_exist(self):
+        with self.assertRaisesRegex(FileNotFoundError, ".env does not exist"):
+            Env()  # .env does not exist by default
+
+    def test_invalid_file(self):
+        self.temp_env_file.write_text("\n".join(["OK=ok", "KO≃KO"]))
+        with self.assertRaisesRegex(ValueError, "Unable to parse line 2"):
+            Env(self.temp_env_file)
+
+
+class TestGetAttr(TestEnv):
+    def test_not_implemented(self):
+        with self.assertRaises(NotImplementedError):
+            self.env.dict("YO")
+
+    def test_handle_dunders(self):
+        self.assertIn("duckenv.Env", self.env.__str__())
+
+
+class TestGet(TestEnv):
+    def test_required_var_exists(self):
+        self.assertEqual(self.env._get("NAME", DEFAULT), "Jean-Michel")
+
+    def test_required_var_missing(self):
+        with self.assertRaisesRegex(KeyError, "Env var UNKNOWN is required"):
+            self.env._get("UNKNOWN", DEFAULT)
+
+    def test_with_default(self):
+        self.assertEqual(self.env._get("UNKNOWN", "default"), "default")
+
+
+class TestStr(TestEnv):
+    def test_existing_var(self):
+        self.assertEqual(self.env.str("NAME"), "Jean-Michel")
+
+    def test_empty_var(self):
+        self.assertEqual(self.env.str("EMPTY"), "")
+
+    def test_missing_with_default(self):
+        self.assertEqual(self.env.str("UNKNOWN", "default"), "default")
+        self.assertEqual(self.env.str("UNKNOWN", None), None)
+
+    def test_missing(self):
+        with self.assertRaisesRegex(KeyError, "Env var UNKNOWN is required"):
+            self.env.str("UNKNOWN")
+
+
+class TestList(TestEnv):
+    def test_from_comma_separated_string(self):
+        self.assertEqual(self.env.list("THIEVES"), ["Margaret", "Brittany", "Prudence"])
+
+    def test_from_string_no_commas(self):
+        self.assertEqual(self.env.list("NAME"), ["Jean-Michel"])
+
+    def test_from_list(self):
+        self.assertEqual(self.env.list("TEST_LIST", ["x", "y"]), ["x", "y"])
+
+    def test_invalid_type(self):
+        with self.assertRaises(ValueError):
+            self.env.list("TEST_DICT", {"a": 1})
+
+    def test_missing_with_default(self):
+        self.assertEqual(self.env.list("UNKNOWN", ["default"]), ["default"])
+
+    def test_missing(self):
+        with self.assertRaisesRegex(KeyError, "Env var UNKNOWN is required"):
+            self.env.list("UNKNOWN")
+
+
+class TestInt(TestEnv):
+    def test_conversion(self):
+        self.assertEqual(self.env.int("TTL"), 30)
+
+    def test_missing_with_default(self):
+        self.assertEqual(self.env.int("UNKNOWN", 42), 42)
+
+    def test_missing(self):
+        with self.assertRaisesRegex(KeyError, "Env var UNKNOWN is required"):
+            self.env.int("UNKNOWN")
+
+    def test_invalid_string(self):
+        os.environ["INVALID_INT"] = "not_a_number"
+        with self.assertRaisesRegex(ValueError, "INVALID_INT is not int-able"):
+            self.env.int("INVALID_INT")
+
+
+class TestBool(TestEnv):
+    def test_conversion(self):
+        self.assertTrue(self.env.bool("DJANGO_DEBUG"))
+
+    def test_possible_values(self):
+        os.environ["ON"] = "on"
+        os.environ["OFF"] = "off"
+        self.assertTrue(self.env.bool("ON"))
+        self.assertFalse(self.env.bool("OFF"))
+
+    def test_int(self):
+        os.environ["ZERO"] = "0"
+        os.environ["ONE"] = "1"
+        self.assertTrue(self.env.bool("ONE"))
+        self.assertFalse(self.env.bool("ZERO"))
+
+    def test_bool(self):
+        self.assertTrue(self.env.bool("BOOL_TRUE", True))
+        self.assertFalse(self.env.bool("BOOL_FALSE", False))
+        self.assertTrue(self.env.bool("BOOL_TRUE", 1))
+        self.assertFalse(self.env.bool("BOOL_FALSE", 0))
+
+    def test_invalid(self):
+        os.environ["INVALID_BOOL"] = "maybe"
+        with self.assertRaisesRegex(ValueError, "INVALID_BOOL must be a bool"):
+            self.env.bool("INVALID_BOOL")
+
+    def test_missing(self):
+        with self.assertRaisesRegex(KeyError, "Env var UNKNOWN is required"):
+            self.env.bool("UNKNOWN")
+
+    def test_missing_with_default(self):
+        self.assertIsNone(self.env.bool("UNKNOWN", None))
+        self.assertTrue(self.env.bool("UNKNOWN", True))