datastore.py

#!/usr/bin/env python
#
# Copyright 2007 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#


"""The Python datastore API used by app developers.

Defines Entity, Query, and Iterator classes, as well as methods for all of the
datastore's calls. Also defines conversions between the Python classes and
their `PB` counterparts.

The datastore errors are defined in the datastore_errors module. That module is
only required to avoid circular imports. datastore imports datastore_types,
which needs `BadValueError`, so it can't be defined in datastore.
"""

















import heapq
import logging
import os
import re
import sys
import threading
import traceback
from xml.sax import saxutils

import six
from six.moves import range
from six.moves import zip

from google.appengine.api import apiproxy_stub_map
from google.appengine.api import capabilities
from google.appengine.api import cmp_compat
from google.appengine.api import datastore_errors
from google.appengine.api import datastore_types
from google.appengine.datastore import datastore_pb
from google.appengine.datastore import datastore_query
from google.appengine.datastore import datastore_rpc
from google.appengine.datastore import entity_bytes_pb2 as entity_pb2


MAX_ALLOWABLE_QUERIES = 30


MAXIMUM_RESULTS = 1000





DEFAULT_TRANSACTION_RETRIES = 3


READ_CAPABILITY = capabilities.CapabilitySet('datastore_v3')
WRITE_CAPABILITY = capabilities.CapabilitySet(
    'datastore_v3',
    capabilities=['write'])







_MAX_INDEXED_PROPERTIES = 20000


_MAX_ID_BATCH_SIZE = datastore_rpc._MAX_ID_BATCH_SIZE

Key = datastore_types.Key
typename = datastore_types.typename


STRONG_CONSISTENCY = datastore_rpc.Configuration.STRONG_CONSISTENCY
EVENTUAL_CONSISTENCY = datastore_rpc.Configuration.EVENTUAL_CONSISTENCY



_MAX_INT_32 = 2**31-1


def NormalizeAndTypeCheck(arg, types):
  """Normalizes and type checks the given argument.

  Args:
    arg: an instance or iterable of the given type(s)
    types: allowed type or tuple of types

  Returns:
    A `(list, bool)` tuple. The list is a normalized, shallow copy of the
    argument. The boolean is `True` if the argument was a sequence, False
    if it was a single object.

  Raises:
    AssertionError: types includes list or tuple.
    BadArgumentError: arg is not an instance or sequence of one of the given
    types.
  """
  if not isinstance(types, (list, tuple)):
    types = (types,)

  assert list not in types and tuple not in types

  if isinstance(arg, types):

    return [arg], False
  else:


    if isinstance(arg, six.string_types):
      raise datastore_errors.BadArgumentError(
          'Expected an instance or iterable of %s; received %s (a %s).' %
          (types, arg, typename(arg)))

    try:

      arg_list = list(arg)
    except TypeError:

      raise datastore_errors.BadArgumentError(
          'Expected an instance or iterable of %s; received %s (a %s).' %
          (types, arg, typename(arg)))


    for val in arg_list:
      if not isinstance(val, types):
        raise datastore_errors.BadArgumentError(
            'Expected one of %s; received %s (a %s).' %
            (types, val, typename(val)))

    return arg_list, True


def NormalizeAndTypeCheckKeys(keys):
  """Normalizes and type checks that the given argument is a valid key or keys.

  A wrapper around `NormalizeAndTypeCheck()` that accepts strings, Keys, and
  Entities, and normalizes to Keys.

  Args:
    keys: a Key or sequence of Keys

  Returns:
    A `(list of Keys, bool)` tuple. See `NormalizeAndTypeCheck`.

  Raises:
    BadArgumentError: arg is not an instance or sequence of one of the given
    types.
  """
  keys, multiple = NormalizeAndTypeCheck(keys, (six.string_types, Entity, Key))

  keys = [_GetCompleteKeyOrError(key) for key in keys]

  return (keys, multiple)


