#!/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.appengine.api import namespace_manager

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

_NAMESPACE_SEPARATOR='!'

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,

                   max_len=_MAX_STRING_LENGTH,

                   empty_ok=False):

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

    empty_ok: allow empty value.

  """

  if value is None and empty_ok:

    return

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

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

                    (name, value, typename(value)))

  if not value and not empty_ok:

    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 ValidateInteger(value,

                   name='unused',

                   exception=datastore_errors.BadValueError,

                   empty_ok=False,

                   zero_ok=False,

                   negative_ok=False):

  """Raises an exception if value is not a valid integer.

  An integer is valid if it's not negative or empty and is an integer.

  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.

    empty_ok: allow None value.

    zero_ok: allow zero value.

    negative_ok: allow negative value.

  """

  if value is None and empty_ok:

    return

  if not isinstance(value, int):

    raise exception('%s should be an integer; received %s (a %s).' %

                    (name, value, typename(value)))

  if not value and not zero_ok:

    raise exception('%s must not be 0 (zero)' % name)

  if value < 0 and not negative_ok:

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

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

  """Combined AppId and Namespace

  An identifier that combines the application identifier and the

  namespace.

  """

  __app_id = None

  __namespace = None

  def __init__(self, app_id, namespace):

    """Constructor. Creates a AppIdNamespace from two strings.

    Args:

      app_id: application identifier string

      namespace: namespace identifier string

    Raises:

      BadArgumentError if the values contain

      the _NAMESPACE_SEPARATOR character (!) or

      the app_id is empty.

    """

    self.__app_id = app_id

    if namespace:

      self.__namespace = namespace

    else:

      self.__namespace = None

    ValidateString(self.__app_id, 'app_id', datastore_errors.BadArgumentError)

    ValidateString(self.__namespace,

                   'namespace', datastore_errors.BadArgumentError,

                   empty_ok=True)

    if _NAMESPACE_SEPARATOR in self.__app_id:

      raise datastore_errors.BadArgumentError(

        'app_id must not contain a "%s"' % _NAMESPACE_SEPARATOR)

    if self.__namespace and _NAMESPACE_SEPARATOR in self.__namespace:

      raise datastore_errors.BadArgumentError(

        'namespace must not contain a "%s"' % _NAMESPACE_SEPARATOR)

  def __cmp__(self, other):

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

    Args:

      other: AppIdNamespace 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, AppIdNamespace):

      return cmp(id(self), id(other))

    return cmp((self.__app_id, self.__namespace),

               (other.__app_id, other.__namespace))

  def to_encoded(self):

    """Returns this AppIdNamespace's string equivalent

    i.e. "app!namespace"

    """

    if not self.__namespace:

      return self.__app_id

    else:

      return self.__app_id + _NAMESPACE_SEPARATOR + self.__namespace

  def app_id(self):

    """Returns this AppId portion of this AppIdNamespace.

    """

    return self.__app_id;

  def namespace(self):

    """Returns this namespace portion of this AppIdNamespace.

    """

    return self.__namespace;

def PartitionString(value, separator):

  """Equivalent to python2.5 str.partition()

     TODO(gmariani) use str.partition() when python 2.5 is adopted.

  Args:

    value: String to be partitioned

    separator: Separator string

  """

  index = value.find(separator);

  if index == -1:

    return (value, '', value[0:0]);

  else:

    return (value[0:index], separator, value[index+len(separator):len(value)])

def parse_app_id_namespace(app_id_namespace):

  """

  An app_id_namespace string is valid if it's not empty, and contains

  at most one namespace separator ('!').  Also, an app_id_namespace

  with an empty namespace must not contain a namespace separator.

  Args:

    app_id_namespace: an encoded app_id_namespace.

  Raises exception if format of app_id_namespace is invalid.

  """

  if not app_id_namespace:

    raise datastore_errors.BadArgumentError(

        'app_id_namespace must be non empty')

  parts = PartitionString(app_id_namespace, _NAMESPACE_SEPARATOR)

  if parts[1] == _NAMESPACE_SEPARATOR:

    if not parts[2]:

      raise datastore_errors.BadArgumentError(

        'app_id_namespace must not contain a "%s" if the namespace is empty' %

        _NAMESPACE_SEPARATOR)

  if parts[2]:

    return AppIdNamespace(parts[0], parts[2])

  return AppIdNamespace(parts[0], None)

def ResolveAppIdNamespace(

    app_id=None, namespace=None, app_id_namespace=None):

  """Validate an app id/namespace and substitute default values.

  If the argument is None, $APPLICATION_ID!$NAMESPACE is substituted.

  Args:

    app_id: The app id argument value to be validated.

    namespace: The namespace argument value to be validated.

    app_id_namespace: An AppId/Namespace pair

  Returns:

    An AppIdNamespace object initialized with AppId and Namespace.

  Raises:

    BadArgumentError if the value is empty or not a string.

  """

  if app_id_namespace is None:

    if app_id is None:

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

    if namespace is None:

      namespace = namespace_manager.get_request_namespace();

  else:

    if not app_id is None:

      raise datastore_errors.BadArgumentError(

          'app_id is overspecified.  Cannot define app_id_namespace and app_id')

    if not namespace is None:

      raise datastore_errors.BadArgumentError(

          'namespace is overspecified.  ' +

          'Cannot define app_id_namespace and namespace')

    return parse_app_id_namespace(app_id_namespace)

  return AppIdNamespace(app_id, namespace)

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

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

    """Construct the "path" of this key as a list.

    Returns:

      A list [kind_1, id_or_name_1, ..., kind_n, id_or_name_n] of the key path.

    Raises:

      datastore_errors.BadKeyError if this key does not have a valid path.

    """

    path = []

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

      path.append(path_element.type().decode('utf-8'))

      if path_element.has_name():

        path.append(path_element.name().decode('utf-8'))

      elif path_element.has_id():

        path.append(path_element.id())

      else:

        raise datastore_errors.BadKeyError('Incomplete key found in to_path')

    return path

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

    _app_id_namespace_obj = ResolveAppIdNamespace(

        kwds.pop('_app', None),

        kwds.pop('_namespace', None),

        kwds.pop('_app_id_namespace', 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.')

      if _app_id_namespace_obj != parent.app_id_namespace():

        raise datastore_errors.BadArgumentError(

            'The app_id/namespace arguments (%r) should match ' +

            'parent.app_id_namespace().to_encoded() (%s)' %

            (_app_id_namespace_obj, parent.app_id_namespace()))

    key = Key()

    ref = key.__reference

    if parent is not None:

      ref.CopyFrom(parent.__reference)

    else:

      ref.set_app(_app_id_namespace_obj.to_encoded())

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

      return self.app_id_namespace().app_id().decode('utf-8')

    else:

      return None

  def namespace(self):

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

    if self.__reference.app():

      return self.app_id_namespace().namespace().decode('utf-8')

    else:

      return None

  def app_id_namespace(self):

    """Returns this entity's app id/namespace, an appIdNamespace object."""

    if self.__reference.app():

      return parse_app_id_namespace(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