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

#

"""Classes for common kinds, including Contact, Message, and Event.

Most of these kinds are based on the gd namespace "kinds" from GData:

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

"""

import types

import urlparse

from xml.sax import saxutils

from google.appengine.datastore import datastore_pb

from google.appengine.api import datastore

from google.appengine.api import datastore_errors

from google.appengine.api import datastore_types

class GdKind(datastore.Entity):

  """ A base class for gd namespace kinds.

  This class contains common logic for all gd namespace kinds. For example,

  this class translates datastore (app id, kind, key) tuples to tag:

  URIs appropriate for use in <key> tags.

  """

  HEADER = u"""<entry xmlns:gd='http://schemas.google.com/g/2005'>

  <category scheme='http://schemas.google.com/g/2005#kind'

            term='http://schemas.google.com/g/2005#%s' />"""

  FOOTER = u"""

</entry>"""

  _kind_properties = set()

  _contact_properties = set()

  def __init__(self, kind, title, kind_properties, contact_properties=[]):

    """ Ctor.

    title is the name of this particular entity, e.g. Bob Jones or Mom's

    Birthday Party.

    kind_properties is a list of property names that should be included in

    this entity's XML encoding as first-class XML elements, instead of

    <property> elements. 'title' and 'content' are added to kind_properties

    automatically, and may not appear in contact_properties.

    contact_properties is a list of property names that are Keys that point to

    Contact entities, and should be included in this entity's XML encoding as

    <gd:who> elements. If a property name is included in both kind_properties

    and contact_properties, it is treated as a Contact property.

    Args:

    kind: string

    title: string

    kind_properties: list of strings

    contact_properties: list of string

    """

    datastore.Entity.__init__(self, kind)

    if not isinstance(title, types.StringTypes):

      raise datastore_errors.BadValueError(

        'Expected a string for title; received %s (a %s).' %

        (title, datastore_types.typename(title)))

    self['title'] = title

    self['content'] = ''

    self._contact_properties = set(contact_properties)

    assert not self._contact_properties.intersection(self.keys())

    self._kind_properties = set(kind_properties) - self._contact_properties

    self._kind_properties.add('title')

    self._kind_properties.add('content')

  def _KindPropertiesToXml(self):

    """ Convert the properties that are part of this gd kind to XML. For

    testability, the XML elements in the output are sorted alphabetically

    by property name.

    Returns:

    string  # the XML representation of the gd kind properties

    """

    properties = self._kind_properties.intersection(set(self.keys()))

    xml = u''

    for prop in sorted(properties):

      prop_xml = saxutils.quoteattr(prop)[1:-1]

      value = self[prop]

      has_toxml = (hasattr(value, 'ToXml') or

                   isinstance(value, list) and hasattr(value[0], 'ToXml'))

      for val in self._XmlEscapeValues(prop):

        if has_toxml:

          xml += '\n  %s' % val

        else:

          xml += '\n  <%s>%s</%s>' % (prop_xml, val, prop_xml)

    return xml

  def _ContactPropertiesToXml(self):

    """ Convert this kind's Contact properties kind to XML. For testability,

    the XML elements in the output are sorted alphabetically by property name.

    Returns:

    string  # the XML representation of the Contact properties

    """

    properties = self._contact_properties.intersection(set(self.keys()))

    xml = u''

    for prop in sorted(properties):

      values = self[prop]

      if not isinstance(values, list):

        values = [values]

      for value in values:

        assert isinstance(value, datastore_types.Key)

        xml += """

  <gd:who rel="http://schemas.google.com/g/2005#%s.%s>

    <gd:entryLink href="%s" />

  </gd:who>""" % (self.kind().lower(), prop, value.ToTagUri())

    return xml

  def _LeftoverPropertiesToXml(self):

    """ Convert all of this entity's properties that *aren't* part of this gd

    kind to XML.

    Returns:

    string  # the XML representation of the leftover properties

    """

    leftovers = set(self.keys())

    leftovers -= self._kind_properties

    leftovers -= self._contact_properties

    if leftovers:

      return u'\n  ' + '\n  '.join(self._PropertiesToXml(leftovers))

    else:

      return u''

  def ToXml(self):

    """ Returns an XML representation of this entity, as a string.

    """

    xml = GdKind.HEADER % self.kind().lower()

    xml += self._KindPropertiesToXml()

    xml += self._ContactPropertiesToXml()

    xml += self._LeftoverPropertiesToXml()

    xml += GdKind.FOOTER

    return xml

class Message(GdKind):

  """A message, such as an email, a discussion group posting, or a comment.

  Includes the message title, contents, participants, and other properties.

  This is the gd Message kind. See:

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

  These properties are meaningful. They are all optional.

  property name  property type    meaning

  -------------------------------------

  title          string         message subject

  content        string         message body

  from           Contact*       sender

  to             Contact*       primary recipient

  cc             Contact*       CC recipient

  bcc            Contact*       BCC recipient

  reply-to       Contact*       intended recipient of replies

  link           Link*          attachment

  category       Category*      tag or label associated with this message

  geoPt          GeoPt*         geographic location the message was posted from

  rating         Rating*        message rating, as defined by the application

  * means this property may be repeated.

  The Contact properties should be Keys of Contact entities. They are

  represented in the XML encoding as linked <gd:who> elements.

  """

  KIND_PROPERTIES = ['title', 'content', 'link', 'category', 'geoPt', 'rating']

  CONTACT_PROPERTIES = ['from', 'to', 'cc', 'bcc', 'reply-to']

  def __init__(self, title, kind='Message'):

    GdKind.__init__(self, kind, title, Message.KIND_PROPERTIES,

                    Message.CONTACT_PROPERTIES)