def _GetConfigFromKwargs(kwargs, convert_rpc=False,
                         config_class=datastore_rpc.Configuration):
  """Get a Configuration object from the keyword arguments.

  This is purely an internal helper for the various public `APIs` below
  such as `Get()`.

  Args:
    kwargs: A dict containing the keyword arguments passed to a public API.
    convert_rpc: If the an rpc should be converted or passed on directly.
    config_class: The config class that should be generated.

  Returns:
    A `UserRPC` instance, or a Configuration instance, or None.

  Raises:
    `TypeError` if unexpected keyword arguments are present.
  """
  if not kwargs:
    return None


  rpc = kwargs.pop('rpc', None)
  if rpc is not None:
    if not isinstance(rpc, apiproxy_stub_map.UserRPC):
      raise datastore_errors.BadArgumentError(
        'rpc= argument should be None or a UserRPC instance')
    if 'config' in kwargs:
      raise datastore_errors.BadArgumentError(
          'Expected rpc= or config= argument but not both')
    if not convert_rpc:
      if kwargs:
        raise datastore_errors.BadArgumentError(
            'Unexpected keyword arguments: %s' % ', '.join(kwargs))
      return rpc


    read_policy = getattr(rpc, 'read_policy', None)
    kwargs['config'] = datastore_rpc.Configuration(
       deadline=rpc.deadline, read_policy=read_policy,
       config=_GetConnection().config)

  return config_class(**kwargs)


class _BaseIndex(object):


  BUILDING, SERVING, DELETING, ERROR = list(range(4))





  ASCENDING = datastore_query.PropertyOrder.ASCENDING
  DESCENDING = datastore_query.PropertyOrder.DESCENDING

  def __init__(self, index_id, kind, has_ancestor, properties):
    """Construct a datastore index instance.

    Args:
      index_id: Required long; Uniquely identifies the index
      kind: Required string; Specifies the kind of the entities to index
      has_ancestor: Required boolean; indicates if the index supports a query
        that filters entities by the entity group parent
      properties: Required list of `(string, int)` tuples; The entity properties
        to index. First item in a tuple is the property name and the second
        item is the sorting direction (ASCENDING|DESCENDING).
        The order of the properties is based on the order in the index.
    """
    argument_error = datastore_errors.BadArgumentError
    datastore_types.ValidateInteger(index_id, 'index_id', argument_error,
                                    zero_ok=True)
    datastore_types.ValidateString(kind, 'kind', argument_error, empty_ok=True)
    if not isinstance(properties, (list, tuple)):
      raise argument_error('properties must be a list or a tuple')
    for idx, index_property in enumerate(properties):
      if not isinstance(index_property, (list, tuple)):
        raise argument_error('property[%d] must be a list or a tuple' % idx)
      if len(index_property) != 2:
        raise argument_error('property[%d] length should be 2 but was %d' %
                        (idx, len(index_property)))
      datastore_types.ValidateString(index_property[0], 'property name',
                                     argument_error)
      _BaseIndex.__ValidateEnum(index_property[1],
                               (self.ASCENDING, self.DESCENDING),
                               'sort direction')
    self.__id = int(index_id)
    self.__kind = kind
    self.__has_ancestor = bool(has_ancestor)
    self.__properties = properties

  @staticmethod
  def __ValidateEnum(value, accepted_values, name='value',
                     exception=datastore_errors.BadArgumentError):
    datastore_types.ValidateInteger(value, name, exception)
    if not value in accepted_values:
      raise exception('%s should be one of %s but was %d' %
                      (name, str(accepted_values), value))

  def _Id(self):
    """Returns the index id, a long."""
    return self.__id

  def _Kind(self):
    """Returns the index kind, a string.  Empty string ('') if none."""
    return self.__kind

  def _HasAncestor(self):
    """Indicates if this is an ancestor index, a boolean."""
    return self.__has_ancestor

  def _Properties(self):
    """Returns the index properties. a tuple of
    `(index name as a string, [ASCENDING|DESCENDING])` tuples.
    """
    return self.__properties

  def __eq__(self, other):
    return self.__id == other.__id

  def __ne__(self, other):
    return self.__id != other.__id

  def __hash__(self):
    return hash(self.__id)


class Index(_BaseIndex):
  """A datastore index."""

  Id = _BaseIndex._Id
  Kind = _BaseIndex._Kind
  HasAncestor = _BaseIndex._HasAncestor
  Properties = _BaseIndex._Properties


