Note

You are viewing the documentation for an older version of boto (boto2).

Boto3, the next version of Boto, is now stable and recommended for general use. It can be used side-by-side with Boto in the same project, so it is easy to start using Boto3 in your existing projects as well as new projects. Going forward, API updates and all new feature work will be focused on Boto3.

For more information, see the documentation for boto3.

boto

boto

class boto.NullHandler(level=0)

Initializes the instance - basically setting the formatter to None and the filter list to empty.

emit(record)

Do whatever it takes to actually log the specified logging record.

This version is intended to be implemented by subclasses and so raises a NotImplementedError.

boto.connect_autoscale(aws_access_key_id=None, aws_secret_access_key=None, **kwargs)
Parameters:
  • aws_access_key_id (string) – Your AWS Access Key ID
  • aws_secret_access_key (string) – Your AWS Secret Access Key
Return type:

boto.ec2.autoscale.AutoScaleConnection

Returns:

A connection to Amazon’s Auto Scaling Service

:type use_block_device_types bool :param use_block_device_types: Specifies whether to return described Launch Configs with block device mappings containing

block device types, or a list of old style block device mappings (deprecated). This defaults to false for compatability with the old incorrect style.
boto.connect_awslambda(aws_access_key_id=None, aws_secret_access_key=None, **kwargs)

Connect to AWS Lambda

Parameters:
  • aws_access_key_id (string) – Your AWS Access Key ID
  • aws_secret_access_key (string) – Your AWS Secret Access Key

rtype: boto.awslambda.layer1.AWSLambdaConnection :return: A connection to the AWS Lambda service

boto.connect_beanstalk(aws_access_key_id=None, aws_secret_access_key=None, **kwargs)
Parameters:
  • aws_access_key_id (string) – Your AWS Access Key ID
  • aws_secret_access_key (string) – Your AWS Secret Access Key
Return type:

boto.beanstalk.layer1.Layer1

Returns:

A connection to Amazon’s Elastic Beanstalk service

boto.connect_cloudformation(aws_access_key_id=None, aws_secret_access_key=None, **kwargs)
Parameters:
  • aws_access_key_id (string) – Your AWS Access Key ID
  • aws_secret_access_key (string) – Your AWS Secret Access Key
Return type:

boto.cloudformation.CloudFormationConnection

Returns:

A connection to Amazon’s CloudFormation Service

boto.connect_cloudfront(aws_access_key_id=None, aws_secret_access_key=None, **kwargs)
Parameters:
  • aws_access_key_id (string) – Your AWS Access Key ID
  • aws_secret_access_key (string) – Your AWS Secret Access Key
Return type:

boto.fps.connection.FPSConnection

Returns:

A connection to FPS

boto.connect_cloudhsm(aws_access_key_id=None, aws_secret_access_key=None, **kwargs)

Connect to AWS CloudHSM

Parameters:
  • aws_access_key_id (string) – Your AWS Access Key ID
  • aws_secret_access_key (string) – Your AWS Secret Access Key

rtype: boto.cloudhsm.layer1.CloudHSMConnection :return: A connection to the AWS CloudHSM service

boto.connect_cloudsearch(aws_access_key_id=None, aws_secret_access_key=None, **kwargs)
Parameters:
  • aws_access_key_id (string) – Your AWS Access Key ID
  • aws_secret_access_key (string) – Your AWS Secret Access Key
Return type:

boto.cloudsearch.layer2.Layer2

Returns:

A connection to Amazon’s CloudSearch service

boto.connect_cloudsearch2(aws_access_key_id=None, aws_secret_access_key=None, sign_request=False, **kwargs)
Parameters:
  • aws_access_key_id (string) – Your AWS Access Key ID
  • aws_secret_access_key (string) – Your AWS Secret Access Key
  • sign_request (bool) – whether or not to sign search and upload requests
Return type:

boto.cloudsearch2.layer2.Layer2

Returns:

A connection to Amazon’s CloudSearch2 service

boto.connect_cloudsearchdomain(aws_access_key_id=None, aws_secret_access_key=None, **kwargs)
Parameters:
  • aws_access_key_id (string) – Your AWS Access Key ID
  • aws_secret_access_key (string) – Your AWS Secret Access Key
Return type:

boto.cloudsearchdomain.layer1.CloudSearchDomainConnection

Returns:

A connection to Amazon’s CloudSearch Domain service

boto.connect_cloudtrail(aws_access_key_id=None, aws_secret_access_key=None, **kwargs)

Connect to AWS CloudTrail

Parameters:
  • aws_access_key_id (string) – Your AWS Access Key ID
  • aws_secret_access_key (string) – Your AWS Secret Access Key
Return type:

boto.cloudtrail.layer1.CloudtrailConnection

Returns:

A connection to the AWS Cloudtrail service

boto.connect_cloudwatch(aws_access_key_id=None, aws_secret_access_key=None, **kwargs)
Parameters:
  • aws_access_key_id (string) – Your AWS Access Key ID
  • aws_secret_access_key (string) – Your AWS Secret Access Key
Return type:

boto.ec2.cloudwatch.CloudWatchConnection

Returns:

A connection to Amazon’s EC2 Monitoring service

boto.connect_codedeploy(aws_access_key_id=None, aws_secret_access_key=None, **kwargs)

