Described the MediaEntry structure in the docstring.

mediagoblin/db/models.py

@@ -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 = {