Skip to content

API Reference

Bases: SettingsConfigDict

Configuration dictionary for AWS-backed pydantic-settings sources.

Extends :class:pydantic_settings.SettingsConfigDict with options specific to AWS Secrets Manager and AWS Systems Manager (SSM) Parameter Store sources.

Example::

class MySettings(SecretsManagerBaseSettings):
    model_config = AWSSettingsConfigDict(
        secrets_name="myapp/prod/db",
        aws_region="us-east-1",
    )

    db_host: str
    db_password: str
Source code in pydantic_settings_aws/config.py 
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
class AWSSettingsConfigDict(SettingsConfigDict, total=False):
    """Configuration dictionary for AWS-backed pydantic-settings sources.

    Extends :class:`pydantic_settings.SettingsConfigDict` with options specific to
    AWS Secrets Manager and AWS Systems Manager (SSM) Parameter Store sources.

    Example::

        class MySettings(SecretsManagerBaseSettings):
            model_config = AWSSettingsConfigDict(
                secrets_name="myapp/prod/db",
                aws_region="us-east-1",
            )

            db_host: str
            db_password: str
    """

    # boto3 session args
    aws_region: str | None
    """AWS region name (e.g. ``"us-east-1"``). When ``None``, boto3 falls back to the standard credential chain."""

    aws_profile: str | None
    """Named AWS CLI / boto3 profile to use. When ``None``, the default profile is used."""

    aws_access_key_id: str | None
    """Explicit AWS access key ID. Should be paired with ``aws_secret_access_key``. When ``None``, boto3 resolves credentials through the standard chain."""

    aws_secret_access_key: str | None
    """Explicit AWS secret access key. Should be paired with ``aws_access_key_id``. When ``None``, boto3 resolves credentials through the standard chain."""

    aws_session_token: str | None
    """Temporary session token, required when using short-lived STS credentials. When ``None``, boto3 resolves credentials through the standard chain."""

    # Secrets Manager args
    secrets_name: str
    """Name or full ARN of the Secrets Manager secret to retrieve. Required when using ``SecretsManagerSettingsSource``."""

    secrets_version: str | None
    """Version ID (UUID) of the secret. When ``None``, the latest version labelled ``AWSCURRENT`` is returned."""

    secrets_stage: str | None
    """Version stage label of the secret (e.g. ``"AWSCURRENT"`` or ``"AWSPREVIOUS"``). When ``None``, defaults to ``AWSCURRENT``."""

    secrets_client: Any
    """Pre-constructed ``boto3`` Secrets Manager client. Useful for injecting custom clients in tests. When not provided, a client is created automatically."""

    # SSM Parameter Store args
    ssm_client: Any
    """Pre-constructed ``boto3`` SSM client. Useful for injecting custom clients in tests. When not provided, a client is created automatically."""

aws_access_key_id instance-attribute

Explicit AWS access key ID. Should be paired with aws_secret_access_key. When None, boto3 resolves credentials through the standard chain.

aws_profile instance-attribute

Named AWS CLI / boto3 profile to use. When None, the default profile is used.

aws_region instance-attribute

AWS region name (e.g. "us-east-1"). When None, boto3 falls back to the standard credential chain.

aws_secret_access_key instance-attribute

Explicit AWS secret access key. Should be paired with aws_access_key_id. When None, boto3 resolves credentials through the standard chain.

aws_session_token instance-attribute

Temporary session token, required when using short-lived STS credentials. When None, boto3 resolves credentials through the standard chain.

secrets_client instance-attribute

Pre-constructed boto3 Secrets Manager client. Useful for injecting custom clients in tests. When not provided, a client is created automatically.

secrets_name instance-attribute

Name or full ARN of the Secrets Manager secret to retrieve. Required when using SecretsManagerSettingsSource.

secrets_stage instance-attribute

Version stage label of the secret (e.g. "AWSCURRENT" or "AWSPREVIOUS"). When None, defaults to AWSCURRENT.

secrets_version instance-attribute

Version ID (UUID) of the secret. When None, the latest version labelled AWSCURRENT is returned.

ssm_client instance-attribute

Pre-constructed boto3 SSM client. Useful for injecting custom clients in tests. When not provided, a client is created automatically.

Bases: BaseSettings

Base settings class that loads values from a single AWS Secrets Manager secret.

The secret must contain a JSON object whose keys map to the model's field names. The secret is fetched once at instantiation time and cached for the lifetime of the source.

Requires secrets_name to be set in :class:AWSSettingsConfigDict.

Source priority order: init > Secrets Manager > env > dotenv > file secrets.

Source code in pydantic_settings_aws/settings.py 
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
class SecretsManagerBaseSettings(BaseSettings):
    """Base settings class that loads values from a single AWS Secrets Manager secret.

    The secret must contain a JSON object whose keys map to the model's field
    names. The secret is fetched once at instantiation time and cached for the
    lifetime of the source.

    Requires ``secrets_name`` to be set in :class:`AWSSettingsConfigDict`.

    Source priority order: init > Secrets Manager > env > dotenv > file secrets.
    """

    @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, ...]:
        return (
            init_settings,
            SecretsManagerSettingsSource(settings_cls),
            env_settings,
            dotenv_settings,
            file_secret_settings,
        )

Bases: BaseSettings

Base settings class that loads values from AWS SSM Parameter Store.

By default each field name is used as the parameter name. Use Annotated to override the parameter name with a string or a dict (the latter also allows supplying a per-field ssm_client).

Fields whose parameter is not found in Parameter Store are silently skipped and resolved by the remaining pydantic-settings sources (environment variables, dotenv, etc.).

Source priority order: init > Parameter Store > env > dotenv > file secrets.

Source code in pydantic_settings_aws/settings.py 
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
class ParameterStoreBaseSettings(BaseSettings):
    """Base settings class that loads values from AWS SSM Parameter Store.

    By default each field name is used as the parameter name. Use ``Annotated``
    to override the parameter name with a string or a dict (the latter also
    allows supplying a per-field ``ssm_client``).

    Fields whose parameter is not found in Parameter Store are silently skipped
    and resolved by the remaining pydantic-settings sources (environment
    variables, dotenv, etc.).

    Source priority order: init > Parameter Store > env > dotenv > file secrets.
    """

    @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, ...]:
        return (
            init_settings,
            ParameterStoreSettingsSource(settings_cls),
            env_settings,
            dotenv_settings,
            file_secret_settings,
        )

Bases: BaseSettings

Base settings class that loads values from both AWS Secrets Manager and SSM Parameter Store.

Fields are routed to the appropriate AWS source via Annotated metadata: use {"service": "secrets"} for Secrets Manager and {"service": "ssm"} for Parameter Store. Fields without AWS metadata fall through to the standard pydantic-settings sources (environment variables, dotenv, etc.).

Source priority order: init > AWS > env > dotenv > file secrets.

Source code in pydantic_settings_aws/settings.py 
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
class AWSBaseSettings(BaseSettings):
    """Base settings class that loads values from both AWS Secrets Manager and SSM Parameter Store.

    Fields are routed to the appropriate AWS source via ``Annotated`` metadata:
    use ``{"service": "secrets"}`` for Secrets Manager and ``{"service": "ssm"}``
    for Parameter Store. Fields without AWS metadata fall through to the standard
    pydantic-settings sources (environment variables, dotenv, etc.).

    Source priority order: init > AWS > env > dotenv > file secrets.
    """

    @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, ...]:
        return (
            init_settings,
            AWSSettingsSource(settings_cls),
            env_settings,
            dotenv_settings,
            file_secret_settings,
        )