Connect to AWS CodeDeploy

Parameters:
  • aws_access_key_id (string) – Your AWS Access Key ID
  • aws_secret_access_key (string) – Your AWS Secret Access Key

rtype: boto.cognito.sync.layer1.CodeDeployConnection :return: A connection to the AWS CodeDeploy service

boto.connect_cognito_identity(aws_access_key_id=None, aws_secret_access_key=None, **kwargs)

Connect to Amazon Cognito Identity

Parameters:
  • aws_access_key_id (string) – Your AWS Access Key ID
  • aws_secret_access_key (string) – Your AWS Secret Access Key

rtype: boto.cognito.identity.layer1.CognitoIdentityConnection :return: A connection to the Amazon Cognito Identity service

boto.connect_cognito_sync(aws_access_key_id=None, aws_secret_access_key=None, **kwargs)

Connect to Amazon Cognito Sync

Parameters:
  • aws_access_key_id (string) – Your AWS Access Key ID
  • aws_secret_access_key (string) – Your AWS Secret Access Key

rtype: boto.cognito.sync.layer1.CognitoSyncConnection :return: A connection to the Amazon Cognito Sync service

boto.connect_configservice(aws_access_key_id=None, aws_secret_access_key=None, **kwargs)

Connect to AWS Config

Parameters:
  • aws_access_key_id (string) – Your AWS Access Key ID
  • aws_secret_access_key (string) – Your AWS Secret Access Key

rtype: boto.kms.layer1.ConfigServiceConnection :return: A connection to the AWS Config service

boto.connect_directconnect(aws_access_key_id=None, aws_secret_access_key=None, **kwargs)

Connect to AWS DirectConnect

Parameters:
  • aws_access_key_id (string) – Your AWS Access Key ID
  • aws_secret_access_key (string) – Your AWS Secret Access Key
Return type:

boto.directconnect.layer1.DirectConnectConnection

Returns:

A connection to the AWS DirectConnect service

boto.connect_dynamodb(aws_access_key_id=None, aws_secret_access_key=None, **kwargs)
Parameters:
  • aws_access_key_id (string) – Your AWS Access Key ID
  • aws_secret_access_key (string) – Your AWS Secret Access Key
Return type:

boto.dynamodb.layer2.Layer2

Returns:

A connection to the Layer2 interface for DynamoDB.

boto.connect_ec2(aws_access_key_id=None, aws_secret_access_key=None, **kwargs)
Parameters:
  • aws_access_key_id (string) – Your AWS Access Key ID
  • aws_secret_access_key (string) – Your AWS Secret Access Key
Return type:

boto.ec2.connection.EC2Connection

Returns:

A connection to Amazon’s EC2

boto.connect_ec2_endpoint(url, aws_access_key_id=None, aws_secret_access_key=None, **kwargs)

Connect to an EC2 Api endpoint. Additional arguments are passed through to connect_ec2.

Parameters:
  • url (string) – A url for the ec2 api endpoint to connect to
  • aws_access_key_id (string) – Your AWS Access Key ID
  • aws_secret_access_key (string) – Your AWS Secret Access Key
Return type:

boto.ec2.connection.EC2Connection

Returns:

A connection to Eucalyptus server

boto.connect_ec2containerservice(aws_access_key_id=None, aws_secret_access_key=None, **kwargs)

Connect to Amazon EC2 Container Service rtype: boto.ec2containerservice.layer1.EC2ContainerServiceConnection :return: A connection to the Amazon EC2 Container Service

boto.connect_elastictranscoder(aws_access_key_id=None, aws_secret_access_key=None, **kwargs)
Parameters:
  • aws_access_key_id (string) – Your AWS Access Key ID
  • aws_secret_access_key (string) – Your AWS Secret Access Key
Return type:

boto.ets.layer1.ElasticTranscoderConnection

Returns:

A connection to Amazon’s Elastic Transcoder service

boto.connect_elb(aws_access_key_id=None, aws_secret_access_key=None, **kwargs)
Parameters:
  • aws_access_key_id (string) – Your AWS Access Key ID
  • aws_secret_access_key (string) – Your AWS Secret Access Key
Return type:

boto.ec2.elb.ELBConnection

Returns:

A connection to Amazon’s Load Balancing Service

boto.connect_emr(aws_access_key_id=None, aws_secret_access_key=None, **kwargs)
Parameters:
  • aws_access_key_id (string) – Your AWS Access Key ID
  • aws_secret_access_key (string) – Your AWS Secret Access Key
Return type:

boto.emr.EmrConnection

Returns:

A connection to Elastic mapreduce

boto.connect_euca(host=None, aws_access_key_id=None, aws_secret_access_key=None, port=8773, path='/services/Eucalyptus', is_secure=False, **kwargs)

Connect to a Eucalyptus service.

Parameters:
  • host (string) – the host name or ip address of the Eucalyptus server
  • aws_access_key_id (string) – Your AWS Access Key ID
  • aws_secret_access_key (string) – Your AWS Secret Access Key
Return type:

boto.ec2.connection.EC2Connection

Returns:

A connection to Eucalyptus server

boto.connect_fps(aws_access_key_id=None, aws_secret_access_key=None, **kwargs)
Parameters:
  • aws_access_key_id (string) – Your AWS Access Key ID
  • aws_secret_access_key (string) – Your AWS Secret Access Key
