#!/usr/bin/env python

#

# Copyright 2007 Google Inc.

#

# 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.

#

"""Simple, schema-based database abstraction layer for the datastore.

Modeled after Django's abstraction layer on top of SQL databases,

http://www.djangoproject.com/documentation/mode_api/. Ours is a little simpler

and a lot less code because the datastore is so much simpler than SQL

databases.

The programming model is to declare Python subclasses of the Model class,

declaring datastore properties as class members of that class. So if you want to

publish a story with title, body, and created date, you would do it like this:

    class Story(db.Model):

      title = db.StringProperty()

      body = db.TextProperty()

      created = db.DateTimeProperty(auto_now_add=True)

You can create a new Story in the datastore with this usage pattern:

    story = Story(title='My title')

    story.body = 'My body'

    story.put()

You query for Story entities using built in query interfaces that map directly

to the syntax and semantics of the datastore:

    stories = Story.all().filter('date >=', yesterday).order('-date')

    for story in stories:

      print story.title

The Property declarations enforce types by performing validation on assignment.

For example, the DateTimeProperty enforces that you assign valid datetime

objects, and if you supply the "required" option for a property, you will not

be able to assign None to that property.

We also support references between models, so if a story has comments, you

would represent it like this:

    class Comment(db.Model):

      story = db.ReferenceProperty(Story)

      body = db.TextProperty()

When you get a story out of the datastore, the story reference is resolved

automatically the first time it is referenced, which makes it easy to use

model instances without performing additional queries by hand:

    comment = Comment.get(key)

    print comment.story.title

Likewise, you can access the set of comments that refer to each story through

this property through a reverse reference called comment_set, which is a Query

preconfigured to return all matching comments:

    story = Story.get(key)

    for comment in story.comment_set:

       print comment.body

"""

import base64

import copy

import datetime

import logging

import re

import time

import urlparse

import warnings

from google.appengine.api import datastore

from google.appengine.api import datastore_errors

from google.appengine.api import datastore_types

from google.appengine.api import users

from google.appengine.datastore import datastore_pb

Error = datastore_errors.Error

BadValueError = datastore_errors.BadValueError

BadPropertyError = datastore_errors.BadPropertyError

BadRequestError = datastore_errors.BadRequestError

EntityNotFoundError = datastore_errors.EntityNotFoundError

BadArgumentError = datastore_errors.BadArgumentError

QueryNotFoundError = datastore_errors.QueryNotFoundError

TransactionNotFoundError = datastore_errors.TransactionNotFoundError

Rollback = datastore_errors.Rollback

TransactionFailedError = datastore_errors.TransactionFailedError

BadFilterError = datastore_errors.BadFilterError

BadQueryError = datastore_errors.BadQueryError

BadKeyError = datastore_errors.BadKeyError

InternalError = datastore_errors.InternalError

NeedIndexError = datastore_errors.NeedIndexError

Timeout = datastore_errors.Timeout

ValidationError = BadValueError

Key = datastore_types.Key

Category = datastore_types.Category

Link = datastore_types.Link

Email = datastore_types.Email

GeoPt = datastore_types.GeoPt

IM = datastore_types.IM

PhoneNumber = datastore_types.PhoneNumber

PostalAddress = datastore_types.PostalAddress

Rating = datastore_types.Rating

Text = datastore_types.Text

Blob = datastore_types.Blob

ByteString = datastore_types.ByteString

BlobKey = datastore_types.BlobKey

READ_CAPABILITY = datastore.READ_CAPABILITY

WRITE_CAPABILITY = datastore.WRITE_CAPABILITY

_kind_map = {}

_SELF_REFERENCE = object()

_RESERVED_WORDS = set(['key_name'])

class NotSavedError(Error):

  """Raised when a saved-object action is performed on a non-saved object."""

class KindError(BadValueError):

  """Raised when an entity is used with incorrect Model."""

class PropertyError(Error):

  """Raised when non-existent property is referenced."""

class DuplicatePropertyError(Error):

  """Raised when a property is duplicated in a model definition."""

class ConfigurationError(Error):

  """Raised when a property or model is improperly configured."""

class ReservedWordError(Error):

  """Raised when a property is defined for a reserved word."""

class DerivedPropertyError(Error):

  """Raised when attempting to assign a value to a derived property."""

_ALLOWED_PROPERTY_TYPES = set([

    basestring,

    str,

    unicode,

    bool,

    int,

    long,

    float,

    Key,

    datetime.datetime,

    datetime.date,

    datetime.time,

    Blob,

    ByteString,

    Text,

    users.User,

    Category,

    Link,

    Email,

    GeoPt,

    IM,

    PhoneNumber,

    PostalAddress,

    Rating,

    BlobKey,

    ])

