v1.0.9

Fixed

• Custom separator parsing now correctly respects custom separators across parser and CLI flows.
• Async loading now honors TOMLEV_STRICT_DISABLE the same way as synchronous loading.
• Include merge isolation now deep-copies reused payloads to prevent cross-table alias leakage.

Enhanced

• Refactored substitution logic into smaller parser helpers with cached separator-aware regex patterns.
• Removed async temporary-file roundtrips by sharing .env content parsing between sync and async paths.
• Unified CLI env-building behavior and standardized CLI error output to stderr.

Convenience Function tomlev(...), new streamlined function for one-line configuration loading

• Convenience Function tomlev(): New streamlined function for one-line configuration loading
• Shorthand for TomlEv(...).validate() pattern
• Simplifies the most common use case with a single function call
• Accepts same parameters as TomlEv class: cls, toml_file, env_file, strict, include_environment
• Returns validated configuration model directly
• Full backward compatibility - existing TomlEv class approach continues to work
• Example usage:

# New simple approach
config = tomlev(AppConfig, "env.toml", ".env")

# Equivalent to existing approach
config = TomlEv(AppConfig, "env.toml", ".env").validate()

• When to use: Perfect for simple configuration loading without needing access to .environ, .strict, or .raw
  properties
• Comprehensive test coverage with new tests in test_simple.py
• Fully documented with Google-style docstrings and examples

Python 3.14 Support

Added

• Python 3.14 Support: Full compatibility with Python 3.14
  • Updated CI/CD pipeline to test on Python 3.14 across all platforms (Ubuntu, Windows, macOS)
  • Updated mypy configuration to use Python 3.14 (python_version = "3.14")
  • Updated ruff configuration to focus on Python 3.14 (target-version = "py314")
  • Compatible with PEP 649 (deferred annotation evaluation)
  • Compatible with PEP 750 (template string literals)
  • Compatible with PEP 779 (free-threaded Python)
  • Compatible with all Python 3.14 new features and optimizations

Enhanced

• Updated development tooling to support Python 3.14 syntax and features
• CI/CD now validates across Python 3.11, 3.12, 3.13, and 3.14
• Updated ruff pre-commit hook to v0.12.5 for better Python 3.14 support
• Improved future compatibility with the latest Python releases

v1.0.5 - Improved exception handling and performance

Fixed

• Improved Exception Handling: Replaced assert statement with proper ConfigValidationError for unknown configuration attributes

  • Previously used assert which could be disabled with Python's -O optimization flag
  • Now raises ConfigValidationError with detailed error messages for unknown keys
  • Better runtime validation and error reporting

• Enhanced CLI Error Handling: Replaced broad exception catching with specific exception types

  • Changed from generic Exception to specific exceptions: OSError, IOError, PermissionError, ValueError, TypeError
  • Better error categorization and more informative error messages
  • Improved debugging experience for users

Performance

• Optimized String Processing in Parser: Significantly improved performance for large configuration files

  • Replaced O(n²) string concatenation with O(n) segment-based approach
  • Implemented single-pass replacement algorithm sorted by length to avoid partial replacements
  • Added LRU cache (maxsize=32) for file reads to avoid repeated disk I/O
  • Benchmarks show consistent performance improvements across all configuration sizes

• Optimized Default Value Handling: Improved memory efficiency for configuration models

  • Deep copy only performed on mutable defaults (list, dict, set)
  • Immutable types (str, int, float, bool, tuple, None) returned directly
  • Reduced unnecessary object copying overhead

Enhanced

• Better Error Context: Added file path information to all parsing errors

  • Environment variable errors now include source file location
  • TOML parsing errors display the problematic file path
  • Improved debugging and troubleshooting experience

• Improved Code Quality: Enhanced variable naming and code readability

  • Renamed shifting variable to use cleaner segment-based approach
  • Renamed replaces to substitutions for better clarity
  • Improved code maintainability and comprehensibility

Added

• Comprehensive Examples: Added production-ready example implementations

  • examples/basic/: Simple configuration loading with environment variables
  • examples/advanced/: Complex configs with includes, custom types, and nested structures
  • examples/integrations/: FastAPI integration with dependency injection
  • Each example includes runnable code, configuration files, and detailed README

• Mutation Testing Support: Added configuration for mutation testing with mutmut

  • Added mutmut~=3.3.0 to development dependencies
  • Created .mutmut_config configuration file
  • Added [tool.mutmut] section to pyproject.toml
  • Enables verification of test suite quality

Quality