Return type:

boto.fps.connection.FPSConnection

Returns:

A connection to FPS

boto.connect_glacier(aws_access_key_id=None, aws_secret_access_key=None, **kwargs)
Parameters:
  • aws_access_key_id (string) – Your AWS Access Key ID
  • aws_secret_access_key (string) – Your AWS Secret Access Key
Return type:

boto.glacier.layer2.Layer2

Returns:

A connection to Amazon’s Glacier Service

boto.connect_gs(gs_access_key_id=None, gs_secret_access_key=None, **kwargs)

@type gs_access_key_id: string @param gs_access_key_id: Your Google Cloud Storage Access Key ID

@type gs_secret_access_key: string @param gs_secret_access_key: Your Google Cloud Storage Secret Access Key

@rtype: L{GSConnection<boto.gs.connection.GSConnection>} @return: A connection to Google’s Storage service

boto.connect_ia(ia_access_key_id=None, ia_secret_access_key=None, is_secure=False, **kwargs)

Connect to the Internet Archive via their S3-like API.

Parameters:
  • ia_access_key_id (string) – Your IA Access Key ID. This will also look in your boto config file for an entry in the Credentials section called “ia_access_key_id”
  • ia_secret_access_key (string) – Your IA Secret Access Key. This will also look in your boto config file for an entry in the Credentials section called “ia_secret_access_key”
Return type:

boto.s3.connection.S3Connection

Returns:

A connection to the Internet Archive

boto.connect_iam(aws_access_key_id=None, aws_secret_access_key=None, **kwargs)
Parameters:
  • aws_access_key_id (string) – Your AWS Access Key ID
  • aws_secret_access_key (string) – Your AWS Secret Access Key
Return type:

boto.iam.IAMConnection

Returns:

A connection to Amazon’s IAM

boto.connect_kinesis(aws_access_key_id=None, aws_secret_access_key=None, **kwargs)

Connect to Amazon Kinesis

Parameters:
  • aws_access_key_id (string) – Your AWS Access Key ID
  • aws_secret_access_key (string) – Your AWS Secret Access Key

rtype: boto.kinesis.layer1.KinesisConnection :return: A connection to the Amazon Kinesis service

boto.connect_kms(aws_access_key_id=None, aws_secret_access_key=None, **kwargs)

Connect to AWS Key Management Service

Parameters:
  • aws_access_key_id (string) – Your AWS Access Key ID
  • aws_secret_access_key (string) – Your AWS Secret Access Key

rtype: boto.kms.layer1.KMSConnection :return: A connection to the AWS Key Management Service

boto.connect_logs(aws_access_key_id=None, aws_secret_access_key=None, **kwargs)

Connect to Amazon CloudWatch Logs

Parameters:
  • aws_access_key_id (string) – Your AWS Access Key ID
  • aws_secret_access_key (string) – Your AWS Secret Access Key

rtype: boto.kinesis.layer1.CloudWatchLogsConnection :return: A connection to the Amazon CloudWatch Logs service

boto.connect_machinelearning(aws_access_key_id=None, aws_secret_access_key=None, **kwargs)

Connect to Amazon Machine Learning service rtype: boto.machinelearning.layer1.MachineLearningConnection :return: A connection to the Amazon Machine Learning service

boto.connect_mturk(aws_access_key_id=None, aws_secret_access_key=None, **kwargs)
Parameters:
  • aws_access_key_id (string) – Your AWS Access Key ID
  • aws_secret_access_key (string) – Your AWS Secret Access Key
Return type:

boto.mturk.connection.MTurkConnection

Returns:

A connection to MTurk

boto.connect_opsworks(aws_access_key_id=None, aws_secret_access_key=None, **kwargs)
boto.connect_rds(aws_access_key_id=None, aws_secret_access_key=None, **kwargs)
Parameters:
  • aws_access_key_id (string) – Your AWS Access Key ID
  • aws_secret_access_key (string) – Your AWS Secret Access Key
Return type:

boto.rds.RDSConnection

Returns:

A connection to RDS

boto.connect_rds2(aws_access_key_id=None, aws_secret_access_key=None, **kwargs)
Parameters:
  • aws_access_key_id (string) – Your AWS Access Key ID
  • aws_secret_access_key (string) – Your AWS Secret Access Key
Return type:

boto.rds2.layer1.RDSConnection

Returns:

A connection to RDS

boto.connect_redshift(aws_access_key_id=None, aws_secret_access_key=None, **kwargs)
Parameters:
  • aws_access_key_id (string) – Your AWS Access Key ID
  • aws_secret_access_key (string) – Your AWS Secret Access Key
Return type:

boto.redshift.layer1.RedshiftConnection

Returns:

A connection to Amazon’s Redshift service

boto.connect_route53(aws_access_key_id=None, aws_secret_access_key=None, **kwargs)
Parameters:
  • aws_access_key_id (string) – Your AWS Access Key ID
  • aws_secret_access_key (string) – Your AWS Secret Access Key
Return type:

boto.dns.Route53Connection

Returns:

A connection to Amazon’s Route53 DNS Service

boto.connect_route53domains(aws_access_key_id=None, aws_secret_access_key=None, **kwargs)

Connect to Amazon Route 53 Domains

