AWS Error Utils

Warnings

• breaking Python 3.6 support was removed in version 2.7. Users on Python 3.6 or earlier must upgrade their Python version or use an older version of `aws-error-utils`.
  Fix: Upgrade Python to 3.7 or higher. If upgrading Python is not feasible, pin `aws-error-utils<2.7.0`.
• breaking Python 3.5 support was removed in version 2.4.
  Fix: Upgrade Python to 3.6 or higher. If upgrading Python is not feasible, pin `aws-error-utils<2.4.0`.
• gotcha The `errors` class (e.g., `errors.NoSuchBucket`) provides a simpler syntax but is limited to error codes that can be valid Python property names. For complex error codes (e.g., `InvalidInstanceID.NotFound`), you must use the `catch_aws_error()` function directly with the full string code.
  Fix: For error codes containing special characters or periods, always use `except catch_aws_error('Complex.ErrorCode'):` instead of `except errors.ComplexErrorCode:`.
• gotcha `errors.SomeError` is an alias for `catch_aws_error('SomeError')`, not an actual exception class. This means you cannot subclass `errors.SomeError` or use it in `issubclass()` checks.
  Fix: Treat `errors.SomeError` as a convenience function call within an `except` block rather than a standard Python exception class.
• gotcha When using `catch_aws_error()`, you must provide an error code. To match an exception exclusively by its `operation_name` (e.g., for all errors from a specific API call), you need to use `aws_error_utils.ALL_CODES` as the error code argument.
  Fix: Use `except catch_aws_error(aws_error_utils.ALL_CODES, operation_name='GetObject'):` to match all errors from the 'GetObject' operation.

Install

• pip install aws-error-utils Install stable version

Imports

• catch_aws_error

  from aws_error_utils import catch_aws_error

• errors
  wrong:

  from aws_error_utils.errors import NoSuchBucket

  correct:

  from aws_error_utils import errors

  The 'errors' object is imported directly, and its attributes (e.g., `errors.NoSuchBucket`) are aliases to `catch_aws_error()` calls, not actual exception classes.
• aws_error_matches

  from aws_error_utils import aws_error_matches

• get_aws_error_info

  from aws_error_utils import get_aws_error_info

Quickstart

This quickstart demonstrates how to use `catch_aws_error` to handle specific AWS `ClientError` exceptions. It attempts to access a non-existent S3 bucket, which typically raises a `NoSuchBucket` error. It also shows the alternative `errors.NoSuchBucket` syntax, which is an alias for `catch_aws_error('NoSuchBucket')`.

import boto3
from aws_error_utils import catch_aws_error, errors
import os
from botocore.exceptions import ClientError

# Configure boto3 client with dummy credentials for local testing, or load from environment
s3_client = boto3.client(
    's3',
    aws_access_key_id=os.environ.get('AWS_ACCESS_KEY_ID', 'test'),
    aws_secret_access_key=os.environ.get('AWS_SECRET_ACCESS_KEY', 'test'),
    aws_session_token=os.environ.get('AWS_SESSION_TOKEN'), # Optional
    region_name=os.environ.get('AWS_DEFAULT_REGION', 'us-east-1')
)

non_existent_bucket = "non-existent-aws-error-utils-test-bucket-12345"

print(f"Attempting to list objects in '{non_existent_bucket}'...")
try:
    s3_client.list_objects_v2(Bucket=non_existent_bucket)
except catch_aws_error("NoSuchBucket") as e:
    print(f"Caught expected AWS error using catch_aws_error: Code={e.code}, Message='{e.message}'")
except ClientError as e:
    print(f"Caught an unexpected ClientError: {e}")
except Exception as e:
    print(f"Caught a generic exception: {e}")

print("\nDemonstrating 'errors' class for common error codes (if applicable) (alias to catch_aws_error)...")
try:
    s3_client.list_objects_v2(Bucket=non_existent_bucket)
except errors.NoSuchBucket as e:
    print(f"Caught expected AWS error using errors.NoSuchBucket: Code={e.code}, Message='{e.message}'")
except ClientError as e:
    print(f"Caught an unexpected ClientError via ClientError: {e}")