/gdata/media/__init__.py

  1# -*-*- encoding: utf-8 -*-*-
  2#
  3# This is gdata.photos.media, implementing parts of the MediaRSS spec in gdata structures
  4#
  5# $Id: __init__.py 81 2007-10-03 14:41:42Z havard.gulldahl $
  6#
  7# Copyright 2007 H?vard Gulldahl 
  8# Portions copyright 2007 Google Inc.
  9#
 10# Licensed under the Apache License, Version 2.0 (the "License");
 11# you may not use this file except in compliance with the License.
 12# You may obtain a copy of the License at
 13#
 14#      http://www.apache.org/licenses/LICENSE-2.0
 15#
 16# Unless required by applicable law or agreed to in writing, software
 17# distributed under the License is distributed on an "AS IS" BASIS,
 18# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 19# See the License for the specific language governing permissions and
 20# limitations under the License.
 21
 22
 23"""Essential attributes of photos in Google Photos/Picasa Web Albums are 
 24expressed using elements from the `media' namespace, defined in the 
 25MediaRSS specification[1].
 26
 27Due to copyright issues, the elements herein are documented sparingly, please 
 28consult with the Google Photos API Reference Guide[2], alternatively the 
 29official MediaRSS specification[1] for details. 
 30(If there is a version conflict between the two sources, stick to the 
 31Google Photos API).
 32
 33[1]: http://search.yahoo.com/mrss (version 1.1.1)
 34[2]: http://code.google.com/apis/picasaweb/reference.html#media_reference
 35
 36Keep in mind that Google Photos only uses a subset of the MediaRSS elements 
 37(and some of the attributes are trimmed down, too): 
 38
 39media:content
 40media:credit
 41media:description
 42media:group
 43media:keywords
 44media:thumbnail
 45media:title
 46"""
 47
 48__author__ = u'havard@gulldahl.no'# (H?vard Gulldahl)' #BUG: api chokes on non-ascii chars in __author__
 49__license__ = 'Apache License v2'
 50
 51
 52import atom
 53import gdata
 54
 55MEDIA_NAMESPACE = 'http://search.yahoo.com/mrss/'
 56YOUTUBE_NAMESPACE = 'http://gdata.youtube.com/schemas/2007'
 57
 58
 59class MediaBaseElement(atom.AtomBase):
 60  """Base class for elements in the MEDIA_NAMESPACE. 
 61  To add new elements, you only need to add the element tag name to self._tag
 62  """
 63  
 64  _tag = ''
 65  _namespace = MEDIA_NAMESPACE
 66  _children = atom.AtomBase._children.copy()
 67  _attributes = atom.AtomBase._attributes.copy()
 68
 69  def __init__(self, name=None, extension_elements=None,
 70      extension_attributes=None, text=None):
 71    self.name = name
 72    self.text = text
 73    self.extension_elements = extension_elements or []
 74    self.extension_attributes = extension_attributes or {}
 75
 76
 77class Content(MediaBaseElement):
 78  """(attribute container) This element describes the original content,
 79    e.g. an image or a video. There may be multiple Content elements
 80    in a media:Group.
 81
 82    For example, a video may have a
 83    <media:content medium="image"> element that specifies a JPEG
 84    representation of the video, and a <media:content medium="video">
 85    element that specifies the URL of the video itself.
 86  
 87  Attributes:
 88    url: non-ambigous reference to online object
 89    width: width of the object frame, in pixels
 90    height: width of the object frame, in pixels
 91    medium: one of `image' or `video', allowing the api user to quickly
 92            determine the object's type
 93    type: Internet media Type[1] (a.k.a. mime type) of the object -- a more
 94          verbose way of determining the media type. To set the type member
 95          in the contructor, use the content_type parameter.
 96    (optional) fileSize: the size of the object, in bytes
 97  
 98  [1]: http://en.wikipedia.org/wiki/Internet_media_type
 99  """