• All Quality Checks Passing: Achieved 100% success rate on comprehensive quality suite
  • Ruff linting: No issues
  • Ruff formatting: All 33 files properly formatted
  • MyPy type checking: Success in strict mode
  • Bandit security scan: No security issues (1,322 LOC scanned)
  • Docstring coverage: Passed
  • Code complexity: Average B rating (6.37)
  • Maintainability index: All modules rated A
  • Test coverage: 91.42% (exceeds 90% requirement)
  • Property-based tests: All 7 tests passing

Support for set and tuple types

Added

• Support for set and tuple types: Added type conversion support for set[T] and tuple[T, ...] types
  • New convert_set function to convert TOML lists to Python sets with proper type conversion
  • New convert_tuple function to convert TOML lists to Python tuples with position-based type conversion
  • Extended convert_generic_type to handle set and tuple origins
  • Added default value support for set and tuple types in get_default_value
  • Enables configuration models to use set types for unique collections
  • Enables configuration models to use tuple types for fixed-size immutable sequences

Enhanced

• Comprehensive test coverage for set and tuple types: Added extensive test suites for robust type conversion
  • New test_set_types.py with tests for all set type conversions, deduplication, and edge cases
  • New test_tuple_types.py with tests for position-based type conversion, overflow handling, and immutability
  • Improved overall test coverage to ensure reliability of new type conversions

Added support for setting default file paths via environment variables

[1.0.3] - 2025-01-14

Added

• Environment Variable Defaults for File Paths: New support for setting default file paths via environment variables
  • TOMLEV_TOML_FILE: Sets the default TOML configuration file path
  • TOMLEV_ENV_FILE: Sets the default .env file path
  • Useful for CI/CD pipelines and containerized environments
  • Precedence order: explicit arguments > environment variables > hardcoded defaults
  • Works with both CLI commands (validate, render) and Python API
  • Example usage:

    export TOMLEV_TOML_FILE="config/production.toml"
    export TOMLEV_ENV_FILE="config/.env.production"
    tomlev validate  # Uses environment variable defaults

  • Added comprehensive tests to verify functionality
  • Updated documentation with usage examples

v1.0.2

[1.0.2] - 2025-01-13

Added

• Major Refactoring for Improved Maintainability:

  • Created 8 new focused modules to better organize the codebase:
    • constants.py: Centralized configuration constants
    • patterns.py: Regex patterns for parsing
    • errors.py: Custom exception classes with factory methods
    • env_loader.py: Environment file handling logic
    • include_handler.py: TOML include directive processing
    • parser.py: TOML parsing and substitution logic
    • cli.py: CLI command logic
    • converters.py: Type conversion methods

• CLI Render Command: New render command for outputting resolved configuration as JSON

  • Processes TOML files with full environment variable substitution and include resolution
  • Outputs pretty-formatted JSON with 2-space indentation for readability
  • Useful for debugging configuration resolution and integration with other tools
  • Supports same arguments as validate command for consistency

• CLI Version Support: Added -V/--version flag to display current version

  • Works from any CLI context for quick version checking
  • Centralized version management through constants module

• Include Directive Support: New __include feature for composing TOML configurations from multiple files

  • Supports single file: __include = "file.toml"
  • Supports multiple files: __include = ["file1.toml", "file2.toml"]
  • Recursive include resolution with cycle detection
  • Relative path resolution from parent TOML file
  • Deep merge of included configurations
  • Caching of included files for performance

• Enhanced Error Handling:

  • New specialized exception classes: EnvironmentVariableError, IncludeError, TypeConversionError
  • Factory methods for common error scenarios
  • Better error messages with more context

• Improved Test Coverage and Organization:

  • New test module test_include_feature.py for include directive testing
  • Decoupled monolithic test file into focused modules:
    • test_type_conversions.py: Union, Optional, nested model, and literal type tests
    • test_core_features.py: Raw config access and dollar escape tests
    • test_env_file_parsing.py: Advanced .env file parsing edge cases
    • test_cli_commands.py: CLI validate and render command tests
  • Additional edge case coverage with maintained 90%+ test coverage

Enhanced

• Code Organization:

  • Reduced __main__.py from 549 to 181 lines (-67%)
  • Reduced __model__.py from 389 to 169 lines (-57%)
  • Better separation of concerns with single-responsibility modules
  • Improved import structure and dependency management
  • Reorganized test suite into focused, maintainable modules for better discoverability

• Type Safety:

  • Better handling of typing.Any in generic collections
  • Enhanced type conversion for complex nested structures
  • Improved Union and Optional type handling

