Add some docstrings to model/activity.py

ckan/model/activity.py

@@ -69,6 +69,7 @@ def __init__(self, activity_id, object_id, object_type, activity_type,
 
 
 def _most_recent_activities(q, limit):
+    '''Return the 'limit' most recent activites from activity query 'q'.'''
     import ckan.model as model
     q = q.order_by(desc(model.Activity.timestamp))
     if limit:
@@ -77,30 +78,33 @@ def _most_recent_activities(q, limit):
 
 
 def _activities_from_user_query(user_id):
+    '''Return an SQLAlchemy query for all activities from user_id.'''
     import ckan.model as model
     q = model.Session.query(model.Activity)
     q = q.filter(model.Activity.user_id == user_id)
     return q
 
 
 def _activities_about_user_query(user_id):
+    '''Return an SQLAlchemy query for all activities about user_id.'''
     import ckan.model as model
     q = model.Session.query(model.Activity)
     q = q.filter(model.Activity.object_id == user_id)
     return q
 
 
 def _user_activity_query(user_id):
+    '''Return an SQLAlchemy query for all activities from or about user_id.'''
     q = _activities_from_user_query(user_id)
     q = q.union(_activities_about_user_query(user_id))
     return q
 
 
 def user_activity_list(user_id, limit=15):
-    '''Return the given user's public activity stream.
+    '''Return user_id's public activity stream.
 
-    Returns all activities from or about the given user, i.e. where the given
-    user is the subject or object of the activity, e.g.:
+    Return a list of all activities from or about the given user, i.e. where
+    the given user is the subject or object of the activity, e.g.:
 
     "{USER} created the dataset {DATASET}"
     "{OTHER_USER} started following {USER}"
@@ -112,6 +116,9 @@ def user_activity_list(user_id, limit=15):
 
 
 def _package_activity_query(package_id):
+    '''Return an SQLAlchemy query for all activities about package_id.
+
+    '''
     import ckan.model as model
     q = model.Session.query(model.Activity)
     q = q.filter_by(object_id=package_id)
@@ -134,6 +141,12 @@ def package_activity_list(package_id, limit=15):
 
 
 def _group_activity_query(group_id, limit=15):
+    '''Return an SQLAlchemy query for all activities about group_id.
+
+    Returns a query for all activities whose object is either the group itself
+    or one of the group's datasets.
+
+    '''
     import ckan.model as model
 
     group = model.Group.get(group_id)
@@ -164,6 +177,7 @@ def group_activity_list(group_id, limit=15):
 
 
 def _activites_from_users_followed_by_user_query(user_id):
+    '''Return a query for all activities from users that user_id follows.'''
     import ckan.model as model
     q = model.Session.query(model.Activity)
     q = q.join(model.UserFollowingUser,
@@ -173,6 +187,7 @@ def _activites_from_users_followed_by_user_query(user_id):
 
 
 def _activities_from_datasets_followed_by_user_query(user_id):
+    '''Return a query for all activities from datasets that user_id follows.'''
     import ckan.model as model
     q = model.Session.query(model.Activity)
     q = q.join(model.UserFollowingDataset,
@@ -182,6 +197,13 @@ def _activities_from_datasets_followed_by_user_query(user_id):
 
 
 def _activities_from_groups_followed_by_user_query(user_id):
+    '''Return a query for all activities about groups the given user follows.
+
+    Return a query for all activities about the groups the given user follows,
+    or about any of the group's datasets. This is the union of
+    _group_activity_query(group_id) for each of the groups the user follows.
+
+    '''
     import ckan.model as model
 
     # Get a list of the group's that the user is following.
@@ -197,6 +219,7 @@ def _activities_from_groups_followed_by_user_query(user_id):
 
 
 def _activities_from_everything_followed_by_user_query(user_id):
+    '''Return a query for all activities from everything user_id follows.'''
     q = _activites_from_users_followed_by_user_query(user_id)
     q = q.union(_activities_from_datasets_followed_by_user_query(user_id))
     q = q.union(_activities_from_groups_followed_by_user_query(user_id))
@@ -215,6 +238,7 @@ def activities_from_everything_followed_by_user(user_id, limit=15):
 
 
 def _dashboard_activity_query(user_id):
+    '''Return an SQLAlchemy query for user_id's dashboard activity stream.'''
     q = _user_activity_query(user_id)
     q = q.union(_activities_from_everything_followed_by_user_query(user_id))
     return q
@@ -234,13 +258,25 @@ def dashboard_activity_list(user_id, limit=15):
     return _most_recent_activities(q, limit)
 
 
-def _recently_changed_packages_activity_query():
+def _changed_packages_activity_query():
+    '''Return an SQLAlchemyu query for all changed package activities.
+
+    Return a query for all activities with activity_type '*package', e.g.
+    'new_package', 'changed_package', 'deleted_package'.
+
+    '''
     import ckan.model as model
     q = model.Session.query(model.Activity)
     q = q.filter(model.Activity.activity_type.endswith('package'))
     return q
 
 
 def recently_changed_packages_activity_list(limit=15):
-    q = _recently_changed_packages_activity_query()
+    '''Return the site-wide stream of recently changed package activities.
+
+    This activity stream includes recent 'new package', 'changed package' and
+    'deleted package' activities for the whole site.
+
+    '''
+    q = _changed_packages_activity_query()
     return _most_recent_activities(q, limit)