py_tasks_melange: comparison thirdparty/google_appengine/google/appengine/api/datastore.py

equal deleted inserted replaced

-:81c128f487e6
+:be1b94099f2d
 """A datastore entity.
 Includes read-only accessors for app id, kind, and primary key. Also
 provides dictionary-style access to properties.
 """
-def __init__(self, kind, parent=None, _app=None, name=None):
+def __init__(self, kind, parent=None, _app=None, name=None,
+unindexed_properties=[]):
 """Constructor. Takes the kind and transaction root, which cannot be
 changed after the entity is constructed, and an optional parent. Raises
 BadArgumentError or BadKeyError if kind is invalid or parent is not an
 existing Entity or Key in the datastore.
 kind: string
 # if provided, this entity's parent. Its key must be complete.
 parent: Entity or Key
 # if provided, this entity's name.
 name: string
+# if provided, a sequence of property names that should not be indexed
+# by the built-in single property indices.
+unindexed_properties: list or tuple of strings
 """
 ref = entity_pb.Reference()
 _app = datastore_types.ResolveAppId(_app)
 ref.set_app(_app)
 datastore_types.ValidateString(name, 'name')
 if name[0] in string.digits:
 raise datastore_errors.BadValueError('name cannot begin with a digit')
 last_path.set_name(name.encode('utf-8'))
+unindexed_properties, multiple = NormalizeAndTypeCheck(unindexed_properties, basestring)
+if not multiple:
+raise datastore_errors.BadArgumentError(
+'unindexed_properties must be a sequence; received %s (a %s).' %
+(unindexed_properties, typename(unindexed_properties)))
+for prop in unindexed_properties:
+datastore_types.ValidateProperty(prop, None)
+self.__unindexed_properties = frozenset(unindexed_properties)
 self.__key = Key._FromPb(ref)
 def app(self):
 """Returns the name of the application that created this entity, a
 string.
 returns None.
 """
 return self.key().parent()
 def entity_group(self):
-"""Returns this entitys's entity group as a Key.
+"""Returns this entity's entity group as a Key.
 Note that the returned Key will be incomplete if this is a a root entity
 and its key is incomplete.
 """
 return self.key().entity_group()
+def unindexed_properties(self):
+"""Returns this entity's unindexed properties, as a frozenset of strings."""
+return self.__unindexed_properties
 def __setitem__(self, name, value):
 """Implements the [] operator. Used to set property value(s).
 If the property name is the empty string or not a string, raises
 sample = values
 if isinstance(sample, list):
 sample = values[0]
-if isinstance(sample, datastore_types._RAW_PROPERTY_TYPES):
+if (isinstance(sample, datastore_types._RAW_PROPERTY_TYPES) or
+name in self.__unindexed_properties):
 pb.raw_property_list().extend(properties)
 else:
 pb.property_list().extend(properties)
 if pb.property_size() > _MAX_INDEXED_PROPERTIES:
 assert last_path.id() != 0
 else:
 assert last_path.has_name()
 assert last_path.name()
-e = Entity(unicode(last_path.type().decode('utf-8')))
+unindexed_properties = [p.name() for p in pb.raw_property_list()]
+e = Entity(unicode(last_path.type().decode('utf-8')),
+unindexed_properties=unindexed_properties)
 ref = e.__key._Key__reference
 ref.CopyFrom(pb.key())
 temporary_values = {}
 for prop_list in (pb.property_list(), pb.raw_property_list()):
 for prop in prop_list:
-if not prop.has_multiple():
-raise datastore_errors.Error(
-'Property %s is corrupt in the datastore; it\'s missing the '
-'multiple valued field.' % prop.name())
 try:
 value = datastore_types.FromPropertyPb(prop)
 except (AssertionError, AttributeError, TypeError, ValueError), e:
 raise datastore_errors.Error(
 'Property %s is corrupt in the datastore. %s: %s' %
 __filter_counter = 0
 __inequality_prop = None
 __inequality_count = 0
-def __init__(self, kind, filters={}, _app=None):
+def __init__(self, kind, filters={}, _app=None, keys_only=False):
 """Constructor.
 Raises BadArgumentError if kind is not a string. Raises BadValueError or
 BadFilterError if filters is not a dictionary of valid filters.
 Args:
 # kind is required. filters is optional; if provided, it's used
