#!/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 datetime

import logging

import time

import urlparse

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

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

_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):

class ReservedWordError(Error):

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

_ALLOWED_PROPERTY_TYPES = set([

    basestring,

    str,

    unicode,

    bool,

    int,

    long,

    float,

    Key,

    datetime.datetime,

    datetime.date,

    datetime.time,

    Blob,

    Text,

    users.User,

    Category,

    Link,

    Email,

    GeoPt,

    IM,

    PhoneNumber,

    PostalAddress,

    Rating,

    ])

_ALLOWED_EXPANDO_PROPERTY_TYPES = set(_ALLOWED_PROPERTY_TYPES)

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

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

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.

  """

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

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

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

    """

    self.verbose_name = verbose_name

    self.name = name

    self.default = default

    self.required = required

    self.validator = validator

    self.choices = choices

    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

    if necessary.

    Args:

      value: Value to validate against this Property.

    Returns:

      True if this value is considered empty in the context of this Property

      type, otherwise False.

    """

    return not value

  def get_value_for_datastore(self, model_instance):

    """Datastore representation of this property.

    Looks for this property in the given model instance, and returns the proper

    datastore representation of the value that can be stored in a datastore

    entity.  Most critically, it will fetch the datastore key value for

    reference properties.

    Args:

      model_instance: Instance to fetch datastore value from.

    Returns:

      Datastore representation of the model value in a form that is

      appropriate for storing in the datastore.

    """

    return self.__get__(model_instance, model_instance.__class__)

  def make_value_from_datastore(self, value):

    """Native representation of this property.

    Given a value retrieved from a datastore entity, return a value,

    possibly converted, to be stored on the model instance.  Usually

    this returns the value unchanged, but a property class may

    override this when it uses a different datatype on the model

    instance than on the entity.

    This API is not quite symmetric with get_value_for_datastore(),

    because the model instance on which to store the converted value

    may not exist yet -- we may be collecting values to be passed to a

    model constructor.

    Args:

      value: value retrieved from the datastore entity.

    Returns:

      The value converted for use as a model instance attribute.

    """

    return value

  def _attr_name(self):

    return '_' + self.name

  data_type = str

  def datastore_type(self):

    """Deprecated backwards-compatible accessor method for self.data_type."""

    return self.data_type

class Model(object):

  """Model is the superclass of all object entities in the datastore.

  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)

  A model instance can have a single parent.  Model instances without any

  parent are root entities.  It is possible to efficiently query for

  instances by their shared parent.  All descendents of a single root

  instance also behave as a transaction group.  This means that when you

  work one member of the group within a transaction all descendents of that

  root join the transaction.  All operations within a transaction on this

  group are ACID.

  """

  __metaclass__ = PropertiedClass