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

#

"""Higher-level, semantic data types for the datastore. These types

are expected to be set as attributes of Entities.  See "Supported Data Types"

in the API Guide.

Most of these types are based on XML elements from Atom and GData elements

from the atom and gd namespaces. For more information, see:

  http://www.atomenabled.org/developers/syndication/

  http://code.google.com/apis/gdata/common-elements.html

The namespace schemas are:

  http://www.w3.org/2005/Atom

  http://schemas.google.com/g/2005

"""

import base64

import calendar

import datetime

import os

import re

import string

import time

import urlparse

from xml.sax import saxutils

from google.appengine.datastore import datastore_pb

from google.appengine.api import datastore_errors

from google.appengine.api import users

from google.net.proto import ProtocolBuffer

from google.appengine.datastore import entity_pb

_MAX_STRING_LENGTH = 500

_MAX_LINK_PROPERTY_LENGTH = 2083

class UtcTzinfo(datetime.tzinfo):

  def utcoffset(self, dt): return datetime.timedelta(0)

  def dst(self, dt): return datetime.timedelta(0)

  def tzname(self, dt): return 'UTC'

  def __repr__(self): return 'datastore_types.UTC'

UTC = UtcTzinfo()

def typename(obj):

  """Returns the type of obj as a string. More descriptive and specific than

  type(obj), and safe for any object, unlike __class__."""

  if hasattr(obj, '__class__'):

    return getattr(obj, '__class__').__name__

  else:

    return type(obj).__name__

                   exception=datastore_errors.BadValueError,

                   max_len=_MAX_STRING_LENGTH):

  """Raises an exception if value is not a valid string or a subclass thereof.

  A string is valid if it's not empty, no more than _MAX_STRING_LENGTH bytes,

  and not a Blob. The exception type can be specified with the exception

  argument; it defaults to BadValueError.

  Args:

    value: the value to validate.

    name: the name of this value; used in the exception message.

    exception: the type of exception to raise.

    max_len: the maximum allowed length, in bytes

  """

  if not isinstance(value, basestring) or isinstance(value, Blob):

    raise exception('%s should be a string; received %s (a %s):' %

                    (name, value, typename(value)))

    raise exception('%s must not be empty.' % name)

    raise exception('%s must be under %d bytes.' % (name, max_len))