class Event(GdKind):

  """A calendar event.

  Includes the event title, description, location, organizer, start and end

  time, and other details.

  This is the gd Event kind. See:

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

  These properties are meaningful. They are all optional.

  property name  property type    meaning

  -------------------------------------

  title          string         event name

  content        string         event description

  author         string         the organizer's name

  where          string*        human-readable location (not a GeoPt)

  startTime      timestamp      start time

  endTime        timestamp      end time

  eventStatus    string         one of the Event.Status values

  link           Link*          page with more information

  category       Category*      tag or label associated with this event

  attendee       Contact*       attendees and other related people

  * means this property may be repeated.

  The Contact properties should be Keys of Contact entities. They are

  represented in the XML encoding as linked <gd:who> elements.

  """

  KIND_PROPERTIES = ['title', 'content', 'author', 'where', 'startTime',

                     'endTime', 'eventStatus', 'link', 'category']

  CONTACT_PROPERTIES = ['attendee']

  class Status:

    CONFIRMED = 'confirmed'

    TENTATIVE = 'tentative'

    CANCELED = 'canceled'

  def __init__(self, title, kind='Event'):

    GdKind.__init__(self, kind, title, Event.KIND_PROPERTIES,

                    Event.CONTACT_PROPERTIES)

  def ToXml(self):

    """ Override GdKind.ToXml() to special-case author, gd:where, gd:when, and

    gd:eventStatus.

    """

    xml = GdKind.HEADER % self.kind().lower()

    self._kind_properties = set(Contact.KIND_PROPERTIES)

    xml += self._KindPropertiesToXml()

    if 'author' in self:

      xml += """

  <author><name>%s</name></author>""" % self['author']

    if 'eventStatus' in self:

      xml += """

  <gd:eventStatus value="http://schemas.google.com/g/2005#event.%s" />""" % (

    self['eventStatus'])

    if 'where' in self:

      lines = ['<gd:where valueString="%s" />' % val

               for val in self._XmlEscapeValues('where')]

      xml += '\n  ' + '\n  '.join(lines)

    iso_format = '%Y-%m-%dT%H:%M:%S'

    xml += '\n  <gd:when'

    for key in ['startTime', 'endTime']:

      if key in self:

        xml += ' %s="%s"' % (key, self[key].isoformat())

    xml += ' />'

    self._kind_properties.update(['author', 'where', 'startTime', 'endTime',

                                  'eventStatus'])

    xml += self._ContactPropertiesToXml()

    xml += self._LeftoverPropertiesToXml()

    xml += GdKind.FOOTER

    return xml

class Contact(GdKind):

  """A contact: a person, a venue such as a club or a restaurant, or an

  organization.

  This is the gd Contact kind. See:

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

  Most of the information about the contact is in the <gd:contactSection>

  element; see the reference section for that element for details.

  These properties are meaningful. They are all optional.

  property name  property type    meaning

  -------------------------------------

  title          string         contact's name

  content        string         notes

  email          Email*         email address

  geoPt          GeoPt*         geographic location

  im             IM*            IM address

  phoneNumber    Phonenumber*   phone number

  postalAddress  PostalAddress* mailing address

  link           Link*          link to more information

  category       Category*      tag or label associated with this contact

  * means this property may be repeated.

  """

  CONTACT_SECTION_HEADER = """

  <gd:contactSection>"""

  CONTACT_SECTION_FOOTER = """

  </gd:contactSection>"""

  KIND_PROPERTIES = ['title', 'content', 'link', 'category']

  CONTACT_SECTION_PROPERTIES = ['email', 'geoPt', 'im', 'phoneNumber',

                                'postalAddress']

  def __init__(self, title, kind='Contact'):

    GdKind.__init__(self, kind, title, Contact.KIND_PROPERTIES)

  def ToXml(self):

    """ Override GdKind.ToXml() to put some properties inside a

    gd:contactSection.

    """

    xml = GdKind.HEADER % self.kind().lower()

    self._kind_properties = set(Contact.KIND_PROPERTIES)

    xml += self._KindPropertiesToXml()

    xml += Contact.CONTACT_SECTION_HEADER

    self._kind_properties = set(Contact.CONTACT_SECTION_PROPERTIES)

    xml += self._KindPropertiesToXml()

    xml += Contact.CONTACT_SECTION_FOOTER

    self._kind_properties.update(Contact.KIND_PROPERTIES)

    xml += self._LeftoverPropertiesToXml()

    xml += GdKind.FOOTER

    return xml