Parameters:
  • aws_access_key_id (string) – Your AWS Access Key ID
  • aws_secret_access_key (string) – Your AWS Secret Access Key

rtype: boto.route53.domains.layer1.Route53DomainsConnection :return: A connection to the Amazon Route 53 Domains service

boto.connect_s3(aws_access_key_id=None, aws_secret_access_key=None, **kwargs)
Parameters:
  • aws_access_key_id (string) – Your AWS Access Key ID
  • aws_secret_access_key (string) – Your AWS Secret Access Key
Return type:

boto.s3.connection.S3Connection

Returns:

A connection to Amazon’s S3

boto.connect_sdb(aws_access_key_id=None, aws_secret_access_key=None, **kwargs)
Parameters:
  • aws_access_key_id (string) – Your AWS Access Key ID
  • aws_secret_access_key (string) – Your AWS Secret Access Key
Return type:

boto.sdb.connection.SDBConnection

Returns:

A connection to Amazon’s SDB

boto.connect_ses(aws_access_key_id=None, aws_secret_access_key=None, **kwargs)
Parameters:
  • aws_access_key_id (string) – Your AWS Access Key ID
  • aws_secret_access_key (string) – Your AWS Secret Access Key
Return type:

boto.ses.SESConnection

Returns:

A connection to Amazon’s SES

boto.connect_sns(aws_access_key_id=None, aws_secret_access_key=None, **kwargs)
Parameters:
  • aws_access_key_id (string) – Your AWS Access Key ID
  • aws_secret_access_key (string) – Your AWS Secret Access Key
Return type:

boto.sns.SNSConnection

Returns:

A connection to Amazon’s SNS

boto.connect_sqs(aws_access_key_id=None, aws_secret_access_key=None, **kwargs)
Parameters:
  • aws_access_key_id (string) – Your AWS Access Key ID
  • aws_secret_access_key (string) – Your AWS Secret Access Key
Return type:

boto.sqs.connection.SQSConnection

Returns:

A connection to Amazon’s SQS

boto.connect_sts(aws_access_key_id=None, aws_secret_access_key=None, **kwargs)
Parameters:
  • aws_access_key_id (string) – Your AWS Access Key ID
  • aws_secret_access_key (string) – Your AWS Secret Access Key
Return type:

boto.sts.STSConnection

Returns:

A connection to Amazon’s STS

boto.connect_support(aws_access_key_id=None, aws_secret_access_key=None, **kwargs)
Parameters:
  • aws_access_key_id (string) – Your AWS Access Key ID
  • aws_secret_access_key (string) – Your AWS Secret Access Key
Return type:

boto.support.layer1.SupportConnection

Returns:

A connection to Amazon’s Support service

boto.connect_swf(aws_access_key_id=None, aws_secret_access_key=None, **kwargs)
Parameters:
  • aws_access_key_id (string) – Your AWS Access Key ID
  • aws_secret_access_key (string) – Your AWS Secret Access Key
Return type:

boto.swf.layer1.Layer1

Returns:

A connection to the Layer1 interface for SWF.

boto.connect_vpc(aws_access_key_id=None, aws_secret_access_key=None, **kwargs)
Parameters:
  • aws_access_key_id (string) – Your AWS Access Key ID
  • aws_secret_access_key (string) – Your AWS Secret Access Key
Return type:

boto.vpc.VPCConnection

Returns:

A connection to VPC

boto.connect_walrus(host=None, aws_access_key_id=None, aws_secret_access_key=None, port=8773, path='/services/Walrus', is_secure=False, **kwargs)

Connect to a Walrus service.

Parameters:
  • host (string) – the host name or ip address of the Walrus server
  • aws_access_key_id (string) – Your AWS Access Key ID
  • aws_secret_access_key (string) – Your AWS Secret Access Key
Return type:

boto.s3.connection.S3Connection

Returns:

A connection to Walrus

boto.init_logging()
boto.set_file_logger(name, filepath, level=20, format_string=None)
boto.set_stream_logger(name, level=10, format_string=None)
boto.storage_uri(uri_str, default_scheme='file', debug=0, validate=True, bucket_storage_uri_class=<class 'boto.storage_uri.BucketStorageUri'>, suppress_consec_slashes=True, is_latest=False)

Instantiate a StorageUri from a URI string.

Parameters:
  • uri_str (string) – URI naming bucket + optional object.
  • default_scheme (string) – default scheme for scheme-less URIs.
  • debug (int) – debug level to pass in to boto connection (range 0..2).
  • validate (bool) – whether to check for bucket name validity.
  • bucket_storage_uri_class (BucketStorageUri interface.) – Allows mocking for unit tests.
  • suppress_consec_slashes – If provided, controls whether consecutive slashes will be suppressed in key paths.
  • is_latest (bool) – whether this versioned object represents the current version.

We allow validate to be disabled to allow caller to implement bucket-level wildcarding (outside the boto library; see gsutil).

Return type:boto.StorageUri subclass
Returns:StorageUri subclass for given URI.

uri_str must be one of the following formats:

  • gs://bucket/name
  • gs://bucket/name#ver
  • s3://bucket/name
  • gs://bucket
  • s3://bucket
  • filename (which could be a Unix path like /a/b/c or a Windows path like C:c)

