Described the MediaEntry structure in the docstring.

mediagoblin/db/models.py

@@ -88,7 +88,7 @@ class User(Document):
         'status': u'needs_email_verification',
         'verification_key': lambda: unicode(uuid.uuid4()),
         'is_admin': False}
-        
+
     def check_login(self, password):
         """
         See if a user can login with this password
@@ -98,6 +98,81 @@ class User(Document):
 
 
 class MediaEntry(Document):
+    """
+    Record of a piece of media.
+
+    Structure:
+     - uploader: A reference to a User who uploaded this.
+
+     - title: Title of this work
+
+     - slug: A normalized "slug" which can be used as part of a URL to retrieve
+       this work, such as 'my-works-name-in-slug-form' may be viewable by
+       'http://mg.example.org/u/username/m/my-works-name-in-slug-form/'
+       Note that since URLs are constructed this way, slugs must be unique
+       per-uploader.  (An index is provided to enforce that but code should be
+       written on the python side to ensure this as well.)
+
+     - created: Date and time of when this piece of work was uploaded.
+
+     - description: Uploader-set description of this work.  This can be marked
+       up with MarkDown for slight fanciness (links, boldness, italics,
+       paragraphs...)
+
+     - description_html: Rendered version of the description, run through
+       Markdown and cleaned with our cleaning tool.
+
+     - media_type: What type of media is this?  Currently we only support
+       'image' ;)
+
+     - media_data: Extra information that's media-format-dependent.
+       For example, images might contain some EXIF data that's not appropriate
+       to other formats.  You might store it like:
+
+         mediaentry['media_data']['exif'] = {
+             'manufacturer': 'CASIO',
+             'model': 'QV-4000',
+             'exposure_time': .659}
+
+       Alternately for video you might store:
+
+         # play length in seconds
+         mediaentry['media_data']['play_length'] = 340
+
+       ... so what's appropriate here really depends on the media type.
+
+     - plugin_data: a mapping of extra plugin information for this User.
+       Nothing uses this yet as we don't have plugins, but someday we
+       might... :)
+
+     - tags: A list of tags.  Each tag is stored as a dictionary that has a key
+       for the actual name and the normalized name-as-slug, so ultimately this
+       looks like:
+         [{'name': 'Gully Gardens',
+           'slug': 'gully-gardens'},
+          {'name': 'Castle Adventure Time?!",
+           'slug': 'castle-adventure-time'}]
+
+     - state: What's the state of this file?  Active, inactive, disabled, etc...
+       But really for now there are only two states:
+        "unprocessed": uploaded but needs to go through processing for display
+        "processed": processed and able to be displayed
+
+     - queued_media_file: storage interface style filepath describing a file
+       queued for processing.  This is stored in the mg_globals.queue_store
+       storage system.
+
+     - media_files: Files relevant to this that have actually been processed
+       and are available for various types of display.  Stored like:
+         {'thumb': ['dir1', 'dir2', 'pic.png'}
+
+     - attachment_files: A list of "attachment" files, ones that aren't
+       critical to this piece of media but may be usefully relevant to people
+       viewing the work.  (currently unused.)
+
+     - thumbnail_file: Deprecated... we should remove this ;)
+
+    """
     __collection__ = 'media_entries'
 
     structure = {
@@ -164,7 +239,7 @@ class MediaEntry(Document):
 
         duplicate = mg_globals.database.media_entries.find_one(
             {'slug': self['slug']})
-        
+
         if duplicate:
             self['slug'] = "%s-%s" % (self['_id'], self['slug'])
 
@@ -186,12 +261,12 @@ class MediaEntry(Document):
                 'mediagoblin.user_pages.media_home',
                 user=uploader['username'],
                 media=unicode(self['_id']))
-            
+
     def url_to_prev(self, urlgen):
         """
         Provide a url to the previous entry from this user, if there is one
         """
-        cursor = self.db.MediaEntry.find({'_id' : {"$gt": self['_id']}, 
+        cursor = self.db.MediaEntry.find({'_id' : {"$gt": self['_id']},
                                           'uploader': self['uploader'],
                                           'state': 'processed'}).sort(
                                                     '_id', ASCENDING).limit(1)
@@ -199,12 +274,12 @@ class MediaEntry(Document):
             return urlgen('mediagoblin.user_pages.media_home',
                           user=self.uploader()['username'],
                           media=unicode(cursor[0]['slug']))
-        
+
     def url_to_next(self, urlgen):
         """
         Provide a url to the next entry from this user, if there is one
         """
-        cursor = self.db.MediaEntry.find({'_id' : {"$lt": self['_id']}, 
+        cursor = self.db.MediaEntry.find({'_id' : {"$lt": self['_id']},
                                           'uploader': self['uploader'],
                                           'state': 'processed'}).sort(
                                                     '_id', DESCENDING).limit(1)