crashbytes-envguard 1.0.0__tar.gz

crashbytes_envguard-1.0.0/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @CrashBytes

crashbytes_envguard-1.0.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.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: ruff check src/ tests/
+      - run: mypy --strict src/
+      - run: pytest --cov=crashbytes_envguard --cov-branch --cov-fail-under=90

crashbytes_envguard-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,19 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ["*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

crashbytes_envguard-1.0.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+*.pyo
+dist/
+build/
+*.egg-info/
+.coverage
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+

crashbytes_envguard-1.0.0/LICENSE

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

crashbytes_envguard-1.0.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: crashbytes-envguard
+Version: 1.0.0
+Summary: Lightweight environment variable validation with schema, type coercion, and .env loading.
+Project-URL: Homepage, https://github.com/CrashBytes/crashbytes-envguard
+Project-URL: Repository, https://github.com/CrashBytes/crashbytes-envguard
+Project-URL: Issues, https://github.com/CrashBytes/crashbytes-envguard/issues
+Author-email: CrashBytes <crashbytes@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: config,dotenv,env,environment,validation
+Classifier: Development Status :: 5 - Production/Stable
+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: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# crashbytes-envguard
+
+Lightweight environment variable validation with schema, type coercion, and .env loading.
+
+## Install
+
+```bash
+pip install crashbytes-envguard
+```
+
+## Usage
+
+```python
+from crashbytes_envguard import create_env, s
+
+env = create_env({
+    "PORT": s.port().default(8080),
+    "DB_URL": s.url(),
+    "DEBUG": s.boolean().default(False),
+    "LOG_LEVEL": s.string().choices("debug", "info", "warn", "error").default("info"),
+})
+
+print(env["PORT"])      # 8080 (int, type-coerced)
+print(env["DB_URL"])    # "https://..." (validated)
+print(env["DEBUG"])     # False (bool, type-coerced)
+```
+
+Fails fast with **all** errors at once:
+
+```
+EnvError: Environment validation failed:
+  - DB_URL: required but not set
+  - PORT: must be >= 1 (got 0)
+```
+
+## Schema Types
+
+| Builder | Type | Extra Validation |
+|---------|------|-----------------|
+| `s.string()` | `str` | — |
+| `s.integer()` | `int` | — |
+| `s.number()` | `float` | — |
+| `s.boolean()` | `bool` | true/1/yes/on, false/0/no/off |
+| `s.port()` | `int` | 1–65535 |
+| `s.url()` | `str` | Must start with http(s):// |
+| `s.email()` | `str` | Must be valid email format |
+
+## Field Modifiers
+
+`.default(value)`, `.optional()`, `.choices(...)`, `.min(n)`, `.max(n)`, `.pattern(regex)`
+
+## License
+
+MIT

crashbytes_envguard-1.0.0/README.md

@@ -0,0 +1,54 @@
+# crashbytes-envguard
+
+Lightweight environment variable validation with schema, type coercion, and .env loading.
+
+## Install
+
+```bash
+pip install crashbytes-envguard
+```
+
+## Usage
+
+```python
+from crashbytes_envguard import create_env, s
+
+env = create_env({
+    "PORT": s.port().default(8080),
+    "DB_URL": s.url(),
+    "DEBUG": s.boolean().default(False),
+    "LOG_LEVEL": s.string().choices("debug", "info", "warn", "error").default("info"),
+})
+
+print(env["PORT"])      # 8080 (int, type-coerced)
+print(env["DB_URL"])    # "https://..." (validated)
+print(env["DEBUG"])     # False (bool, type-coerced)
+```
+
+Fails fast with **all** errors at once:
+
+```
+EnvError: Environment validation failed:
+  - DB_URL: required but not set
+  - PORT: must be >= 1 (got 0)
+```
+
+## Schema Types
+
+| Builder | Type | Extra Validation |
+|---------|------|-----------------|
+| `s.string()` | `str` | — |
+| `s.integer()` | `int` | — |
+| `s.number()` | `float` | — |
+| `s.boolean()` | `bool` | true/1/yes/on, false/0/no/off |
+| `s.port()` | `int` | 1–65535 |
+| `s.url()` | `str` | Must start with http(s):// |
+| `s.email()` | `str` | Must be valid email format |
+
+## Field Modifiers
+
+`.default(value)`, `.optional()`, `.choices(...)`, `.min(n)`, `.max(n)`, `.pattern(regex)`
+
+## License
+
+MIT

crashbytes_envguard-1.0.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "crashbytes-envguard"
+version = "1.0.0"
+description = "Lightweight environment variable validation with schema, type coercion, and .env loading."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "CrashBytes", email = "crashbytes@users.noreply.github.com" }]
+keywords = ["env", "environment", "validation", "config", "dotenv"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "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",
+    "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+dev = ["pytest", "pytest-cov", "mypy", "ruff"]
+
+[project.urls]
+Homepage = "https://github.com/CrashBytes/crashbytes-envguard"
+Repository = "https://github.com/CrashBytes/crashbytes-envguard"
+Issues = "https://github.com/CrashBytes/crashbytes-envguard/issues"
+
+[tool.ruff]
+target-version = "py310"
+line-length = 99
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "UP", "B", "SIM", "TCH"]
+
+[tool.mypy]
+strict = true
+python_version = "3.10"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.coverage.run]
+branch = true
+source = ["crashbytes_envguard"]
+
+[tool.coverage.report]
+fail_under = 90

