diff env/lib/python3.9/site-packages/boto/sdb/connection.py @ 0:4f3585e2f14b draft default tip

"planemo upload commit 60cee0fc7c0cda8592644e1aad72851dec82c959"

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/env/lib/python3.9/site-packages/boto/sdb/connection.py	Mon Mar 22 18:12:50 2021 +0000
@@ -0,0 +1,618 @@
+# Copyright (c) 2006,2007 Mitch Garnaat http://garnaat.org/
+#
+# Permission is hereby granted, free of charge, to any person obtaining a
+# copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish, dis-
+# tribute, sublicense, and/or sell copies of the Software, and to permit
+# persons to whom the Software is furnished to do so, subject to the fol-
+# lowing conditions:
+#
+# The above copyright notice and this permission notice shall be included
+# in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+# OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABIL-
+# ITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT
+# SHALL THE AUTHOR BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+# WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
+import xml.sax
+import threading
+import boto
+from boto import handler
+from boto.connection import AWSQueryConnection
+from boto.sdb.domain import Domain, DomainMetaData
+from boto.sdb.item import Item
+from boto.sdb.regioninfo import SDBRegionInfo
+from boto.exception import SDBResponseError
+
+class ItemThread(threading.Thread):
+    """
+    A threaded :class:`Item <boto.sdb.item.Item>` retriever utility class.
+    Retrieved :class:`Item <boto.sdb.item.Item>` objects are stored in the
+    ``items`` instance variable after :py:meth:`run() <run>` is called.
+
+    .. tip:: The item retrieval will not start until
+        the :func:`run() <boto.sdb.connection.ItemThread.run>` method is called.
+    """
+    def __init__(self, name, domain_name, item_names):
+        """
+        :param str name: A thread name. Used for identification.
+        :param str domain_name: The name of a SimpleDB
+            :class:`Domain <boto.sdb.domain.Domain>`
+        :type item_names: string or list of strings
+        :param item_names: The name(s) of the items to retrieve from the specified
+            :class:`Domain <boto.sdb.domain.Domain>`.
+        :ivar list items: A list of items retrieved. Starts as empty list.
+        """
+        super(ItemThread, self).__init__(name=name)
+        #print 'starting %s with %d items' % (name, len(item_names))
+        self.domain_name = domain_name
+        self.conn = SDBConnection()
+        self.item_names = item_names
+        self.items = []
+
+    def run(self):
+        """
+        Start the threaded retrieval of items. Populates the
+        ``items`` list with :class:`Item <boto.sdb.item.Item>` objects.
+        """
+        for item_name in self.item_names:
+            item = self.conn.get_attributes(self.domain_name, item_name)
+            self.items.append(item)
+
+#boto.set_stream_logger('sdb')
+
+class SDBConnection(AWSQueryConnection):
+    """
+    This class serves as a gateway to your SimpleDB region (defaults to
+    us-east-1). Methods within allow access to SimpleDB
+    :class:`Domain <boto.sdb.domain.Domain>` objects and their associated
+    :class:`Item <boto.sdb.item.Item>` objects.
+
+    .. tip::
+        While you may instantiate this class directly, it may be easier to
+        go through :py:func:`boto.connect_sdb`.
+    """
+    DefaultRegionName = 'us-east-1'
+    DefaultRegionEndpoint = 'sdb.us-east-1.amazonaws.com'
+    APIVersion = '2009-04-15'
+    ResponseError = SDBResponseError
+
+    def __init__(self, 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):
+        """
+        For any keywords that aren't documented, refer to the parent class,
+        :py:class:`boto.connection.AWSAuthConnection`. You can avoid having
+        to worry about these keyword arguments by instantiating these objects
+        via :py:func:`boto.connect_sdb`.
+
+        :type region: :class:`boto.sdb.regioninfo.SDBRegionInfo`
+        :keyword region: Explicitly specify a region. Defaults to ``us-east-1``
+            if not specified. You may also specify the region in your ``boto.cfg``:
+
+            .. code-block:: cfg
+
+                [SDB]
+                region = eu-west-1
+
+        """
+        if not region:
+            region_name = boto.config.get('SDB', 'region', self.DefaultRegionName)
+            for reg in boto.sdb.regions():
+                if reg.name == region_name:
+                    region = reg
+                    break
+
+        self.region = region
+        super(SDBConnection, self).__init__(aws_access_key_id,
+                                    aws_secret_access_key,
+                                    is_secure, port, proxy,
+                                    proxy_port, proxy_user, proxy_pass,
+                                    self.region.endpoint, debug,
+                                    https_connection_factory, path,
+                                    security_token=security_token,
+                                    validate_certs=validate_certs,
+                                    profile_name=profile_name)
+        self.box_usage = 0.0
+        self.converter = converter
+        self.item_cls = Item
+
+    def _required_auth_capability(self):
+        return ['sdb']
+
+    def set_item_cls(self, cls):
+        """
+        While the default item class is :py:class:`boto.sdb.item.Item`, this
+        default may be overridden. Use this method to change a connection's
+        item class.
+
+        :param object cls: 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.
+        """
+        self.item_cls = cls
+
+    def _build_name_value_list(self, params, attributes, replace=False,
+                              label='Attribute'):
+        keys = sorted(attributes.keys())
+        i = 1
+        for key in keys:
+            value = attributes[key]
+            if isinstance(value, list):
+                for v in value:
+                    params['%s.%d.Name' % (label, i)] = key
+                    if self.converter:
+                        v = self.converter.encode(v)
+                    params['%s.%d.Value' % (label, i)] = v
+                    if replace:
+                        params['%s.%d.Replace' % (label, i)] = 'true'
+                    i += 1
+            else:
+                params['%s.%d.Name' % (label, i)] = key
+                if self.converter:
+                    value = self.converter.encode(value)
+                params['%s.%d.Value' % (label, i)] = value
+                if replace:
+                    params['%s.%d.Replace' % (label, i)] = 'true'
+            i += 1
+
+    def _build_expected_value(self, params, expected_value):
+        params['Expected.1.Name'] = expected_value[0]
+        if expected_value[1] is True:
+            params['Expected.1.Exists'] = 'true'
+        elif expected_value[1] is False:
+            params['Expected.1.Exists'] = 'false'
+        else:
+            params['Expected.1.Value'] = expected_value[1]
+
+    def _build_batch_list(self, params, items, replace=False):
+        item_names = items.keys()
+        i = 0
+        for item_name in item_names:
+            params['Item.%d.ItemName' % i] = item_name
+            j = 0
+            item = items[item_name]
+            if item is not None:
+                attr_names = item.keys()
+                for attr_name in attr_names:
+                    value = item[attr_name]
+                    if isinstance(value, list):
+                        for v in value:
+                            if self.converter:
+                                v = self.converter.encode(v)
+                            params['Item.%d.Attribute.%d.Name' % (i, j)] = attr_name
+                            params['Item.%d.Attribute.%d.Value' % (i, j)] = v
+                            if replace:
+                                params['Item.%d.Attribute.%d.Replace' % (i, j)] = 'true'
+                            j += 1
+                    else:
+                        params['Item.%d.Attribute.%d.Name' % (i, j)] = attr_name
+                        if self.converter:
+                            value = self.converter.encode(value)
+                        params['Item.%d.Attribute.%d.Value' % (i, j)] = value
+                        if replace:
+                            params['Item.%d.Attribute.%d.Replace' % (i, j)] = 'true'
+                        j += 1
+            i += 1
+
+    def _build_name_list(self, params, attribute_names):
+        i = 1
+        attribute_names.sort()
+        for name in attribute_names:
+            params['Attribute.%d.Name' % i] = name
+            i += 1
+
+    def get_usage(self):
+        """
+        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.
+
+        :rtype: float
+        :return: The accumulated BoxUsage of all requests made on the connection.
+        """
+        return self.box_usage
+
+    def print_usage(self):
+        """
+        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.
+        """
+        print('Total Usage: %f compute seconds' % self.box_usage)
+        cost = self.box_usage * 0.14
+        print('Approximate Cost: $%f' % cost)
+
+    def get_domain(self, domain_name, validate=True):
+        """
+        Retrieves a :py:class:`boto.sdb.domain.Domain` object whose name
+        matches ``domain_name``.
+
+        :param str domain_name: The name of the domain to retrieve
+        :keyword bool validate: When ``True``, check to see if the domain
+            actually exists. If ``False``, blindly return a
+            :py:class:`Domain <boto.sdb.domain.Domain>` object with the
+            specified name set.
+
+        :raises:
+            :py:class:`boto.exception.SDBResponseError` if ``validate`` is
+            ``True`` and no match could be found.
+
+        :rtype: :py:class:`boto.sdb.domain.Domain`
+        :return: The requested domain
+        """
+        domain = Domain(self, domain_name)
+        if validate:
+            self.select(domain, """select * from `%s` limit 1""" % domain_name)
+        return domain
+
+    def lookup(self, domain_name, validate=True):
+        """
+        Lookup an existing SimpleDB domain. This differs from
+        :py:meth:`get_domain` in that ``None`` is returned if ``validate`` is
+        ``True`` and no match was found (instead of raising an exception).
+
+        :param str domain_name: The name of the domain to retrieve
+
+        :param bool validate: If ``True``, a ``None`` value will be returned
+            if the specified domain can't be found. If ``False``, a
+            :py:class:`Domain <boto.sdb.domain.Domain>` object will be dumbly
+            returned, regardless of whether it actually exists.
+
+        :rtype: :class:`boto.sdb.domain.Domain` object or ``None``
+        :return: The Domain object or ``None`` if the domain does not exist.
+        """
+        try:
+            domain = self.get_domain(domain_name, validate)
+        except:
+            domain = None
+        return domain
+
+    def get_all_domains(self, max_domains=None, next_token=None):
+        """
+        Returns a :py:class:`boto.resultset.ResultSet` containing
+        all :py:class:`boto.sdb.domain.Domain` objects associated with
+        this connection's Access Key ID.
+
+        :keyword int max_domains: Limit the returned
+            :py:class:`ResultSet <boto.resultset.ResultSet>` to the specified
+            number of members.
+        :keyword str next_token: A token string that was returned in an
+            earlier call to this method as the ``next_token`` attribute
+            on the returned :py:class:`ResultSet <boto.resultset.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.
+        """
+        params = {}
+        if max_domains:
+            params['MaxNumberOfDomains'] = max_domains
+        if next_token:
+            params['NextToken'] = next_token
+        return self.get_list('ListDomains', params, [('DomainName', Domain)])
+
+    def create_domain(self, domain_name):
+        """
+        Create a SimpleDB domain.
+
+        :type domain_name: string
+        :param domain_name: The name of the new domain
+
+        :rtype: :class:`boto.sdb.domain.Domain` object
+        :return: The newly created domain
+        """
+        params = {'DomainName': domain_name}
+        d = self.get_object('CreateDomain', params, Domain)
+        d.name = domain_name
+        return d
+
+    def get_domain_and_name(self, domain_or_name):
+        """
+        Given a ``str`` or :class:`boto.sdb.domain.Domain`, return a
+        ``tuple`` with the following members (in order):
+
+            * In instance of :class:`boto.sdb.domain.Domain` for the requested
+              domain
+            * The domain's name as a ``str``
+
+        :type domain_or_name: ``str`` or :class:`boto.sdb.domain.Domain`
+        :param domain_or_name: The domain or domain name to get the domain
+            and name for.
+
+        :raises: :class:`boto.exception.SDBResponseError` when an invalid
+            domain name is specified.
+
+        :rtype: tuple
+        :return: A ``tuple`` with contents outlined as per above.
+        """
+        if (isinstance(domain_or_name, Domain)):
+            return (domain_or_name, domain_or_name.name)
+        else:
+            return (self.get_domain(domain_or_name), domain_or_name)
+
+    def delete_domain(self, domain_or_name):
+        """
+        Delete a SimpleDB domain.
+
+        .. caution:: This will delete the domain and all items within the domain.
+
+        :type domain_or_name: string or :class:`boto.sdb.domain.Domain` object.
+        :param domain_or_name: Either the name of a domain or a Domain object
+
+        :rtype: bool
+        :return: True if successful
+
+        """
+        domain, domain_name = self.get_domain_and_name(domain_or_name)
+        params = {'DomainName': domain_name}
+        return self.get_status('DeleteDomain', params)
+
+    def domain_metadata(self, domain_or_name):
+        """
+        Get the Metadata for a SimpleDB domain.
+
+        :type domain_or_name: string or :class:`boto.sdb.domain.Domain` object.
+        :param domain_or_name: Either the name of a domain or a Domain object
+
+        :rtype: :class:`boto.sdb.domain.DomainMetaData` object
+        :return: The newly created domain metadata object
+        """
+        domain, domain_name = self.get_domain_and_name(domain_or_name)
+        params = {'DomainName': domain_name}
+        d = self.get_object('DomainMetadata', params, DomainMetaData)
+        d.domain = domain
+        return d
+
+    def put_attributes(self, domain_or_name, item_name, attributes,
+                       replace=True, expected_value=None):
+        """
+        Store attributes for a given item in a domain.
+
+        :type domain_or_name: string or :class:`boto.sdb.domain.Domain` object.
+        :param domain_or_name: Either the name of a domain or a Domain object
+
+        :type item_name: string
+        :param item_name: The name of the item whose attributes are being
+                          stored.
+
+        :type attribute_names: dict or dict-like object
+        :param attribute_names: The name/value pairs to store as attributes
+
+        :type expected_value: list
+        :param expected_value: 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.
+
+        :type replace: bool
+        :param replace: Whether the attribute values passed in will replace
+                        existing values or will be added as addition values.
+                        Defaults to True.
+
+        :rtype: bool
+        :return: True if successful
+        """
+        domain, domain_name = self.get_domain_and_name(domain_or_name)
+        params = {'DomainName': domain_name,
+                  'ItemName': item_name}
+        self._build_name_value_list(params, attributes, replace)
+        if expected_value:
+            self._build_expected_value(params, expected_value)
+        return self.get_status('PutAttributes', params)
+
+    def batch_put_attributes(self, domain_or_name, items, replace=True):
+        """
+        Store attributes for multiple items in a domain.
+
+        :type domain_or_name: string or :class:`boto.sdb.domain.Domain` object.
+        :param domain_or_name: Either the name of a domain or a Domain object
+
+        :type items: dict or dict-like object
+        :param items: 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.
+
+        :type replace: bool
+        :param replace: Whether the attribute values passed in will replace
+                        existing values or will be added as addition values.
+                        Defaults to True.
+
+        :rtype: bool
+        :return: True if successful
+        """
+        domain, domain_name = self.get_domain_and_name(domain_or_name)
+        params = {'DomainName': domain_name}
+        self._build_batch_list(params, items, replace)
+        return self.get_status('BatchPutAttributes', params, verb='POST')
+
+    def get_attributes(self, domain_or_name, item_name, attribute_names=None,
+                       consistent_read=False, item=None):
+        """
+        Retrieve attributes for a given item in a domain.
+
+        :type domain_or_name: string or :class:`boto.sdb.domain.Domain` object.
+        :param domain_or_name: Either the name of a domain or a Domain object
+
+        :type item_name: string
+        :param item_name: The name of the item whose attributes are
+            being retrieved.
+
+        :type attribute_names: string or list of strings
+        :param attribute_names: An attribute name or list of attribute names.
+            This parameter is optional.  If not supplied, all attributes will
+            be retrieved for the item.
+
+        :type consistent_read: bool
+        :param consistent_read: When set to true, ensures that the most recent
+            data is returned.
+
+        :type item: :class:`boto.sdb.item.Item`
+        :keyword item: Instead of instantiating a new Item object, you may
+            specify one to update.
+
+        :rtype: :class:`boto.sdb.item.Item`
+        :return: An Item with the requested attribute name/values set on it
+        """
+        domain, domain_name = self.get_domain_and_name(domain_or_name)
+        params = {'DomainName': domain_name,
+                  'ItemName': item_name}
+        if consistent_read:
+            params['ConsistentRead'] = 'true'
+        if attribute_names:
+            if not isinstance(attribute_names, list):
+                attribute_names = [attribute_names]
+            self.build_list_params(params, attribute_names, 'AttributeName')
+        response = self.make_request('GetAttributes', params)
+        body = response.read()
+        if response.status == 200:
+            if item is None:
+                item = self.item_cls(domain, item_name)
+            h = handler.XmlHandler(item, self)
+            xml.sax.parseString(body, h)
+            return item
+        else:
+            raise SDBResponseError(response.status, response.reason, body)
+
+    def delete_attributes(self, domain_or_name, item_name, attr_names=None,
+                          expected_value=None):
+        """
+        Delete attributes from a given item in a domain.
+
+        :type domain_or_name: string or :class:`boto.sdb.domain.Domain` object.
+        :param domain_or_name: Either the name of a domain or a Domain object
+
+        :type item_name: string
+        :param item_name: The name of the item whose attributes are being
+                          deleted.
+
+        :type attributes: dict, list or :class:`boto.sdb.item.Item`
+        :param attributes: 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.
+
+        :type expected_value: list
+        :param expected_value: 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.
+
+        :rtype: bool
+        :return: True if successful
+        """
+        domain, domain_name = self.get_domain_and_name(domain_or_name)
+        params = {'DomainName': domain_name,
+                  'ItemName': item_name}
+        if attr_names:
+            if isinstance(attr_names, list):
+                self._build_name_list(params, attr_names)
+            elif isinstance(attr_names, dict) or isinstance(attr_names, self.item_cls):
+                self._build_name_value_list(params, attr_names)
+        if expected_value:
+            self._build_expected_value(params, expected_value)
+        return self.get_status('DeleteAttributes', params)
+
+    def batch_delete_attributes(self, domain_or_name, items):
+        """
+        Delete multiple items in a domain.
+
+        :type domain_or_name: string or :class:`boto.sdb.domain.Domain` object.
+        :param domain_or_name: Either the name of a domain or a Domain object
+
+        :type items: dict or dict-like object
+        :param items: 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: True if successful
+        """
+        domain, domain_name = self.get_domain_and_name(domain_or_name)
+        params = {'DomainName': domain_name}
+        self._build_batch_list(params, items, False)
+        return self.get_status('BatchDeleteAttributes', params, verb='POST')
+
+    def select(self, 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.
+
+        :type domain_or_name: string or :class:`boto.sdb.domain.Domain` object
+        :param domain_or_name: Either the name of a domain or a Domain object
+
+        :type query: string
+        :param query: The SimpleDB query to be performed.
+
+        :type consistent_read: bool
+        :param consistent_read: When set to true, ensures that the most recent
+                                data is returned.
+
+        :rtype: ResultSet
+        :return: An iterator containing the results.
+        """
+        domain, domain_name = self.get_domain_and_name(domain_or_name)
+        params = {'SelectExpression': query}
+        if consistent_read:
+            params['ConsistentRead'] = 'true'
+        if next_token:
+            params['NextToken'] = next_token
+        try:
+            return self.get_list('Select', params, [('Item', self.item_cls)],
+                             parent=domain)
+        except SDBResponseError as e:
+            e.body = "Query: %s\n%s" % (query, e.body)
+            raise e