Metadata-Version: 2.4
Name: boto3-errors
Version: 0.16.0
Summary: Typed, statically-importable exception classes for every AWS service
Keywords: aws,boto3,botocore,errors,exceptions,types
Author: Adrián Tomás
Author-email: Adrián Tomás <22175056+adriantomas@users.noreply.github.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
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: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development
Classifier: Typing :: Typed
Requires-Dist: botocore>=1.43.5
Requires-Python: >=3.10, <3.15
Project-URL: Homepage, https://github.com/adriantomas/boto3-errors
Project-URL: Repository, https://github.com/adriantomas/boto3-errors
Project-URL: Issues, https://github.com/adriantomas/boto3-errors/issues
Description-Content-Type: text/markdown

# (Better) boto3 errors

[![Python 3.10 | 3.11 | 3.12 | 3.13 | 3.14](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue.svg)](https://www.python.org/downloads/)
[![PyPI](https://img.shields.io/pypi/v/boto3_errors.svg)](https://pypi.org/project/boto3_errors/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Typed, statically-importable exception classes for every AWS service.

## Install

```bash
pip install boto3-errors
```

## Quick start

```python
import boto3
from boto3_errors import patch_client
from boto3_errors.dynamodb import ConditionalCheckFailedException

client = boto3.client("dynamodb")
patch_client(client)

try:
    client.put_item(
        TableName="users",
        Item={"pk": {"S": "user#1"}, "name": {"S": "Ada"}},
        ConditionExpression="attribute_not_exists(pk)",
    )
except ConditionalCheckFailedException as e:
    print(e.message)  # "The conditional request failed"
    print(e.error_code)  # "ConditionalCheckFailedException"
    print(e.item)  # {"pk": {"S": "user#1"}, "name": {"S": "Ada"}}
```

## The problem

Every boto3 error comes back as a `ClientError`. The only way to distinguish them is by parsing `e.response["Error"]["Code"]` — a stringly-typed dict lookup with no autocomplete, no type checking, and no IDE support. A typo in the error code string won't be caught until it crashes.

## What you get

All AWS services with exception classes auto-generated from botocore's service model.

### Exception hierarchy

```text
ClientError                     # botocore base — still works
└── Boto3Error                  # boto3-errors base
    └── DynamoDBError           # per-service base
        ├── ConditionalCheckFailedException
        ├── ResourceNotFoundException
        ├── TransactionCanceledException
        └── ...
```

Every exception is a `ClientError` subclass, so existing `except ClientError` handlers keep working.

### Built-in properties

Every `Boto3Error` exposes:

| Property | Type | Source |
| ------------------ | ----- | ----------------------------------- |
| `message` | `str` | `Error.Message` |
| `error_code` | `str` | `Error.Code` |
| `http_status_code` | `int` | `ResponseMetadata.HTTPStatusCode` |
| `request_id` | `str` | `ResponseMetadata.RequestId` |

### Service-specific properties

Some exceptions expose extra fields from the API response:

```python
from boto3_errors.dynamodb import (
    ConditionalCheckFailedException,
    TransactionCanceledException,
)

# ConditionalCheckFailedException.item -> dict | None
# TransactionCanceledException.cancellation_reasons -> list | None
```