class DatastoreAdapter(datastore_rpc.AbstractAdapter):
  """Adapter between datatypes defined here (Entity etc.) and protobufs.

  See the base class in datastore_rpc.py for more docs.
  """


  index_state_mappings = {
      entity_pb2.CompositeIndex.ERROR: Index.ERROR,
      entity_pb2.CompositeIndex.DELETED: Index.DELETING,
      entity_pb2.CompositeIndex.READ_WRITE: Index.SERVING,
      entity_pb2.CompositeIndex.WRITE_ONLY: Index.BUILDING
  }


  index_direction_mappings = {
      entity_pb2.Index.Property.ASCENDING: Index.ASCENDING,
      entity_pb2.Index.Property.DESCENDING: Index.DESCENDING
  }

  def __init__(self, _id_resolver=None):
    super(DatastoreAdapter, self).__init__(_id_resolver)

  def key_to_pb(self, key):
    return key._Key__reference

  def pb_to_key(self, pb):
    return Key._FromPb(pb)

  def entity_to_pb(self, entity):
    return entity._ToPb()

  def pb_to_entity(self, pb):
    return Entity._FromPb(pb)

  def pb_to_index(self, pb):
    index_def = pb.definition
    properties = [
        (property.name,
         DatastoreAdapter.index_direction_mappings.get(property.direction))
        for property in index_def.property
    ]
    index = Index(pb.id, index_def.entity_type, index_def.ancestor, properties)
    state = DatastoreAdapter.index_state_mappings.get(pb.state)
    return index, state


_adapter = DatastoreAdapter()
_thread_local = threading.local()


_ENV_KEY = '__DATASTORE_CONNECTION_INITIALIZED__'


def __InitConnection():
  """Internal method to make sure the connection state has been initialized."""












  if os.getenv(_ENV_KEY) and hasattr(_thread_local, 'connection_stack'):
    return


  def CreateConnection(adapter=None,
                       _id_resolver=None,
                       _api_version=datastore_rpc._DATASTORE_V3):
    if _id_resolver:
      adapter = DatastoreAdapter(_id_resolver=_id_resolver)
    return datastore_rpc.Connection(adapter=adapter, _api_version=_api_version)

  _thread_local.connection_stack = [
      datastore_rpc._CreateDefaultConnection(CreateConnection,
                                             adapter=_adapter)
  ]


  os.environ[_ENV_KEY] = '1'


def _GetConnection():
  """Internal method to retrieve a datastore connection local to the thread."""
  __InitConnection()
  return _thread_local.connection_stack[-1]


def _SetConnection(connection):
  """Internal method to replace the current thread local connection."""
  __InitConnection()
  _thread_local.connection_stack[-1] = connection


def _PushConnection(new_connection):
  """Internal method to save the current connection and sets a new one.

  Args:
    new_connection: The connection to set.
  """
  __InitConnection()
  _thread_local.connection_stack.append(new_connection)


def _PopConnection():
  """Internal method to restores the previous connection.

  Returns:
    The current connection.
  """

  assert len(_thread_local.connection_stack) >= 2
  return _thread_local.connection_stack.pop()





def _MakeSyncCall(service, call, request, response, config=None):
  """The `APIProxy` entry point for a synchronous API call.

  Args:
    service: For backwards compatibility, must be 'datastore_v3'.
    call: String representing which function to call.
    request: Protocol buffer for the request.
    response: Protocol buffer for the response.
    config: Optional Configuration to use for this request.

  Returns:
    Response protocol buffer. Caller should always use returned value
    which may or may not be same as passed in 'response'.

  Raises:
    apiproxy_errors.Error or a subclass.
  """
  conn = _GetConnection()
  if isinstance(request, datastore_pb.Query):
    conn._set_request_read_policy(request, config)
    conn._set_request_transaction(request)
  rpc = conn._make_rpc_call(config, call, request, response)
  conn.check_rpc_success(rpc)
  return response


def CreateRPC(service='datastore_v3',
              deadline=None, callback=None, read_policy=None):
  """Create an rpc for use in configuring datastore calls.

  NOTE: This functions exists for backwards compatibility.  Please use
  `CreateConfig()` instead.  NOTE: the latter uses 'on_completion',
  which is a function taking an argument, wherease `CreateRPC` uses
  'callback' which is a function without arguments.

  Args:
    service: Optional string; for backwards compatibility, must be
      'datastore_v3'.
    deadline: Optional int or float, deadline for calls in seconds.
    callback: Optional callable, a callback triggered when this rpc
      completes; takes no arguments.
    read_policy: Optional read policy; set to EVENTUAL_CONSISTENCY to
      enable eventually consistent reads (i.e. reads that may be
      satisfied from an older version of the datastore in some cases).
      The default read policy may have to wait until in-flight
      transactions are committed.

  Returns:
    A `UserRPC` instance.
  """
  assert service == 'datastore_v3'
  conn = _GetConnection()
  config = None
  if deadline is not None:
    config = datastore_rpc.Configuration(deadline=deadline)
  rpc = conn._create_rpc(config)
  rpc.callback = callback
  if read_policy is not None:
    rpc.read_policy = read_policy
  return rpc