• Performance:

  • Include file caching to avoid redundant parsing
  • Optimized pattern matching in type conversions

Fixed

• Fixed TypeError when handling list[dict[str, Any]] with mixed item types
• Corrected type conversion issues with typing.Any instantiation
• Resolved import ordering and unused import issues

Changed

• Modularized codebase structure for better maintainability
• Moved type conversion logic to dedicated converters.py module
• Separated CLI functionality into cli.py module
• Extracted environment file handling to env_loader.py

v1.0.1 - Improvements in error handling

Fixed

• Breaking: Error handling now uses ConfigValidationError instead of ValueError for configuration validation
  errors
• Undefined environment variable errors in strict mode now raise appropriate ConfigValidationError
• Consistent exception handling across the entire codebase for configuration-related errors

Added

• New test case test_undefined_variable_raises_config_validation_error to ensure proper exception handling
• Multi-platform quality checks now run on Ubuntu, Windows, and macOS in CI/CD pipeline
• Comprehensive workflow documentation with detailed job descriptions and dependency explanations
• TDD (Test-Driven Development) workflow documentation
• Comprehensive quality check enforcement in development workflow

Enhanced

• CI/CD Pipeline Improvements:
  • Mandatory quality gates with continue-on-error: false on all critical steps
  • Quality checks achieve 100% success rate requirement before deployment
  • Cross-platform cache handling for Windows vs Unix systems
  • Enhanced job dependencies ensuring no deployment without quality validation
  • Improved workflow structure with clear documentation and failure handling
• Better error messages and validation consistency throughout the library
• Test coverage for edge cases in strict mode validation

Changed

• GitHub Actions workflow now enforces mandatory quality checks across all platforms
• Quality checks must pass on Ubuntu, Windows, and macOS before package building
• CI/CD pipeline structure enhanced with explicit job dependencies and failure conditions
• Development workflow now mandates running uv run scripts/quality_check.py after any code changes
• Enhanced development guidelines with mandatory quality assurance requirements

TomlEv 1.0.0 - Production Release

TomlEv 1.0.0 - Production Release 🎉

Type-safe TOML configuration management for Python 3.11+

Release Highlights

TomlEv 1.0.0 marks the production-ready release of this lightweight configuration framework that brings type safety and modern Python features to environment variable management.

🚀 Key Features

• Type-Safe Configuration Models - Define configuration schemas with Python classes and automatic type validation
• Environment Variable Substitution - Seamless ${VAR|-default} syntax in TOML files
• Zero Dependencies - Pure Python implementation using only stdlib
• Modern Python 3.11+ - Leverages pattern matching, type aliases, and advanced type hints
• Comprehensive Type Support - Handles str, int, float, bool, lists, dicts, and nested models
• Production Ready - 91%+ test coverage, security scanning, and quality checks

📊 Quality Metrics

• ✅ 91.38% test coverage with pytest
• ✅ 100% type safe with strict mypy checking
• ✅ Zero security issues verified by Bandit
• ✅ 100% docstring coverage for public APIs
• ✅ Grade B complexity via Radon analysis
• ✅ Ruff compliant code formatting

🎯 What's New in 1.0.0

• Enhanced CI/CD Pipeline - Modern GitHub Actions with quality gates, artifact builds, and PyPI publishing
• Professional Package Structure - Complete with py.typed marker, comprehensive classifiers, and metadata
• Developer Experience - Full IDE support with autocompletion and type checking
• Robust Testing - Property-based testing with Hypothesis, performance benchmarks, edge case coverage
• Documentation - Complete API docs, contribution guidelines, security policy, and changelog

💻 Quick Start

from tomlev import BaseConfigModel, TomlEv

class AppConfig(BaseConfigModel):
debug: bool
database_url: str
port: int

Load with automatic type conversion and validation

config = TomlEv(AppConfig).validate()

📦 Installation

pip install tomlev==1.0.0

or

uv add tomlev@1.0.0

🔗 Links

• Documentation: https://github.com/thesimj/tomlev
• PyPI: https://pypi.org/project/tomlev/
• Issues: https://github.com/thesimj/tomlev/issues

🙏 Acknowledgments

Thank you to all contributors and users who helped shape TomlEv into a production-ready tool. Special thanks to the Python community for feedback during the alpha phase.

---

Breaking Change: This release requires Python 3.11 or later. Users on older Python versions should continue using v0.9.x.

v0.2.2

Full Changelog: v0.2.1...v0.2.2