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,
        )

Typed descriptor for mapping a model field to a key in an AWS Secrets Manager secret.

Use this as Annotated metadata instead of a raw {"service": "secrets"} dict. All arguments are optional — omitting them falls back to the behaviour of the plain dict annotation.

Examples:

Map a field to a differently-named key in the secret::

class MySettings(SecretsManagerBaseSettings):
    model_config = AWSSettingsConfigDict(secrets_name="myapp/prod")

    db_password: Annotated[str, Secrets(field="password")]

Use the model field name as the key (equivalent to the raw dict annotation)::

db_host: Annotated[str, Secrets()]
Source code in pydantic_settings_aws/fields.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
@dataclass
class Secrets:
    """Typed descriptor for mapping a model field to a key in an AWS Secrets Manager secret.

    Use this as ``Annotated`` metadata instead of a raw ``{"service": "secrets"}`` dict.
    All arguments are optional — omitting them falls back to the behaviour of the
    plain dict annotation.

    Examples:
        Map a field to a differently-named key in the secret::

            class MySettings(SecretsManagerBaseSettings):
                model_config = AWSSettingsConfigDict(secrets_name="myapp/prod")

                db_password: Annotated[str, Secrets(field="password")]

        Use the model field name as the key (equivalent to the raw dict annotation)::

            db_host: Annotated[str, Secrets()]
    """

    field: str | None = None
    """The key to look up inside the secret's JSON object. When ``None``, the model field name is used as the key."""

    client: Any = dc_field(default=None, repr=False)
    """A pre-constructed ``boto3`` Secrets Manager client to use for this field. When ``None``, the client is resolved from :class:`AWSSettingsConfigDict` or created automatically."""

client = dc_field(default=None, repr=False) class-attribute instance-attribute

A pre-constructed boto3 Secrets Manager client to use for this field. When None, the client is resolved from :class:AWSSettingsConfigDict or created automatically.

field = None class-attribute instance-attribute

The key to look up inside the secret's JSON object. When None, the model field name is used as the key.

Typed descriptor for mapping a model field to an AWS SSM Parameter Store parameter.

Use this as Annotated metadata instead of a raw string or {"ssm": "...", "ssm_client": ...} dict. All arguments are optional — omitting them falls back to the behaviour of the plain string/dict annotation.

Examples:

Map a field to a specific parameter name::

class MySettings(ParameterStoreBaseSettings):
    db_host: Annotated[str, SSM(name="/prod/db/host")]

Use a per-field client for a multi-account setup::

class MySettings(ParameterStoreBaseSettings):
    prod_host: Annotated[str, SSM(name="/prod/db/host", client=prod_client)]
    staging_host: Annotated[str, SSM(name="/staging/db/host", client=staging_client)]

Use the model field name as the parameter name::

mongodb_host: Annotated[str, SSM()]
Source code in pydantic_settings_aws/fields.py 
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
@dataclass
class SSM:
    """Typed descriptor for mapping a model field to an AWS SSM Parameter Store parameter.

    Use this as ``Annotated`` metadata instead of a raw string or
    ``{"ssm": "...", "ssm_client": ...}`` dict. All arguments are optional —
    omitting them falls back to the behaviour of the plain string/dict annotation.

    Examples:
        Map a field to a specific parameter name::

            class MySettings(ParameterStoreBaseSettings):
                db_host: Annotated[str, SSM(name="/prod/db/host")]

        Use a per-field client for a multi-account setup::

            class MySettings(ParameterStoreBaseSettings):
                prod_host: Annotated[str, SSM(name="/prod/db/host", client=prod_client)]
                staging_host: Annotated[str, SSM(name="/staging/db/host", client=staging_client)]

        Use the model field name as the parameter name::

            mongodb_host: Annotated[str, SSM()]
    """

    name: str | None = None
    """The SSM parameter name or ARN to retrieve. When ``None``, the model field name is used as the parameter name."""

    client: Any = dc_field(default=None, repr=False)
    """A pre-constructed ``boto3`` SSM client to use for this field. When ``None``, the client is resolved from :class:`AWSSettingsConfigDict` or created automatically. Useful for per-field multi-account or multi-region setups."""

client = dc_field(default=None, repr=False) class-attribute instance-attribute

A pre-constructed boto3 SSM client to use for this field. When None, the client is resolved from :class:AWSSettingsConfigDict or created automatically. Useful for per-field multi-account or multi-region setups.

name = None class-attribute instance-attribute

The SSM parameter name or ARN to retrieve. When None, the model field name is used as the parameter name.

Bases: Exception

Base exception for all pydantic-settings-aws errors.

Source code in pydantic_settings_aws/errors.py 
1
2
class PydanticSettingsAWSError(Exception):
    """Base exception for all pydantic-settings-aws errors."""

Bases: PydanticSettingsAWSError

Base exception for AWS Secrets Manager errors.

Source code in pydantic_settings_aws/errors.py 
13
14
class SecretsManagerError(PydanticSettingsAWSError):
    """Base exception for AWS Secrets Manager errors."""

Bases: SecretsManagerError

Raised when the requested secret does not exist in Secrets Manager.

Source code in pydantic_settings_aws/errors.py 
17
18
class SecretNotFoundError(SecretsManagerError):
    """Raised when the requested secret does not exist in Secrets Manager."""

Bases: SecretsManagerError

Raised when a secret exists but its content is empty or missing.

Source code in pydantic_settings_aws/errors.py 
21
22
class SecretContentError(SecretsManagerError):
    """Raised when a secret exists but its content is empty or missing."""

Bases: SecretsManagerError

Raised when the secret content cannot be decoded as valid JSON.

Source code in pydantic_settings_aws/errors.py 
25
26
class SecretDecodeError(SecretsManagerError):
    """Raised when the secret content cannot be decoded as valid JSON."""

Bases: PydanticSettingsAWSError

Base exception for AWS SSM Parameter Store errors.

Source code in pydantic_settings_aws/errors.py 
29
30
class SSMError(PydanticSettingsAWSError):
    """Base exception for AWS SSM Parameter Store errors."""

Bases: SSMError

Raised when the requested parameter does not exist in Parameter Store.

Source code in pydantic_settings_aws/errors.py 
33
34
class ParameterNotFoundError(SSMError):
    """Raised when the requested parameter does not exist in Parameter Store."""

Bases: PydanticSettingsAWSError

Raised when a boto3 client cannot be created.

Source code in pydantic_settings_aws/errors.py 
5
6
class AWSClientError(PydanticSettingsAWSError):
    """Raised when a boto3 client cannot be created."""

Bases: PydanticSettingsAWSError

Raised when the settings configuration is invalid or missing required fields.

Source code in pydantic_settings_aws/errors.py 
 9
10
class AWSSettingsConfigError(PydanticSettingsAWSError):
    """Raised when the settings configuration is invalid or missing required fields."""