def CreateConfig(**kwds):
  """Create a Configuration object for use in configuring datastore calls.

  This configuration can be passed to most datastore calls using the
  'config=...' argument.

  Args:
    deadline: Optional deadline; default None (which means the
      system default deadline will be used, typically 5 seconds).
    on_completion: Optional callback function; default None.  If
      specified, it will be called with a `UserRPC` object as argument
      when an RPC completes.
    read_policy: Optional read policy; set to EVENTUAL_CONSISTENCY to
      enable eventually consistent reads (i.e. reads that may be
      satisfied from an older version of the datastore in some cases).
      The default read policy may have to wait until in-flight
      transactions are committed.
    **kwds: Other keyword arguments as long as they are supported by
      datastore_rpc.Configuration().

  Returns:
    A datastore_rpc.Configuration instance.
  """
  return datastore_rpc.Configuration(**kwds)


def CreateTransactionOptions(**kwds):
  """Create a configuration object for use in configuring transactions.

  This configuration can be passed as run_in_transaction_option's first
  argument.

  Args:
    deadline: Optional deadline; default None (which means the
      system default deadline will be used, typically 5 seconds).
    on_completion: Optional callback function; default None.  If
      specified, it will be called with a `UserRPC` object as argument
      when an RPC completes.
    xg: set to true to allow cross-group transactions (high replication
      datastore only)
    retries: set the number of retries for a transaction
    **kwds: Other keyword arguments as long as they are supported by
      datastore_rpc.TransactionOptions().

  Returns:
    A datastore_rpc.TransactionOptions instance.
  """
  return datastore_rpc.TransactionOptions(**kwds)


def PutAsync(entities, **kwargs):
  """Asynchronously store one or more entities in the datastore.

  Identical to datastore.Put() except returns an asynchronous object. Call
  `get_result()` on the return value to block on the call and get the results.
  """
  extra_hook = kwargs.pop('extra_hook', None)
  config = _GetConfigFromKwargs(kwargs)
  if getattr(config, 'read_policy', None) == EVENTUAL_CONSISTENCY:
    raise datastore_errors.BadRequestError(
        'read_policy is only supported on read operations.')
  entities, multiple = NormalizeAndTypeCheck(entities, Entity)

  for entity in entities:
    if entity.is_projection():
      raise datastore_errors.BadRequestError(
        'Cannot put a partial entity: %s' % entity)
    if not entity.kind() or not entity.app():
      raise datastore_errors.BadRequestError(
          'App and kind must not be empty, in entity: %s' % entity)

  def local_extra_hook(keys):
    num_keys = len(keys)
    num_entities = len(entities)
    if num_keys != num_entities:
      raise datastore_errors.InternalError(
          'Put accepted %d entities but returned %d keys.' %
          (num_entities, num_keys))

    for entity, key in zip(entities, keys):
      if entity._Entity__key._Key__reference != key._Key__reference:
        assert not entity._Entity__key.has_id_or_name()
        entity._Entity__key._Key__reference.CopyFrom(key._Key__reference)

    if multiple:
      result = keys
    else:
      result = keys[0]

    if extra_hook:
      return extra_hook(result)
    return result

  return _GetConnection().async_put(config, entities, local_extra_hook)


def Put(entities, **kwargs):
  """Store one or more entities in the datastore.

  The entities may be new or previously existing. For new entities, `Put()` will
  fill in the app id and key assigned by the datastore.

  If the argument is a single Entity, a single Key will be returned. If the
  argument is a list of Entity, a list of Keys will be returned.

  Args:
    entities: Entity or list of Entities
    config: Optional Configuration to use for this request, must be specified
      as a keyword argument.

  Returns:
    Key or list of Keys

  Raises:
    `TransactionFailedError`, if the Put could not be committed.
  """
  return PutAsync(entities, **kwargs).get_result()


def GetAsync(keys, **kwargs):
  """Asynchronously retrieves one or more entities from the datastore.

  Identical to datastore.Get() except returns an asynchronous object. Call
  `get_result()` on the return value to block on the call and get the results.
  """
  extra_hook = kwargs.pop('extra_hook', None)
  config = _GetConfigFromKwargs(kwargs)
  keys, multiple = NormalizeAndTypeCheckKeys(keys)

  def local_extra_hook(entities):
    if multiple:
      result = entities
    else:
      if entities[0] is None:
        raise datastore_errors.EntityNotFoundError()
      result = entities[0]
    if extra_hook:
      return extra_hook(result)
    return result

  return _GetConnection().async_get(config, keys, local_extra_hook)


