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.

SDB Reference

In addition to what is seen below, boto includes an abstraction layer for SimpleDB that may be used:

boto.sdb

boto.sdb.connect_to_region(region_name, **kw_params)

Given a valid region name, return a boto.sdb.connection.SDBConnection.

Type:str
Parameters:region_name – The name of the region to connect to.
Return type:boto.sdb.connection.SDBConnection or None
Returns:A connection to the given region, or None if an invalid region name is given
boto.sdb.regions()

Get all available regions for the SDB service.

Return type:list
Returns:A list of boto.sdb.regioninfo.RegionInfo instances

boto.sdb.connection

class boto.sdb.connection.ItemThread(name, domain_name, item_names)

A threaded Item retriever utility class. Retrieved Item objects are stored in the items instance variable after run() is called.

Tip

The item retrieval will not start until the run() method is called.

Parameters:
  • name (str) – A thread name. Used for identification.
  • domain_name (str) – The name of a SimpleDB Domain
  • item_names (string or list of strings) – The name(s) of the items to retrieve from the specified Domain.
Variables:

items (list) – A list of items retrieved. Starts as empty list.

run()

Start the threaded retrieval of items. Populates the items list with Item objects.

class boto.sdb.connection.SDBConnection(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, region=None, path='/', converter=None, security_token=None, validate_certs=True, profile_name=None)

This class serves as a gateway to your SimpleDB region (defaults to us-east-1). Methods within allow access to SimpleDB Domain objects and their associated Item objects.

Tip

While you may instantiate this class directly, it may be easier to go through boto.connect_sdb().

For any keywords that aren’t documented, refer to the parent class, boto.connection.AWSAuthConnection. You can avoid having to worry about these keyword arguments by instantiating these objects via boto.connect_sdb().

Parameters:region (boto.sdb.regioninfo.SDBRegionInfo) –

Explicitly specify a region. Defaults to us-east-1 if not specified. You may also specify the region in your boto.cfg:

[SDB]
region = eu-west-1
APIVersion = '2009-04-15'
DefaultRegionEndpoint = 'sdb.us-east-1.amazonaws.com'
DefaultRegionName = 'us-east-1'
ResponseError

alias of boto.exception.SDBResponseError

batch_delete_attributes(domain_or_name, items)

Delete multiple items in a domain.

Parameters:
  • domain_or_name (string or boto.sdb.domain.Domain object.) – Either the name of a domain or a Domain object
  • items (dict or dict-like object) –

    A dictionary-like object. The keys of the dictionary are the item names and the values are either:

    • dictionaries of attribute names/values, exactly the same as the attribute_names parameter of the scalar put_attributes call. The attribute name/value pairs will only be deleted if they match the name/value pairs passed in.
    • None which means that all attributes associated with the item should be deleted.
Returns:

True if successful

batch_put_attributes(domain_or_name, items, replace=True)

Store attributes for multiple items in a domain.

Parameters:
  • domain_or_name (string or boto.sdb.domain.Domain object.) – Either the name of a domain or a Domain object
  • items (dict or dict-like object) – A dictionary-like object. The keys of the dictionary are the item names and the values are themselves dictionaries of attribute names/values, exactly the same as the attribute_names parameter of the scalar put_attributes call.
  • replace (bool) – Whether the attribute values passed in will replace existing values or will be added as addition values. Defaults to True.
Return type:

bool

Returns:

True if successful

create_domain(domain_name)

Create a SimpleDB domain.

Parameters:domain_name (string) – The name of the new domain
Return type:boto.sdb.domain.Domain object
Returns:The newly created domain
delete_attributes(domain_or_name, item_name, attr_names=None, expected_value=None)

Delete attributes from a given item in a domain.

Parameters:
  • domain_or_name (string or boto.sdb.domain.Domain object.) – Either the name of a domain or a Domain object
  • item_name (string) – The name of the item whose attributes are being deleted.
  • attributes (dict, list or boto.sdb.item.Item) – Either a list containing attribute names which will cause all values associated with that attribute name to be deleted or a dict or Item containing the attribute names and keys and list of values to delete as the value. If no value is supplied, all attribute name/values for the item will be deleted.
  • expected_value (list) –

    If supplied, this is a list or tuple consisting of a single attribute name and expected value. The list can be of the form:

    • [‘name’, ‘value’]

    In which case the call will first verify that the attribute “name” of this item has a value of “value”. If it does, the delete will proceed, otherwise a ConditionalCheckFailed error will be returned. The list can also be of the form:

    • [‘name’, True|False]

    which will simply check for the existence (True) or non-existence (False) of the attribute.