crashbytes_envguard-1.0.0/src/crashbytes_envguard/__init__.py

@@ -0,0 +1,5 @@
+"""crashbytes-envguard — Lightweight environment variable validation."""
+
+from crashbytes_envguard._core import EnvError, SchemaField, create_env, load_dotenv, s
+
+__all__ = ["EnvError", "SchemaField", "create_env", "load_dotenv", "s"]

crashbytes_envguard-1.0.0/src/crashbytes_envguard/_core.py

@@ -0,0 +1,220 @@
+"""Environment variable validation with schema, type coercion, and .env loading."""
+
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+class EnvError(Exception):
+    """Raised when environment validation fails."""
+
+    def __init__(self, errors: list[str]) -> None:
+        self.errors = errors
+        msg = "Environment validation failed:\n" + "\n".join(f"  - {e}" for e in errors)
+        super().__init__(msg)
+
+
+@dataclass
+class _FieldSpec:
+    name: str
+    coerce: type[Any]
+    required: bool = True
+    default: Any = None
+    choices: list[Any] = field(default_factory=list)
+    min_val: float | None = None
+    max_val: float | None = None
+    pattern: str | None = None
+    custom_name: str | None = None
+
+
+class SchemaField:
+    """Builder for a single environment variable schema field."""
+
+    def __init__(self, coerce: type[Any] = str) -> None:
+        self._coerce = coerce
+        self._required = True
+        self._default: Any = None
+        self._choices: list[Any] = []
+        self._min_val: float | None = None
+        self._max_val: float | None = None
+        self._pattern: str | None = None
+
+    def default(self, value: Any) -> SchemaField:
+        """Set a default value (makes the field optional)."""
+        self._default = value
+        self._required = False
+        return self
+
+    def optional(self) -> SchemaField:
+        """Mark as optional with no default (value will be ``None`` if missing)."""
+        self._required = False
+        return self
+
+    def choices(self, *values: Any) -> SchemaField:
+        """Restrict to a set of allowed values."""
+        self._choices = list(values)
+        return self
+
+    def min(self, value: float) -> SchemaField:
+        """Set minimum value (numeric fields)."""
+        self._min_val = value
+        return self
+
+    def max(self, value: float) -> SchemaField:
+        """Set maximum value (numeric fields)."""
+        self._max_val = value
+        return self
+
+    def pattern(self, regex: str) -> SchemaField:
+        """Require the value to match a regex pattern."""
+        self._pattern = regex
+        return self
+
+    def _to_spec(self, name: str) -> _FieldSpec:
+        return _FieldSpec(
+            name=name,
+            coerce=self._coerce,
+            required=self._required,
+            default=self._default,
+            choices=self._choices,
+            min_val=self._min_val,
+            max_val=self._max_val,
+            pattern=self._pattern,
+        )
+
+
+class s:  # noqa: N801
+    """Schema builder — shorthand for defining field types."""
+
+    @staticmethod
+    def string() -> SchemaField:
+        return SchemaField(str)
+
+    @staticmethod
+    def integer() -> SchemaField:
+        return SchemaField(int)
+
+    @staticmethod
+    def number() -> SchemaField:
+        return SchemaField(float)
+
+    @staticmethod
+    def boolean() -> SchemaField:
+        return SchemaField(bool)
+
+    @staticmethod
+    def port() -> SchemaField:
+        """Integer constrained to 1–65535."""
+        return SchemaField(int).min(1).max(65535)
+
+    @staticmethod
+    def url() -> SchemaField:
+        """String that must start with http:// or https://."""
+        return SchemaField(str).pattern(r"^https?://")
+
+    @staticmethod
+    def email() -> SchemaField:
+        """String that must be a valid email format."""
+        return SchemaField(str).pattern(r"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$")
+
+
+def _coerce_bool(raw: str) -> bool:
+    low = raw.lower()
+    if low in ("true", "1", "yes", "on"):
+        return True
+    if low in ("false", "0", "no", "off"):
+        return False
+    raise ValueError(f"Cannot convert {raw!r} to bool")
+
+
+def _coerce_value(raw: str, target: type[Any]) -> Any:
+    if target is bool:
+        return _coerce_bool(raw)
+    return target(raw)
+
+
+def load_dotenv(path: str | Path = ".env") -> None:
+    """Load variables from a .env file into ``os.environ``."""
+    p = Path(path)
+    if not p.exists():
+        return
+    for line in p.read_text().splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        key = key.strip()
+        value = value.strip()
+        # Strip surrounding quotes
+        if len(value) >= 2 and value[0] == value[-1] and value[0] in ('"', "'"):
+            value = value[1:-1]
+        os.environ.setdefault(key, value)
+
+
+def create_env(
+    schema: dict[str, SchemaField],
+    *,
+    env_file: str | Path | None = ".env",
+) -> dict[str, Any]:
+    """Validate environment variables against *schema*.
+
+    Loads from *env_file* first (if it exists), then validates every field.
+    Collects **all** errors before raising.
+
+    Returns a dict of coerced values.
+    """
+    if env_file is not None:
+        load_dotenv(env_file)
+
+    errors: list[str] = []
+    result: dict[str, Any] = {}
+
+    for name, field_builder in schema.items():
+        spec = field_builder._to_spec(name)  # noqa: SLF001
+        raw = os.environ.get(name)
+
+        if raw is None or raw == "":
+            if spec.required:
+                errors.append(f"{name}: required but not set")
+                continue
+            result[name] = spec.default
+            continue
+
+        try:
+            value = _coerce_value(raw, spec.coerce)
+        except (ValueError, TypeError):
+            errors.append(f"{name}: cannot convert {raw!r} to {spec.coerce.__name__}")
+            continue
+
+        if spec.choices and value not in spec.choices:
+            errors.append(f"{name}: must be one of {spec.choices} (got {value!r})")
+            continue
+
+        if spec.min_val is not None and isinstance(value, (int, float)) and value < spec.min_val:
+            errors.append(f"{name}: must be >= {spec.min_val} (got {value})")
+            continue
+
+        if spec.max_val is not None and isinstance(value, (int, float)) and value > spec.max_val:
+            errors.append(f"{name}: must be <= {spec.max_val} (got {value})")
+            continue
+
+        if (
+            spec.pattern is not None
+            and isinstance(value, str)
+            and not re.match(spec.pattern, value)
+        ):
+            errors.append(f"{name}: must match pattern {spec.pattern!r} (got {value!r})")
+            continue
+
+        result[name] = value
+
+    if errors:
+        raise EnvError(errors)
+
+    return result

