
boto
****


boto
====

class class boto.NullHandler(level=0)

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

   emit(record)

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_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_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, **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.cloudsearch2.layer2.Layer2"

   Returns:
      A connection to Amazon's CloudSearch2 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_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_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_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_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 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{httplib.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()

   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 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)

   APIVersion = ''

   ResponseError

      alias of "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')

class 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 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 class boto.connection.HTTPResponse(*args, **kwargs)

   read(amt=None)

      Read the response.

      This method does not have the same behavior as
      httplib.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 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 exception boto.exception.AWSConnectionError(reason, *args)

   General error connecting to Amazon Web Services.

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

   General Boto Client error (error accessing AWS)

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

   endElement(name, value, connection)

   startElement(name, attrs, connection)

class class boto.exception.ConsoleOutput(parent=None)

   endElement(name, value, connection)

   startElement(name, attrs, connection)

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

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

   Error in response from EC2.

   endElement(name, value, connection)

   startElement(name, attrs, connection)

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

   Error in response from EMR

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

   Error copying a key on GS.

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

   Error creating a bucket or key on GS.

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

   Error receiving data from GS.

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

   Permissions error when accessing a bucket or key on GS.

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

   Error in response from GS.

exception exception boto.exception.InvalidAclError(message)

   Exception raised when ACL XML is invalid.

exception exception boto.exception.InvalidCorsError(message)

   Exception raised when CORS XML is invalid.

exception exception boto.exception.InvalidLifecycleConfigError(message)

   Exception raised when GCS lifecycle configuration XML is invalid.

exception exception boto.exception.InvalidUriError(message)

   Exception raised when URI is invalid.

exception 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 exception boto.exception.NoAuthHandlerFound

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

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

   Indicates a request should be retried.

exception exception boto.exception.ResumableDownloadException(message, disposition)

   Exception raised for various resumable download problems.

   self.disposition is of type ResumableTransferDisposition.

class class boto.exception.ResumableTransferDisposition

   ABORT = 'ABORT'

   ABORT_CUR_PROCESS = 'ABORT_CUR_PROCESS'

   START_OVER = 'START_OVER'

   WAIT_BEFORE_RETRY = 'WAIT_BEFORE_RETRY'

exception exception boto.exception.ResumableUploadException(message, disposition)

   Exception raised for various resumable upload problems.

   self.disposition is of type ResumableTransferDisposition.

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

   Error copying a key on S3.

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

   Error creating a bucket or key on S3.

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

   Error receiving data from S3.

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

   Permissions error when accessing a bucket or key on S3.

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

   Error in response from S3.

exception exception boto.exception.SDBPersistenceError

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

   Error in responses from SDB.

exception exception boto.exception.SQSDecodeError(reason, message)

   Error when decoding an SQS message.

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

   General Error on Simple Queue Service.

   endElement(name, value, connection)

   startElement(name, attrs, connection)

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

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

   Error copying a key on a storage service.

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

   Error creating a bucket or key on a storage service.

   endElement(name, value, connection)

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

   Error receiving data from a storage service.

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

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

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

   Error in response from a storage service.

   endElement(name, value, connection)

   startElement(name, attrs, connection)

exception exception boto.exception.TooManyRecordsException(message)

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


boto.handler
============

class class boto.handler.XmlHandler(root_node, connection)

   characters(content)

   endElement(name)

   startElement(name, attrs)

class class boto.handler.XmlHandlerWrapper(root_node, connection)

   parseString(content)


boto.resultset
==============

class class boto.resultset.BooleanResult(marker_elem=None)

   endElement(name, value, connection)

   startElement(name, attrs, connection)

   to_boolean(value, true_value='true')

class 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 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 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 class boto.utils.LazyLoadMetadata(url, num_retries)

   get(key, default=None)

   items()

   values()

class 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 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 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')

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.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_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)

   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.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:
