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
orNone
Returns: A connection to the given region, or None if an invalid region name is given
-
boto.sdb.
get_region
(region_name, **kw_params)¶ Find and return a
boto.sdb.regioninfo.RegionInfo
object given a region name.Type: str Param: The name of the region. Return type: boto.sdb.regioninfo.RegionInfo
Returns: The RegionInfo object for the given region or None if an invalid region name is provided.
boto.sdb.connection¶
-
class
boto.sdb.connection.
ItemThread
(name, domain_name, item_names)¶ A threaded
Item
retriever utility class. RetrievedItem
objects are stored in theitems
instance variable afterrun()
is called.Tip
The item retrieval will not start until the
run()
method is called.Parameters: Variables: items (list) – A list of items retrieved. Starts as empty list.
-
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)¶ 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 associatedItem
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 viaboto.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 yourboto.cfg
:[SDB] region = eu-west-1
-
APIVersion
= '2009-04-15'¶
-
DefaultRegionEndpoint
= 'sdb.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
- domain_or_name (string or
-
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: Returns: True if successful
- domain_or_name (string or
-
create_domain
(domain_name)¶ Create a SimpleDB domain.
Parameters: domain_name (string) – The name of the new domain Return type: boto.sdb.domain.Domain
objectReturns: 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: Returns: True if successful
- domain_or_name (string or
-
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 objectReturn 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 objectReturn type: boto.sdb.domain.DomainMetaData
objectReturns: The newly created domain metadata object
-
get_all_domains
(max_domains=None, next_token=None)¶ Returns a
boto.resultset.ResultSet
containing allboto.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 returnedResultSet
object. This attribute is set if there are more than Domains than the value specified in themax_domains
keyword. Pass thenext_token
value from you earlier query in this keyword to get the next ‘page’ of domains.
- max_domains (int) – Limit the returned
-
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: Returns: An Item with the requested attribute name/values set on it
- domain_or_name (string or
-
get_domain
(domain_name, validate=True)¶ Retrieves a
boto.sdb.domain.Domain
object whose name matchesdomain_name
.Parameters: Raises: boto.exception.SDBResponseError
ifvalidate
isTrue
and no match could be found.Return type: Returns: The requested domain
-
get_domain_and_name
(domain_or_name)¶ Given a
str
orboto.sdb.domain.Domain
, return atuple
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
orboto.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.- In instance of
-
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 thatNone
is returned ifvalidate
isTrue
and no match was found (instead of raising an exception).Parameters: Return type: boto.sdb.domain.Domain
object orNone
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: Returns: True if successful
- domain_or_name (string or
-
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: Returns: An iterator containing the results.
- domain_or_name (string or
-
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¶
Represents an 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: 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: 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: 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: Return type: boto.sdb.item.Item
orNone
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: 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)¶
-
-
class
boto.sdb.domain.
DomainDumpParser
(domain)¶ SAX parser for a domain that has been dumped
-
characters
(ch)¶
-
endElement
(name)¶
-
startElement
(name, attrs)¶
-
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 aDomain
, 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 givenvalue
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:
-
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 aNone
value on this object.
-
startElement
(name, attrs, connection)¶
- domain (
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)¶