Return type:

bool

Returns:

True if successful

delete_domain(domain_or_name)

Delete a SimpleDB domain.

Caution

This will delete the domain and all items within the domain.

Parameters:domain_or_name (string or boto.sdb.domain.Domain object.) – Either the name of a domain or a Domain object
Return type:bool
Returns:True if successful
domain_metadata(domain_or_name)

Get the Metadata for a SimpleDB domain.

Parameters:domain_or_name (string or boto.sdb.domain.Domain object.) – Either the name of a domain or a Domain object
Return type:boto.sdb.domain.DomainMetaData object
Returns:The newly created domain metadata object
get_all_domains(max_domains=None, next_token=None)

Returns a boto.resultset.ResultSet containing all boto.sdb.domain.Domain objects associated with this connection’s Access Key ID.

Parameters:
  • max_domains (int) – Limit the returned ResultSet to the specified number of members.
  • next_token (str) – A token string that was returned in an earlier call to this method as the next_token attribute on the returned ResultSet object. This attribute is set if there are more than Domains than the value specified in the max_domains keyword. Pass the next_token value from you earlier query in this keyword to get the next ‘page’ of domains.
get_attributes(domain_or_name, item_name, attribute_names=None, consistent_read=False, item=None)

Retrieve attributes for a given item in a domain.

Parameters:
  • domain_or_name (string or boto.sdb.domain.Domain object.) – Either the name of a domain or a Domain object
  • item_name (string) – The name of the item whose attributes are being retrieved.
  • attribute_names (string or list of strings) – An attribute name or list of attribute names. This parameter is optional. If not supplied, all attributes will be retrieved for the item.
  • consistent_read (bool) – When set to true, ensures that the most recent data is returned.
  • item (boto.sdb.item.Item) – Instead of instantiating a new Item object, you may specify one to update.
Return type:

boto.sdb.item.Item

Returns:

An Item with the requested attribute name/values set on it

get_domain(domain_name, validate=True)

Retrieves a boto.sdb.domain.Domain object whose name matches domain_name.

Parameters:
  • domain_name (str) – The name of the domain to retrieve
  • validate (bool) – When True, check to see if the domain actually exists. If False, blindly return a Domain object with the specified name set.
Raises:

boto.exception.SDBResponseError if validate is True and no match could be found.

Return type:

boto.sdb.domain.Domain

Returns:

The requested domain

get_domain_and_name(domain_or_name)

Given a str or boto.sdb.domain.Domain, return a tuple with the following members (in order):

Parameters:domain_or_name (str or boto.sdb.domain.Domain) – The domain or domain name to get the domain and name for.
Raises:boto.exception.SDBResponseError when an invalid domain name is specified.
Return type:tuple
Returns:A tuple with contents outlined as per above.
get_usage()

Returns the BoxUsage (in USD) accumulated on this specific SDBConnection instance.

Tip

This can be out of date, and should only be treated as a rough estimate. Also note that this estimate only applies to the requests made on this specific connection instance. It is by no means an account-wide estimate.

Return type:float
Returns:The accumulated BoxUsage of all requests made on the connection.
lookup(domain_name, validate=True)

Lookup an existing SimpleDB domain. This differs from get_domain() in that None is returned if validate is True and no match was found (instead of raising an exception).

Parameters:
  • domain_name (str) – The name of the domain to retrieve
  • validate (bool) – If True, a None value will be returned if the specified domain can’t be found. If False, a Domain object will be dumbly returned, regardless of whether it actually exists.
Return type:

boto.sdb.domain.Domain object or None

Returns:

The Domain object or None if the domain does not exist.

print_usage()

Print the BoxUsage and approximate costs of all requests made on this specific SDBConnection instance.

Tip

This can be out of date, and should only be treated as a rough estimate. Also note that this estimate only applies to the requests made on this specific connection instance. It is by no means an account-wide estimate.

put_attributes(domain_or_name, item_name, attributes, replace=True, expected_value=None)

Store attributes for a given item in a domain.

