boto3-errors 0.1.0__tar.gz

boto3_errors-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Adrián Tomás
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

boto3_errors-0.1.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: boto3-errors
+Version: 0.1.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.42.46
+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
+```

boto3_errors-0.1.0/README.md

@@ -0,0 +1,82 @@
+# (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
+```

boto3_errors-0.1.0/pyproject.toml

@@ -0,0 +1,99 @@
+[project]
+name = "boto3-errors"
+version = "0.1.0"
+description = "Typed, statically-importable exception classes for every AWS service"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["aws", "boto3", "botocore", "errors", "exceptions", "types"]
+authors = [
+    { name = "Adrián Tomás", email = "22175056+adriantomas@users.noreply.github.com" }
+]
+requires-python = ">=3.10,<3.15"
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Information Technology",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: Implementation :: CPython",
+    "Programming Language :: Python :: Implementation :: PyPy",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Software Development",
+    "Typing :: Typed",
+]
+dependencies = [
+    "botocore>=1.42.46",
+]
+
+[project.urls]
+Homepage = "https://github.com/adriantomas/boto3-errors"
+Repository = "https://github.com/adriantomas/boto3-errors"
+Issues = "https://github.com/adriantomas/boto3-errors/issues"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.0",
+    "mypy>=1.19",
+    "prek>=0.3.2",
+    "ruff>=0.15.0",
+    "commitizen>=4.13.6",
+    "mdformat>=1.0.0",
+    "mdformat-ruff>=0.1.3",
+    "botocore-stubs>=1.42.41",
+    "boto3>=1.38.0",
+    "testcontainers[generic]>=4.0.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.10.0,<0.11.0"]
+build-backend = "uv_build"
+
+[tool.uv]
+required-version = ">=0.10.0"
+
+[tool.mypy]
+strict = true
+
+[tool.pytest.ini_options]
+markers = ["integration: requires Docker"]
+
+[tool.ruff]
+fix = true
+# Exclude auto-generated service modules — they are produced by scripts/generate.py
+# and should not be hand-edited or linted.
+exclude = ["src/boto3_errors/[!_]*.py"]
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "TC002", # typing-only-third-party-import
+    "TC003", # typing-only-standard-library-import
+    "D203", # incorrect-blank-line-before-class (D203)
+    "D213", # multi-line-summary-second-line (D213)
+    "COM812", # missing-trailing-comma
+    "N818", # error-suffix-on-exception-name
+]
+
+[tool.ruff.lint.per-file-ignores]
+"src/boto3_errors/_patch.py" = [
+    "SLF001", # private-member-access — we must monkey-patch client internals
+]
+"tests/**/*.py" = [
+    "D100",    # undocumented-public-module
+    "D101",    # undocumented-public-class
+    "D102",    # undocumented-public-method
+    "D104",    # undocumented-public-package
+    "S101",    # use of assert detected
+    "SLF001",  # private-member-access — tests must inspect internals
+    "INP001",  # implicit-namespace-package — tests don't need __init__.py
+]

boto3_errors-0.1.0/src/boto3_errors/__init__.py

@@ -0,0 +1,6 @@
+"""Typed, statically-importable exception classes for every AWS service."""
+
+from boto3_errors._base import Boto3Error
+from boto3_errors._patch import patch_client
+
+__all__ = ["Boto3Error", "patch_client"]

boto3_errors-0.1.0/src/boto3_errors/_base.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from typing import Any
+
+from botocore.exceptions import ClientError
+
+
+class Boto3Error(ClientError):
+    """Base class for all typed boto3 exceptions.
+
+    Inherits from ClientError so existing ``except ClientError`` handlers
+    still catch these exceptions.
+    """
+
+    _SERVICE: str = ""
+    _ERROR_CODE: str = ""
+
+    # Widen from botocore-stubs' TypedDict so that generated properties
+    # can ``self.response.get("SomeField")`` without returning ``object``.
+    response: dict[str, Any]  # type: ignore[assignment]
+
+    @property
+    def message(self) -> str:
+        """Human-readable error message from the ``Error.Message`` field."""
+        return self.response.get("Error", {}).get("Message", "")  # type: ignore[no-any-return]
+
+    @property
+    def error_code(self) -> str:
+        """AWS error code from the ``Error.Code`` field."""
+        return self.response.get("Error", {}).get("Code", "")  # type: ignore[no-any-return]
+
+    @property
+    def http_status_code(self) -> int:
+        """HTTP status code from ``ResponseMetadata``."""
+        return self.response.get("ResponseMetadata", {}).get("HTTPStatusCode", 0)  # type: ignore[no-any-return]
+
+    @property
+    def request_id(self) -> str:
+        """AWS request ID from ``ResponseMetadata``."""
+        return self.response.get("ResponseMetadata", {}).get("RequestId", "")  # type: ignore[no-any-return]