100  
101  _tag = 'content'
102  _attributes = atom.AtomBase._attributes.copy()
103  _attributes['url'] = 'url'
104  _attributes['width'] = 'width'
105  _attributes['height'] = 'height'
106  _attributes['medium'] = 'medium'
107  _attributes['type'] = 'type'
108  _attributes['fileSize'] = 'fileSize'
109
110  def __init__(self, url=None, width=None, height=None,
111      medium=None, content_type=None, fileSize=None, format=None,
112      extension_elements=None, extension_attributes=None, text=None):
113    MediaBaseElement.__init__(self, extension_elements=extension_elements,
114                              extension_attributes=extension_attributes,
115                              text=text)
116    self.url = url
117    self.width = width
118    self.height = height
119    self.medium = medium
120    self.type = content_type
121    self.fileSize = fileSize
122
123
124def ContentFromString(xml_string):
125  return atom.CreateClassFromXMLString(Content, xml_string)
126
127
128class Credit(MediaBaseElement):
129  """(string) Contains the nickname of the user who created the content,
130  e.g. `Liz Bennet'.
131  
132  This is a user-specified value that should be used when referring to
133  the user by name.
134
135  Note that none of the attributes from the MediaRSS spec are supported.
136  """
137  
138  _tag = 'credit'
139
140
141def CreditFromString(xml_string):
142  return atom.CreateClassFromXMLString(Credit, xml_string)
143
144
145class Description(MediaBaseElement):
146  """(string) A description of the media object.
147  Either plain unicode text, or entity-encoded html (look at the `type'
148  attribute).
149
150  E.g `A set of photographs I took while vacationing in Italy.'
151  
152  For `api' projections, the description is in plain text;
153  for `base' projections, the description is in HTML.
154  
155  Attributes:
156    type: either `text' or `html'. To set the type member in the contructor,
157          use the description_type parameter.
158  """
159  
160  _tag = 'description'
161  _attributes = atom.AtomBase._attributes.copy()
162  _attributes['type'] = 'type'
163  def __init__(self, description_type=None, 
164      extension_elements=None, extension_attributes=None, text=None):
165    MediaBaseElement.__init__(self, extension_elements=extension_elements,
166                              extension_attributes=extension_attributes,
167                              text=text)
168    
169    self.type = description_type
170
171
172def DescriptionFromString(xml_string):
173  return atom.CreateClassFromXMLString(Description, xml_string)
174
175
176class Keywords(MediaBaseElement):
177  """(string) Lists the tags associated with the entry,
178  e.g `italy, vacation, sunset'.
179  
180  Contains a comma-separated list of tags that have been added to the photo, or
181  all tags that have been added to photos in the album.
182  """
183  
184  _tag = 'keywords'
185
186
187def KeywordsFromString(xml_string):
188  return atom.CreateClassFromXMLString(Keywords, xml_string)
189
190
191class Thumbnail(MediaBaseElement):
192  """(attributes) Contains the URL of a thumbnail of a photo or album cover.
193  
194  There can be multiple <media:thumbnail> elements for a given <media:group>; 
195  for example, a given item may have multiple thumbnails at different sizes. 
196  Photos generally have two thumbnails at different sizes; 
197  albums generally have one cropped thumbnail.  
198    
199  If the thumbsize parameter is set to the initial query, this element points 
200  to thumbnails of the requested sizes; otherwise the thumbnails are the 
201  default thumbnail size. 
202  
203  This element must not be confused with the <gphoto:thumbnail> element.
204  
205  Attributes:
206  url:  The URL of the thumbnail image.
207  height:  The height of the thumbnail image, in pixels.
208  width:  The width of the thumbnail image, in pixels.
209  """
210  
211  _tag = 'thumbnail'
212  _attributes = atom.AtomBase._attributes.copy()
213  _attributes['url'] = 'url'
214  _attributes['width'] = 'width'
215  _attributes['height'] = 'height'
216  def __init__(self, url=None, width=None, height=None,
217      extension_attributes=None, text=None, extension_elements=None):
218    MediaBaseElement.__init__(self, extension_elements=extension_elements,
219                              extension_attributes=extension_attributes,
220                              text=text)
221    self.url = url
222    self.width = width
223    self.height = height
224
225
226def ThumbnailFromString(xml_string):
227  return atom.CreateClassFromXMLString(Thumbnail, xml_string)
228
229
230class Title(MediaBaseElement):
231  """(string) Contains the title of the entry's media content, in plain text.
232  
233  Attributes:
234    type: Always set to plain. To set the type member in the constructor, use
235          the title_type parameter.
236  """
237  
238  _tag = 'title'
239  _attributes = atom.AtomBase._attributes.copy()
240  _attributes['type'] = 'type'
241  def __init__(self, title_type=None, 
242      extension_attributes=None, text=None, extension_elements=None):
243    MediaBaseElement.__init__(self, extension_elements=extension_elements,
244                              extension_attributes=extension_attributes,
245                              text=text)
246    self.type = title_type
247
248
249def TitleFromString(xml_string):
250  return atom.CreateClassFromXMLString(Title, xml_string)
251
252
253class Player(MediaBaseElement):
254  """(string) Contains the embeddable player URL for the entry's media content 
255  if the media is a video.
256  
257  Attributes:
258  url: Always set to plain
259  """
260  
261  _tag = 'player'
262  _attributes = atom.AtomBase._attributes.copy()
263  _attributes['url'] = 'url'
264  
265  def __init__(self, player_url=None, 
266      extension_attributes=None, extension_elements=None):
267    MediaBaseElement.__init__(self, extension_elements=extension_elements,
268                              extension_attributes=extension_attributes)
269    self.url= player_url
270
271
272class Private(atom.AtomBase):
273  """The YouTube Private element"""
274  _tag = 'private'
275  _namespace = YOUTUBE_NAMESPACE
276
277
278class Duration(atom.AtomBase):
279  """The YouTube Duration element"""
280  _tag = 'duration'
281  _namespace = YOUTUBE_NAMESPACE
282  _attributes = atom.AtomBase._attributes.copy()
283  _attributes['seconds'] = 'seconds'
284
285
286class Category(MediaBaseElement):
287  """The mediagroup:category element"""
288
289  _tag = 'category'
290  _attributes = atom.AtomBase._attributes.copy()
291  _attributes['term'] = 'term'
292  _attributes['scheme'] = 'scheme'
293  _attributes['label'] = 'label'
294
295  def __init__(self, term=None, scheme=None, label=None, text=None, 
296               extension_elements=None, extension_attributes=None):
297    """Constructor for Category
298
299    Args:
300      term: str
301      scheme: str
302      label: str
303      text: str The text data in the this element
304      extension_elements: list A  list of ExtensionElement instances
305      extension_attributes: dict A dictionary of attribute value string pairs
306    """
307
308    self.term = term
309    self.scheme = scheme
310    self.label = label
311    self.text = text
312    self.extension_elements = extension_elements or []
313    self.extension_attributes = extension_attributes or {}
314
315
316class Group(MediaBaseElement):
317  """Container element for all media elements.
318  The <media:group> element can appear as a child of an album, photo or 
319  video entry."""
320
321  _tag = 'group'
322  _children = atom.AtomBase._children.copy()
323  _children['{%s}content' % MEDIA_NAMESPACE] = ('content', [Content,]) 
324  _children['{%s}credit' % MEDIA_NAMESPACE] = ('credit', Credit) 
325  _children['{%s}description' % MEDIA_NAMESPACE] = ('description', Description) 
326  _children['{%s}keywords' % MEDIA_NAMESPACE] = ('keywords', Keywords) 
327  _children['{%s}thumbnail' % MEDIA_NAMESPACE] = ('thumbnail', [Thumbnail,])
328  _children['{%s}title' % MEDIA_NAMESPACE] = ('title', Title) 
329  _children['{%s}category' % MEDIA_NAMESPACE] = ('category', [Category,]) 
330  _children['{%s}duration' % YOUTUBE_NAMESPACE] = ('duration', Duration)
331  _children['{%s}private' % YOUTUBE_NAMESPACE] = ('private', Private)
332  _children['{%s}player' % MEDIA_NAMESPACE] = ('player', Player)
333
334  def __init__(self, content=None, credit=None, description=None, keywords=None,
335               thumbnail=None, title=None, duration=None, private=None, 
336               category=None, player=None, extension_elements=None, 
337               extension_attributes=None, text=None):
338
339    MediaBaseElement.__init__(self, extension_elements=extension_elements,
340                              extension_attributes=extension_attributes,
341                              text=text)
342    self.content=content
343    self.credit=credit
344    self.description=description
345    self.keywords=keywords
346    self.thumbnail=thumbnail or []
347    self.title=title
348    self.duration=duration
349    self.private=private
350    self.category=category or []
351    self.player=player
352
353
354def GroupFromString(xml_string):
355  return atom.CreateClassFromXMLString(Group, xml_string)