-# as an initial set of property filters.
+# as an initial set of property filters. keys_only defaults to False.
 kind: string
 filters: dict
+keys_only: boolean
 """
 datastore_types.ValidateString(kind, 'kind',
 datastore_errors.BadArgumentError)
 self.__kind = kind
 self.__orderings = []
 self.__filter_order = {}
 self.update(filters)
 self.__app = datastore_types.ResolveAppId(_app)
+self.__keys_only = keys_only
 def Order(self, *orderings):
 """Specify how the query results should be sorted.
 Result entities will be sorted by the first property argument, then by the
 """
 key = _GetCompleteKeyOrError(ancestor)
 self.__ancestor = datastore_pb.Reference()
 self.__ancestor.CopyFrom(key._Key__reference)
 return self
+def IsKeysOnly(self):
+"""Returns True if this query is keys only, false otherwise."""
+return self.__keys_only
 def Run(self):
 """Runs this query.
 If a filter string is invalid, raises BadFilterError. If a filter value is
 yaml = datastore_index.IndexYamlForQuery(
 *datastore_index.CompositeIndexForQuery(pb)[1:-1])
 raise datastore_errors.NeedIndexError(
 str(exc) + '\nThis query needs this index:\n' + yaml)
-return Iterator._FromPb(result.cursor())
+return Iterator._FromPb(result)
 def Get(self, limit, offset=0):
 """Fetches and returns a maximum number of results from the query.
 This method fetches and returns a list of resulting entities that matched
 datastore_pb.Query
 """
 pb = datastore_pb.Query()
 pb.set_kind(self.__kind.encode('utf-8'))
+pb.set_keys_only(bool(self.__keys_only))
 if self.__app:
 pb.set_app(self.__app.encode('utf-8'))
 if limit is not None:
 pb.set_limit(limit)
 if offset is not None:
 class MultiQuery(Query):
 """Class representing a query which requires multiple datastore queries.
 This class is actually a subclass of datastore.Query as it is intended to act
 like a normal Query object (supporting the same interface).
+Does not support keys only queries, since it needs whole entities in order
+to merge sort them. (That's not true if there are no sort orders, or if the
+sort order is on __key__, but allowing keys only queries in those cases, but
+not in others, would be confusing.)
 """
 def __init__(self, bound_queries, orderings):
 if len(bound_queries) > MAX_ALLOWABLE_QUERIES:
 raise datastore_errors.BadArgumentError(
 'Cannot satisfy query -- too many subqueries (max: %d, got %d).'
 ' Probable cause: too many IN/!= filters in query.' %
 (MAX_ALLOWABLE_QUERIES, len(bound_queries)))
+for query in bound_queries:
+if query.IsKeysOnly():
+raise datastore_errors.BadQueryError(
+'MultiQuery does not support keys_only.')
 self.__bound_queries = bound_queries
 self.__orderings = orderings
 def __str__(self):
 res = 'MultiQuery: '
 if result:
 return result
 return 0
 def __GetValueForId(self, sort_order_entity, identifier, sort_order):
-value = sort_order_entity.__entity[identifier]
+value = _GetPropertyValue(sort_order_entity.__entity, identifier)
 entity_key = sort_order_entity.__entity.key()
 if (entity_key, identifier) in self.__min_max_value_cache:
 value = self.__min_max_value_cache[(entity_key, identifier)]
 elif isinstance(value, list):
 if sort_order == Query.DESCENDING:
 > it = Query('Person').Run()
 > for person in it:
 >   print 'Hi, %s!' % person['name']
 """
-def __init__(self, cursor):
+def __init__(self, cursor, keys_only=False):
 self.__cursor = cursor
 self.__buffer = []
 self.__more_results = True
+self.__keys_only = keys_only
 def _Next(self, count):
 """Returns the next result(s) of the query.
 Not intended to be used by application developers. Use the python
 iterator protocol instead.