boto3_errors-0.1.0/src/boto3_errors/_patch.py

@@ -0,0 +1,54 @@
+import functools
+import importlib
+from typing import Any
+
+from botocore.client import BaseClient
+from botocore.exceptions import ClientError
+
+
+def patch_client(client: BaseClient) -> None:
+    """Wrap *client*'s ``_make_api_call``.
+
+    Re-raises ``ClientError`` as a typed :class:`~boto3_errors._base.Boto3Error`
+    subclass when a matching exception class exists.
+
+    Safe to call more than once on the same client (subsequent calls are
+    no-ops).
+    """
+    if getattr(client, "_boto3_errors_patched", False):
+        return
+
+    service: str = client._service_model.service_name  # type: ignore[attr-defined]
+    module_name = _service_to_module(service)
+
+    try:
+        mod = importlib.import_module(f"boto3_errors.{module_name}")
+    except ModuleNotFoundError:
+        # No generated module for this service — nothing to patch.
+        return
+
+    exceptions: dict[str, type] = getattr(mod, "EXCEPTIONS", {})
+    original = client._make_api_call  # type: ignore[attr-defined]
+
+    @functools.wraps(original)
+    def _patched_make_api_call(
+        operation_name: str, api_params: dict[str, Any]
+    ) -> dict[str, Any]:
+        try:
+            return original(operation_name, api_params)  # type: ignore[no-any-return]
+        except ClientError as e:
+            code = e.response.get("Error", {}).get("Code", "")
+            exc_cls = exceptions.get(code)
+            if exc_cls is not None:
+                raise exc_cls(e.response, e.operation_name) from e
+            raise
+
+    client._make_api_call = _patched_make_api_call  # type: ignore[attr-defined]
+    client._boto3_errors_patched = True  # type: ignore[attr-defined]
+
+
+def _service_to_module(service: str) -> str:
+    name = service.replace("-", "_")
+    if name == "lambda":
+        name = "lambda_"
+    return name

boto3_errors-0.1.0/src/boto3_errors/accessanalyzer.py

@@ -0,0 +1,118 @@
+# Auto-generated. Do not edit manually.
+from __future__ import annotations
+
+from typing import Any
+
+from boto3_errors._base import Boto3Error
+
+
+class AccessAnalyzerError(Boto3Error):
+    _SERVICE = "accessanalyzer"
+
+
+class AccessDeniedException(AccessAnalyzerError):
+    """You do not have sufficient access to perform this action."""
+    _ERROR_CODE = "AccessDeniedException"
+
+
+class ConflictException(AccessAnalyzerError):
+    """A conflict exception error."""
+    _ERROR_CODE = "ConflictException"
+
+    @property
+    def resource_id(self) -> str | None:
+        """The ID of the resource."""
+        return self.response.get("resourceId")
+
+    @property
+    def resource_type(self) -> str | None:
+        """The resource type."""
+        return self.response.get("resourceType")
+
+
+class InternalServerException(AccessAnalyzerError):
+    """Internal server error."""
+    _ERROR_CODE = "InternalServerException"
+
+    @property
+    def retry_after_seconds(self) -> int | None:
+        """The seconds to wait to retry."""
+        return self.response.get("retryAfterSeconds")
+
+
+class InvalidParameterException(AccessAnalyzerError):
+    """The specified parameter is invalid."""
+    _ERROR_CODE = "InvalidParameterException"
+
+
+class ResourceNotFoundException(AccessAnalyzerError):
+    """The specified resource could not be found."""
+    _ERROR_CODE = "ResourceNotFoundException"
+
+    @property
+    def resource_id(self) -> str | None:
+        """The ID of the resource."""
+        return self.response.get("resourceId")
+
+    @property
+    def resource_type(self) -> str | None:
+        """The type of the resource."""
+        return self.response.get("resourceType")
+
+
+class ServiceQuotaExceededException(AccessAnalyzerError):
+    """Service quote met error."""
+    _ERROR_CODE = "ServiceQuotaExceededException"
+
+    @property
+    def resource_id(self) -> str | None:
+        """The resource ID."""
+        return self.response.get("resourceId")
+
+    @property
+    def resource_type(self) -> str | None:
+        """The resource type."""
+        return self.response.get("resourceType")
+
+
+class ThrottlingException(AccessAnalyzerError):
+    """Throttling limit exceeded error."""
+    _ERROR_CODE = "ThrottlingException"
+
+    @property
+    def retry_after_seconds(self) -> int | None:
+        """The seconds to wait to retry."""
+        return self.response.get("retryAfterSeconds")
+
+
+class UnprocessableEntityException(AccessAnalyzerError):
+    """The specified entity could not be processed."""
+    _ERROR_CODE = "UnprocessableEntityException"
+
+
+class ValidationException(AccessAnalyzerError):
+    """Validation exception error."""
+    _ERROR_CODE = "ValidationException"
+
+    @property
+    def reason(self) -> str | None:
+        """The reason for the exception."""
+        return self.response.get("reason")
+
+    @property
+    def field_list(self) -> list[Any] | None:
+        """A list of fields that didn't validate."""
+        return self.response.get("fieldList")
+
+
+EXCEPTIONS: dict[str, type[AccessAnalyzerError]] = {
+    "AccessDeniedException": AccessDeniedException,
+    "ConflictException": ConflictException,
+    "InternalServerException": InternalServerException,
+    "InvalidParameterException": InvalidParameterException,
+    "ResourceNotFoundException": ResourceNotFoundException,
+    "ServiceQuotaExceededException": ServiceQuotaExceededException,
+    "ThrottlingException": ThrottlingException,
+    "UnprocessableEntityException": UnprocessableEntityException,
+    "ValidationException": ValidationException,
+}

