Source code for

# Copyright 2011 Google Inc. All Rights Reserved.
# 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
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# See the License for the specific language governing permissions and
# limitations under the License.

"""Data model classes for representing elements of the Documents List API."""

__author__ = ' (Vic Fryzel)'

import re
import atom.core

DOCUMENT_LABEL = 'document'
SPREADSHEET_LABEL = 'spreadsheet'
DRAWING_LABEL = 'drawing'
PRESENTATION_LABEL = 'presentation'
FILE_LABEL = 'file'
PDF_LABEL = 'pdf'
FORM_LABEL = 'form'
ITEM_LABEL = 'item'
STARRED_LABEL = 'starred'
VIEWED_LABEL = 'viewed'
HIDDEN_LABEL = 'hidden'
TRASHED_LABEL = 'trashed'
MINE_LABEL = 'mine'
PRIVATE_LABEL = 'private'
SHAREDWITHDOMAIN_LABEL = 'shared-with-domain'
RESTRICTEDDOWNLOAD_LABEL = 'restricted-download'

[docs]class ResourceId(atom.core.XmlElement): """The DocList gd:resourceId element.""" _qname = % 'resourceId'
[docs]class LastModifiedBy( """The DocList gd:lastModifiedBy element.""" _qname = % 'lastModifiedBy'
[docs]class LastViewed( """The DocList gd:lastViewed element.""" _qname = % 'lastViewed'
[docs]class WritersCanInvite(atom.core.XmlElement): """The DocList docs:writersCanInvite element.""" _qname = DOCUMENTS_TEMPLATE % 'writersCanInvite' value = 'value'
[docs]class Deleted(atom.core.XmlElement): """The DocList gd:deleted element.""" _qname = % 'deleted'
[docs]class QuotaBytesUsed(atom.core.XmlElement): """The DocList gd:quotaBytesUsed element.""" _qname = % 'quotaBytesUsed'
[docs]class Publish(atom.core.XmlElement): """The DocList docs:publish element.""" _qname = DOCUMENTS_TEMPLATE % 'publish' value = 'value'
[docs]class PublishAuto(atom.core.XmlElement): """The DocList docs:publishAuto element.""" _qname = DOCUMENTS_TEMPLATE % 'publishAuto' value = 'value'
[docs]class PublishOutsideDomain(atom.core.XmlElement): """The DocList docs:publishOutsideDomain element.""" _qname = DOCUMENTS_TEMPLATE % 'publishOutsideDomain' value = 'value'
[docs]class Filename(atom.core.XmlElement): """The DocList docs:filename element.""" _qname = DOCUMENTS_TEMPLATE % 'filename'
[docs]class SuggestedFilename(atom.core.XmlElement): """The DocList docs:suggestedFilename element.""" _qname = DOCUMENTS_TEMPLATE % 'suggestedFilename'
[docs]class CategoryFinder(object): """Mixin to provide category finding functionality. Analogous to, but a simpler API, specialized for DocList categories. """
[docs] def add_category(self, scheme, term, label): """Add a category for a scheme, term and label. Args: scheme: The scheme for the category. term: The term for the category. label: The label for the category Returns: The newly created """ category =, term=term, label=label) self.category.append(category) return category
AddCategory = add_category
[docs] def get_categories(self, scheme): """Fetch the category elements for a scheme. Args: scheme: The scheme to fetch the elements for. Returns: Generator of elements. """ for category in self.category: if category.scheme == scheme: yield category
GetCategories = get_categories
[docs] def remove_categories(self, scheme): """Remove category elements for a scheme. Args: scheme: The scheme of category to remove. """ for category in list(self.get_categories(scheme)): self.category.remove(category)
RemoveCategories = remove_categories
[docs] def get_first_category(self, scheme): """Fetch the first category element for a scheme. Args: scheme: The scheme of category to return. Returns: if found or None. """ try: return self.get_categories(scheme).next() except StopIteration, e: # The entry doesn't have the category return None
GetFirstCategory = get_first_category
[docs] def set_resource_type(self, label): """Set the document type for an entry, by building the appropriate Args: label: str The value for the category entry. If None is passed the category is removed and not set. Returns: An or None if label is None. """ self.remove_categories(DATA_KIND_SCHEME) if label is not None: return self.add_category(scheme=DATA_KIND_SCHEME, term='%s#%s' % (DOCUMENTS_NS, label), label=label) else: return None
SetResourceType = set_resource_type
[docs] def get_resource_type(self): """Extracts the type of document this Resource is. This method returns the type of document the Resource represents. Possible values are document, presentation, drawing, spreadsheet, file, folder, form, item, or pdf. 'folder' is a possible return value of this method because, for legacy support, we have not yet renamed the folder keyword to collection in the API itself. Returns: String representing the type of document. """ category = self.get_first_category(DATA_KIND_SCHEME) if category is not None: return category.label else: return None
GetResourceType = get_resource_type
[docs] def get_labels(self): """Extracts the labels for this Resource. This method returns the labels as a set, for example: 'hidden', 'starred', 'viewed'. Returns: Set of string labels. """ return set(category.label for category in self.get_categories(LABELS_SCHEME))
GetLabels = get_labels
[docs] def has_label(self, label): """Whether this Resource has a label. Args: label: The str label to test for Returns: Boolean value indicating presence of label. """ return label in self.get_labels()
HasLabel = has_label
[docs] def add_label(self, label): """Add a label, if it is not present. Args: label: The str label to set """ if not self.has_label(label): self.add_category(scheme=LABELS_SCHEME, term='%s#%s' % (LABELS_NS, label), label=label)
AddLabel = add_label
[docs] def remove_label(self, label): """Remove a label, if it is present. Args: label: The str label to remove """ for category in self.get_categories(LABELS_SCHEME): if category.label == label: self.category.remove(category)
RemoveLabel = remove_label
[docs] def is_starred(self): """Whether this Resource is starred. Returns: Boolean value indicating that the resource is starred. """ return self.has_label(STARRED_LABEL)
IsStarred = is_starred
[docs] def is_hidden(self): """Whether this Resource is hidden. Returns: Boolean value indicating that the resource is hidden. """ return self.has_label(HIDDEN_LABEL)
IsHidden = is_hidden
[docs] def is_viewed(self): """Whether this Resource is viewed. Returns: Boolean value indicating that the resource is viewed. """ return self.has_label(VIEWED_LABEL)
IsViewed = is_viewed
[docs] def is_trashed(self): """Whether this resource is trashed. Returns: Boolean value indicating that the resource is trashed. """ return self.has_label(TRASHED_LABEL)
IsTrashed = is_trashed
[docs] def is_mine(self): """Whether this resource is marked as mine. Returns: Boolean value indicating that the resource is marked as mine. """ return self.has_label(MINE_LABEL)
IsMine = is_mine
[docs] def is_private(self): """Whether this resource is private. Returns: Boolean value indicating that the resource is private. """ return self.has_label(PRIVATE_LABEL)
IsPrivate = is_private
[docs] def is_shared_with_domain(self): """Whether this resource is shared with the domain. Returns: Boolean value indicating that the resource is shared with the domain. """ return self.has_label(SHAREDWITHDOMAIN_LABEL)
IsSharedWithDomain = is_shared_with_domain
[docs] def is_restricted_download(self): """Whether this resource is restricted download. Returns: Boolean value indicating whether the resource is restricted download. """ return self.has_label(RESTRICTEDDOWNLOAD_LABEL)
IsRestrictedDownload = is_restricted_download
[docs]class AclEntry(, """Resource ACL entry.""" @staticmethod def get_instance(role=None, scope_type=None, scope_value=None, key=False): entry = AclEntry() if role is not None: if isinstance(role, basestring): role = if key: entry.with_key ='', role=role) else: entry.role = role if scope_type is not None: if scope_value is not None: entry.scope =, value=scope_value) else: entry.scope = return entry GetInstance = get_instance
[docs]class AclFeed( """Resource ACL feed.""" entry = [AclEntry]
[docs]class Resource(, CategoryFinder): """DocList version of an Atom Entry.""" last_viewed = LastViewed last_modified_by = LastModifiedBy resource_id = ResourceId deleted = Deleted writers_can_invite = WritersCanInvite quota_bytes_used = QuotaBytesUsed feed_link = [] filename = Filename suggested_filename = SuggestedFilename # Only populated if you request /feeds/default/private/expandAcl acl_feed = AclFeed def __init__(self, type=None, title=None, **kwargs): super(Resource, self).__init__(**kwargs) if isinstance(type, basestring): self.set_resource_type(type) if title is not None: if isinstance(title, basestring): self.title = else: self.title = title GetAclFeedLink = get_acl_feed_link GetRevisionsFeedLink = get_revisions_feed_link GetResumableCreateMediaLink = get_resumable_create_media_link GetResumableEditMediaLink = get_resumable_edit_media_link
[docs] def in_collections(self): """Returns the parents link(s) (collections) of this entry.""" links = [] for link in if link.rel == PARENT_LINK_REL and link.href: links.append(link) return links
InCollections = in_collections
[docs]class ResourceFeed( """Main feed containing a list of resources.""" entry = [Resource]
[docs]class Revision( """Resource Revision entry.""" publish = Publish publish_auto = PublishAuto publish_outside_domain = PublishOutsideDomain FindPublishLink = find_publish_link GetPublishLink = get_publish_link
[docs]class RevisionFeed( """A DocList Revision feed.""" entry = [Revision]
[docs]class ArchiveResourceId(atom.core.XmlElement): """The DocList docs:removed element.""" _qname = DOCUMENTS_TEMPLATE % 'archiveResourceId'
[docs]class ArchiveFailure(atom.core.XmlElement): """The DocList docs:archiveFailure element.""" _qname = DOCUMENTS_TEMPLATE % 'archiveFailure'
[docs]class ArchiveComplete(atom.core.XmlElement): """The DocList docs:archiveComplete element.""" _qname = DOCUMENTS_TEMPLATE % 'archiveComplete'
[docs]class ArchiveTotal(atom.core.XmlElement): """The DocList docs:archiveTotal element.""" _qname = DOCUMENTS_TEMPLATE % 'archiveTotal'
[docs]class ArchiveTotalComplete(atom.core.XmlElement): """The DocList docs:archiveTotalComplete element.""" _qname = DOCUMENTS_TEMPLATE % 'archiveTotalComplete'
[docs]class ArchiveTotalFailure(atom.core.XmlElement): """The DocList docs:archiveTotalFailure element.""" _qname = DOCUMENTS_TEMPLATE % 'archiveTotalFailure'
[docs]class ArchiveConversion(atom.core.XmlElement): """The DocList docs:removed element.""" _qname = DOCUMENTS_TEMPLATE % 'archiveConversion' source = 'source' target = 'target'
[docs]class ArchiveNotify(atom.core.XmlElement): """The DocList docs:archiveNotify element.""" _qname = DOCUMENTS_TEMPLATE % 'archiveNotify'
[docs]class ArchiveStatus(atom.core.XmlElement): """The DocList docs:archiveStatus element.""" _qname = DOCUMENTS_TEMPLATE % 'archiveStatus'
[docs]class ArchiveNotifyStatus(atom.core.XmlElement): """The DocList docs:archiveNotifyStatus element.""" _qname = DOCUMENTS_TEMPLATE % 'archiveNotifyStatus'
[docs]class Archive( """Archive entry.""" archive_resource_ids = [ArchiveResourceId] status = ArchiveStatus date_completed = ArchiveComplete num_resources = ArchiveTotal num_complete_resources = ArchiveTotalComplete num_failed_resources = ArchiveTotalFailure failed_resource_ids = [ArchiveFailure] notify_status = ArchiveNotifyStatus conversions = [ArchiveConversion] notification_email = ArchiveNotify size = QuotaBytesUsed @staticmethod def from_resource_list(resources): resource_ids = [] for resource in resources: id = ArchiveResourceId(text=resource.resource_id.text) resource_ids.append(id) return Archive(archive_resource_ids=resource_ids) FromResourceList = from_resource_list
[docs]class Removed(atom.core.XmlElement): """The DocList docs:removed element.""" _qname = DOCUMENTS_TEMPLATE % 'removed'
[docs]class Changestamp(atom.core.XmlElement): """The DocList docs:changestamp element.""" _qname = DOCUMENTS_TEMPLATE % 'changestamp' value = 'value'
[docs]class Change(Resource): """Change feed entry.""" changestamp = Changestamp removed = Removed
[docs]class ChangeFeed( """DocList Changes feed.""" entry = [Change]
[docs]class QuotaBytesTotal(atom.core.XmlElement): """The DocList gd:quotaBytesTotal element.""" _qname = % 'quotaBytesTotal'
[docs]class QuotaBytesUsedInTrash(atom.core.XmlElement): """The DocList docs:quotaBytesUsedInTrash element.""" _qname = DOCUMENTS_TEMPLATE % 'quotaBytesUsedInTrash'
[docs]class ImportFormat(atom.core.XmlElement): """The DocList docs:importFormat element.""" _qname = DOCUMENTS_TEMPLATE % 'importFormat' source = 'source' target = 'target'
[docs]class ExportFormat(atom.core.XmlElement): """The DocList docs:exportFormat element.""" _qname = DOCUMENTS_TEMPLATE % 'exportFormat' source = 'source' target = 'target'
[docs]class FeatureName(atom.core.XmlElement): """The DocList docs:featureName element.""" _qname = DOCUMENTS_TEMPLATE % 'featureName'
[docs]class FeatureRate(atom.core.XmlElement): """The DocList docs:featureRate element.""" _qname = DOCUMENTS_TEMPLATE % 'featureRate'
[docs]class Feature(atom.core.XmlElement): """The DocList docs:feature element.""" _qname = DOCUMENTS_TEMPLATE % 'feature' name = FeatureName rate = FeatureRate
[docs]class MaxUploadSize(atom.core.XmlElement): """The DocList docs:maxUploadSize element.""" _qname = DOCUMENTS_TEMPLATE % 'maxUploadSize' kind = 'kind'
[docs]class AdditionalRoleSet(atom.core.XmlElement): """The DocList docs:additionalRoleSet element.""" _qname = DOCUMENTS_TEMPLATE % 'additionalRoleSet' primaryRole = 'primaryRole' additional_role = []
[docs]class AdditionalRoleInfo(atom.core.XmlElement): """The DocList docs:additionalRoleInfo element.""" _qname = DOCUMENTS_TEMPLATE % 'additionalRoleInfo' kind = 'kind' additional_role_set = [AdditionalRoleSet]
[docs]class Metadata( """Metadata entry for a user.""" quota_bytes_total = QuotaBytesTotal quota_bytes_used = QuotaBytesUsed quota_bytes_used_in_trash = QuotaBytesUsedInTrash import_formats = [ImportFormat] export_formats = [ExportFormat] features = [Feature] max_upload_sizes = [MaxUploadSize] additional_role_info = [AdditionalRoleInfo]