The last example uses the default scheme (‘file’, unless overridden).

boto.storage_uri_for_key(key)

Returns a StorageUri for the given key.

Parameters:key (boto.s3.key.Key or subclass) – URI naming bucket + optional object.

boto.connection

Handles basic connections to AWS

class boto.connection.AWSAuthConnection(host, aws_access_key_id=None, aws_secret_access_key=None, is_secure=True, port=None, proxy=None, proxy_port=None, proxy_user=None, proxy_pass=None, debug=0, https_connection_factory=None, path='/', provider='aws', security_token=None, suppress_consec_slashes=True, validate_certs=True, profile_name=None)
Parameters:
  • host (str) – The host to make the connection to
  • aws_access_key_id (str) – Your AWS Access Key ID (provided by Amazon). If none is specified, the value in your AWS_ACCESS_KEY_ID environmental variable is used.
  • aws_secret_access_key (str) – Your AWS Secret Access Key (provided by Amazon). If none is specified, the value in your AWS_SECRET_ACCESS_KEY environmental variable is used.
  • security_token (str) – The security token associated with temporary credentials issued by STS. Optional unless using temporary credentials. If none is specified, the environment variable AWS_SECURITY_TOKEN is used if defined.
  • is_secure (boolean) – Whether the connection is over SSL
  • https_connection_factory (list or tuple) – A pair of an HTTP connection factory and the exceptions to catch. The factory should have a similar interface to L{http_client.HTTPSConnection}.
  • proxy (str) – Address/hostname for a proxy server
  • proxy_port (int) – The port to use when connecting over a proxy
  • proxy_user (str) – The username to connect with on the proxy
  • proxy_pass (str) – The password to use when connection over a proxy.
  • port (int) – The port to use to connect
  • suppress_consec_slashes (bool) – If provided, controls whether consecutive slashes will be suppressed in key paths.
  • validate_certs (bool) – Controls whether SSL certificates will be validated or not. Defaults to True.
  • profile_name (str) – Override usual Credentials section in config file to use a named set of keys instead.
access_key
auth_region_name
auth_service_name
aws_access_key_id
aws_secret_access_key
build_base_http_request(method, path, auth_path, params=None, headers=None, data='', host=None)
close()

(Optional) Close any open HTTP connections. This is non-destructive, and making a new request will open a connection again.

connection
get_http_connection(host, port, is_secure)
get_path(path='/')
get_proxy_auth_header()
get_proxy_url_with_auth()
gs_access_key_id
gs_secret_access_key
handle_proxy(proxy, proxy_port, proxy_user, proxy_pass)
make_request(method, path, headers=None, data='', host=None, auth_path=None, sender=None, override_num_retries=None, params=None, retry_handler=None)

Makes a request to the server, with stock multiple-retry logic.

new_http_connection(host, port, is_secure)
prefix_proxy_to_path(path, host=None)
profile_name
proxy_ssl(host=None, port=None)
put_http_connection(host, port, is_secure, connection)
secret_key
server_name(port=None)
set_host_header(request)
set_request_hook(hook)
skip_proxy(host)
class boto.connection.AWSQueryConnection(aws_access_key_id=None, aws_secret_access_key=None, is_secure=True, port=None, proxy=None, proxy_port=None, proxy_user=None, proxy_pass=None, host=None, debug=0, https_connection_factory=None, path='/', security_token=None, validate_certs=True, profile_name=None, provider='aws')
APIVersion = ''
ResponseError

alias of boto.exception.BotoServerError

build_complex_list_params(params, items, label, names)

Serialize a list of structures.

For example:

items = [('foo', 'bar', 'baz'), ('foo2', 'bar2', 'baz2')]
label = 'ParamName.member'
names = ('One', 'Two', 'Three')
self.build_complex_list_params(params, items, label, names)

would result in the params dict being updated with these params:

ParamName.member.1.One = foo
ParamName.member.1.Two = bar
ParamName.member.1.Three = baz

ParamName.member.2.One = foo2
ParamName.member.2.Two = bar2
ParamName.member.2.Three = baz2
Parameters:
  • params (dict) – The params dict. The complex list params will be added to this dict.
  • items (list of tuples) – The list to serialize.
  • label (string) – The prefix to apply to the parameter.
  • names (tuple of strings) – The names associated with each tuple element.
build_list_params(params, items, label)
get_list(action, params, markers, path='/', parent=None, verb='GET')
get_object(action, params, cls, path='/', parent=None, verb='GET')
get_status(action, params, path='/', parent=None, verb='GET')
get_utf8_value(value)
make_request(action, params=None, path='/', verb='GET')

Makes a request to the server, with stock multiple-retry logic.

class boto.connection.ConnectionPool

A connection pool that expires connections after a fixed period of time. This saves time spent waiting for a connection that AWS has timed out on the other end.

This class is thread-safe.

CLEAN_INTERVAL = 5.0
STALE_DURATION = 60.0
clean()

Clean up the stale connections in all of the pools, and then get rid of empty pools. Pools clean themselves every time a connection is fetched; this cleaning takes care of pools that aren’t being used any more, so nothing is being gotten from them.

get_http_connection(host, port, is_secure)

Gets a connection from the pool for the named host. Returns None if there is no connection that can be reused. It’s the caller’s responsibility to call close() on the connection when it’s no longer needed.

