Advanced configuration management for Python applications with smart caching, template resolution, multi-format support, and seamless Pydantic integration.
mountainash-settings provides sophisticated configuration management that goes beyond standard Pydantic BaseSettings. It offers smart caching, template resolution, multi-format configuration files (YAML, TOML, JSON), and a powerful parameter system - all while maintaining the familiar Pydantic interface developers love.
pip install mountainash-settings# Clone and install in development mode
git clone <repository-url>
cd mountainash-settings
pip install -e .from pydantic import Field
from mountainash_settings import MountainAshBaseSettings
class AppSettings(MountainAshBaseSettings):
"""Application settings with smart caching and template support."""
debug: bool = Field(default=False)
app_name: str = Field(default="MyApp")
database_url: str = Field(default="sqlite:///app.db")
log_file: str = Field(default="logs/{app_name}.log") # Template support
# Simple usage - works like standard Pydantic
settings = AppSettings()
print(settings.app_name) # "MyApp"
# With runtime overrides
settings = AppSettings(debug=True, app_name="ProductionApp")
print(settings.debug) # True
# Smart caching with get_settings()
cached_settings = AppSettings.get_settings(
namespace="production",
config_files=["config.yaml"],
debug=True
)
# Template resolution
log_path = settings.format_template_from_settings("logs/{app_name}_debug.log")
print(log_path) # "logs/ProductionApp_debug.log"Create config.yaml:
debug: false
app_name: "MyWebApp"
database_url: "postgresql://localhost/myapp"from mountainash_settings import MountainAshBaseSettings
from pydantic_settings import SettingsConfigDict
class ConfigSettings(MountainAshBaseSettings):
debug: bool = Field(default=True)
app_name: str = Field(default="DefaultApp")
database_url: str = Field(default="sqlite:///default.db")
model_config = SettingsConfigDict(yaml_file="config.yaml")
settings = ConfigSettings()
print(settings.app_name) # "MyWebApp" (from YAML file)from mountainash_settings import SettingsParameters
# Create reusable parameter configurations
params = SettingsParameters.create(
namespace="microservice_auth",
settings_class=AppSettings,
config_files=["base.yaml", "auth.yaml"],
env_prefix="AUTH_",
debug=False, # Runtime override
app_name="AuthService"
)
# Use with any compatible settings class
settings = AppSettings.get_settings(settings_parameters=params)
print(settings.app_name) # "AuthService"
print(settings.SETTINGS_NAMESPACE) # "microservice_auth"
# Works with any MountainAshBaseSettings class
params = SettingsParameters.create(
namespace="microservice_auth",
settings_class=AppSettings,
config_files=["base.yaml", "auth.yaml"],
env_prefix="AUTH_",
debug=False,
app_name="AuthService"
)- Enhanced Pydantic Interface: Extended BaseSettings with advanced functionality
- Template Support: Dynamic field substitution with
{field_name}placeholders - Multi-Format Configuration: YAML, TOML, JSON support out of the box
- Smart Caching: Intelligent instance caching and management
- Structural Parameter Caching: Cache based on namespace, config files, and class structure
- Runtime Override Support: Apply kwargs without affecting cache identity
- Memory Efficient: Intelligent cache key generation and cleanup
- Cross-Application Support: Share cached instances across modules
- Dynamic Configuration: Use
{field_name}placeholders in any string field - Post-Initialization Processing: Templates resolved automatically after object creation
- Flexible API:
format_template_from_settings()for ad-hoc formatting - Custom Logic Support: Integrate with custom
post_init()methods
- Universal Support: YAML, TOML, JSON, and .env files
- Priority System: Hierarchical configuration loading with clear precedence
- File Validation: Automatic validation that configuration files exist
- Environment Integration: Seamless environment variable support
- Reusable Configuration: Create parameter objects for consistent settings
- Dynamic Resolution: SettingsParameters carry type information for runtime resolution
- Serialization Safe: Store and transmit configuration parameters securely
- JIT Security: Just-in-time settings loading to minimize secret exposure
- Complex Scenarios: Support for multi-tenant and dynamic configuration needs
- Full Traceability: Track configuration sources, files, and overrides
- Debugging Support: Comprehensive metadata for troubleshooting
- Configuration Audit: Know exactly where each setting value came from
- Parameter Reconstruction: Extract SettingsParameters from any instance
- Authentication Integration: Built-in support for database, storage, and secret providers
- Secret Management: Integration with AWS, Azure, GCP, and HashiCorp Vault
- Performance Optimized: Minimal overhead with intelligent caching strategies
- Production Tested: Battle-tested in large-scale applications
- CLAUDE.md - Complete development guide and API reference
- Examples - Working code examples and patterns
- TESTING.md - Testing guidelines and procedures
- CONTRIBUTING.md - Contribution guidelines
- CLAUDE.md - Development guide and technical details
- Mountain Ash Documentation - Complete ecosystem docs
from mountainash_settings import MountainAshBaseSettings
from pydantic_settings import SettingsConfigDict
# High-performance service
class HighPerfSettings(MountainAshBaseSettings):
api_timeout: int = Field(default=5)
max_connections: int = Field(default=100)
# Complex configuration service with templates
class ComplexAppSettings(MountainAshBaseSettings):
environment: str = Field(default="dev")
service_name: str = Field(default="myapp")
# Template-based paths
log_dir: str = Field(default="logs/{environment}/{service_name}")
config_file: str = Field(default="config/{service_name}/{environment}.yaml")
model_config = SettingsConfigDict(
yaml_file=["base.yaml", "{environment}.yaml"],
env_prefix="APP_"
)
# Testing settings
class TestSettings(MountainAshBaseSettings):
test_database: str = Field(default="sqlite:///:memory:")
mock_external_apis: bool = Field(default=True)# Multi-tenant configuration
def create_tenant_settings(tenant_id: str):
class TenantSettings(MountainAshBaseSettings):
database_url: str = Field(default="sqlite:///default.db")
feature_flags: dict = Field(default_factory=dict)
@classmethod
def get_namespace(cls):
return f"tenant_{tenant_id}"
return TenantSettings
# Environment-based configuration
class EnvironmentAwareSettings(MountainAshBaseSettings):
debug: bool = Field(default=False)
log_level: str = Field(default="INFO")
model_config = SettingsConfigDict(
yaml_file=[
"base.yaml",
f"{os.getenv('ENVIRONMENT', 'dev')}.yaml",
"local.yaml" # Optional local overrides
]
)
@classmethod
def get_namespace(cls):
return f"app_{os.getenv('ENVIRONMENT', 'dev')}"MountainAshBaseSettings provides powerful patterns for complex configuration scenarios:
from mountainash_settings import MountainAshBaseSettings, SettingsParameters
class AppSettings(MountainAshBaseSettings):
debug: bool = Field(default=False)
app_name: str = Field(default="MyApp")
database_url: str = Field(default="sqlite:///app.db")
# Smart caching with SettingsParameters
params = SettingsParameters.create(
namespace="production",
settings_class=AppSettings,
config_files=["config.yaml"],
debug=True
)
# Cached instance - subsequent calls return same instance
settings = AppSettings.get_settings(settings_parameters=params)Key Benefits:
- ✅ Smart Caching: Intelligent instance management and caching
- ✅ Template Support: Dynamic field substitution
- ✅ Multi-Format Config: YAML, TOML, JSON support
- ✅ Enterprise Ready: Production-tested performance and features
- ✅ Full Observability: Complete configuration traceability
# Run all tests
hatch run test:test
# Run with coverage
hatch run test:cov
# Run specific tests
pytest tests/test_base_settings.py -v
# Performance benchmarks
pytest tests/test_base_settings.py::TestBaseSettingsPerformance -v# Code linting
hatch run ruff:check
# Auto-fix issues
hatch run ruff:fix
# Type checking
hatch run mypy:check# Build package
hatch build
# Clean build artifacts
hatch cleanSee CLAUDE.md for complete development commands.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes with tests
- Run tests and linting (
hatch run test:test && hatch run ruff:check) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
git clone https://github.com/mountainash-io/mountainash-settings.git
cd mountainash-settings
pip install -e .
hatch env create # Set up development environment- ✅ Smart Caching: Automatically cache settings for better performance
- ✅ Template Support: Dynamic configuration with
{field}placeholders - ✅ Multi-Format Files: YAML, TOML, JSON support out of the box
- ✅ Configuration Reuse: SettingsParameters for consistent configuration
- ✅ Metadata Tracking: Full observability of configuration sources
- ✅ Pydantic Integration: Built on Pydantic for validation and type safety
- ✅ Enterprise Features: Secret management, authentication, multi-tenancy
- ✅ Production Ready: Battle-tested caching and performance optimizations
- ✅ Developer Experience: Familiar interface with powerful features
- ✅ Incremental Adoption: Use only the features you need
MIT License - see LICENSE file for details.
This package is part of the Mountain Ash ecosystem of Python packages for building production-ready applications.
- mountainash-core: Core utilities and foundations
- mountainash-auth: Authentication and authorization
- mountainash-data: Data processing and analysis tools
- mountainash-api: API development utilities
Ready to get started? Check out our CLAUDE.md development guide or try the examples!