/gdata/media/__init__.py
Python | 355 lines | 300 code | 19 blank | 36 comment | 15 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 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)