_ALLOWED_EXPANDO_PROPERTY_TYPES = set(_ALLOWED_PROPERTY_TYPES)

_ALLOWED_EXPANDO_PROPERTY_TYPES.update((list, tuple, type(None)))

_OPERATORS = ['<', '<=', '>', '>=', '=', '==', '!=', 'in']

_FILTER_REGEX = re.compile(

    '^\s*([^\s]+)(\s+(%s)\s*)?$' % '|'.join(_OPERATORS),

    re.IGNORECASE | re.UNICODE)

def class_for_kind(kind):

  """Return base-class responsible for implementing kind.

  Necessary to recover the class responsible for implementing provided

  kind.

  Args:

    kind: Entity kind string.

  Returns:

    Class implementation for kind.

  Raises:

    KindError when there is no implementation for kind.

  """

  try:

    return _kind_map[kind]

  except KeyError:

    raise KindError('No implementation for kind \'%s\'' % kind)

def check_reserved_word(attr_name):

  """Raise an exception if attribute name is a reserved word.

  Args:

    attr_name: Name to check to see if it is a reserved word.

  Raises:

    ReservedWordError when attr_name is determined to be a reserved word.

  """

  if datastore_types.RESERVED_PROPERTY_NAME.match(attr_name):

    raise ReservedWordError(

        "Cannot define property.  All names both beginning and "

        "ending with '__' are reserved.")

  if attr_name in _RESERVED_WORDS or attr_name in dir(Model):

    raise ReservedWordError(

        "Cannot define property using reserved word '%(attr_name)s'. "

        "If you would like to use this name in the datastore consider "

        "using a different name like %(attr_name)s_ and adding "

        "name='%(attr_name)s' to the parameter list of the property "

        "definition." % locals())

def query_descendants(model_instance):

  """Returns a query for all the descendants of a model instance.

  Args:

    model_instance: Model instance to find the descendants of.

  Returns:

    Query that will retrieve all entities that have the given model instance

  as an ancestor. Unlike normal ancestor queries, this does not include the

  ancestor itself.

  """

  result = Query().ancestor(model_instance);

  result.filter(datastore_types._KEY_SPECIAL_PROPERTY + ' >',

                model_instance.key());

  return result;

def model_to_protobuf(model_instance, _entity_class=datastore.Entity):

  """Encodes a model instance as a protocol buffer.

  Args:

    model_instance: Model instance to encode.

  Returns:

    entity_pb.EntityProto representation of the model instance

  """

  return model_instance._populate_entity(_entity_class).ToPb()

def model_from_protobuf(pb, _entity_class=datastore.Entity):

  """Decodes a model instance from a protocol buffer.

  Args:

    pb: The protocol buffer representation of the model instance. Can be an

        entity_pb.EntityProto or str encoding of an entity_bp.EntityProto

  Returns:

    Model instance resulting from decoding the protocol buffer

  """

  entity = _entity_class.FromPb(pb)

  return class_for_kind(entity.kind()).from_entity(entity)

def _initialize_properties(model_class, name, bases, dct):

  """Initialize Property attributes for Model-class.

  Args:

    model_class: Model class to initialize properties for.

  """

  model_class._properties = {}

  property_source = {}

  def get_attr_source(name, cls):

    for src_cls  in cls.mro():

      if name in src_cls.__dict__:

        return src_cls

  defined = set()

  for base in bases:

    if hasattr(base, '_properties'):

      property_keys = set(base._properties.keys())

      duplicate_property_keys = defined & property_keys

      for dupe_prop_name in duplicate_property_keys:

        old_source = property_source[dupe_prop_name] = get_attr_source(

            dupe_prop_name, property_source[dupe_prop_name])

        new_source = get_attr_source(dupe_prop_name, base)

        if old_source != new_source:

          raise DuplicatePropertyError(

              'Duplicate property, %s, is inherited from both %s and %s.' %

              (dupe_prop_name, old_source.__name__, new_source.__name__))

      property_keys -= duplicate_property_keys

      if property_keys:

        defined |= property_keys

        property_source.update(dict.fromkeys(property_keys, base))

        model_class._properties.update(base._properties)

  for attr_name in dct.keys():

    attr = dct[attr_name]

    if isinstance(attr, Property):

      check_reserved_word(attr_name)

      if attr_name in defined:

        raise DuplicatePropertyError('Duplicate property: %s' % attr_name)

      defined.add(attr_name)

      model_class._properties[attr_name] = attr

      attr.__property_config__(model_class, attr_name)

  model_class._unindexed_properties = frozenset(

    name for name, prop in model_class._properties.items() if not prop.indexed)