put_http_connection(host, port, is_secure, conn)

Adds a connection to the pool of connections that can be reused for the named host.

size()

Returns the number of connections in the pool.

class boto.connection.HTTPRequest(method, protocol, host, port, path, auth_path, params, headers, body)

Represents an HTTP request.

Parameters:
  • method (string) – The HTTP method name, ‘GET’, ‘POST’, ‘PUT’ etc.
  • protocol (string) – The http protocol used, ‘http’ or ‘https’.
  • host (string) – Host to which the request is addressed. eg. abc.com
  • port (int) – port on which the request is being sent. Zero means unset, in which case default port will be chosen.
  • path (string) – URL path that is being accessed.
  • path – The part of the URL path used when creating the authentication string.
  • params (dict) – HTTP url query parameters, with key as name of the param, and value as value of param.
  • headers (dict) – HTTP headers, with key as name of the header and value as value of header.
  • body (string) – Body of the HTTP request. If not present, will be None or empty string (‘’).
authorize(connection, **kwargs)
class boto.connection.HTTPResponse(*args, **kwargs)
read(amt=None)

Read the response.

This method does not have the same behavior as http_client.HTTPResponse.read. Instead, if this method is called with no amt arg, then the response body will be cached. Subsequent calls to read() with no args will return the cached response.

class boto.connection.HostConnectionPool

A pool of connections for one remote (host,port,is_secure).

When connections are added to the pool, they are put into a pending queue. The _mexe method returns connections to the pool before the response body has been read, so they connections aren’t ready to send another request yet. They stay in the pending queue until they are ready for another request, at which point they are returned to the pool of ready connections.

The pool of ready connections is an ordered list of (connection,time) pairs, where the time is the time the connection was returned from _mexe. After a certain period of time, connections are considered stale, and discarded rather than being reused. This saves having to wait for the connection to time out if AWS has decided to close it on the other end because of inactivity.

Thread Safety:

This class is used only from ConnectionPool while it’s mutex is held.
clean()

Get rid of stale connections.

get()

Returns the next connection in this pool that is ready to be reused. Returns None if there aren’t any.

put(conn)

Adds a connection to the pool, along with the time it was added.

size()

Returns the number of connections in the pool for this host. Some of the connections may still be in use, and may not be ready to be returned by get().

boto.exception

Exception classes - Subclassing allows you to check for specific errors

exception boto.exception.AWSConnectionError(reason, *args)

General error connecting to Amazon Web Services.

exception boto.exception.BotoClientError(reason, *args)

General Boto Client error (error accessing AWS)

exception boto.exception.BotoServerError(status, reason, body=None, *args)
endElement(name, value, connection)
startElement(name, attrs, connection)
class boto.exception.ConsoleOutput(parent=None)
endElement(name, value, connection)
startElement(name, attrs, connection)
exception boto.exception.DynamoDBResponseError(status, reason, body=None, *args)
exception boto.exception.EC2ResponseError(status, reason, body=None)

Error in response from EC2.

endElement(name, value, connection)
startElement(name, attrs, connection)
exception boto.exception.EmrResponseError(status, reason, body=None, *args)

Error in response from EMR

exception boto.exception.GSCopyError(status, reason, body=None, *args)

Error copying a key on GS.

exception boto.exception.GSCreateError(status, reason, body=None)

Error creating a bucket or key on GS.

exception boto.exception.GSDataError(reason, *args)

Error receiving data from GS.

exception boto.exception.GSPermissionsError(reason, *args)

Permissions error when accessing a bucket or key on GS.

exception boto.exception.GSResponseError(status, reason, body=None)

Error in response from GS.

exception boto.exception.InvalidAclError(message)

Exception raised when ACL XML is invalid.

exception boto.exception.InvalidCorsError(message)

Exception raised when CORS XML is invalid.

exception boto.exception.InvalidEncryptionConfigError(message)

Exception raised when GCS encryption configuration XML is invalid.

exception boto.exception.InvalidInstanceMetadataError(msg)
MSG = "You can set the 'metadata_service_num_attempts' in your boto config file to increase the number of times boto will attempt to retrieve credentials from the instance metadata service."
exception boto.exception.InvalidLifecycleConfigError(message)

Exception raised when GCS lifecycle configuration XML is invalid.

exception boto.exception.InvalidUriError(message)

Exception raised when URI is invalid.

exception boto.exception.JSONResponseError(status, reason, body=None, *args)

This exception expects the fully parsed and decoded JSON response body to be passed as the body parameter.

Variables:
  • status – The HTTP status code.
  • reason – The HTTP reason message.
  • body – The Python dict that represents the decoded JSON response body.
  • error_message – The full description of the AWS error encountered.
  • error_code – A short string that identifies the AWS error (e.g. ConditionalCheckFailedException)
exception boto.exception.NoAuthHandlerFound

Is raised when no auth handlers were found ready to authenticate.

exception boto.exception.PleaseRetryException(message, response=None)

Indicates a request should be retried.

exception boto.exception.ResumableDownloadException(message, disposition)

Exception raised for various resumable download problems.

self.disposition is of type ResumableTransferDisposition.

