]> git.parisson.com Git - telemeta.git/commitdiff
models: document media classes and queries
authordavid <>
Tue, 22 Sep 2009 12:28:36 +0000 (12:28 +0000)
committerdavid <>
Tue, 22 Sep 2009 12:28:36 +0000 (12:28 +0000)
telemeta/models/media.py
telemeta/models/query.py

index 452bfbb45e0bdcb3a2c914960319cc1147e08b5d..28fd05a879d7c1c3ffa09f633221791d65194333 100644 (file)
@@ -93,6 +93,7 @@ class MediaCore(object):
         return doc
     
     def is_well_formed_id(cls, value):
+        "Check if the media id is well formed"
         regex = re.compile(r"^" + media_id_regex + r"$")
         if regex.match(value):
             return True 
@@ -181,6 +182,7 @@ class MediaCollection(Model, MediaCore):
         return False
 
     def is_published(self):
+        "Tell if this collection is published"
         if len(self.publisher_reference) < 3:
           return True
         if self.publisher_reference[:3] == 'BM.':
@@ -188,9 +190,11 @@ class MediaCollection(Model, MediaCore):
         return True
 
     def ordered_items(self):
+        "Order this item by id and title"
         return self.items.order_by('id', '_title')
 
     def get_countries(self):
+        "Return the country from this item"
         countries = []
         items = self.items.order_by('etat')
         for item in items:
@@ -199,6 +203,7 @@ class MediaCollection(Model, MediaCore):
         return countries
 
     def get_ethnic_groups(self):
+        "Return the ethnic groups of the items"
         groups = []
         items = self.items.order_by('ethnie_grsocial')
         for item in items:
@@ -211,6 +216,7 @@ class MediaCollection(Model, MediaCore):
         return self.id
 
     def save(self, force_insert=False, force_update=False):
+        "Do a save of the item and a revision of it"
         if not MediaCore.is_well_formed_id(self.id):
             raise MediaInvalidIdError()
         super(MediaCollection, self).save(force_insert, force_update)
@@ -265,6 +271,7 @@ class MediaItem(Model, MediaCore):
     objects = MediaItemManager()
 
     def _get_title(self):
+        "Get the title of the item"
         # to (sort of) sync with models.query.MediaItemQuerySet.by_title()
         if self._title == "":
             try:
@@ -315,12 +322,14 @@ class MediaItem(Model, MediaCore):
         return duration
 
     def get_revision(self):
+        "Query the revisions of the item ordered by date"
         return Revision.objects.filter(element_type='item', element_id=self.id).order_by('-time')[0]
 
     def __unicode__(self):
         return self.title
 
     def save(self, force_insert=False, force_update=False):
+        "Do a save of the item and a revision"
         if not MediaCore.is_well_formed_id(self.id):
             raise MediaInvalidIdError()
         super(MediaItem, self).save(force_insert, force_update)
@@ -360,6 +369,7 @@ class MediaPart(Model, MediaCore):
         return self.title
 
     def save(self, force_insert=False, force_update=False):
+        "Do a save of the item and a revision"
         super(MediaPart, self).save(force_insert, force_update)
         Revision(element_type='part', element_id=self.id).touch()
 
@@ -372,6 +382,7 @@ class MediaPart(Model, MediaCore):
         db_table = 'telemeta_part'
 
 class Revision(Model):
