tessl/pypi-botocore

Low-level, data-driven core of boto 3 providing foundational AWS service access.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Exception Handling

Name: tessl/pypi-botocore
Author: tessl

Structured exception hierarchy for handling AWS service errors, connection issues, credential problems, and validation failures. Botocore provides specific exception types for different error categories to enable precise error handling.

Capabilities

Base Exceptions

Foundation exception classes for all botocore errors.

class BotoCoreError(Exception):
    """Base exception for all botocore errors."""
    pass

class ClientError(BotoCoreError):
    """
    Service-specific errors returned by AWS APIs.
    
    Attributes:
        response: Complete error response from AWS service
        operation_name: AWS operation that caused the error
    """
    
    def __init__(self, error_response: dict, operation_name: str):
        """
        Initialize client error.
        
        Args:
            error_response: Error response from AWS service
            operation_name: AWS operation name
        """
        self.response = error_response
        self.operation_name = operation_name

Connection Exceptions

Network and HTTP connection-related errors.

class ConnectionError(BotoCoreError):
    """Base class for connection errors."""
    pass

class EndpointConnectionError(ConnectionError):
    """
    Error connecting to AWS service endpoint.
    
    Attributes:
        endpoint_url: URL that failed to connect
    """
    pass

class SSLError(ConnectionError):
    """SSL/TLS certificate verification errors."""
    pass

class ConnectTimeoutError(ConnectionError):
    """Connection timeout exceeded."""
    pass

class ProxyConnectionError(ConnectionError):
    """Proxy connection failures."""
    pass

class HTTPClientError(ConnectionError):
    """HTTP client-level errors."""
    pass

Credential Exceptions

AWS credential and authentication-related errors.

class NoCredentialsError(BotoCoreError):
    """No AWS credentials found in credential chain."""
    pass

class PartialCredentialsError(BotoCoreError):
    """
    Incomplete AWS credentials found.
    
    Raised when some but not all required credential components are available.
    """
    pass

class CredentialRetrievalError(BotoCoreError):
    """Error retrieving credentials from provider."""
    pass

class NoAuthTokenError(BotoCoreError):
    """Missing authentication token for token-based services."""
    pass

class TokenRetrievalError(BotoCoreError):
    """Error retrieving authentication token."""
    pass

Configuration Exceptions

Configuration file and profile-related errors.

class ProfileNotFound(BotoCoreError):
    """
    AWS profile not found in configuration.
    
    Attributes:
        profile: Profile name that was not found
    """
    pass

class ConfigNotFound(BotoCoreError):
    """AWS configuration file not found."""
    pass

class ConfigParseError(BotoCoreError):
    """Error parsing AWS configuration file."""
    pass

class InvalidConfigError(BotoCoreError):
    """Invalid configuration values."""
    pass

Service and Data Exceptions

AWS service discovery and data-related errors.

class UnknownServiceError(BotoCoreError):
    """
    Unknown AWS service name.
    
    Attributes:
        service_name: Service name that was not recognized
        known_services: List of available service names
    """
    pass

class DataNotFoundError(BotoCoreError):
    """Service data not found in botocore data directory."""
    pass

class ApiVersionNotFoundError(BotoCoreError):
    """
    Specified API version not found for service.
    
    Attributes:
        api_version: API version that was not found
        available_api_versions: List of available API versions
    """
    pass

class UnknownRegionError(BotoCoreError):
    """
    Unknown AWS region name.
    
    Attributes:
        region_name: Region name that was not recognized
    """
    pass

Validation Exceptions

Parameter and input validation errors.

class ParamValidationError(BotoCoreError):
    """
    Parameter validation failure.
    
    Attributes:
        report: Validation error report with details
    """
    pass

class ValidationError(BotoCoreError):
    """General validation error."""
    pass

class MissingParametersError(ValidationError):
    """Required parameters missing from operation call."""
    pass

class ParamValidationDecoratorError(ParamValidationError):
    """Parameter validation decorator error."""
    pass

Operation-Specific Exceptions

Errors specific to certain botocore operations.

class PaginationError(BotoCoreError):
    """Pagination-related errors."""
    pass

class WaiterError(BotoCoreError):
    """
    Base class for waiter errors.
    
    Attributes:
        name: Waiter name
        reason: Error reason
    """
    pass

class WaiterConfigError(WaiterError):
    """Waiter configuration error."""
    pass

class ChecksumError(BotoCoreError):
    """Checksum validation failure."""
    pass

class EventStreamError(BotoCoreError):
    """Event streaming errors."""
    pass

class InvalidRetryConfigurationError(BotoCoreError):
    """Invalid retry configuration."""
    pass

class InvalidMaxRetryAttemptsError(InvalidRetryConfigurationError):
    """Invalid maximum retry attempts value."""
    pass

class StubResponseError(BotoCoreError):
    """Testing stub response errors."""
    pass