Parameters:
  • domain_or_name (string or boto.sdb.domain.Domain object.) – Either the name of a domain or a Domain object
  • item_name (string) – The name of the item whose attributes are being stored.
  • attribute_names (dict or dict-like object) – The name/value pairs to store as attributes
  • expected_value (list) –

    If supplied, this is a list or tuple consisting of a single attribute name and expected value. The list can be of the form:

    • [‘name’, ‘value’]

    In which case the call will first verify that the attribute “name” of this item has a value of “value”. If it does, the delete will proceed, otherwise a ConditionalCheckFailed error will be returned. The list can also be of the form:

    • [‘name’, True|False]

    which will simply check for the existence (True) or non-existence (False) of the attribute.

  • replace (bool) – Whether the attribute values passed in will replace existing values or will be added as addition values. Defaults to True.
Return type:

bool

Returns:

True if successful

select(domain_or_name, query='', next_token=None, consistent_read=False)

Returns a set of Attributes for item names within domain_name that match the query. The query must be expressed in using the SELECT style syntax rather than the original SimpleDB query language. Even though the select request does not require a domain object, a domain object must be passed into this method so the Item objects returned can point to the appropriate domain.

Parameters:
  • domain_or_name (string or boto.sdb.domain.Domain object) – Either the name of a domain or a Domain object
  • query (string) – The SimpleDB query to be performed.
  • consistent_read (bool) – When set to true, ensures that the most recent data is returned.
Return type:

ResultSet

Returns:

An iterator containing the results.

set_item_cls(cls)

While the default item class is boto.sdb.item.Item, this default may be overridden. Use this method to change a connection’s item class.

Parameters:cls (object) – The new class to set as this connection’s item class. See the default item class for inspiration as to what your replacement should/could look like.

boto.sdb.domain

class boto.sdb.domain.Domain(connection=None, name=None)
batch_delete_attributes(items)

Delete multiple items in this domain.

Parameters:items (dict or dict-like object) –

A dictionary-like object. The keys of the dictionary are the item names and the values are either:

  • dictionaries of attribute names/values, exactly the same as the attribute_names parameter of the scalar put_attributes call. The attribute name/value pairs will only be deleted if they match the name/value pairs passed in.
  • None which means that all attributes associated with the item should be deleted.
Return type:bool
Returns:True if successful
batch_put_attributes(items, replace=True)

Store attributes for multiple items.

Parameters:
  • items (dict or dict-like object) – A dictionary-like object. The keys of the dictionary are the item names and the values are themselves dictionaries of attribute names/values, exactly the same as the attribute_names parameter of the scalar put_attributes call.
  • replace (bool) – Whether the attribute values passed in will replace existing values or will be added as addition values. Defaults to True.
Return type:

bool

Returns:

True if successful

delete()

Delete this domain, and all items under it

delete_attributes(item_name, attributes=None, expected_values=None)

Delete attributes from a given item.

Parameters:
  • item_name (string) – The name of the item whose attributes are being deleted.
  • attributes (dict, list or boto.sdb.item.Item) – Either a list containing attribute names which will cause all values associated with that attribute name to be deleted or a dict or Item containing the attribute names and keys and list of values to delete as the value. If no value is supplied, all attribute name/values for the item will be deleted.
  • expected_value (list) –

    If supplied, this is a list or tuple consisting of a single attribute name and expected value. The list can be of the form:

    • [‘name’, ‘value’]

    In which case the call will first verify that the attribute “name” of this item has a value of “value”. If it does, the delete will proceed, otherwise a ConditionalCheckFailed error will be returned. The list can also be of the form:

    • [‘name’, True|False]

    which will simply check for the existence (True) or non-existence (False) of the attribute.

Return type:

bool

Returns:

True if successful

delete_item(item)
endElement(name, value, connection)
from_xml(doc)

Load this domain based on an XML document

get_attributes(item_name, attribute_name=None, consistent_read=False, item=None)

Retrieve attributes for a given item.

Parameters:
  • item_name (string) – The name of the item whose attributes are being retrieved.
  • attribute_names (string or list of strings) – An attribute name or list of attribute names. This parameter is optional. If not supplied, all attributes will be retrieved for the item.
Return type:

boto.sdb.item.Item

Returns:

An Item mapping type containing the requested attribute name/values

get_item(item_name, consistent_read=False)

Retrieves an item from the domain, along with all of its attributes.

Parameters:
  • item_name (string) – The name of the item to retrieve.
  • consistent_read (bool) – When set to true, ensures that the most recent data is returned.
Return type:

