python-gdata 2.0.18+dfsg1-2 / usr / lib / python2.7 / dist-packages / gdata / sites / client.py

#!/usr/bin/python
#
# Copyright 2009 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
#
#      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.

"""SitesClient extends gdata.client.GDClient to streamline Sites API calls."""


__author__ = 'e.bidelman (Eric Bidelman)'

import atom.data
import gdata.client
import gdata.sites.data
import gdata.gauth


# Feed URI templates
CONTENT_FEED_TEMPLATE = '/feeds/content/%s/%s/'
REVISION_FEED_TEMPLATE = '/feeds/revision/%s/%s/'
ACTIVITY_FEED_TEMPLATE = '/feeds/activity/%s/%s/'
SITE_FEED_TEMPLATE = '/feeds/site/%s/'
ACL_FEED_TEMPLATE = '/feeds/acl/site/%s/%s/'


class SitesClient(gdata.client.GDClient):

  """Client extension for the Google Sites API service."""

  host = 'sites.google.com'  # default server for the API
  domain = 'site'  # default site domain name
  api_version = '1.1'  # default major version for the service.
  auth_service = 'jotspot'
  auth_scopes = gdata.gauth.AUTH_SCOPES['jotspot']
  ssl = True

  def __init__(self, site=None, domain=None, auth_token=None, **kwargs):
    """Constructs a new client for the Sites API.

    Args:
      site: string (optional) Name (webspace) of the Google Site
      domain: string (optional) Domain of the (Google Apps hosted) Site.
          If no domain is given, the Site is assumed to be a consumer Google
          Site, in which case the value 'site' is used.
      auth_token: (optional) gdata.gauth.ClientLoginToken, AuthSubToken, or
          OAuthToken which authorizes this client to edit the user's data.
      kwargs: The other parameters to pass to gdata.client.GDClient
          constructor.
    """
    gdata.client.GDClient.__init__(self, auth_token=auth_token, **kwargs)
    self.site = site
    if domain is not None:
      self.domain = domain

  def __make_kind_category(self, label):
    if label is None:
      return None
    return atom.data.Category(
        scheme=gdata.sites.data.SITES_KIND_SCHEME,
        term='%s#%s' % (gdata.sites.data.SITES_NAMESPACE, label), label=label)

  __MakeKindCategory = __make_kind_category

  def __upload(self, entry, media_source, auth_token=None, **kwargs):
    """Uploads an attachment file to the Sites API.

    Args:
      entry: gdata.sites.data.ContentEntry The Atom XML to include.
      media_source: gdata.data.MediaSource The file payload to be uploaded.
      auth_token: (optional) gdata.gauth.ClientLoginToken, AuthSubToken, or
          OAuthToken which authorizes this client to edit the user's data.
      kwargs: Other parameters to pass to gdata.client.post().

    Returns:
      The created entry.
    """
    uri = self.make_content_feed_uri()
    return self.post(entry, uri, media_source=media_source,
                     auth_token=auth_token, **kwargs)

  def _get_file_content(self, uri):
    """Fetches the file content from the specified URI.

    Args:
      uri: string The full URL to fetch the file contents from.

    Returns:
      The binary file content.

    Raises:
      gdata.client.RequestError: on error response from server.
    """
    server_response = self.request('GET', uri)
    if server_response.status != 200:
      raise  gdata.client.RequestError, {'status': server_response.status,
                                         'reason': server_response.reason,
                                         'body': server_response.read()}
    return server_response.read()

  _GetFileContent = _get_file_content

  def make_content_feed_uri(self):
    return CONTENT_FEED_TEMPLATE % (self.domain, self.site)

  MakeContentFeedUri = make_content_feed_uri

  def make_revision_feed_uri(self):
    return REVISION_FEED_TEMPLATE % (self.domain, self.site)

  MakeRevisionFeedUri = make_revision_feed_uri

  def make_activity_feed_uri(self):
    return ACTIVITY_FEED_TEMPLATE % (self.domain, self.site)

  MakeActivityFeedUri = make_activity_feed_uri

  def make_site_feed_uri(self, site_name=None):
    if site_name is not None:
      return (SITE_FEED_TEMPLATE % self.domain) + site_name
    else:
      return SITE_FEED_TEMPLATE % self.domain

  MakeSiteFeedUri = make_site_feed_uri

  def make_acl_feed_uri(self):
    return ACL_FEED_TEMPLATE % (self.domain, self.site)

  MakeAclFeedUri = make_acl_feed_uri

  def get_content_feed(self, uri=None, auth_token=None, **kwargs):
    """Retrieves the content feed containing the current state of site.

    Args:
      uri: string (optional) A full URI to query the Content feed with.
      auth_token: (optional) gdata.gauth.ClientLoginToken, AuthSubToken, or
          OAuthToken which authorizes this client to edit the user's data.
      kwargs: Other parameters to pass to self.get_feed().

    Returns:
      gdata.sites.data.ContentFeed
    """
    if uri is None:
      uri = self.make_content_feed_uri()
    return self.get_feed(uri, desired_class=gdata.sites.data.ContentFeed,
                         auth_token=auth_token, **kwargs)

  GetContentFeed = get_content_feed

  def get_revision_feed(self, entry_or_uri_or_id, auth_token=None, **kwargs):
    """Retrieves the revision feed containing the revision history for a node.

    Args:
      entry_or_uri_or_id: string or gdata.sites.data.ContentEntry A full URI,
          content entry node ID, or a content entry object of the entry to
          retrieve revision information for.
      auth_token: (optional) gdata.gauth.ClientLoginToken, AuthSubToken, or
          OAuthToken which authorizes this client to edit the user's data.
      kwargs: Other parameters to pass to self.get_feed().

    Returns:
      gdata.sites.data.RevisionFeed
    """
    uri = self.make_revision_feed_uri()
    if isinstance(entry_or_uri_or_id, gdata.sites.data.ContentEntry):
      uri = entry_or_uri_or_id.FindRevisionLink()
    elif entry_or_uri_or_id.find('/') == -1:
      uri += entry_or_uri_or_id
    else:
      uri = entry_or_uri_or_id
    return self.get_feed(uri, desired_class=gdata.sites.data.RevisionFeed,
                         auth_token=auth_token, **kwargs)

  GetRevisionFeed = get_revision_feed

  def get_activity_feed(self, uri=None, auth_token=None, **kwargs):
    """Retrieves the activity feed containing recent Site activity.

    Args:
      uri: string (optional) A full URI to query the Activity feed.
      auth_token: (optional) gdata.gauth.ClientLoginToken, AuthSubToken, or
          OAuthToken which authorizes this client to edit the user's data.
      kwargs: Other parameters to pass to self.get_feed().

    Returns:
      gdata.sites.data.ActivityFeed
    """
    if uri is None:
      uri = self.make_activity_feed_uri()
    return self.get_feed(uri, desired_class=gdata.sites.data.ActivityFeed,
                         auth_token=auth_token, **kwargs)

  GetActivityFeed = get_activity_feed

  def get_site_feed(self, uri=None, auth_token=None, **kwargs):
    """Retrieves the site feed containing a list of sites a user has access to.

    Args:
      uri: string (optional) A full URI to query the site feed.
      auth_token: (optional) gdata.gauth.ClientLoginToken, AuthSubToken, or
          OAuthToken which authorizes this client to edit the user's data.
      kwargs: Other parameters to pass to self.get_feed().

    Returns:
      gdata.sites.data.SiteFeed
    """
    if uri is None:
      uri = self.make_site_feed_uri()
    return self.get_feed(uri, desired_class=gdata.sites.data.SiteFeed,
                         auth_token=auth_token, **kwargs)

  GetSiteFeed = get_site_feed

  def get_acl_feed(self, uri=None, auth_token=None, **kwargs):
    """Retrieves the acl feed containing a site's sharing permissions.

    Args:
      uri: string (optional) A full URI to query the acl feed.
      auth_token: (optional) gdata.gauth.ClientLoginToken, AuthSubToken, or
          OAuthToken which authorizes this client to edit the user's data.
      kwargs: Other parameters to pass to self.get_feed().

    Returns:
      gdata.sites.data.AclFeed
    """
    if uri is None:
      uri = self.make_acl_feed_uri()
    return self.get_feed(uri, desired_class=gdata.sites.data.AclFeed,
                         auth_token=auth_token, **kwargs)

  GetAclFeed = get_acl_feed

  def create_site(self, title, description=None, source_site=None,
                  theme=None, uri=None, auth_token=None, **kwargs):
    """Creates a new Google Site.

    Note: This feature is only available to Google Apps domains.

    Args:
      title: string Title for the site.
      description: string (optional) A description/summary for the site.
      source_site: string (optional) The site feed URI of the site to copy.
          This parameter should only be specified when copying a site.
      theme: string (optional) The name of the theme to create the site with.
      uri: string (optional) A full site feed URI to override where the site
          is created/copied. By default, the site will be created under
          the currently set domain (e.g. self.domain).
      auth_token: (optional) gdata.gauth.ClientLoginToken, AuthSubToken, or
          OAuthToken which authorizes this client to edit the user's data.
      kwargs: Other parameters to pass to gdata.client.post().

    Returns:
      gdata.sites.data.SiteEntry of the created site.
    """
    new_entry = gdata.sites.data.SiteEntry(title=atom.data.Title(text=title))

    if description is not None:
      new_entry.summary = gdata.sites.data.Summary(text=description)

    # Add the source link if we're making a copy of a site.
    if source_site is not None:
      source_link = atom.data.Link(rel=gdata.sites.data.SITES_SOURCE_LINK_REL,
                                   type='application/atom+xml',
                                   href=source_site)
      new_entry.link.append(source_link)

    if theme is not None:
      new_entry.theme = gdata.sites.data.Theme(text=theme)

    if uri is None:
      uri = self.make_site_feed_uri()

    return self.post(new_entry, uri, auth_token=auth_token, **kwargs)

  CreateSite = create_site

  def create_page(self, kind, title, html='', page_name=None, parent=None,
                  auth_token=None, template=None, **kwargs):
    """Creates a new page (specified by kind) on a Google Site.

    Args:
      kind: string The type of page/item to create. For example, webpage,
          listpage, comment, announcementspage, filecabinet, etc. The full list
          of supported kinds can be found in gdata.sites.gdata.SUPPORT_KINDS.
      title: string Title for the page.
      html: string (optional) XHTML for the page's content body.
      page_name: string (optional) The URL page name to set. If not set, the
          title will be normalized and used as the page's URL path.
      parent: string or gdata.sites.data.ContentEntry (optional) The parent
          entry or parent link url to create the page under.
      auth_token: (optional) gdata.gauth.ClientLoginToken, AuthSubToken, or
          OAuthToken which authorizes this client to edit the user's data.
      template: string or gdata.sites.data.ContentEntry (optional) Create page
          using the given template.  Any content elements will be discarded as
          they are not valid when creating a page from a template.
      kwargs: Other parameters to pass to gdata.client.post().

    Returns:
      gdata.sites.data.ContentEntry of the created page.
    """
    content = gdata.sites.data.Content(text=html)
    if template is not None:
      content = None
    new_entry = gdata.sites.data.ContentEntry(
        title=atom.data.Title(text=title), kind=kind,
        content=content)

    if page_name is not None:
      new_entry.page_name = gdata.sites.data.PageName(text=page_name)

    # Add parent link to entry if it should be uploaded as a subpage.
    if isinstance(parent, gdata.sites.data.ContentEntry):
      parent_link = atom.data.Link(rel=gdata.sites.data.SITES_PARENT_LINK_REL,
                                   type='application/atom+xml',
                                   href=parent.GetSelfLink().href)
      new_entry.link.append(parent_link)
    elif parent is not None:
      parent_link = atom.data.Link(rel=gdata.sites.data.SITES_PARENT_LINK_REL,
                                   type='application/atom+xml',
                                   href=parent)
      new_entry.link.append(parent_link)

    # Add template link to entry if present.
    if isinstance(template, gdata.sites.data.ContentEntry):
      template_link = atom.data.Link(
          rel=gdata.sites.data.SITES_TEMPLATE_LINK_REL,
          type='application/atom+xml', href=template.GetSelfLink().href)
      new_entry.link.append(template_link)
    elif template is not None:
      template_link = atom.data.Link(
          rel=gdata.sites.data.SITES_TEMPLATE_LINK_REL,
          type='application/atom+xml', href=template)
      new_entry.link.append(template_link)

    return self.post(new_entry, self.make_content_feed_uri(),
                     auth_token=auth_token, **kwargs)

  CreatePage = create_page

  def create_webattachment(self, src, content_type, title, parent,
                           description=None, auth_token=None, **kwargs):
    """Creates a new webattachment within a filecabinet.

    Args:
      src: string The url of the web attachment.
      content_type: string The MIME type of the web attachment.
      title: string The title to name the web attachment.
      parent: string or gdata.sites.data.ContentEntry (optional) The
          parent entry or url of the filecabinet to create the attachment under.
      description: string (optional) A summary/description for the attachment.
      auth_token: (optional) gdata.gauth.ClientLoginToken, AuthSubToken, or
          OAuthToken which authorizes this client to edit the user's data.
      kwargs: Other parameters to pass to gdata.client.post().

    Returns:
      gdata.sites.data.ContentEntry of the created page.
    """
    new_entry = gdata.sites.data.ContentEntry(
        title=atom.data.Title(text=title), kind='webattachment',
        content=gdata.sites.data.Content(src=src, type=content_type))

    if isinstance(parent, gdata.sites.data.ContentEntry):
      link = atom.data.Link(rel=gdata.sites.data.SITES_PARENT_LINK_REL,
                            type='application/atom+xml',
                            href=parent.GetSelfLink().href)
    elif parent is not None:
      link = atom.data.Link(rel=gdata.sites.data.SITES_PARENT_LINK_REL,
                            type='application/atom+xml', href=parent)

    new_entry.link.append(link)

    # Add file decription if it was specified
    if description is not None:
      new_entry.summary = gdata.sites.data.Summary(type='text',
                                                   text=description)

    return self.post(new_entry, self.make_content_feed_uri(),
                     auth_token=auth_token, **kwargs)

  CreateWebAttachment = create_webattachment

  def upload_attachment(self, file_handle, parent, content_type=None,
                        title=None, description=None, folder_name=None,
                        auth_token=None, **kwargs):
    """Uploads an attachment to a parent page.

    Args:
      file_handle: MediaSource or string A gdata.data.MediaSource object
          containing the file to be uploaded or the full path name to the
          file on disk.
      parent: gdata.sites.data.ContentEntry or string The parent page to
          upload the file to or the full URI of the entry's self link.
      content_type: string (optional) The MIME type of the file
          (e.g 'application/pdf'). This should be provided if file is not a
          MediaSource object.
      title: string (optional) The title to name the attachment. If not
          included, the filepath or media source's filename is used.
      description: string (optional) A summary/description for the attachment.
      folder_name: string (optional) The name of an existing folder to upload
          the attachment to. This only applies when the parent parameter points
          to a filecabinet entry.
      auth_token: (optional) gdata.gauth.ClientLoginToken, AuthSubToken, or
          OAuthToken which authorizes this client to edit the user's data.
      kwargs: Other parameters to pass to self.__upload().

    Returns:
      A gdata.sites.data.ContentEntry containing information about the created
      attachment.
    """
    if isinstance(parent, gdata.sites.data.ContentEntry):
      link = atom.data.Link(rel=gdata.sites.data.SITES_PARENT_LINK_REL,
                            type='application/atom+xml',
                            href=parent.GetSelfLink().href)
    else:
      link = atom.data.Link(rel=gdata.sites.data.SITES_PARENT_LINK_REL,
                            type='application/atom+xml',
                            href=parent)

    if not isinstance(file_handle, gdata.data.MediaSource):
      ms = gdata.data.MediaSource(file_path=file_handle,
                                  content_type=content_type)
    else:
      ms = file_handle

    # If no title specified, use the file name
    if title is None:
      title = ms.file_name

    new_entry = gdata.sites.data.ContentEntry(kind='attachment')
    new_entry.title = atom.data.Title(text=title)
    new_entry.link.append(link)

    # Add file decription if it was specified
    if description is not None:
      new_entry.summary = gdata.sites.data.Summary(type='text',
                                                   text=description)

    # Upload the attachment to a filecabinet folder?
    if parent.Kind() == 'filecabinet' and folder_name is not None:
      folder_category = atom.data.Category(
          scheme=gdata.sites.data.FOLDER_KIND_TERM, term=folder_name)
      new_entry.category.append(folder_category)

    return self.__upload(new_entry, ms, auth_token=auth_token, **kwargs)

  UploadAttachment = upload_attachment

  def download_attachment(self, uri_or_entry, file_path):
    """Downloads an attachment file to disk.

    Args:
      uri_or_entry: string The full URL to download the file from.
      file_path: string The full path to save the file to.

    Raises:
      gdata.client.RequestError: on error response from server.
    """
    uri = uri_or_entry
    if isinstance(uri_or_entry, gdata.sites.data.ContentEntry):
      uri = uri_or_entry.content.src

    f = open(file_path, 'wb')
    try:
      f.write(self._get_file_content(uri))
    except gdata.client.RequestError, e:
      f.close()
      raise e
    f.flush()
    f.close()

  DownloadAttachment = download_attachment