boto3_errors-0.1.0/src/boto3_errors/account.py

@@ -0,0 +1,113 @@
+# Auto-generated. Do not edit manually.
+from __future__ import annotations
+
+from typing import Any
+
+from boto3_errors._base import Boto3Error
+
+
+class AccountError(Boto3Error):
+    _SERVICE = "account"
+
+
+class AccessDeniedException(AccountError):
+    """The operation failed because the calling identity doesn't have the minimum required
+    permissions.
+    """
+
+    _ERROR_CODE = "AccessDeniedException"
+
+    @property
+    def error_type(self) -> str | None:
+        """The value populated to the `x-amzn-ErrorType` response header by API Gateway."""
+        return self.response.get("errorType")
+
+
+class ConflictException(AccountError):
+    """The request could not be processed because of a conflict in the current status of
+    the resource. For example, this happens if you try to enable a Region that is
+    currently being disabled (in a status of DISABLING) or if you try to change an
+    account’s root user email to an email address which is already in use.
+    """
+
+    _ERROR_CODE = "ConflictException"
+
+    @property
+    def error_type(self) -> str | None:
+        """The value populated to the `x-amzn-ErrorType` response header by API Gateway."""
+        return self.response.get("errorType")
+
+
+class InternalServerException(AccountError):
+    """The operation failed because of an error internal to Amazon Web Services. Try your
+    operation again later.
+    """
+
+    _ERROR_CODE = "InternalServerException"
+
+    @property
+    def error_type(self) -> str | None:
+        """The value populated to the `x-amzn-ErrorType` response header by API Gateway."""
+        return self.response.get("errorType")
+
+
+class ResourceNotFoundException(AccountError):
+    """The operation failed because it specified a resource that can't be found."""
+    _ERROR_CODE = "ResourceNotFoundException"
+
+    @property
+    def error_type(self) -> str | None:
+        """The value populated to the `x-amzn-ErrorType` response header by API Gateway."""
+        return self.response.get("errorType")
+
+
+class ResourceUnavailableException(AccountError):
+    """The operation failed because it specified a resource that is not currently
+    available.
+    """
+
+    _ERROR_CODE = "ResourceUnavailableException"
+
+    @property
+    def error_type(self) -> str | None:
+        """The value populated to the `x-amzn-ErrorType` response header by API Gateway."""
+        return self.response.get("errorType")
+
+
+class TooManyRequestsException(AccountError):
+    """The operation failed because it was called too frequently and exceeded a throttle
+    limit.
+    """
+
+    _ERROR_CODE = "TooManyRequestsException"
+
+    @property
+    def error_type(self) -> str | None:
+        """The value populated to the `x-amzn-ErrorType` response header by API Gateway."""
+        return self.response.get("errorType")
+
+
+class ValidationException(AccountError):
+    """The operation failed because one of the input parameters was invalid."""
+    _ERROR_CODE = "ValidationException"
+
+    @property
+    def field_list(self) -> list[Any] | None:
+        """The field where the invalid entry was detected."""
+        return self.response.get("fieldList")
+
+    @property
+    def reason(self) -> str | None:
+        """The reason that validation failed."""
+        return self.response.get("reason")
+
+
+EXCEPTIONS: dict[str, type[AccountError]] = {
+    "AccessDeniedException": AccessDeniedException,
+    "ConflictException": ConflictException,
+    "InternalServerException": InternalServerException,
+    "ResourceNotFoundException": ResourceNotFoundException,
+    "ResourceUnavailableException": ResourceUnavailableException,
+    "TooManyRequestsException": TooManyRequestsException,
+    "ValidationException": ValidationException,
+}