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

RESERVED_PROPERTY_NAME = re.compile('^__.*__$')

_KEY_SPECIAL_PROPERTY = '__key__'

_SPECIAL_PROPERTIES = frozenset([_KEY_SPECIAL_PROPERTY])

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__

def ValidateString(value,

                   name='unused',

                   exception=datastore_errors.BadValueError,

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

  """

  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)

  if len(value.encode('utf-8')) > max_len:

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

def ResolveAppId(app, name='_app'):

  """Validate app id, providing a default.

  If the argument is None, $APPLICATION_ID is substituted.

  Args:

    app: The app id argument value to be validated.

    name: The argument name, for error messages.

  Returns:

    The value of app, or the substituted default.  Always a non-empty string.

  Raises:

    BadArgumentError if the value is empty or not a string.

  """

  if app is None:

    app = os.environ.get('APPLICATION_ID', '')

  ValidateString(app, '_app', datastore_errors.BadArgumentError)

  return app

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(

    key = Key()

    ref = key.__reference

    if parent is not None:

      ref.CopyFrom(parent.__reference)

    else:

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

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

    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