class Key(object):

  """The primary key for a datastore entity.

  A datastore GUID. A Key instance uniquely identifies an entity across all

  apps, and includes all information necessary to fetch the entity from the

  datastore with Get().

  Key implements __hash__, and key instances are immutable, so Keys may be

  used in sets and as dictionary keys.

  """

  __reference = None

  def __init__(self, encoded=None):

    """Constructor. Creates a Key from a string.

    Args:

      # a base64-encoded primary key, generated by Key.__str__

      encoded: str

    """

    if encoded is not None:

      if not isinstance(encoded, basestring):

        try:

          repr_encoded = repr(encoded)

        except:

          repr_encoded = "<couldn't encode>"

        raise datastore_errors.BadArgumentError(

          'Key() expects a string; received %s (a %s).' %

          (repr_encoded, typename(encoded)))

      try:

        modulo = len(encoded) % 4

        if modulo != 0:

          encoded += ('=' * (4 - modulo))

        encoded_pb = base64.urlsafe_b64decode(str(encoded))

        self.__reference = entity_pb.Reference(encoded_pb)

        assert self.__reference.IsInitialized()

      except (AssertionError, TypeError), e:

        raise datastore_errors.BadKeyError(

          'Invalid string key %s. Details: %s' % (encoded, e))

      except Exception, e:

        if e.__class__.__name__ == 'ProtocolBufferDecodeError':

          raise datastore_errors.BadKeyError('Invalid string key %s.' % encoded)

        else:

          raise

    else:

      self.__reference = entity_pb.Reference()

  @staticmethod

  def from_path(*args, **kwds):

    """Static method to construct a Key out of a "path" (kind, id or name, ...).

    This is useful when an application wants to use just the id or name portion

    of a key in e.g. a URL, where the rest of the URL provides enough context to

    fill in the rest, i.e. the app id (always implicit), the entity kind, and

    possibly an ancestor key. Since ids and names are usually small, they're

    more attractive for use in end-user-visible URLs than the full string

    representation of a key.

    Args:

      kind: the entity kind (a str or unicode instance)

      id_or_name: the id (an int or long) or name (a str or unicode instance)

    Additional positional arguments are allowed and should be

    alternating kind and id/name.

    Keyword args:

      parent: optional parent Key; default None.

    Returns:

      A new Key instance whose .kind() and .id() or .name() methods return

      the *last* kind and id or name positional arguments passed.

    Raises:

      BadArgumentError for invalid arguments.

      BadKeyError if the parent key is incomplete.

    """

    parent = kwds.pop('parent', None)

    if kwds:

      raise datastore_errors.BadArgumentError(

          'Excess keyword arguments ' + repr(kwds))

    if not args or len(args) % 2:

      raise datastore_errors.BadArgumentError(

          'A non-zero even number of positional arguments is required '

          '(kind, id or name, kind, id or name, ...); received %s' % repr(args))

    if parent is not None:

      if not isinstance(parent, Key):

        raise datastore_errors.BadArgumentError(

            'Expected None or a Key as parent; received %r (a %s).' %

            (parent, typename(parent)))

      if not parent.has_id_or_name():

        raise datastore_errors.BadKeyError(

            'The parent Key is incomplete.')

        raise datastore_errors.BadArgumentError(

            'The _app argument (%r) should match parent.app() (%s)' %

            (_app, parent.app()))

    key = Key()

    ref = key.__reference

    if parent is not None:

      ref.CopyFrom(parent.__reference)

      ref.set_app(_app)

    path = ref.mutable_path()

    for i in xrange(0, len(args), 2):

      kind, id_or_name = args[i:i+2]

      if isinstance(kind, basestring):

        kind = kind.encode('utf-8')

      else:

        raise datastore_errors.BadArgumentError(

            'Expected a string kind as argument %d; received %r (a %s).' %

            (i + 1, kind, typename(kind)))

      elem = path.add_element()

      elem.set_type(kind)

      if isinstance(id_or_name, (int, long)):

        elem.set_id(id_or_name)

      elif isinstance(id_or_name, basestring):

        ValidateString(id_or_name, 'name')

        if id_or_name and id_or_name[0] in string.digits:

          raise datastore_errors.BadArgumentError(

            'Names may not begin with a digit; received %s.' % id_or_name)

        elem.set_name(id_or_name.encode('utf-8'))

      else:

        raise datastore_errors.BadArgumentError(

            'Expected an integer id or string name as argument %d; '

            'received %r (a %s).' % (i + 2, id_or_name, typename(id_or_name)))

    assert ref.IsInitialized()

    return key

  def app(self):

    """Returns this entity's app id, a string."""

    if self.__reference.app():

      return self.__reference.app().decode('utf-8')

    else:

      return None

  def kind(self):

    """Returns this entity's kind, as a string."""

    if self.__reference.path().element_size() > 0:

      encoded = self.__reference.path().element_list()[-1].type()

      return unicode(encoded.decode('utf-8'))

    else:

      return None

  def id(self):

    """Returns this entity's id, or None if it doesn't have one."""

    elems = self.__reference.path().element_list()

    if elems and elems[-1].has_id() and elems[-1].id():

      return elems[-1].id()

    else:

      return None

  def name(self):

    """Returns this entity's name, or None if it doesn't have one."""

    elems = self.__reference.path().element_list()

    if elems and elems[-1].has_name() and elems[-1].name():

      return elems[-1].name().decode('utf-8')

    else:

      return None

  def id_or_name(self):

    """Returns this entity's id or name, whichever it has, or None."""

    if self.id() is not None:

      return self.id()

    else:

      return self.name()

  def has_id_or_name(self):

    """Returns True if this entity has an id or name, False otherwise.

    """

    return self.id_or_name() is not None

  def parent(self):

    """Returns this entity's parent, as a Key. If this entity has no parent,

    returns None."""

    if self.__reference.path().element_size() > 1:

      parent = Key()

      parent.__reference.CopyFrom(self.__reference)

      parent.__reference.path().element_list().pop()

      return parent

    else:

      return None

  def ToTagUri(self):

    """Returns a tag: URI for this entity for use in XML output.

    Foreign keys for entities may be represented in XML output as tag URIs.

    RFC 4151 describes the tag URI scheme. From http://taguri.org/:

      The tag algorithm lets people mint - create - identifiers that no one

      else using the same algorithm could ever mint. It is simple enough to do

      in your head, and the resulting identifiers can be easy to read, write,

      and remember. The identifiers conform to the URI (URL) Syntax.

    Tag URIs for entities use the app's auth domain and the date that the URI

     is generated. The namespace-specific part is <kind>[<key>].

    For example, here is the tag URI for a Kitten with the key "Fluffy" in the

    catsinsinks app:

      tag:catsinsinks.googleapps.com,2006-08-29:Kitten[Fluffy]

    Raises a BadKeyError if this entity's key is incomplete.

    """

    if not self.has_id_or_name():

      raise datastore_errors.BadKeyError(

        'ToTagUri() called for an entity with an incomplete key.')

    return u'tag:%s.%s,%s:%s[%s]' % (saxutils.escape(self.app()),

                                     os.environ['AUTH_DOMAIN'],

                                     datetime.date.today().isoformat(),

                                     saxutils.escape(self.kind()),

                                     saxutils.escape(str(self)))

  ToXml = ToTagUri

  def entity_group(self):

    """Returns this key's entity group as a Key.

    Note that the returned Key will be incomplete if this Key is for a root

    entity and it is incomplete.

    """

    group = Key._FromPb(self.__reference)

    del group.__reference.path().element_list()[1:]

    return group

  @staticmethod

  def _FromPb(pb):

    """Static factory method. Creates a Key from an entity_pb.Reference.

    Not intended to be used by application developers. Enforced by hiding the

    entity_pb classes.

    Args:

      pb: entity_pb.Reference

    """

    if not isinstance(pb, entity_pb.Reference):

      raise datastore_errors.BadArgumentError(

        'Key constructor takes an entity_pb.Reference; received %s (a %s).' %

        (pb, typename(pb)))

    key = Key()

    key.__reference = entity_pb.Reference()

    key.__reference.CopyFrom(pb)

    return key

  def _ToPb(self):

    """Converts this Key to its protocol buffer representation.

    Not intended to be used by application developers. Enforced by hiding the

    entity_pb classes.

    Returns:

      # the Reference PB representation of this Key

      entity_pb.Reference

    """

    pb = entity_pb.Reference()

    pb.CopyFrom(self.__reference)

    if not self.has_id_or_name():

      pb.mutable_path().element_list()[-1].set_id(0)

    pb.app().decode('utf-8')

    for pathelem in pb.path().element_list():

      pathelem.type().decode('utf-8')

    return pb

  def __str__(self):

    """Encodes this Key as an opaque string.

    Returns a string representation of this key, suitable for use in HTML,

    URLs, and other similar use cases. If the entity's key is incomplete,

    raises a BadKeyError.

    Unfortunately, this string encoding isn't particularly compact, and its

    length varies with the length of the path. If you want a shorter identifier

    and you know the kind and parent (if any) ahead of time, consider using just

    the entity's id or name.

    Returns:

      string

    """

    if (self.has_id_or_name()):

      encoded = base64.urlsafe_b64encode(self.__reference.Encode())

      return encoded.replace('=', '')

    else:

      raise datastore_errors.BadKeyError(

        'Cannot string encode an incomplete key!\n%s' % self.__reference)

  def __repr__(self):

    """Returns an eval()able string representation of this key.

    Returns a Python string of the form 'datastore_types.Key.from_path(...)'

    that can be used to recreate this key.

    Returns:

      string

    """

    args = []

    for elem in self.__reference.path().element_list():

      args.append(repr(elem.type()))

      if elem.has_name():

        args.append(repr(elem.name().decode('utf-8')))

      else:

        args.append(repr(elem.id()))

    args.append('_app=%r' % self.__reference.app().decode('utf-8'))

    return u'datastore_types.Key.from_path(%s)' % ', '.join(args)

  def __cmp__(self, other):

    """Returns negative, zero, or positive when comparing two keys.

    TODO(ryanb): for API v2, we should change this to make incomplete keys, ie

    keys without an id or name, not equal to any other keys.

    Args:

      other: Key to compare to.

    Returns:

      Negative if self is less than "other"

      Zero if "other" is equal to self

      Positive if self is greater than "other"

    """

    if not isinstance(other, Key):

      return -2

    self_args = []

    other_args = []

    for elem in self.__reference.path().element_list():

      self_args.append(repr(elem.type()))

      if elem.has_name():

        self_args.append(repr(elem.name().decode('utf-8')))

      else:

        self_args.append(elem.id())

    for elem in other.__reference.path().element_list():

      other_args.append(repr(elem.type()))

      if elem.has_name():

        other_args.append(repr(elem.name().decode('utf-8')))

      else:

        other_args.append(elem.id())

    result = cmp(self_args, other_args)

    return result

  def __hash__(self):

    """Returns a 32-bit integer hash of this key.

    Implements Python's hash protocol so that Keys may be used in sets and as

    dictionary keys.

    Returns:

      int

    """

    return hash(self.__str__())

class Category(unicode):

  """A tag, ie a descriptive word or phrase. Entities may be tagged by users,

  and later returned by a queries for that tag. Tags can also be used for

  ranking results (frequency), photo captions, clustering, activity, etc.

  Here's a more in-depth description:  http://www.zeldman.com/daily/0405d.shtml

  This is the Atom "category" element. In XML output, the tag is provided as

  the term attribute. See:

  http://www.atomenabled.org/developers/syndication/#category

  Raises BadValueError if tag is not a string or subtype.

  """

  TERM = 'user-tag'

  def __init__(self, tag):

    super(Category, self).__init__(self, tag)

    ValidateString(tag, 'tag')

  def ToXml(self):

    return u'<category term="%s" label=%s />' % (Category.TERM,

                                                 saxutils.quoteattr(self))

class Link(unicode):

  """A fully qualified URL. Usually http: scheme, but may also be file:, ftp:,

  news:, among others.

  If you have email (mailto:) or instant messaging (aim:, xmpp:) links,

  consider using the Email or IM classes instead.

  This is the Atom "link" element. In XML output, the link is provided as the

  href attribute. See:

  http://www.atomenabled.org/developers/syndication/#link