def Get(keys, **kwargs):
  """Retrieves one or more entities from the datastore.

  Retrieves the entity or entities with the given key(s) from the datastore
  and returns them as fully populated Entity objects, as defined below. If
  there is an error, raises a subclass of datastore_errors.Error.

  If keys is a single key or string, an Entity will be returned, or
  `EntityNotFoundError` will be raised if no existing entity matches the key.

  However, if keys is a list or tuple, a list of entities will be returned
  that corresponds to the sequence of keys. It will include entities for keys
  that were found and None placeholders for keys that were not found.

  Args:
    keys: Key or string or list of Keys or strings
    config: Optional Configuration to use for this request, must be specified
      as a keyword argument.

  Returns:
    Entity or list of Entity objects
  """
  return GetAsync(keys, **kwargs).get_result()

def GetIndexesAsync(**kwargs):
  """Asynchronously retrieves the application indexes and their states.

  Identical to `GetIndexes()` except returns an asynchronous object. Call
  `get_result()` on the return value to block on the call and get the results.
  """
  extra_hook = kwargs.pop('extra_hook', None)
  config = _GetConfigFromKwargs(kwargs)

  def local_extra_hook(result):
    if extra_hook:
      return extra_hook(result)
    return result

  return _GetConnection().async_get_indexes(config, local_extra_hook)


def GetIndexes(**kwargs):
  """Retrieves the application indexes and their states.

  Args:
    config: Optional Configuration to use for this request, must be specified
      as a keyword argument.

  Returns:
    A list of `(Index, Index.[BUILDING|SERVING|DELETING|ERROR])` tuples.
    An index can be in the following states:
      Index.BUILDING: Index is being built and therefore can not serve queries
      Index.SERVING: Index is ready to service queries
      Index.DELETING: Index is being deleted
      Index.ERROR: Index encounted an error in the `BUILDING` state
  """
  return GetIndexesAsync(**kwargs).get_result()

def DeleteAsync(keys, **kwargs):
  """Asynchronously deletes one or more entities from the datastore.

  Identical to datastore.Delete() except returns an asynchronous object. Call
  `get_result()` on the return value to block on the call.
  """
  config = _GetConfigFromKwargs(kwargs)
  if getattr(config, 'read_policy', None) == EVENTUAL_CONSISTENCY:
    raise datastore_errors.BadRequestError(
        'read_policy is only supported on read operations.')
  keys, _ = NormalizeAndTypeCheckKeys(keys)

  return _GetConnection().async_delete(config, keys)


def Delete(keys, **kwargs):
  """Deletes one or more entities from the datastore. Use with care!

  Deletes the given `entity(ies)` from the datastore. You can only delete
  entities from your app. If there is an error, raises a subclass of
  datastore_errors.Error.

  Args:
    # the primary keys of the entities to delete
    keys: Key or string or list of Keys or strings
    config: Optional Configuration to use for this request, must be specified
      as a keyword argument.

  Raises:
    `TransactionFailedError`, if the Delete could not be committed.
  """
  return DeleteAsync(keys, **kwargs).get_result()


