Skip to content

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

1.1.0 (2026-09-01)

Features

  • add read_environ load knob, plus typing fixes and a docs accuracy pass (#68) (a061acc)

1.0.0 (2026-08-31)

⚠ BREAKING CHANGES

  • a string default containing ${VAR} text resolves at load time instead of being taken literally; an unset reference yields "" where the raw ${...} text was kept before.
  • load()/reload()/cached() no longer mutate os.environ — call python-dotenv load_dotenv() yourself if you relied on injection. override default flipped True -> False; real env vars now beat .env files unless override=True or DOTENV_OVERRIDE=true. load_env_files() removed in favor of read_env_files(), a pure reader returning a DotenvLayer (later file wins, bare keys left unset like load_dotenv()). loaded_with() returns LoadParams instead of a 3-tuple and raises RuntimeError on instances never loaded from the environment. boolean load params are now bool | None with DOTENV_OVERRIDE/DOTENV_READ_DOTFILES/DOTENV_LOAD_LOCAL env-var overrides (unrecognized values warn and fall back to the default). .local files are skipped by default when env is test (case-insensitive) — extending the Next.js/dotenv-flow rule, which skips only .env.local in test, to all .local files, because a gitignored .env.test.local must not decide test outcomes either (load_local=True or DOTENV_LOAD_LOCAL=true restores them).

Features

  • field_validator decorator with before and after modes (#65) (f50b97d)
  • interpolate references in string defaults (#62) (27ec71d)
  • resolve config without mutating os.environ (#60) (15b6386)

Bug Fixes

  • compare unwrapped secrets against choices (#63) (c7abdeb)

Continuous Integration

  • pin actions, gate publishing, trim permissions, lock the sdist (#64) (1c382b3)

0.6.3 (2026-07-28)

Bug Fixes

  • reload() must update the instance's recorded load arguments (#56) (a293461)

0.6.2 (2026-07-28)

Bug Fixes

  • warn on cached() argument disagreement, not on non-default args (#54) (ba80777)

0.6.1 (2026-07-27)

Bug Fixes

  • eliminate cross-class reentrancy deadlock in cached() locking (#52) (592297a)

0.6.0 (2026-07-27)

Features

  • add cached() / reset_cached() / cached_override() singleton accessor (#51) (638f8cc)

Continuous Integration

0.5.4 (2026-07-22)

Continuous Integration

  • local self-contained publish workflow with attestations off (#46) (1f72487)

0.5.3 (2026-07-22)

Continuous Integration

  • publish via centralized reusable workflow (#44) (d653161)

0.5.2 (2026-07-22)

Continuous Integration

  • standardize publish workflow on org template (pypa action, conditional attestations) (#42) (32960d4)

0.5.1 (2026-07-22)

Continuous Integration

  • activate release-please manifest mode; fix stale version seeds (#40) (91fb40a)

0.5.0 (2026-07-21)

Features

  • add post_load hook for cross-field validation and normalization (78bcef1)
  • add post_load hook for cross-field validation and normalization (#39) (39241ed)

Bug Fixes

  • mask hook-authored constraint in sensitive validator errors (6f99371)

Documentation

  • correct post_load raise-propagation boundary, document partial reload (9ec9a00)
  • document post_load cross-field validation hook (536c981)
  • post_load discoverability and secrets-warning scope (895566e)
  • qualify post_load claims for validate=False and reload paths (0786c8d)
  • qualify post_load raise propagation for nested ValidationError (40416b6)

0.4.0 (2026-07-20)

Features

  • add strip, starts_with/ends_with, and custom validator hook to Field (#36) (8e4210e)

0.3.2 (2026-07-15)

Bug Fixes

  • resolve nested DotEnvConfig field defaults not being loaded (#34) (4a3bb88)

0.3.1 (2026-07-13)

Bug Fixes

  • redact credentials in DSN repr, errors, docs, and secret exception chains (#29) (cfdd218)

0.3.0 (2026-07-09)

Features

  • release readiness for public open-source release (#20) (43937d0)

0.2.0 (2025-12-05)

Features

  • add describe functionality for configuration classes and related tests (#6) (49767ea)

0.1.1 (2025-12-05)

Bug Fixes

  • update PyPI publishing workflow configuration (f854abb)
  • update PyPI publishing workflow configuration (8c3ed30)

0.1.0 (2025-12-05)

Features

  • v0.1.0 - Complete type-safe environment configuration library (#1) (7e9b2a9)

0.1.0 - 2025-12-05

Added

  • Core Configuration System
  • DotEnvConfig base class with metaclass-based field discovery
  • Type-safe field definitions with full IntelliSense support

  • Automatic type coercion for common Python types

  • Type Support

  • Basic types: str, int, float, bool, Path
  • Collection types: list, set, tuple, dict
  • Special types: UUID, Decimal, datetime, timedelta
  • URL/DSN types: HttpUrl, PostgresDsn, RedisDsn
  • Security: SecretStr for sensitive values

  • Flexible: Json[T] for typed JSON parsing

  • Validation

  • Numeric constraints: ge, le, gt, lt
  • String constraints: min_length, max_length, regex
  • Choice validation
  • Collection size constraints: min_items, max_items

  • UUID version validation

  • Environment Management

  • Automatic .env file loading with cascading (.env, .env.{env}, .env.{env}.local)
  • Support for multiple environments (dev, prod, test, staging)
  • Custom .env file locations via env_dir parameter

  • Override control with override parameter

  • Advanced Features

  • Configuration Reload: reload() method to update config at runtime without creating new instances
  • Environment Prefixes: Class-level env_prefix to namespace environment variables
  • Field aliases for environment variable names
  • Default values and factories

  • Optional fields with proper None handling

  • Developer Experience

  • Comprehensive error messages with helpful hints
  • Optional logging support for debugging
  • load_from_dict() for testing without environment variables

  • Helper methods: dict(), get(), __repr__()

  • Testing & Quality

  • 315 comprehensive tests
  • 98% code coverage
  • Full type safety with py.typed marker
  • Linting with ruff

  • CI/CD ready configuration

  • Documentation

  • Comprehensive README with examples
  • Type safety and IntelliSense documentation
  • Complete API documentation
  • Advanced usage patterns and best practices

Changed

  • N/A (initial release)

Deprecated

  • N/A (initial release)

Removed

  • N/A (initial release)

Fixed

  • N/A (initial release)

Security

  • No known security issues