Metadata-Version: 2.4
Name: pydantic-settings-aws
Version: 1.2.0b1
Summary: Load Pydantic v2 settings from AWS Secrets Manager and SSM Parameter Store
Project-URL: Homepage, https://github.com/ceb10n/pydantic-settings-aws
Project-URL: Documentation, https://ceb10n.github.io/pydantic-settings-aws
Project-URL: Repository, https://github.com/ceb10n/pydantic-settings-aws
Project-URL: Issues, https://github.com/ceb10n/pydantic-settings-aws/issues
Project-URL: Changelog, https://github.com/ceb10n/pydantic-settings-aws/releases
Author-email: Rafael de Oliveira Marques <rafaelomarques@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: aws,aws configuration,aws secrets manager,aws secrets manager python,configuration management,fastapi,parameter store python,pydantic,pydantic aws,pydantic-settings,python configuration aws,secrets management,ssm,ssm parameter store,typed configuration
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Framework :: Pydantic
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Unix
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Systems Administration
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: boto3<2.0.0,>=1.27.0
Requires-Dist: pydantic-settings<3.0.0,>=2.0.2
Requires-Dist: pydantic<3.0.0,>=2.12.0
Provides-Extra: dev
Requires-Dist: black>=26.3.1; extra == 'dev'
Requires-Dist: mypy>=1.20.0; extra == 'dev'
Requires-Dist: pre-commit>=4.5.1; extra == 'dev'
Requires-Dist: pytest-cov>=7.1.0; extra == 'dev'
Requires-Dist: pytest>=9.0.2; extra == 'dev'
Requires-Dist: ruff>=0.15.9; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-git-committers-plugin-2>=2.3.0; extra == 'docs'
Requires-Dist: mkdocs-material>=9.5.29; extra == 'docs'
Requires-Dist: mkdocs>=1.6.0; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.25.1; extra == 'docs'
Description-Content-Type: text/markdown

# Pydantic Settings AWS

<p align="center">
  <img src="docs/assets/logo.png" alt="pydantic-settings-aws logo" width="400"/>
</p>

<br/>

