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