crashbytes_envguard-1.0.0/tests/test_envguard.py

@@ -0,0 +1,227 @@
+"""Tests for crashbytes-envguard."""
+
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING
+
+import pytest
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+from crashbytes_envguard import EnvError, create_env, load_dotenv, s
+
+
+@pytest.fixture(autouse=True)
+def _clean_env(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Remove test env vars before each test."""
+    for key in ["PORT", "DB_URL", "DEBUG", "APP_NAME", "HOST", "WORKERS", "LOG_LEVEL", "EMAIL"]:
+        monkeypatch.delenv(key, raising=False)
+
+
+class TestSchemaTypes:
+    def test_string(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("APP_NAME", "myapp")
+        result = create_env({"APP_NAME": s.string()}, env_file=None)
+        assert result["APP_NAME"] == "myapp"
+
+    def test_integer(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("PORT", "8080")
+        result = create_env({"PORT": s.integer()}, env_file=None)
+        assert result["PORT"] == 8080
+
+    def test_number(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("WORKERS", "3.5")
+        result = create_env({"WORKERS": s.number()}, env_file=None)
+        assert result["WORKERS"] == 3.5
+
+    def test_boolean_true(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        for val in ["true", "1", "yes", "on", "True", "YES"]:
+            monkeypatch.setenv("DEBUG", val)
+            result = create_env({"DEBUG": s.boolean()}, env_file=None)
+            assert result["DEBUG"] is True
+
+    def test_boolean_false(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        for val in ["false", "0", "no", "off", "False", "NO"]:
+            monkeypatch.setenv("DEBUG", val)
+            result = create_env({"DEBUG": s.boolean()}, env_file=None)
+            assert result["DEBUG"] is False
+
+    def test_boolean_invalid(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("DEBUG", "maybe")
+        with pytest.raises(EnvError, match="cannot convert"):
+            create_env({"DEBUG": s.boolean()}, env_file=None)
+
+    def test_port(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("PORT", "443")
+        result = create_env({"PORT": s.port()}, env_file=None)
+        assert result["PORT"] == 443
+
+    def test_port_out_of_range(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("PORT", "99999")
+        with pytest.raises(EnvError, match="must be <="):
+            create_env({"PORT": s.port()}, env_file=None)
+
+    def test_port_zero(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("PORT", "0")
+        with pytest.raises(EnvError, match="must be >="):
+            create_env({"PORT": s.port()}, env_file=None)
+
+    def test_url(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("DB_URL", "https://db.example.com")
+        result = create_env({"DB_URL": s.url()}, env_file=None)
+        assert result["DB_URL"] == "https://db.example.com"
+
+    def test_url_invalid(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("DB_URL", "ftp://nope")
+        with pytest.raises(EnvError, match="must match pattern"):
+            create_env({"DB_URL": s.url()}, env_file=None)
+
+    def test_email(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("EMAIL", "user@example.com")
+        result = create_env({"EMAIL": s.email()}, env_file=None)
+        assert result["EMAIL"] == "user@example.com"
+
+    def test_email_invalid(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("EMAIL", "not-an-email")
+        with pytest.raises(EnvError, match="must match pattern"):
+            create_env({"EMAIL": s.email()}, env_file=None)
+
+
+class TestDefaults:
+    def test_default_value(self) -> None:
+        result = create_env({"PORT": s.port().default(8080)}, env_file=None)
+        assert result["PORT"] == 8080
+
+    def test_optional_none(self) -> None:
+        result = create_env({"HOST": s.string().optional()}, env_file=None)
+        assert result["HOST"] is None
+
+    def test_env_overrides_default(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("PORT", "3000")
+        result = create_env({"PORT": s.port().default(8080)}, env_file=None)
+        assert result["PORT"] == 3000
+
+
+class TestValidation:
+    def test_required_missing(self) -> None:
+        with pytest.raises(EnvError, match="required but not set"):
+            create_env({"PORT": s.port()}, env_file=None)
+
+    def test_empty_string_treated_as_missing(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("PORT", "")
+        with pytest.raises(EnvError, match="required but not set"):
+            create_env({"PORT": s.port()}, env_file=None)
+
+    def test_choices(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("LOG_LEVEL", "info")
+        result = create_env(
+            {"LOG_LEVEL": s.string().choices("debug", "info", "warn", "error")},
+            env_file=None,
+        )
+        assert result["LOG_LEVEL"] == "info"
+
+    def test_choices_invalid(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("LOG_LEVEL", "verbose")
+        with pytest.raises(EnvError, match="must be one of"):
+            create_env(
+                {"LOG_LEVEL": s.string().choices("debug", "info", "warn", "error")},
+                env_file=None,
+            )
+
+    def test_min_max(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("WORKERS", "4")
+        result = create_env(
+            {"WORKERS": s.integer().min(1).max(16)},
+            env_file=None,
+        )
+        assert result["WORKERS"] == 4
+
+    def test_pattern(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("HOST", "abc123")
+        result = create_env(
+            {"HOST": s.string().pattern(r"^[a-z0-9]+$")},
+            env_file=None,
+        )
+        assert result["HOST"] == "abc123"
+
+    def test_pattern_invalid(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("HOST", "ABC!")
+        with pytest.raises(EnvError, match="must match pattern"):
+            create_env(
+                {"HOST": s.string().pattern(r"^[a-z0-9]+$")},
+                env_file=None,
+            )
+
+    def test_coerce_failure(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("PORT", "abc")
+        with pytest.raises(EnvError, match="cannot convert"):
+            create_env({"PORT": s.integer()}, env_file=None)
+
+    def test_multiple_errors(self) -> None:
+        with pytest.raises(EnvError) as exc_info:
+            create_env(
+                {"PORT": s.port(), "DB_URL": s.url()},
+                env_file=None,
+            )
+        assert len(exc_info.value.errors) == 2
+
+
+class TestDotEnv:
+    def test_load_dotenv(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        env_file = tmp_path / ".env"
+        env_file.write_text('PORT=9090\nAPP_NAME="my app"\n')
+        monkeypatch.delenv("PORT", raising=False)
+        monkeypatch.delenv("APP_NAME", raising=False)
+        load_dotenv(env_file)
+        assert os.environ.get("PORT") == "9090"
+        assert os.environ.get("APP_NAME") == "my app"
+
+    def test_dotenv_with_comments(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        env_file = tmp_path / ".env"
+        env_file.write_text("# comment\nPORT=8080\n\n")
+        monkeypatch.delenv("PORT", raising=False)
+        load_dotenv(env_file)
+        assert os.environ.get("PORT") == "8080"
+
+    def test_dotenv_single_quotes(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        env_file = tmp_path / ".env"
+        env_file.write_text("APP_NAME='my app'\n")
+        monkeypatch.delenv("APP_NAME", raising=False)
+        load_dotenv(env_file)
+        assert os.environ.get("APP_NAME") == "my app"
+
+    def test_dotenv_missing_file(self) -> None:
+        load_dotenv("/nonexistent/.env")  # Should not raise
+
+    def test_dotenv_no_equals(self, tmp_path: Path) -> None:
+        env_file = tmp_path / ".env"
+        env_file.write_text("NOPE\n")
+        load_dotenv(env_file)  # Should skip lines without =
+
+    def test_dotenv_does_not_override(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        env_file = tmp_path / ".env"
+        env_file.write_text("PORT=9090\n")
+        monkeypatch.setenv("PORT", "3000")
+        load_dotenv(env_file)
+        assert os.environ.get("PORT") == "3000"
+
+    def test_create_env_with_dotenv(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        env_file = tmp_path / ".env"
+        env_file.write_text("PORT=4000\n")
+        monkeypatch.delenv("PORT", raising=False)
+        result = create_env({"PORT": s.port()}, env_file=env_file)
+        assert result["PORT"] == 4000
+
+
+class TestEnvError:
+    def test_error_message(self) -> None:
+        err = EnvError(["PORT: required", "DB_URL: required"])
+        assert "PORT: required" in str(err)
+        assert "DB_URL: required" in str(err)
+        assert len(err.errors) == 2