class UnStubbedResponseError(StubResponseError):
    """Response not stubbed in testing."""
    pass

Parsing and Serialization Exceptions

Data parsing and request serialization errors.

class ResponseParserError(BotoCoreError):
    """Error parsing AWS service response."""
    pass

class UnsupportedSignatureVersionError(BotoCoreError):
    """Unsupported AWS signature version."""
    pass

class MissingDependencyException(BotoCoreError):
    """Required dependency not available."""
    pass

Usage Examples

Handling Service Errors

from botocore.exceptions import ClientError

try:
    response = s3_client.get_object(Bucket='mybucket', Key='mykey')
except ClientError as e:
    error_code = e.response['Error']['Code']
    error_message = e.response['Error']['Message']
    
    if error_code == 'NoSuchBucket':
        print(f"Bucket does not exist: {error_message}")
    elif error_code == 'NoSuchKey':
        print(f"Object not found: {error_message}")
    elif error_code == 'AccessDenied':
        print(f"Access denied: {error_message}")
    else:
        print(f"Unexpected error {error_code}: {error_message}")

Handling Connection Errors

from botocore.exceptions import (
    ConnectionError, EndpointConnectionError, 
    ConnectTimeoutError, SSLError
)

try:
    client = session.create_client('s3', region_name='us-east-1')
    response = client.list_buckets()
except EndpointConnectionError as e:
    print(f"Cannot connect to AWS endpoint: {e}")
except ConnectTimeoutError:
    print("Connection timeout - check network connectivity")
except SSLError as e:
    print(f"SSL certificate error: {e}")
except ConnectionError as e:
    print(f"Network connection error: {e}")

Handling Credential Errors

from botocore.exceptions import (
    NoCredentialsError, PartialCredentialsError,
    CredentialRetrievalError
)

try:
    session = get_session()
    credentials = session.get_credentials()
    client = session.create_client('dynamodb')
except NoCredentialsError:
    print("No AWS credentials found. Please configure credentials.")
except PartialCredentialsError:
    print("Incomplete credentials found. Check configuration.")
except CredentialRetrievalError as e:
    print(f"Failed to retrieve credentials: {e}")

Handling Configuration Errors

from botocore.exceptions import (
    ProfileNotFound, ConfigNotFound, 
    UnknownServiceError, UnknownRegionError
)

try:
    session = get_session()
    session.profile = 'nonexistent-profile'
    client = session.create_client('invalidservice', region_name='invalid-region')
except ProfileNotFound as e:
    print(f"AWS profile not found: {e}")
except UnknownServiceError as e:
    print(f"Unknown service: {e.service_name}")
    print(f"Available services: {', '.join(e.known_services[:10])}...")
except UnknownRegionError as e:
    print(f"Unknown region: {e.region_name}")

Handling Validation Errors

from botocore.exceptions import ParamValidationError, MissingParametersError

try:
    # Missing required parameter
    response = s3_client.get_object(Bucket='mybucket')  # Missing Key parameter
except ParamValidationError as e:
    print(f"Parameter validation failed: {e}")
    # e.report contains detailed validation errors
except MissingParametersError as e:
    print(f"Missing required parameters: {e}")

Comprehensive Error Handling

from botocore.exceptions import (
    BotoCoreError, ClientError, NoCredentialsError,
    ConnectionError, ValidationError
)

def robust_aws_operation():
    try:
        session = get_session()
        client = session.create_client('s3', region_name='us-east-1')
        
        response = client.list_buckets()
        return response['Buckets']
        
    except NoCredentialsError:
        print("ERROR: No AWS credentials configured")
        return None
    except ConnectionError as e:
        print(f"ERROR: Network connection failed: {e}")
        return None
    except ClientError as e:
        error_code = e.response['Error']['Code']
        if error_code == 'AccessDenied':
            print("ERROR: Access denied - check IAM permissions")
        else:
            print(f"ERROR: AWS service error {error_code}: {e}")
        return None
    except ValidationError as e:
        print(f"ERROR: Invalid parameters: {e}")
        return None
    except BotoCoreError as e:
        print(f"ERROR: Botocore error: {e}")
        return None
    except Exception as e:
        print(f"ERROR: Unexpected error: {e}")
        return None

Testing with Stub Errors

from botocore.exceptions import ClientError
from botocore.stub import Stubber

def test_error_handling():
    client = session.create_client('s3')
    stubber = Stubber(client)
    
    # Stub an error response
    stubber.add_client_error(
        'get_object',
        service_error_code='NoSuchKey',
        service_message='The specified key does not exist.',
        expected_params={'Bucket': 'mybucket', 'Key': 'nonexistent'}
    )
    
    stubber.activate()
    
    try:
        client.get_object(Bucket='mybucket', Key='nonexistent')
    except ClientError as e:
        assert e.response['Error']['Code'] == 'NoSuchKey'
        print("Error handling test passed")
    
    stubber.deactivate()

Install with Tessl CLI