/gdata/projecthosting/client.py

  1#!/usr/bin/env python
  2#
  3# Copyright 2009 Google Inc.
  4#
  5# Licensed under the Apache License, Version 2.0 (the "License");
  6# you may not use this file except in compliance with the License.
  7# You may obtain a copy of the License at
  8#
  9#      http://www.apache.org/licenses/LICENSE-2.0
 10#
 11# Unless required by applicable law or agreed to in writing, software
 12# distributed under the License is distributed on an "AS IS" BASIS,
 13# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 14# See the License for the specific language governing permissions and
 15# limitations under the License.
 16
 17import atom.data
 18import gdata.client
 19import gdata.gauth
 20import gdata.projecthosting.data
 21
 22
 23class ProjectHostingClient(gdata.client.GDClient):
 24  """Client to interact with the Project Hosting GData API."""
 25  api_version = '1.0'
 26  auth_service = 'code'
 27  auth_scopes = gdata.gauth.AUTH_SCOPES['code']
 28  host = 'code.google.com'
 29
 30  def get_issues(self, project_name,
 31                 desired_class=gdata.projecthosting.data.IssuesFeed, **kwargs):
 32    """Get a feed of issues for a particular project.
 33
 34    Args:
 35      project_name str The name of the project.
 36      query Query Set returned issues parameters.
 37
 38    Returns:
 39      data.IssuesFeed
 40    """
 41    return self.get_feed(gdata.projecthosting.data.ISSUES_FULL_FEED %
 42                         project_name, desired_class=desired_class, **kwargs)
 43
 44  def add_issue(self, project_name, title, content, author,
 45                status=None, owner=None, labels=None, ccs=None, **kwargs):
 46    """Create a new issue for the project.
 47
 48    Args:
 49      project_name str The name of the project.
 50      title str The title of the new issue.
 51      content str The summary of the new issue.
 52      author str The authenticated user's username.
 53      status str The status of the new issue, Accepted, etc.
 54      owner str The username of new issue's owner.
 55      labels [str] Labels to associate with the new issue.
 56      ccs [str] usernames to Cc on the new issue.
 57    Returns:
 58      data.IssueEntry
 59    """
 60    new_entry = gdata.projecthosting.data.IssueEntry(
 61        title=atom.data.Title(text=title),
 62        content=atom.data.Content(text=content),
 63        author=[atom.data.Author(name=atom.data.Name(text=author))])
 64
 65    if status:
 66      new_entry.status = gdata.projecthosting.data.Status(text=status)
 67
 68    if owner:
 69      owner = [gdata.projecthosting.data.Owner(
 70          username=gdata.projecthosting.data.Username(text=owner))]
 71
 72    if labels:
 73      new_entry.label = [gdata.projecthosting.data.Label(text=label)
 74                         for label in labels]
 75    if ccs:
 76      new_entry.cc = [
 77          gdata.projecthosting.data.Cc(
 78              username=gdata.projecthosting.data.Username(text=cc))
 79          for cc in ccs]
 80
 81    return self.post(
 82        new_entry,
 83        gdata.projecthosting.data.ISSUES_FULL_FEED % project_name,
 84        **kwargs)
 85
 86  def update_issue(self, project_name, issue_id, author, comment=None,
 87                   summary=None, status=None, owner=None, labels=None, ccs=None,
 88                   **kwargs):
 89    """Update or comment on one issue for the project.
 90
 91    Args:
 92      project_name str The name of the issue's project.
 93      issue_id str The issue number needing updated.
 94      author str The authenticated user's username.
 95      comment str A comment to append to the issue
 96      summary str Rewrite the summary of the issue.
 97      status str A new status for the issue.
 98      owner str The username of the new owner.
 99      labels [str] Labels to set on the issue (prepend issue with - to remove a
100          label).
101      ccs [str] Ccs to set on th enew issue (prepend cc with - to remove a cc).
102
103    Returns:
104      data.CommentEntry
105    """
106    updates = gdata.projecthosting.data.Updates()
107
108    if summary:
109      updates.summary = gdata.projecthosting.data.Summary(text=summary)
110
111    if status:
112      updates.status = gdata.projecthosting.data.Status(text=status)
113
114    if owner:
115      updates.ownerUpdate = gdata.projecthosting.data.OwnerUpdate(text=owner)
116
117    if labels:
118      updates.label = [gdata.projecthosting.data.Label(text=label)
119                       for label in labels]
120    if ccs:
121      updates.ccUpdate = [gdata.projecthosting.data.CcUpdate(text=cc)
122                          for cc in ccs]
123
124    update_entry = gdata.projecthosting.data.CommentEntry(
125        content=atom.data.Content(text=comment),
126        author=[atom.data.Author(name=atom.data.Name(text=author))],
127        updates=updates)
128
129    return self.post(
130        update_entry,
131        gdata.projecthosting.data.COMMENTS_FULL_FEED % (project_name, issue_id),
132        **kwargs)
133
134  def get_comments(self, project_name, issue_id,
135                   desired_class=gdata.projecthosting.data.CommentsFeed,
136                   **kwargs):
137    """Get a feed of all updates to an issue.
138
139    Args:
140      project_name str The name of the issue's project.
141      issue_id str The issue number needing updated.
142
143    Returns:
144      data.CommentsFeed
145    """
146    return self.get_feed(
147        gdata.projecthosting.data.COMMENTS_FULL_FEED % (project_name, issue_id),
148        desired_class=desired_class, **kwargs)
149
150  def update(self, entry, auth_token=None, force=False, **kwargs):
151    """Unsupported GData update method.
152
153    Use update_*() instead.
154    """
155    raise NotImplementedError(
156        'GData Update operation unsupported, try update_*')
157
158  def delete(self, entry_or_uri, auth_token=None, force=False, **kwargs):
159    """Unsupported GData delete method.
160
161    Use update_issue(status='Closed') instead.
162    """
163    raise NotImplementedError(
164        'GData Delete API unsupported, try closing the issue instead.')
165
166
167class Query(gdata.client.Query):
168
169  def __init__(self, issue_id=None, label=None, canned_query=None, owner=None,
170               status=None, **kwargs):
171    """Constructs a Google Data Query to filter feed contents serverside.
172    Args:
173      issue_id: int or str The issue to return based on the issue id.
174      label: str A label returned issues must have.
175      canned_query: str Return issues based on a canned query identifier
176      owner: str Return issues based on the owner of the issue. For Gmail users,
177          this will be the part of the email preceding the '@' sign.
178      status: str Return issues based on the status of the issue.
179    """
180    super(Query, self).__init__(**kwargs)
181    self.label = label
182    self.issue_id = issue_id
183    self.canned_query = canned_query
184    self.owner = owner
185    self.status = status
186
187  def modify_request(self, http_request):
188    if self.issue_id:
189      gdata.client._add_query_param('id', self.issue_id, http_request)
190    if self.label:
191      gdata.client._add_query_param('label', self.label, http_request)
192    if self.canned_query:
193      gdata.client._add_query_param('can', self.canned_query, http_request)
194    if self.owner:
195      gdata.client._add_query_param('owner', self.owner, http_request)
196    if self.status:
197      gdata.client._add_query_param('status', self.status, http_request)
198    super(Query, self).modify_request(http_request)
199
200  ModifyRequest = modify_request