SDB Reference¶

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

SimpleDB DB (Maintained, but little documentation)

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

In instance of boto.sdb.domain.Domain for the requested domain

The domain’s name as a str

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

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:	domain (`boto.sdb.domain.Domain`) – The domain that this item belongs to. name (str) – The name of this item. This name will be used when querying for items using methods like `boto.sdb.domain.Domain.get_item()`

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

SDB Reference¶

boto.sdb¶

boto.sdb.connection¶

boto.sdb.domain¶

boto.sdb.item¶

boto.sdb.queryresultset¶

Table Of Contents

Previous topic

Next topic

This Page

Navigation

SDB Reference¶

boto.sdb¶

boto.sdb.connection¶

boto.sdb.domain¶

boto.sdb.item¶

boto.sdb.queryresultset¶

Table Of Contents

Previous topic

Next topic

This Page

Quick search

Navigation