-This method returns the next entities from the list of resulting
+This method returns the next entities or keys from the list of matching
-entities that matched the query. If the query specified a sort
+results. If the query specified a sort order, results are returned in that
-order, entities are returned in that order. Otherwise, the order
+order. Otherwise, the order is undefined.
-is undefined.
+The argument specifies the number of results to return. If it's greater
-The argument specifies the number of entities to return. If it's
+than the number of remaining results, all of the remaining results are
-greater than the number of remaining entities, all of the
+returned. In that case, the length of the returned list will be smaller
-remaining entities are returned. In that case, the length of the
+than count.
-returned list will be smaller than count.
+There is an internal buffer for use with the next() method. If this buffer
-There is an internal buffer for use with the next() method.  If
+is not empty, up to 'count' values are removed from this buffer and
-this buffer is not empty, up to 'count' values are removed from
+returned. It's best not to mix _Next() and next().
-this buffer and returned.  It's best not to mix _Next() and
-next().
+The results are always returned as a list. If there are no results left,
+an empty list is returned.
-The results are always returned as a list. If there are no results
-left, an empty list is returned.
 Args:
-# the number of entities to return; must be >= 1
+# the number of results to return; must be >= 1
 count: int or long
 Returns:
-# a list of entities
+# a list of entities or keys
-[Entity, ...]
+[Entity or Key, ...]
 """
 if not isinstance(count, (int, long)) or count <= 0:
 raise datastore_errors.BadArgumentError(
 'Argument to _Next must be an int greater than 0; received %s (a %s)' %
 (count, typename(count)))
 except apiproxy_errors.ApplicationError, err:
 raise _ToDatastoreError(err)
 self.__more_results = result.more_results()
-ret = [Entity._FromPb(r) for r in result.result_list()]
+if self.__keys_only:
-return ret
+return [Key._FromPb(e.key()) for e in result.result_list()]
+else:
+return [Entity._FromPb(e) for e in result.result_list()]
 _BUFFER_SIZE = 20
 def next(self):
 if not self.__buffer:
 return pb
 @staticmethod
 def _FromPb(pb):
 """Static factory method. Returns the Iterator representation of the given
-protocol buffer (datastore_pb.Cursor). Not intended to be used by
+protocol buffer (datastore_pb.QueryResult). Not intended to be used by
-application developers. Enforced by not hiding the datastore_pb classes.
+application developers. Enforced by hiding the datastore_pb classes.
 Args:
-# a protocol buffer Cursor
+pb: datastore_pb.QueryResult
-pb: datastore_pb.Cursor
 Returns:
-# the Iterator representation of the argument
 Iterator
 """
-return Iterator(pb.cursor())
+return Iterator(pb.cursor().cursor(), keys_only=pb.keys_only())
 class _Transaction(object):
 """Encapsulates a transaction currently in progress.
 raise datastore_errors.BadKeyError('Key %r is not complete.' % key)
 return key
+def _GetPropertyValue(entity, property):
+"""Returns an entity's value for a given property name.
+Handles special properties like __key__ as well as normal properties.
+Args:
+entity: datastore.Entity
+property: str; the property name
+Returns:
+property value. For __key__, a datastore_types.Key.
+Raises:
+KeyError, if the entity does not have the given property.
+"""
+if property in datastore_types._SPECIAL_PROPERTIES:
+assert property == datastore_types._KEY_SPECIAL_PROPERTY
+return entity.key()
+else:
+return entity[property]
 def _AddOrAppend(dictionary, key, value):
 """Adds the value to the existing values in the dictionary, if any.
 If dictionary[key] doesn't exist, sets dictionary[key] to value.

changeset 2309	be1b94099f2d
parent 1278	a7766286a7be
child 2413	d0b7dac5325c