+    "Describe a revision"
     id              = AutoField(primary_key=True)
     element_type    = CharField(max_length=16, choices=(('collection', 'collection'),
                                                         ('item', 'item'),
@@ -385,6 +396,7 @@ class Revision(Model):
 
 
     def touch(self):
+        "Create or update a revision"
         q = Revision.objects.filter(element_type=self.element_type, element_id=self.element_id) 
         if q.count():
             self.change_type = 'update'
index 309470a5352c08e1aa59aa360caa55dd249cb212..99c3fd5889b2a793200686c5babe63d33514511e 100644 (file)
@@ -43,6 +43,7 @@ class CoreQuerySet(QuerySet):
         return self.extra(where = ["0 = 1"])
 
     def pattern_to_regex(self, pattern):
+        "Cast a pattern into a regex"
         regex = pattern;
         regex = regex.replace('*', '.*')
         regex = regex.replace('.', '.*')
@@ -51,11 +52,13 @@ class CoreQuerySet(QuerySet):
         return regex
 
     def word_search(self, field, pattern):
+        "Search a word from a regex"
         regex = self.pattern_to_regex(pattern)
         kwargs = {field + '__iregex': regex}
         return self.filter(**kwargs)
 
     def _by_change_time(self, type, from_time = None, until_time = None):
+        "Search between two dates"
         where = ["element_type = '%s'" % type]
         if from_time:
             where.append("time >= '%s'" % from_time.strftime('%Y-%m-%d %H:%M:%S'))
@@ -68,6 +71,7 @@ class CoreManager(Manager):
     "Base class for all models managers"
 
     def none(self, *args, **kwargs):
+        ""
         return self.get_query_set().none(*args, **kwargs)
 
 class MediaCollectionQuerySet(CoreQuerySet):
@@ -90,43 +94,55 @@ class MediaCollectionQuerySet(CoreQuerySet):
         return self.filter(items__continent=continent).distinct()
 
     def by_recording_date(self, pattern):
+        "Find collections by recording date"
         return self.filter(annee_enr__icontains=pattern)
 
     def by_publish_date(self, pattern):
+        "Find collections by publishing date"
         return self.filter(date_published__icontains=pattern) 
 
     def by_ethnic_group(self, group):
+        "Find collections by ethnic group"
         return self.filter(items__ethnie_grsocial=group).distinct()
 
     def by_change_time(self, from_time = None, until_time = None):
+        "Find collections between two dates"
         return self._by_change_time('collection', from_time, until_time)
 
 class MediaCollectionManager(CoreManager):
     "Manage collection queries"
 
     def get_query_set(self):
+        "Return the collection query"
         return MediaCollectionQuerySet(self.model)
 
     def quick_search(self, *args, **kwargs):
         return self.get_query_set().quick_search(*args, **kwargs)
+    quick_search.__doc__ = MediaCollectionQuerySet.quick_search.__doc__
 
     def by_country(self, *args, **kwargs):
         return self.get_query_set().by_country(*args, **kwargs)
+    by_country.__doc__ = MediaCollectionQuerySet.by_country.__doc__
 
     def by_continent(self, *args, **kwargs):
         return self.get_query_set().by_continent(*args, **kwargs)
+    by_continent.__doc__ = MediaCollectionQuerySet.by_continent.__doc__
 
     def by_recording_date(self, *args, **kwargs):
         return self.get_query_set().by_recording_date(*args, **kwargs)
+    by_recording_date.__doc__ = MediaCollectionQuerySet.by_recording_date.__doc__
 
     def by_publish_date(self, *args, **kwargs):
         return self.get_query_set().by_publish_date(*args, **kwargs)
+    by_publish_date.__doc__ = MediaCollectionQuerySet.by_publish_date.__doc__
 
     def by_ethnic_group(self, *args, **kwargs):
         return self.get_query_set().by_ethnic_group(*args, **kwargs)
+    by_ethnic_group.__doc__ = MediaCollectionQuerySet.by_ethnic_group.__doc__
 
     def by_change_time(self, *args, **kwargs):
         return self.get_query_set().by_change_time(*args, **kwargs)
+    by_change_time.__doc__ = MediaCollectionQuerySet.by_change_time.__doc__
 
     def stat_continents(self, order_by='num'):      
         "Return the number of collections by continents and countries as a tree"
@@ -182,6 +198,7 @@ class MediaCollectionManager(CoreManager):
         return result
 
 class MediaItemQuerySet(CoreQuerySet):
+    "Base class for all media item query sets"
     
     def quick_search(self, pattern):
         "Perform a quick search on id and title"
@@ -203,40 +220,50 @@ class MediaItemQuerySet(CoreQuerySet):
             | Q(annee_enreg__icontains=pattern))
 
     def by_title(self, pattern):
+        "Find items by title"
         # to (sort of) sync with models.media.MediaItem.get_title()
         regex = self.pattern_to_regex(pattern)
         return self.filter(Q(_title__iregex=regex) 
           | Q(collection__title__iregex=regex))
 
     def by_publish_date(self, pattern):
+        "Find items by publishing date"
         return self.filter(collection__date_published__icontains=pattern) 
 
     def by_change_time(self, from_time = None, until_time = None):
+        "Find items by last change time"  
         return self._by_change_time('item', from_time, until_time)
             
 class MediaItemManager(CoreManager):
     "Manage media items queries"
 
     def get_query_set(self):
+        "Return media query sets"
         return MediaItemQuerySet(self.model)
 
     def quick_search(self, *args, **kwargs):
         return self.get_query_set().quick_search(*args, **kwargs)
+    quick_search.__doc__ = MediaItemQuerySet.quick_search.__doc__
 
     def without_collection(self, *args, **kwargs):
         return self.get_query_set().without_collection(*args, **kwargs)
+    without_collection.__doc__ = MediaItemQuerySet.without_collection.__doc__   
 
     def by_recording_date(self, *args, **kwargs):
         return self.get_query_set().by_recording_date(*args, **kwargs)
+    by_recording_date.__doc__ = MediaItemQuerySet.by_recording_date.__doc__
 
     def by_title(self, *args, **kwargs):
         return self.get_query_set().by_title(*args, **kwargs)
+    by_title.__doc__ = MediaItemQuerySet.by_title.__doc__
 
     def by_publish_date(self, *args, **kwargs):
         return self.get_query_set().by_publish_date(*args, **kwargs)
+    by_publish_date.__doc__ = MediaItemQuerySet.by_publish_date.__doc__
 
     def by_change_time(self, *args, **kwargs):
         return self.get_query_set().by_change_time(*args, **kwargs)
+    by_change_time.__doc__ = MediaItemQuerySet.by_change_time.__doc__    
 
     def list_ethnic_groups(self):
         "Return a list of all ethnic groups"