doc: add lazy loading documentation

Author: fede-bello

docs/index.md

@@ -2932,3 +2932,298 @@ mutable_settings.__init__()
 print(mutable_settings.foo)
 #> foo
 ```
+
+## Lazy Loading
+
+Lazy loading defers field value resolution until fields are actually accessed, rather than eagerly fetching all values during settings initialization. This is particularly useful when working with cloud secret managers where each field access triggers an API call, avoiding unnecessary network requests for fields that may never be used.
+
+### Overview
+
+By default, pydantic-settings eagerly resolves all field values from all configured sources during initialization. For cloud secret managers like AWS Secrets Manager, Azure Key Vault, or Google Cloud Secret Manager, this means every field triggers an API call to fetch the secret value, even if the application never uses that field.
+
+**When to use lazy loading:**
+
+* You use cloud secret managers (AWS Secrets Manager, Azure Key Vault, GCP Secret Manager)
+* Your settings have many fields but your application only uses a subset of them
+* You want to reduce initialization time and API call costs
+* Network latency to secret managers is significant
+
+**Trade-offs:**
+
+* Fields are resolved when first accessed, not during initialization, so errors surface later
+* There's a small overhead on first access to each field (caching minimizes subsequent accesses)
+* `model_dump()` and other full-model operations will trigger resolution of all fields
+
+### Basic Usage
+
+You can enable lazy loading in two ways:
+
+**1. Global configuration via SettingsConfigDict:**
+
+```py
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(lazy_load=True)
+
+    api_key: str
+    database_url: str
+    debug_mode: bool
+```
+
+**2. Per-source configuration via settings_customise_sources:**
+
+```py
+import os
+
+from pydantic_settings import (
+    AWSSecretsManagerSettingsSource,
+    BaseSettings,
+    PydanticBaseSettingsSource,
+)
+
+
+class Settings(BaseSettings):
+    api_key: str
+    database_url: str
+
+    @classmethod
+    def settings_customise_sources(
+        cls,
+        settings_cls: type[BaseSettings],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,
+        file_secret_settings: PydanticBaseSettingsSource,
+    ) -> tuple[PydanticBaseSettingsSource, ...]:
+        aws_settings = AWSSecretsManagerSettingsSource(
+            settings_cls,
+            secret_id=os.environ['AWS_SECRET_ID'],
+            lazy_load=True,  # Enable lazy loading only for AWS Secrets Manager
+        )
+        return (
+            init_settings,
+            env_settings,
+            dotenv_settings,
+            aws_settings,
+            file_secret_settings,
+        )
+```
+
+### Cloud Secret Managers with Lazy Loading
+
+Lazy loading provides significant performance benefits when using cloud secret managers. Here are examples for each provider:
+
+#### AWS Secrets Manager
+
+```py
+import os
+from unittest.mock import MagicMock, patch
+
+from pydantic import Field
+
+from pydantic_settings import (
+    AWSSecretsManagerSettingsSource,
+    BaseSettings,
+    PydanticBaseSettingsSource,
+)
+
+
+class Settings(BaseSettings):
+    # These fields will only be fetched from AWS Secrets Manager when accessed
+    api_key: str = Field(validation_alias='MyApiKey')
+    database_password: str = Field(validation_alias='DbPassword')
+    encryption_key: str = Field(validation_alias='EncryptionKey')
+
+    @classmethod
+    def settings_customise_sources(
+        cls,
+        settings_cls: type[BaseSettings],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,
+        file_secret_settings: PydanticBaseSettingsSource,
+    ) -> tuple[PydanticBaseSettingsSource, ...]:
+        # Mock AWS credentials for demonstration
+        with patch.dict(os.environ, {'AWS_SECRETS_MANAGER_SECRET_ID': 'my-secret'}):
+            aws_secrets = AWSSecretsManagerSettingsSource(
+                settings_cls,
+                secret_id=os.environ['AWS_SECRETS_MANAGER_SECRET_ID'],
+                lazy_load=True,
+            )
+        return (
+            init_settings,
+            env_settings,
+            dotenv_settings,
+            aws_secrets,
+            file_secret_settings,
+        )
+
+
+# Initialization is fast - no API calls made yet
+settings = Settings()
+
+# With lazy_load=True, accessing fields would trigger AWS API calls
+# In production, this would fetch from AWS Secrets Manager
+# settings.api_key  # Would call AWS API if credentials were available
+```
+
+#### Azure Key Vault
+
+```py
+from unittest.mock import MagicMock, patch
+
+from pydantic import Field
+
+from pydantic_settings import (
+    AzureKeyVaultSettingsSource,
+    BaseSettings,
+    PydanticBaseSettingsSource,
+)
+
+
+class Settings(BaseSettings):
+    api_key: str = Field(validation_alias='MyApiKey')
+    database_password: str = Field(validation_alias='DbPassword')
+
+    @classmethod
+    def settings_customise_sources(
+        cls,
+        settings_cls: type[BaseSettings],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,
+        file_secret_settings: PydanticBaseSettingsSource,
+    ) -> tuple[PydanticBaseSettingsSource, ...]:
+        # Mock Azure credentials for demonstration
+        with patch('pydantic_settings.sources.providers.azure.import_azure_key_vault'):
+            with patch('pydantic_settings.sources.providers.azure.SecretClient'):
+                mock_credential = MagicMock()
+                azure_keyvault = AzureKeyVaultSettingsSource(
+                    settings_cls,
+                    vault_url='https://myvault.vault.azure.net/',
+                    credential=mock_credential,
+                    lazy_load=True,
+                )
+        return (
+            init_settings,
+            env_settings,
+            dotenv_settings,
+            azure_keyvault,
+            file_secret_settings,
+        )
+
+
+# Quick initialization - no Azure API calls made
+settings = Settings()
+
+# Fields resolved on first access (would call Azure API in production)
+# settings.api_key
+```
+
+#### Google Cloud Secret Manager
+
+```py
+import os
+from unittest.mock import MagicMock, patch
+
+from pydantic import Field
+
+from pydantic_settings import (
+    BaseSettings,
+    GoogleSecretManagerSettingsSource,
+    PydanticBaseSettingsSource,
+)
+
+
+class Settings(BaseSettings):
+    api_key: str = Field(validation_alias='MyApiKey')
+    database_password: str = Field(validation_alias='DbPassword')
+
+    @classmethod
+    def settings_customise_sources(
+        cls,
+        settings_cls: type[BaseSettings],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,
+        file_secret_settings: PydanticBaseSettingsSource,
+    ) -> tuple[PydanticBaseSettingsSource, ...]:
+        # Mock GCP credentials for demonstration
+        with patch('pydantic_settings.sources.providers.gcp.google_auth_default', return_value=(MagicMock(), 'my-project')):
+            with patch('pydantic_settings.sources.providers.gcp.SecretManagerServiceClient'):
+                gcp_secrets = GoogleSecretManagerSettingsSource(
+                    settings_cls,
+                    project_id=os.environ.get('GCP_PROJECT_ID', 'my-project'),
+                    lazy_load=True,
+                )
+        return (
+            init_settings,
+            env_settings,
+            dotenv_settings,
+            gcp_secrets,
+            file_secret_settings,
+        )
+
+
+# Fast initialization - no GCP API calls made
+settings = Settings()
+
+# First access would trigger GCP Secret Manager API call (in production)
+# settings.api_key
+```
+
+### Behavior and Caching
+
+When lazy loading is enabled:
+
+1. **Initialization**: Settings are created with minimal overhead. Sources return empty dictionaries instead of eagerly fetching all values.
+
+2. **First Access**: When you access a field for the first time (e.g., `settings.api_key`), the value is fetched from the configured source and cached in memory.
+
+3. **Subsequent Access**: Accessing the same field again returns the cached value without making another API call.
+
+4. **All Fields**: Iteration over all fields (via `model_dump()`, etc.) will trigger resolution of all fields at once.
+
+```py
+from pydantic_settings import (
+    AWSSecretsManagerSettingsSource,
+    BaseSettings,
+    PydanticBaseSettingsSource,
+)
+
+
+class Settings(BaseSettings):
+    secret1: str
+    secret2: str
+
+    @classmethod
+    def settings_customise_sources(
+        cls,
+        settings_cls: type[BaseSettings],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,
+        file_secret_settings: PydanticBaseSettingsSource,
+    ) -> tuple[PydanticBaseSettingsSource, ...]:
+        aws_settings = AWSSecretsManagerSettingsSource(
+            settings_cls, secret_id='my-secret', lazy_load=True
+        )
+        return (init_settings, env_settings, dotenv_settings, aws_settings, file_secret_settings)
+
+
+settings = Settings()
+
+# Only secret1 is fetched from AWS Secrets Manager
+print(settings.secret1)
+
+# secret1 is already cached, so this doesn't trigger another API call
+print(settings.secret1)
+
+# secret2 is fetched on first access
+print(settings.secret2)
+
+# This triggers fetching of all remaining fields not yet accessed
+all_values = settings.model_dump()
+```