class PropertiedClass(type):

  """Meta-class for initializing Model classes properties.

  Used for initializing Properties defined in the context of a model.

  By using a meta-class much of the configuration of a Property

  descriptor becomes implicit.  By using this meta-class, descriptors

  that are of class Model are notified about which class they

  belong to and what attribute they are associated with and can

  do appropriate initialization via __property_config__.

  Duplicate properties are not permitted.

  """

  def __init__(cls, name, bases, dct, map_kind=True):

    """Initializes a class that might have property definitions.

    This method is called when a class is created with the PropertiedClass

    meta-class.

    Loads all properties for this model and its base classes in to a dictionary

    for easy reflection via the 'properties' method.

    Configures each property defined in the new class.

    Duplicate properties, either defined in the new class or defined separately

    in two base classes are not permitted.

    Properties may not assigned to names which are in the list of

    _RESERVED_WORDS.  It is still possible to store a property using a reserved

    word in the datastore by using the 'name' keyword argument to the Property

    constructor.

    Args:

      cls: Class being initialized.

      name: Name of new class.

      bases: Base classes of new class.

      dct: Dictionary of new definitions for class.

    Raises:

      DuplicatePropertyError when a property is duplicated either in the new

        class or separately in two base classes.

      ReservedWordError when a property is given a name that is in the list of

        reserved words, attributes of Model and names of the form '__.*__'.

    """

    super(PropertiedClass, cls).__init__(name, bases, dct)

    _initialize_properties(cls, name, bases, dct)

    if map_kind:

      _kind_map[cls.kind()] = cls

class Property(object):

  """A Property is an attribute of a Model.

  It defines the type of the attribute, which determines how it is stored

  in the datastore and how the property values are validated. Different property

  types support different options, which change validation rules, default

  values, etc.  The simplest example of a property is a StringProperty:

     class Story(db.Model):

       title = db.StringProperty()

  """

  creation_counter = 0

  def __init__(self,

               verbose_name=None,

               name=None,

               default=None,

               required=False,

               validator=None,

               choices=None,

               indexed=True):

    """Initializes this Property with the given options.

    Args:

      verbose_name: User friendly name of property.

      name: Storage name for property.  By default, uses attribute name

        as it is assigned in the Model sub-class.

      default: Default value for property if none is assigned.

      required: Whether property is required.

      validator: User provided method used for validation.

      choices: User provided set of valid property values.

      indexed: Whether property is indexed.

    """

    self.verbose_name = verbose_name

    self.name = name

    self.default = default

    self.required = required

    self.validator = validator

    self.choices = choices

    self.indexed = indexed

    self.creation_counter = Property.creation_counter

    Property.creation_counter += 1

  def __property_config__(self, model_class, property_name):

    """Configure property, connecting it to its model.

    Configure the property so that it knows its property name and what class

    it belongs to.

    Args:

      model_class: Model class which Property will belong to.

      property_name: Name of property within Model instance to store property

        values in.  By default this will be the property name preceded by

        an underscore, but may change for different subclasses.

    """

    self.model_class = model_class

    if self.name is None:

      self.name = property_name

  def __get__(self, model_instance, model_class):

    """Returns the value for this property on the given model instance.

    See http://docs.python.org/ref/descriptors.html for a description of

    the arguments to this class and what they mean."""

    if model_instance is None:

      return self

    try:

      return getattr(model_instance, self._attr_name())

    except AttributeError:

      return None

  def __set__(self, model_instance, value):

    """Sets the value for this property on the given model instance.

    See http://docs.python.org/ref/descriptors.html for a description of

    the arguments to this class and what they mean.

    """

    value = self.validate(value)

    setattr(model_instance, self._attr_name(), value)

  def default_value(self):

    """Default value for unassigned values.

    Returns:

      Default value as provided by __init__(default).

    """

    return self.default

  def validate(self, value):

    """Assert that provided value is compatible with this property.

    Args:

      value: Value to validate against this Property.

    Returns:

      A valid value, either the input unchanged or adapted to the

      required type.

    Raises:

      BadValueError if the value is not appropriate for this

      property in any way.

    """

    if self.empty(value):

      if self.required:

        raise BadValueError('Property %s is required' % self.name)

    else:

      if self.choices:

        match = False

        for choice in self.choices:

          if choice == value:

            match = True

        if not match:

          raise BadValueError('Property %s is %r; must be one of %r' %

                              (self.name, value, self.choices))

    if self.validator is not None:

      self.validator(value)

    return value

  def empty(self, value):

    """Determine if value is empty in the context of this property.

    For most kinds, this is equivalent to "not value", but for kinds like

    bool, the test is more subtle, so subclasses can override this method