class Entity(dict):
  """A datastore entity.

  Includes read-only accessors for app id, kind, and primary key. Also
  provides dictionary-style access to properties.
  """


  __projection = False

  def __init__(self, kind, parent=None, _app=None, name=None, id=None,
               unindexed_properties=[], namespace=None, **kwds):
    """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.

    Args:
      # this entity's kind
      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, this entity's id.
      id: integer
      # 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
      namespace: string
      # if provided, overrides the default namespace_manager setting.
    """





    ref = entity_pb2.Reference()

    _app = datastore_types.ResolveAppId(_app)
    ref.app = _app
    _namespace = kwds.pop('_namespace', None)

    if kwds:
      raise datastore_errors.BadArgumentError(
          'Excess keyword arguments ' + repr(kwds))




    if namespace is None:
      namespace = _namespace
    elif _namespace is not None:
      raise datastore_errors.BadArgumentError(
          "Must not set both _namespace and namespace parameters.")

    datastore_types.ValidateString(kind, 'kind',
                                   datastore_errors.BadArgumentError)

    if parent is not None:
      parent = _GetCompleteKeyOrError(parent)
      if _app != parent.app():
        raise datastore_errors.BadArgumentError(
            " %s doesn't match parent's app %s" %
            (_app, parent.app()))


      if namespace is None:
        namespace = parent.namespace()
      elif namespace != parent.namespace():
        raise datastore_errors.BadArgumentError(
            " %s doesn't match parent's namespace %s" %
            (namespace, parent.namespace()))
      ref.CopyFrom(parent._Key__reference)

    namespace = datastore_types.ResolveNamespace(namespace)
    datastore_types.SetNamespace(ref, namespace)

    last_path = ref.path.element.add()
    last_path.type = kind

    if name is not None and id is not None:
      raise datastore_errors.BadArgumentError(
          "Cannot set both name and id on an Entity")


    if name is not None:
      datastore_types.ValidateString(name, 'name')
      last_path.name = six.ensure_binary(name, 'utf-8')

    if id is not None:
      datastore_types.ValidateInteger(id, 'id')
      last_path.id = id

    self.set_unindexed_properties(unindexed_properties)

    self.__key = Key._FromPb(ref)

  def app(self):
    """Returns the name of the application that created this entity, a
    string or None if not set.
    """
    return self.__key.app()

  def namespace(self):
    """Returns the namespace of this entity, a string or None."""
    return self.__key.namespace()

  def kind(self):
    """Returns this entity's kind, a string."""
    return self.__key.kind()

  def is_saved(self):
    """Returns if this entity has been saved to the datastore."""
    last_path = self.__key._Key__reference.path.element[-1]
    return ((last_path.HasField('name') ^ last_path.HasField('id')) and
            self.__key.has_id_or_name())

  def is_projection(self):
    """Returns if this entity is a projection from full entity.

    Projected entities:
    - may not contain all properties from the original entity;
    - only contain single values for lists;
    - may not contain values with the same type as the original entity.
    """
    return self.__projection

  def key(self):
    """Returns this entity's primary key, a Key instance."""
    return self.__key

  def parent(self):
    """Returns this entity's parent, as a Key. If this entity has no parent,
    returns None.
    """
    return self.key().parent()

  def entity_group(self):
    """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 getattr(self, '_Entity__unindexed_properties', [])

  def set_unindexed_properties(self, unindexed_properties):

    unindexed_properties, multiple = NormalizeAndTypeCheck(unindexed_properties, six.string_types)
    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)

  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
    `BadPropertyError`. If the value is not a supported type, raises
    `BadValueError`.
    """

    datastore_types.ValidateProperty(name, value)
    dict.__setitem__(self, name, value)

  def setdefault(self, name, value):
    """If the property exists, returns its value. Otherwise sets it to value.

    If the property name is the empty string or not a string, raises
    `BadPropertyError`. If the value is not a supported type, raises
    `BadValueError`.
    """

    datastore_types.ValidateProperty(name, value)
    return dict.setdefault(self, name, value)

  def update(self, other):
    """Updates this entity's properties from the values in other.

    If any property name is the empty string or not a string, raises
    `BadPropertyError`. If any value is not a supported type, raises
    `BadValueError`.
    """
    for name, value in other.items():
      self.__setitem__(name, value)

  def copy(self):
    """The copy method is not supported.
    """
    raise NotImplementedError('Entity does not support the copy() method.')

  def ToXml(self):
    """Returns an `XML` representation of this entity.

    Atom and gd:namespace
    properties are converted to `XML` according to their respective schemas. For
    more information, see:

      http://www.atomenabled.org/developers/syndication/
      https://developers.google.com/gdata/docs/1.0/elements

    This is *not* optimized. It shouldn't be used anywhere near code that's
    performance-critical.
    """

    xml = u'<entity kind=%s' % saxutils.quoteattr(self.kind())
    if self.__key.has_id_or_name():
      xml += ' key=%s' % saxutils.quoteattr(str(self.__key))
    xml += '>'
    if self.__key.has_id_or_name():
      xml += '\n  <key>%s</key>' % self.__key.ToTagUri()




    properties = list(self.keys())
    if properties:
      properties.sort()
      xml += '\n  ' + '\n  '.join(self._PropertiesToXml(properties))


    xml += '\n</entity>\n'
    return xml

  def _PropertiesToXml(self, properties):
    """Returns a list of the `XML` representations of each of the given properties.

    Ignores properties that don't exist in this entity.

    Arg:
      properties: string or list of strings

    Returns:
      list of strings
    """
    xml_properties = []

    for propname in properties:
      if propname not in self:
        continue

      propname_xml = saxutils.quoteattr(propname)

      values = self[propname]
      if isinstance(values, list) and not values:



        continue
      if not isinstance(values, list):