or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

client.mdconfig.mdcredentials.mdevents.mdexceptions.mdindex.mdmodels.mdpagination.mdresponse.mdsession.mdtesting.mdwaiters.md
tile.json

tessl/pypi-botocore

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/botocore@1.40.x

To install, run

npx @tessl/cli install tessl/pypi-botocore@1.40.0

index.mddocs/

Botocore

Botocore is the foundational Python library that provides low-level, data-driven access to Amazon Web Services (AWS). It serves as the core foundation for both the AWS CLI and boto3, offering direct access to AWS service APIs through a comprehensive client interface. The library handles authentication, request signing, retry logic, and error handling for AWS services, while providing data-driven service models that automatically stay current with AWS API changes.

Package Information

  • Package Name: botocore
  • Language: Python
  • Installation: pip install botocore
  • Requirements: Python >= 3.9

Core Imports

import botocore

For session-based usage (most common):

from botocore.session import get_session

For direct client creation:

from botocore.session import get_session
session = get_session()
client = session.create_client('s3', region_name='us-east-1')

Basic Usage

from botocore.session import get_session

# Create a session
session = get_session()

# Create a client for an AWS service
s3_client = session.create_client('s3', region_name='us-east-1')

# Make an API call
response = s3_client.list_buckets()
print(response['Buckets'])

# Handle service-specific operations
ec2_client = session.create_client('ec2', region_name='us-west-2')
instances = ec2_client.describe_instances()

Architecture

Botocore follows a layered architecture designed for maximum flexibility and extensibility:

  • Session Layer: Central configuration and credential management
  • Client Layer: Service-specific API interfaces with method generation from service models
  • Model Layer: Data-driven service definitions that auto-update with AWS API changes
  • Transport Layer: HTTP handling, request signing, and retry logic
  • Event System: Extensible hooks for customizing request/response processing

This design enables botocore to serve as the foundation for higher-level AWS SDKs while maintaining direct access to all AWS service capabilities.

Package-Level API

def register_initializer(callback: callable) -> None
def unregister_initializer(callback: callable) -> None
def xform_name(name: str, sep: str = '_') -> str

# Constants
__version__: str
UNSIGNED: object
ScalarTypes: tuple
BOTOCORE_ROOT: str

Capabilities

Session Management

Central session management providing configuration, credentials, and service client creation. Sessions serve as the primary entry point and handle AWS profile management, credential resolution, and service discovery.

class Session:
    def create_client(self, service_name: str, **kwargs) -> BaseClient
    def get_credentials(self) -> Credentials
    def get_config_variable(self, logical_name: str, methods=None)
    def get_available_services(self) -> List[str]

def get_session(env_vars=None) -> Session

Session Management

Client API

Service clients provide direct access to AWS APIs with dynamically generated methods based on service models. Clients handle request construction, response parsing, and service-specific logic.

class BaseClient:
    def generate_presigned_url(
        self, 
        ClientMethod: str, 
        Params: dict = None, 
        ExpiresIn: int = 3600, 
        HttpMethod: str = None
    ) -> str
    def get_paginator(self, operation_name: str) -> Paginator
    def get_waiter(self, waiter_name: str) -> Waiter
    def can_paginate(self, operation_name: str) -> bool

class ClientMeta:
    service_model: ServiceModel
    region_name: str
    config: Config

Client API

Configuration

Advanced configuration system for customizing client behavior, timeouts, retry logic, and AWS-specific settings like S3 configuration and proxy handling.

class Config:
    def __init__(
        self,
        region_name: str = None,
        signature_version: str = None,
        user_agent: str = None,
        connect_timeout: Union[int, float] = 60,
        read_timeout: Union[int, float] = 60,
        retries: dict = None,
        **kwargs
    )

Configuration

Credentials and Authentication

Comprehensive credential management supporting multiple AWS authentication methods including environment variables, shared credentials, IAM roles, SSO, and external credential providers.

class Credentials:
    access_key: str
    secret_key: str
    token: str

class RefreshableCredentials(Credentials):
    def get_frozen_credentials(self) -> Credentials
    def refresh_needed(self) -> bool

class CredentialResolver:
    def load_credentials(self) -> Credentials

Credentials

Exception Handling

Structured exception hierarchy for handling AWS service errors, connection issues, credential problems, and validation failures with specific exception types for different error categories.

class BotoCoreError(Exception): pass
class ClientError(BotoCoreError): pass
class NoCredentialsError(BotoCoreError): pass
class ConnectionError(BotoCoreError): pass
class ParamValidationError(BotoCoreError): pass

Exception Handling

Service Models and Data Types

Data-driven service models that define AWS service APIs, operations, and data structures. Models automatically update with AWS API changes and provide type definitions for request/response handling.

class ServiceModel:
    @property
    def service_name(self) -> str
    @property
    def operation_names(self) -> List[str]
    def operation_model(self, operation_name: str) -> OperationModel

class OperationModel:
    @property
    def input_shape(self) -> Shape
    @property
    def output_shape(self) -> Shape

Service Models

Pagination

Automatic pagination for AWS operations that return large result sets, with built-in iterator support and result aggregation capabilities.

class Paginator:
    def paginate(self, **kwargs) -> PageIterator
    @property
    def can_paginate(self) -> bool

class PageIterator:
    def build_full_result(self) -> dict
    def search(self, expression: str) -> Iterator

Pagination

Waiters

Resource state waiters that poll AWS services until resources reach desired states, with configurable polling intervals and timeout handling.

class Waiter:
    def wait(self, **kwargs) -> None
    @property
    def name(self) -> str

Waiters

Response Handling

Streaming response handling for large payloads with support for chunked reading, line iteration, and automatic resource cleanup.

class StreamingBody:
    def read(self, amt: int = None) -> bytes
    def iter_lines(self, chunk_size: int = 1024) -> Iterator[bytes]
    def iter_chunks(self, chunk_size: int = 1024) -> Iterator[bytes]
    def close(self) -> None

Response Handling

Event System

Extensible event system for hooking into request/response lifecycle, enabling custom authentication, logging, monitoring, and request modification.

class HierarchicalEmitter:
    def emit(self, event_name: str, **kwargs) -> List
    def register(self, event_name: str, handler: callable, **kwargs) -> None
    def unregister(self, event_name: str, handler: callable) -> None

Event System

Testing Support

Built-in stubbing capabilities for testing AWS service interactions with mock responses and error simulation.

class Stubber:
    def add_response(self, method: str, service_response: dict, expected_params=None) -> None
    def add_client_error(self, method: str, service_error_code: str, service_message: str) -> None
    def activate(self) -> None
    def deactivate(self) -> None

Testing Support