[![CI](https://github.com/ceb10n/pydantic-settings-aws/actions/workflows/ci.yml/badge.svg)](https://github.com/ceb10n/pydantic-settings-aws/actions)
[![codecov](https://codecov.io/github/ceb10n/pydantic-settings-aws/graph/badge.svg?token=K77HYDZR3P)](https://codecov.io/github/ceb10n/pydantic-settings-aws)
[![PyPI - Implementation](https://img.shields.io/pypi/implementation/pydantic-settings-aws)](https://pypi.org/project/pydantic-settings-aws)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pydantic-settings-aws)](https://pypi.org/project/pydantic-settings-aws)
[![Pydantic v2 only](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/pydantic/pydantic/main/docs/badge/v2.json)](https://docs.pydantic.dev/latest/contributing/#badges)
[![PyPI - License](https://img.shields.io/pypi/l/pydantic-settings-aws)](https://pypi.org/project/pydantic-settings-aws)
[![Downloads](https://static.pepy.tech/badge/pydantic-settings-aws/month)](https://pepy.tech/project/pydantic-settings-aws)

`pydantic-settings-aws` extends Pydantic Settings to load configuration from AWS Secrets Manager and SSM Parameter Store directly into type-safe Pydantic models, eliminating the need for manual boto3 parsing or environment variable mapping.

📖 **[Full documentation](https://ceb10n.github.io/pydantic-settings-aws)**

## ✨ Why pydantic-settings-aws?

- Define your configuration once using Pydantic models
- Load secrets and parameters from AWS without manual boto3 code
- Built-in validation, parsing, and type safety
- Works with any AWS authentication method — profiles, SSO, IAM roles, access keys
- Thread-safe and compatible with free-threaded Python

## ⚡ Quick Start

Add your secret to AWS Secrets Manager as a JSON object:

```json
{
    "username": "admin",
    "password": "s3cr3t"
}
```

Then create your settings class:

```python
from pydantic_settings_aws import AWSSettingsConfigDict, SecretsManagerBaseSettings


class MySettings(SecretsManagerBaseSettings):
    model_config = AWSSettingsConfigDict(
        secrets_name="my/secret"
    )

    username: str
    password: str


settings = MySettings()
print(settings.username)  # "admin"
```

That’s it, `boto3` will resolve your AWS credentials automatically using its standard configuration chain.

## ✅ Features

- Load settings from **AWS Secrets Manager**, **SSM Parameter Store**, or both simultaneously
- Type-safe configuration with full IDE autocomplete via `AWSSettingsConfigDict`
- Typed field descriptors `Secrets` and `SSM` as ergonomic alternatives to raw dict metadata
- Structured exception hierarchy (`SecretNotFoundError`, `ParameterNotFoundError`, etc.) for precise error handling
- Multi-region and multi-account support via per-field boto3 clients
- Thread-safe client cache, compatible with free-threaded Python (3.13t, 3.14t)
- Falls back to environment variables, dotenv, and secret files automatically

## 🔧 Requirements

| Python | Pydantic | boto3 |
| :----- | :------- | :---- |
| 3.10+  | v2       | v1    |

## 💽 Installation

```bash
pip install pydantic-settings-aws
```

Or with [uv](https://docs.astral.sh/uv/):

```bash
uv add pydantic-settings-aws
```

## 📦 Usage

You can provide your own boto3 client or let pydantic-settings-aws create one for you. To learn how boto3 resolves credentials, see [Configuring credentials](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html#configuring-credentials).

### 🔐 Secrets Manager — with boto3 client

```python
import boto3
from pydantic_settings_aws import AWSSettingsConfigDict, SecretsManagerBaseSettings


client = boto3.client("secretsmanager")


class MySettings(SecretsManagerBaseSettings):
    model_config = AWSSettingsConfigDict(
        secrets_name="my/secret",
        secrets_client=client
    )

    username: str
    password: str
    name: str | None = None


settings = MySettings()
```

Your secret content must be valid JSON with keys matching the field names:

```json
{
    "username": "admin",
    "password": "admin",
    "name": "John"
}
```

### 📦 SSM Parameter Store

```python
from typing import Annotated
from pydantic_settings_aws import AWSSettingsConfigDict, ParameterStoreBaseSettings, SSM


class MySettings(ParameterStoreBaseSettings):
    model_config = AWSSettingsConfigDict(aws_region="us-east-1")

    # pydantic-settings-aws looks for a parameter named "db_host"
    db_host: str

    # explicit parameter name via SSM descriptor
    db_port: Annotated[str, SSM(name="/myapp/prod/db/port")]
```

### 🙋🏾‍♂️ Secrets Manager — with AWS profile

```python
from pydantic_settings_aws import AWSSettingsConfigDict, SecretsManagerBaseSettings


class MySettings(SecretsManagerBaseSettings):
    model_config = AWSSettingsConfigDict(
        secrets_name="my/secret",
        aws_region="us-east-1",
        aws_profile="dev"
    )

    username: str
    password: str
```

### 🔑 Secrets Manager — with access key

```python
from pydantic_settings_aws import AWSSettingsConfigDict, SecretsManagerBaseSettings


class MySettings(SecretsManagerBaseSettings):
    model_config = AWSSettingsConfigDict(
        secrets_name="my/secret",
        aws_region="us-east-1",
        aws_access_key_id="aws_access_key_id",
        aws_secret_access_key="aws_secret_access_key",
        aws_session_token="aws_session_token"
    )

    username: str
    password: str
```

### 🔒 Secrets Manager — with AWS IAM Identity Center (SSO)

```shell
aws sso login --profile my-profile
```

```python
from pydantic_settings_aws import AWSSettingsConfigDict, SecretsManagerBaseSettings


class MySettings(SecretsManagerBaseSettings):
    model_config = AWSSettingsConfigDict(
        secrets_name="my/secret"
    )

    username: str
    password: str
```

## 👩🏼‍⚖️ License

This project is licensed under the terms of the [MIT license.](LICENSE)
