Settings & Configuration

API reference for the Pydantic V2 Settings module, SettingsProxy lazy loader, framework boundaries, and environment initializers.

The Settings class parses and validates environment variables and file-based sources (.env). It integrates directly with ZCore's IoC container to support singleton management and provides a dynamic proxy for lazy resolution.

Class Definition

import os
from pydantic_settings import BaseSettings, SettingsConfigDict
from zcore.config import Settings

class Settings(BaseSettings):
    model_config = SettingsConfigDict(
        env_file=os.getenv("ENV_FILE", ".env"),
        extra="ignore",
        case_sensitive=True
    )

Core Configuration Attributes

Prop

Type

Nested Configuration Models

`DatabaseSettings`

Schema defining connection pool and execution parameters for SQLAlchemy asynchronous engines:

from pydantic import BaseModel, Field
from typing import Any

class DatabaseSettings(BaseModel):
    url: str = "sqlite+aiosqlite:///zcore.db"
    pool_size: int = 5
    max_overflow: int = 10
    pool_recycle: int = 1800
    pool_pre_ping: bool = True
    echo: bool = False
    connect_args: dict[str, Any] = Field(default_factory=dict)
    execution_options: dict[str, Any] = Field(default_factory=dict)
    extra_engine_kwargs: dict[str, Any] = Field(default_factory=dict)

Prop

Type

`LoggingSettings`

Schema configuring structured logging, file rotation parameters, and SQL query interception:

from pydantic import BaseModel, Field
from typing import Any

class LoggingSettings(BaseModel):
    level: str = "INFO"
    json_format: bool | None = None
    log_sql_queries: bool = False
    slow_query_threshold_ms: float | None = None
    file_path: str | None = None
    max_bytes: int = 10 * 1024 * 1024
    backup_count: int = 5
    muted_loggers: list[str] = Field(
        default_factory=lambda: [
            "sqlalchemy.engine",
        ]
    )
    passthrough_loggers: list[str] = Field(
        default_factory=lambda: [
            "uvicorn",
            "uvicorn.access",
            "uvicorn.error",
        ]
    )
    intercept_loggers: list[str] = Field(
        default_factory=lambda: [
            "uvicorn",
            "uvicorn.access",
            "uvicorn.error",
        ]
    )
    custom_processors: list[Any] = Field(default_factory=list)

Prop

Type

The Settings Proxy (Lazy Resolution)

ZCore exposes a global settings object via SettingsProxy:

from zcore import settings

Lazy Resolution Architecture: When you import settings, you are importing a dynamic SettingsProxy object. Configuration lookups are resolved against the active registered Settings singleton only when an attribute is accessed. This eliminates circular import errors and prevents premature database pool instantiation during module loading.

Helper Functions

`initialize_settings`

Registers a settings instance (or custom subclass) into the IoC container as a Singleton. If a subclass is provided, it binds both the subclass and the base Settings interface.

from zcore.config import initialize_settings

initialize_settings(AppSettings())

Prop

Type

`get_settings`

Resolves the active settings singleton from the IoC container. If uninitialized, it automatically instantiates and registers the specified class as a fallback.

from zcore.config import get_settings

active_settings = get_settings()

Prop

Type

On this page