/gdata/media/__init__.py

http://radioappz.googlecode.com/ · Python · 355 lines · 287 code · 27 blank · 41 comment · 8 complexity · cd781717889cae7e1a6e37c33c246d25 MD5 · raw file

  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. """Essential attributes of photos in Google Photos/Picasa Web Albums are
  22. expressed using elements from the `media' namespace, defined in the
  23. MediaRSS specification[1].
  24. Due to copyright issues, the elements herein are documented sparingly, please
  25. consult with the Google Photos API Reference Guide[2], alternatively the
  26. official MediaRSS specification[1] for details.
  27. (If there is a version conflict between the two sources, stick to the
  28. Google Photos API).
  29. [1]: http://search.yahoo.com/mrss (version 1.1.1)
  30. [2]: http://code.google.com/apis/picasaweb/reference.html#media_reference
  31. Keep in mind that Google Photos only uses a subset of the MediaRSS elements
  32. (and some of the attributes are trimmed down, too):
  33. media:content
  34. media:credit
  35. media:description
  36. media:group
  37. media:keywords
  38. media:thumbnail
  39. media:title
  40. """
  41. __author__ = u'havard@gulldahl.no'# (H?vard Gulldahl)' #BUG: api chokes on non-ascii chars in __author__
  42. __license__ = 'Apache License v2'
  43. import atom
  44. import gdata
  45. MEDIA_NAMESPACE = 'http://search.yahoo.com/mrss/'
  46. YOUTUBE_NAMESPACE = 'http://gdata.youtube.com/schemas/2007'
  47. class MediaBaseElement(atom.AtomBase):
  48. """Base class for elements in the MEDIA_NAMESPACE.
  49. To add new elements, you only need to add the element tag name to self._tag
  50. """
  51. _tag = ''
  52. _namespace = MEDIA_NAMESPACE
  53. _children = atom.AtomBase._children.copy()
  54. _attributes = atom.AtomBase._attributes.copy()
  55. def __init__(self, name=None, extension_elements=None,
  56. extension_attributes=None, text=None):
  57. self.name = name
  58. self.text = text
  59. self.extension_elements = extension_elements or []
  60. self.extension_attributes = extension_attributes or {}
  61. class Content(MediaBaseElement):
  62. """(attribute container) This element describes the original content,
  63. e.g. an image or a video. There may be multiple Content elements
  64. in a media:Group.
  65. For example, a video may have a
  66. <media:content medium="image"> element that specifies a JPEG
  67. representation of the video, and a <media:content medium="video">
  68. element that specifies the URL of the video itself.
  69. Attributes:
  70. url: non-ambigous reference to online object
  71. width: width of the object frame, in pixels
  72. height: width of the object frame, in pixels
  73. medium: one of `image' or `video', allowing the api user to quickly
  74. determine the object's type
  75. type: Internet media Type[1] (a.k.a. mime type) of the object -- a more
  76. verbose way of determining the media type. To set the type member
  77. in the contructor, use the content_type parameter.
  78. (optional) fileSize: the size of the object, in bytes
  79. [1]: http://en.wikipedia.org/wiki/Internet_media_type
  80. """
  81. _tag = 'content'
  82. _attributes = atom.AtomBase._attributes.copy()
  83. _attributes['url'] = 'url'
  84. _attributes['width'] = 'width'
  85. _attributes['height'] = 'height'
  86. _attributes['medium'] = 'medium'
  87. _attributes['type'] = 'type'
  88. _attributes['fileSize'] = 'fileSize'
  89. def __init__(self, url=None, width=None, height=None,
  90. medium=None, content_type=None, fileSize=None, format=None,
  91. extension_elements=None, extension_attributes=None, text=None):
  92. MediaBaseElement.__init__(self, extension_elements=extension_elements,
  93. extension_attributes=extension_attributes,
  94. text=text)
  95. self.url = url
  96. self.width = width
  97. self.height = height
  98. self.medium = medium
  99. self.type = content_type
  100. self.fileSize = fileSize
  101. def ContentFromString(xml_string):
  102. return atom.CreateClassFromXMLString(Content, xml_string)
  103. class Credit(MediaBaseElement):
  104. """(string) Contains the nickname of the user who created the content,
  105. e.g. `Liz Bennet'.
  106. This is a user-specified value that should be used when referring to
  107. the user by name.
  108. Note that none of the attributes from the MediaRSS spec are supported.
  109. """
  110. _tag = 'credit'
  111. def CreditFromString(xml_string):
  112. return atom.CreateClassFromXMLString(Credit, xml_string)
  113. class Description(MediaBaseElement):
  114. """(string) A description of the media object.
  115. Either plain unicode text, or entity-encoded html (look at the `type'
  116. attribute).
  117. E.g `A set of photographs I took while vacationing in Italy.'
  118. For `api' projections, the description is in plain text;
  119. for `base' projections, the description is in HTML.
  120. Attributes:
  121. type: either `text' or `html'. To set the type member in the contructor,
  122. use the description_type parameter.
  123. """
  124. _tag = 'description'
  125. _attributes = atom.AtomBase._attributes.copy()
  126. _attributes['type'] = 'type'
  127. def __init__(self, description_type=None,
  128. extension_elements=None, extension_attributes=None, text=None):
  129. MediaBaseElement.__init__(self, extension_elements=extension_elements,
  130. extension_attributes=extension_attributes,
  131. text=text)
  132. self.type = description_type
  133. def DescriptionFromString(xml_string):
  134. return atom.CreateClassFromXMLString(Description, xml_string)
  135. class Keywords(MediaBaseElement):
  136. """(string) Lists the tags associated with the entry,
  137. e.g `italy, vacation, sunset'.
  138. Contains a comma-separated list of tags that have been added to the photo, or
  139. all tags that have been added to photos in the album.
  140. """
  141. _tag = 'keywords'
  142. def KeywordsFromString(xml_string):
  143. return atom.CreateClassFromXMLString(Keywords, xml_string)
  144. class Thumbnail(MediaBaseElement):
  145. """(attributes) Contains the URL of a thumbnail of a photo or album cover.
  146. There can be multiple <media:thumbnail> elements for a given <media:group>;
  147. for example, a given item may have multiple thumbnails at different sizes.
  148. Photos generally have two thumbnails at different sizes;
  149. albums generally have one cropped thumbnail.
  150. If the thumbsize parameter is set to the initial query, this element points
  151. to thumbnails of the requested sizes; otherwise the thumbnails are the
  152. default thumbnail size.
  153. This element must not be confused with the <gphoto:thumbnail> element.
  154. Attributes:
  155. url: The URL of the thumbnail image.
  156. height: The height of the thumbnail image, in pixels.
  157. width: The width of the thumbnail image, in pixels.
  158. """
  159. _tag = 'thumbnail'
  160. _attributes = atom.AtomBase._attributes.copy()
  161. _attributes['url'] = 'url'
  162. _attributes['width'] = 'width'
  163. _attributes['height'] = 'height'
  164. def __init__(self, url=None, width=None, height=None,
  165. extension_attributes=None, text=None, extension_elements=None):
  166. MediaBaseElement.__init__(self, extension_elements=extension_elements,
  167. extension_attributes=extension_attributes,
  168. text=text)
  169. self.url = url
  170. self.width = width
  171. self.height = height
  172. def ThumbnailFromString(xml_string):
  173. return atom.CreateClassFromXMLString(Thumbnail, xml_string)
  174. class Title(MediaBaseElement):
  175. """(string) Contains the title of the entry's media content, in plain text.
  176. Attributes:
  177. type: Always set to plain. To set the type member in the constructor, use
  178. the title_type parameter.
  179. """
  180. _tag = 'title'
  181. _attributes = atom.AtomBase._attributes.copy()
  182. _attributes['type'] = 'type'
  183. def __init__(self, title_type=None,
  184. extension_attributes=None, text=None, extension_elements=None):
  185. MediaBaseElement.__init__(self, extension_elements=extension_elements,
  186. extension_attributes=extension_attributes,
  187. text=text)
  188. self.type = title_type
  189. def TitleFromString(xml_string):
  190. return atom.CreateClassFromXMLString(Title, xml_string)
  191. class Player(MediaBaseElement):
  192. """(string) Contains the embeddable player URL for the entry's media content
  193. if the media is a video.
  194. Attributes:
  195. url: Always set to plain
  196. """
  197. _tag = 'player'
  198. _attributes = atom.AtomBase._attributes.copy()
  199. _attributes['url'] = 'url'
  200. def __init__(self, player_url=None,
  201. extension_attributes=None, extension_elements=None):
  202. MediaBaseElement.__init__(self, extension_elements=extension_elements,
  203. extension_attributes=extension_attributes)
  204. self.url= player_url
  205. class Private(atom.AtomBase):
  206. """The YouTube Private element"""
  207. _tag = 'private'
  208. _namespace = YOUTUBE_NAMESPACE
  209. class Duration(atom.AtomBase):
  210. """The YouTube Duration element"""
  211. _tag = 'duration'
  212. _namespace = YOUTUBE_NAMESPACE
  213. _attributes = atom.AtomBase._attributes.copy()
  214. _attributes['seconds'] = 'seconds'
  215. class Category(MediaBaseElement):
  216. """The mediagroup:category element"""
  217. _tag = 'category'
  218. _attributes = atom.AtomBase._attributes.copy()
  219. _attributes['term'] = 'term'
  220. _attributes['scheme'] = 'scheme'
  221. _attributes['label'] = 'label'
  222. def __init__(self, term=None, scheme=None, label=None, text=None,
  223. extension_elements=None, extension_attributes=None):
  224. """Constructor for Category
  225. Args:
  226. term: str
  227. scheme: str
  228. label: str
  229. text: str The text data in the this element
  230. extension_elements: list A list of ExtensionElement instances
  231. extension_attributes: dict A dictionary of attribute value string pairs
  232. """
  233. self.term = term
  234. self.scheme = scheme
  235. self.label = label
  236. self.text = text
  237. self.extension_elements = extension_elements or []
  238. self.extension_attributes = extension_attributes or {}
  239. class Group(MediaBaseElement):
  240. """Container element for all media elements.
  241. The <media:group> element can appear as a child of an album, photo or
  242. video entry."""
  243. _tag = 'group'
  244. _children = atom.AtomBase._children.copy()
  245. _children['{%s}content' % MEDIA_NAMESPACE] = ('content', [Content,])
  246. _children['{%s}credit' % MEDIA_NAMESPACE] = ('credit', Credit)
  247. _children['{%s}description' % MEDIA_NAMESPACE] = ('description', Description)
  248. _children['{%s}keywords' % MEDIA_NAMESPACE] = ('keywords', Keywords)
  249. _children['{%s}thumbnail' % MEDIA_NAMESPACE] = ('thumbnail', [Thumbnail,])
  250. _children['{%s}title' % MEDIA_NAMESPACE] = ('title', Title)
  251. _children['{%s}category' % MEDIA_NAMESPACE] = ('category', [Category,])
  252. _children['{%s}duration' % YOUTUBE_NAMESPACE] = ('duration', Duration)
  253. _children['{%s}private' % YOUTUBE_NAMESPACE] = ('private', Private)
  254. _children['{%s}player' % MEDIA_NAMESPACE] = ('player', Player)
  255. def __init__(self, content=None, credit=None, description=None, keywords=None,
  256. thumbnail=None, title=None, duration=None, private=None,
  257. category=None, player=None, extension_elements=None,
  258. extension_attributes=None, text=None):
  259. MediaBaseElement.__init__(self, extension_elements=extension_elements,
  260. extension_attributes=extension_attributes,
  261. text=text)
  262. self.content=content
  263. self.credit=credit
  264. self.description=description
  265. self.keywords=keywords
  266. self.thumbnail=thumbnail or []
  267. self.title=title
  268. self.duration=duration
  269. self.private=private
  270. self.category=category or []
  271. self.player=player
  272. def GroupFromString(xml_string):
  273. return atom.CreateClassFromXMLString(Group, xml_string)