boto.sdb.item.Item or None

Returns:

The requested item, or None if there was no match found

get_metadata()
new_item(item_name)
put_attributes(item_name, attributes, replace=True, expected_value=None)

Store attributes for a given item.

Parameters:
  • item_name (string) – The name of the item whose attributes are being stored.
  • attribute_names (dict or dict-like object) – The name/value pairs to store as attributes
  • expected_value (list) –

    If supplied, this is a list or tuple consisting of a single attribute name and expected value. The list can be of the form:

    • [‘name’, ‘value’]

    In which case the call will first verify that the attribute “name” of this item has a value of “value”. If it does, the delete will proceed, otherwise a ConditionalCheckFailed error will be returned. The list can also be of the form:

    • [‘name’, True|False]

    which will simply check for the existence (True) or non-existence (False) of the attribute.

  • replace (bool) – Whether the attribute values passed in will replace existing values or will be added as addition values. Defaults to True.
Return type:

bool

Returns:

True if successful

select(query='', next_token=None, consistent_read=False, max_items=None)

Returns a set of Attributes for item names within domain_name that match the query. The query must be expressed in using the SELECT style syntax rather than the original SimpleDB query language.

Parameters:query (string) – The SimpleDB query to be performed.
Return type:iter
Returns:An iterator containing the results. This is actually a generator function that will iterate across all search results, not just the first page.
startElement(name, attrs, connection)
to_xml(f=None)

Get this domain as an XML DOM Document :param f: Optional File to dump directly to :type f: File or Stream

Returns:File object where the XML has been dumped to
Return type:file
class boto.sdb.domain.DomainDumpParser(domain)

SAX parser for a domain that has been dumped

characters(ch)
endElement(name)
startElement(name, attrs)
class boto.sdb.domain.DomainMetaData(domain=None)
endElement(name, value, connection)
startElement(name, attrs, connection)
class boto.sdb.domain.UploaderThread(domain)

Uploader Thread

run()

Method representing the thread’s activity.

You may override this method in a subclass. The standard run() method invokes the callable object passed to the object’s constructor as the target argument, if any, with sequential and keyword arguments taken from the args and kwargs arguments, respectively.

boto.sdb.item

class boto.sdb.item.Item(domain, name='', active=False)

A dict sub-class that serves as an object representation of a SimpleDB item. An item in SDB is similar to a row in a relational database. Items belong to a Domain, which is similar to a table in a relational database.

The keys on instances of this object correspond to attributes that are stored on the SDB item.

Tip

While it is possible to instantiate this class directly, you may want to use the convenience methods on boto.sdb.domain.Domain for that purpose. For example, boto.sdb.domain.Domain.get_item().

Parameters:
add_value(key, value)

Helps set or add to attributes on this item. If you are adding a new attribute that has yet to be set, it will simply create an attribute named key with your given value as its value. If you are adding a value to an existing attribute, this method will convert the attribute to a list (if it isn’t already) and append your new value to said list.

For clarification, consider the following interactive session:

>>> item = some_domain.get_item('some_item')
>>> item.has_key('some_attr')
False
>>> item.add_value('some_attr', 1)
>>> item['some_attr']
1
>>> item.add_value('some_attr', 2)
>>> item['some_attr']
[1, 2]
Parameters:
  • key (str) – The attribute to add a value to.
  • value (object) – The value to set or append to the attribute.
decode_value(value)
delete()

Deletes this item in SDB.

Note

This local Python object remains in its current state after deletion, this only deletes the remote item in SDB.

endElement(name, value, connection)
load()

Loads or re-loads this item’s attributes from SDB.

Warning

If you have changed attribute values on an Item instance, this method will over-write the values if they are different in SDB. For any local attributes that don’t yet exist in SDB, they will be safe.

save(replace=True)

Saves this item to SDB.

Parameters:replace (bool) – If True, delete any attributes on the remote SDB item that have a None value on this object.
startElement(name, attrs, connection)

boto.sdb.queryresultset

class boto.sdb.queryresultset.QueryResultSet(domain=None, query='', max_items=None, attr_names=None)
class boto.sdb.queryresultset.SelectResultSet(domain=None, query='', max_items=None, next_token=None, consistent_read=False)
next()
boto.sdb.queryresultset.query_lister(domain, query='', max_items=None, attr_names=None)
boto.sdb.queryresultset.select_lister(domain, query='', max_items=None)