class boto.exception.ResumableTransferDisposition
ABORT = 'ABORT'
ABORT_CUR_PROCESS = 'ABORT_CUR_PROCESS'
START_OVER = 'START_OVER'
WAIT_BEFORE_RETRY = 'WAIT_BEFORE_RETRY'
exception boto.exception.ResumableUploadException(message, disposition)

Exception raised for various resumable upload problems.

self.disposition is of type ResumableTransferDisposition.

exception boto.exception.S3CopyError(status, reason, body=None, *args)

Error copying a key on S3.

exception boto.exception.S3CreateError(status, reason, body=None)

Error creating a bucket or key on S3.

exception boto.exception.S3DataError(reason, *args)

Error receiving data from S3.

exception boto.exception.S3PermissionsError(reason, *args)

Permissions error when accessing a bucket or key on S3.

exception boto.exception.S3ResponseError(status, reason, body=None)

Error in response from S3.

exception boto.exception.SDBPersistenceError
exception boto.exception.SDBResponseError(status, reason, body=None, *args)

Error in responses from SDB.

exception boto.exception.SQSDecodeError(reason, message)

Error when decoding an SQS message.

exception boto.exception.SQSError(status, reason, body=None)

General Error on Simple Queue Service.

endElement(name, value, connection)
startElement(name, attrs, connection)
exception boto.exception.SWFResponseError(status, reason, body=None, *args)
exception boto.exception.StorageCopyError(status, reason, body=None, *args)

Error copying a key on a storage service.

exception boto.exception.StorageCreateError(status, reason, body=None)

Error creating a bucket or key on a storage service.

endElement(name, value, connection)
exception boto.exception.StorageDataError(reason, *args)

Error receiving data from a storage service.

exception boto.exception.StoragePermissionsError(reason, *args)

Permissions error when accessing a bucket or key on a storage service.

exception boto.exception.StorageResponseError(status, reason, body=None)

Error in response from a storage service.

endElement(name, value, connection)
startElement(name, attrs, connection)
exception boto.exception.TooManyRecordsException(message)

Exception raised when a search of Route53 records returns more records than requested.

boto.handler

class boto.handler.XmlHandler(root_node, connection)
characters(content)
endElement(name)
startElement(name, attrs)
class boto.handler.XmlHandlerWrapper(root_node, connection)
parseString(content)

boto.resultset

class boto.resultset.BooleanResult(marker_elem=None)
endElement(name, value, connection)
startElement(name, attrs, connection)
to_boolean(value, true_value='true')
class boto.resultset.ResultSet(marker_elem=None)

The ResultSet is used to pass results back from the Amazon services to the client. It is light wrapper around Python’s list class, with some additional methods for parsing XML results from AWS. Because I don’t really want any dependencies on external libraries, I’m using the standard SAX parser that comes with Python. The good news is that it’s quite fast and efficient but it makes some things rather difficult.

You can pass in, as the marker_elem parameter, a list of tuples. Each tuple contains a string as the first element which represents the XML element that the resultset needs to be on the lookout for and a Python class as the second element of the tuple. Each time the specified element is found in the XML, a new instance of the class will be created and popped onto the stack.

Variables:next_token (str) – A hash used to assist in paging through very long result sets. In most cases, passing this value to certain methods will give you another ‘page’ of results.
endElement(name, value, connection)
startElement(name, attrs, connection)
to_boolean(value, true_value='true')

boto.utils

Some handy utility functions used by several classes.

class boto.utils.AuthSMTPHandler(mailhost, username, password, fromaddr, toaddrs, subject)

This class extends the SMTPHandler in the standard Python logging module to accept a username and password on the constructor and to then use those credentials to authenticate with the SMTP server. To use this, you could add something like this in your boto config file:

[handler_hand07] class=boto.utils.AuthSMTPHandler level=WARN formatter=form07 args=(‘localhost’, ‘username’, ‘password’, ‘from@abc’, [‘user1@abc’, ‘user2@xyz’], ‘Logger Subject’)

Initialize the handler.

We have extended the constructor to accept a username/password for SMTP authentication.

emit(record)

Emit a record.

Format the record and send it to the specified addressees. It would be really nice if I could add authorization to this class without having to resort to cut and paste inheritance but, no.

class boto.utils.LRUCache(capacity)

A dictionary-like object that stores only a certain number of items, and discards its least recently used item when full.

>>> cache = LRUCache(3)
>>> cache['A'] = 0
>>> cache['B'] = 1
>>> cache['C'] = 2
>>> len(cache)
3
>>> cache['A']
0

Adding new items to the cache does not increase its size. Instead, the least recently used item is dropped:

>>> cache['D'] = 3
>>> len(cache)
3
>>> 'B' in cache
False

Iterating over the cache returns the keys, starting with the most recently used:

>>> for key in cache:
...     print key
D
A
C

This code is based on the LRUCache class from Genshi which is based on Myghty’s LRUCache from myghtyutils.util, written by Mike Bayer and released under the MIT license (Genshi uses the BSD License).

class boto.utils.LazyLoadMetadata(url, num_retries, timeout=None)
get(k[, d]) → D[k] if k in D, else d. d defaults to None.
items() → list of D's (key, value) pairs, as 2-tuples
values() → list of D's values
class boto.utils.Password(str=None, hashfunc=None)

Password object that stores itself as hashed. Hash defaults to SHA512 if available, MD5 otherwise.

Load the string from an initial value, this should be the raw hashed password.

hashfunc()

Returns a sha512 hash object; optionally initialized with a string

set(value)
class boto.utils.RequestHook

This can be extended and supplied to the connection object to gain access to request and response object after the request completes. One use for this would be to implement some specific request logging.

handle_request_data(request, response, error=False)
class boto.utils.ShellCommand(command, wait=True, fail_fast=False, cwd=None)
getOutput()
getStatus()
output

The STDIN and STDERR output of the command

run(cwd=None)
setReadOnly(value)
status

The exit code for the command

boto.utils.canonical_string(method, path, headers, expires=None, provider=None)

Generates the aws canonical string for the given parameters

boto.utils.compute_hash(fp, buf_size=8192, size=None, hash_algorithm=<built-in function openssl_md5>)
boto.utils.compute_md5(fp, buf_size=8192, size=None)

Compute MD5 hash on passed file and return results in a tuple of values.

Parameters:
  • fp (file) – File pointer to the file to MD5 hash. The file pointer will be reset to its current location before the method returns.
  • buf_size (integer) – Number of bytes per read request.
  • size (int) – (optional) The Maximum number of bytes to read from the file pointer (fp). This is useful when uploading a file in multiple parts where the file is being split inplace into different parts. Less bytes may be available.
Return type:

tuple

Returns:

A tuple containing the hex digest version of the MD5 hash as the first element, the base64 encoded version of the plain digest as the second element and the data size as the third element.

boto.utils.fetch_file(uri, file=None, username=None, password=None)

Fetch a file based on the URI provided. If you do not pass in a file pointer a tempfile.NamedTemporaryFile, or None if the file could not be retrieved is returned. The URI can be either an HTTP url, or “s3://bucket_name/key_name”

boto.utils.find_class(module_name, class_name=None)
boto.utils.find_matching_headers(name, headers)

Takes a specific header name and a dict of headers {“name”: “value”}. Returns a list of matching header names, case-insensitive.

boto.utils.get_aws_metadata(headers, provider=None)
boto.utils.get_instance_identity(version='latest', url='http://169.254.169.254', timeout=None, num_retries=5)

Returns the instance identity as a nested Python dictionary.

boto.utils.get_instance_metadata(version='latest', url='http://169.254.169.254', data='meta-data/', timeout=None, num_retries=5)

Returns the instance metadata as a nested Python dictionary. Simple values (e.g. local_hostname, hostname, etc.) will be stored as string values. Values such as ancestor-ami-ids will be stored in the dict as a list of string values. More complex fields such as public-keys and will be stored as nested dicts.

If the timeout is specified, the connection to the specified url will time out after the specified number of seconds.

boto.utils.get_instance_userdata(version='latest', sep=None, url='http://169.254.169.254', timeout=None, num_retries=5)
boto.utils.get_ts(ts=None)
boto.utils.get_utf8_value(value)
boto.utils.guess_mime_type(content, deftype)

Description: Guess the mime type of a block of text :param content: content we’re finding the type of :type str:

Parameters:deftype – Default mime type
Return type:<type>:
Returns:<description>
boto.utils.host_is_ipv6(hostname)

Detect (naively) if the hostname is an IPV6 host. Return a boolean.

boto.utils.merge_headers_by_name(name, headers)

Takes a specific header name and a dict of headers {“name”: “value”}. Returns a string of all header values, comma-separated, that match the input header name, case-insensitive.

boto.utils.merge_meta(headers, metadata, provider=None)
boto.utils.mklist(value)
boto.utils.notify(subject, body=None, html_body=None, to_string=None, attachments=None, append_instance_id=True)
boto.utils.parse_host(hostname)

Given a hostname that may have a port name, ensure that the port is trimmed returning only the host, including hostnames that are IPV6 and may include brackets.

boto.utils.parse_ts(ts)
boto.utils.pythonize_name(name)

Convert camel case to a “pythonic” name.

Examples:

pythonize_name('CamelCase') -> 'camel_case'
pythonize_name('already_pythonized') -> 'already_pythonized'
pythonize_name('HTTPRequest') -> 'http_request'
pythonize_name('HTTPStatus200Ok') -> 'http_status_200_ok'
pythonize_name('UPPER') -> 'upper'
pythonize_name('') -> ''
boto.utils.retry_url(url, retry_on_404=True, num_retries=10, timeout=None)

Retry a url. This is specifically used for accessing the metadata service on an instance. Since this address should never be proxied (for security reasons), we create a ProxyHandler with a NULL dictionary to override any proxy settings in the environment.

boto.utils.setlocale(*args, **kwds)

A context manager to set the locale in a threadsafe manner.

boto.utils.unquote_v(nv)
boto.utils.update_dme(username, password, dme_id, ip_address)

Update your Dynamic DNS record with DNSMadeEasy.com

boto.utils.write_mime_multipart(content, compress=False, deftype='text/plain', delimiter=':')

Description: :param content: A list of tuples of name-content pairs. This is used instead of a dict to ensure that scripts run in order :type list of tuples:

Parameters:
  • compress – Use gzip to compress the scripts, defaults to no compression
  • deftype – The type that should be assumed if nothing else can be figured out
  • delimiter – mime delimiter
Returns:

Final mime multipart

Return type:

str: