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

Represents an SDB Domain

class 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 class boto.sdb.domain.DomainDumpParser(domain)

   SAX parser for a domain that has been dumped

   characters(ch)

   endElement(name)

   startElement(name, attrs)

class class boto.sdb.domain.DomainMetaData(domain=None)

   endElement(name, value, connection)

   startElement(name, attrs, connection)

class class boto.sdb.domain.UploaderThread(domain)

   Uploader Thread

   run()


boto.sdb.item
=============

class 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 class boto.sdb.queryresultset.QueryResultSet(domain=None, query='', max_items=None, attr_names=None)

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