update views.py to add docstrings and change exception name to address pylint errors

lms/djangoapps/django_comment_client/base/views.py

@@ -69,6 +69,10 @@ def ajax_content_response(request, course_id, content, template_name):
 @login_required
 @permitted
 def create_thread(request, course_id, commentable_id):
+    """
+    Given a course and commentble ID, create the thread
+    """
+    
     log.debug("Creating new thread in %r, id %r", course_id, commentable_id)
     course = get_course_with_access(request.user, course_id, 'load')
     post = request.POST
@@ -138,6 +142,9 @@ def create_thread(request, course_id, commentable_id):
 @login_required
 @permitted
 def update_thread(request, course_id, thread_id):
+    """
+    Given a course id and thread id, update a existing thread, used for both static and ajax submissions
+    """
     thread = cc.Thread.find(thread_id)
     thread.update_attributes(**extract(request.POST, ['body', 'title', 'tags']))
     thread.save()
@@ -148,6 +155,10 @@ def update_thread(request, course_id, thread_id):
 
 
 def _create_comment(request, course_id, thread_id=None, parent_id=None):
+    """
+    given a course_id, thread_id, and parent_id, create a comment,
+    called from create_comment to do the actual creation
+    """
     post = request.POST
     comment = cc.Comment(**extract(post, ['body']))
 
@@ -184,6 +195,10 @@ def _create_comment(request, course_id, thread_id=None, parent_id=None):
 @login_required
 @permitted
 def create_comment(request, course_id, thread_id):
+    """
+    given a course_id and thread_id, test for comment depth. if not too deep,
+    call _create_comment to create the actual comment.
+    """
     if cc_settings.MAX_COMMENT_DEPTH is not None:
         if cc_settings.MAX_COMMENT_DEPTH < 0:
             return JsonError("Comment level too deep")
@@ -194,6 +209,10 @@ def create_comment(request, course_id, thread_id):
 @login_required
 @permitted
 def delete_thread(request, course_id, thread_id):
+    """
+    given a course_id and thread_id, delete this thread
+    this is ajax only
+    """
     thread = cc.Thread.find(thread_id)
     thread.delete()
     return JsonResponse(utils.safe_content(thread.to_dict()))
@@ -203,6 +222,10 @@ def delete_thread(request, course_id, thread_id):
 @login_required
 @permitted
 def update_comment(request, course_id, comment_id):
+    """
+    given a course_id and comment_id, update the comment with payload attributes
+    handles static and ajax submissions
+    """
     comment = cc.Comment.find(comment_id)
     comment.update_attributes(**extract(request.POST, ['body']))
     comment.save()
@@ -216,6 +239,10 @@ def update_comment(request, course_id, comment_id):
 @login_required
 @permitted
 def endorse_comment(request, course_id, comment_id):
+    """
+    given a course_id and comment_id, toggle the endorsement of this comment,
+    ajax only
+    """
     comment = cc.Comment.find(comment_id)
     comment.endorsed = request.POST.get('endorsed', 'false').lower() == 'true'
     comment.save()
@@ -226,6 +253,10 @@ def endorse_comment(request, course_id, comment_id):
 @login_required
 @permitted
 def openclose_thread(request, course_id, thread_id):
+    """
+    given a course_id and thread_id, toggle the status of this thread
+    ajax only
+    """
     thread = cc.Thread.find(thread_id)
     thread.closed = request.POST.get('closed', 'false').lower() == 'true'
     thread.save()
@@ -240,6 +271,10 @@ def openclose_thread(request, course_id, thread_id):
 @login_required
 @permitted
 def create_sub_comment(request, course_id, comment_id):
+    """
+    given a course_id and comment_id, create a response to a comment
+    after checking the max depth allowed, if allowed
+    """
     if cc_settings.MAX_COMMENT_DEPTH is not None:
         if cc_settings.MAX_COMMENT_DEPTH <= cc.Comment.find(comment_id).depth:
             return JsonError("Comment level too deep")
@@ -250,6 +285,10 @@ def create_sub_comment(request, course_id, comment_id):
 @login_required
 @permitted
 def delete_comment(request, course_id, comment_id):
+    """
+    given a course_id and comment_id delete this comment
+    ajax only
+    """
     comment = cc.Comment.find(comment_id)
     comment.delete()
     return JsonResponse(utils.safe_content(comment.to_dict()))
@@ -259,6 +298,9 @@ def delete_comment(request, course_id, comment_id):
 @login_required
 @permitted
 def vote_for_comment(request, course_id, comment_id, value):
+    """
+    given a course_id and comment_id,
+    """
     user = cc.User.from_django_user(request.user)
     comment = cc.Comment.find(comment_id)
     user.vote(comment, value)
@@ -269,6 +311,10 @@ def vote_for_comment(request, course_id, comment_id, value):
 @login_required
 @permitted
 def undo_vote_for_comment(request, course_id, comment_id):
+    """
+    given a course id and comment id, remove vote
+    ajax only
+    """
     user = cc.User.from_django_user(request.user)
     comment = cc.Comment.find(comment_id)
     user.unvote(comment)
@@ -279,6 +325,10 @@ def undo_vote_for_comment(request, course_id, comment_id):
 @login_required
 @permitted
 def vote_for_thread(request, course_id, thread_id, value):
+    """
+    given a course id and thread id vote for this thread
+    ajax only
+    """
     user = cc.User.from_django_user(request.user)
     thread = cc.Thread.find(thread_id)
     user.vote(thread, value)
@@ -289,6 +339,10 @@ def vote_for_thread(request, course_id, thread_id, value):
 @login_required
 @permitted
 def flag_abuse_for_thread(request, course_id, thread_id):
+    """
+    given a course_id and thread_id flag this thread for abuse
+    ajax only
+    """
     user = cc.User.from_django_user(request.user)
     thread = cc.Thread.find(thread_id)
     thread.flagAbuse(user, thread)
@@ -299,6 +353,10 @@ def flag_abuse_for_thread(request, course_id, thread_id):
 @login_required
 @permitted
 def un_flag_abuse_for_thread(request, course_id, thread_id):
+    """
+    given a course id and thread id, remove abuse flag for this thread
+    ajax only
+    """
     user = cc.User.from_django_user(request.user)
     course = get_course_by_id(course_id)
     thread = cc.Thread.find(thread_id)
@@ -311,6 +369,10 @@ def un_flag_abuse_for_thread(request, course_id, thread_id):
 @login_required
 @permitted
 def flag_abuse_for_comment(request, course_id, comment_id):
+    """
+    given a course and comment id, flag comment for abuse
+    ajax only
+    """
     user = cc.User.from_django_user(request.user)
     comment = cc.Comment.find(comment_id)
     comment.flagAbuse(user, comment)
@@ -321,6 +383,10 @@ def flag_abuse_for_comment(request, course_id, comment_id):
 @login_required
 @permitted
 def un_flag_abuse_for_comment(request, course_id, comment_id):
+    """
+    given a course_id and comment id, unflag comment for abuse
+    ajax only
+    """
     user = cc.User.from_django_user(request.user)
     course = get_course_by_id(course_id)
     removeAll = cached_has_permission(request.user, 'openclose_thread', course_id) or has_access(request.user, course, 'staff')
@@ -333,6 +399,10 @@ def un_flag_abuse_for_comment(request, course_id, comment_id):
 @login_required
 @permitted
 def undo_vote_for_thread(request, course_id, thread_id):
+    """
+    given a course id and thread id, remove users vote for thread
+    ajax only
+    """
     user = cc.User.from_django_user(request.user)
     thread = cc.Thread.find(thread_id)
     user.unvote(thread)
@@ -343,6 +413,10 @@ def undo_vote_for_thread(request, course_id, thread_id):
 @login_required
 @permitted
 def pin_thread(request, course_id, thread_id):
+    """
+    given a course id and thread id, pin this thread
+    ajax only
+    """
     user = cc.User.from_django_user(request.user)
     thread = cc.Thread.find(thread_id)
     thread.pin(user, thread_id)
@@ -350,6 +424,10 @@ def pin_thread(request, course_id, thread_id):
 
 
 def un_pin_thread(request, course_id, thread_id):
+    """
+    given a course id and thread id, remove pin from this thread
+    ajax only
+    """
     user = cc.User.from_django_user(request.user)
     thread = cc.Thread.find(thread_id)
     thread.un_pin(user, thread_id)
@@ -370,6 +448,10 @@ def follow_thread(request, course_id, thread_id):
 @login_required
 @permitted
 def follow_commentable(request, course_id, commentable_id):
+    """
+    given a course_id and commentable id, follow this commentable
+    ajax only
+    """
     user = cc.User.from_django_user(request.user)
     commentable = cc.Commentable.find(commentable_id)
     user.follow(commentable)
@@ -390,6 +472,10 @@ def follow_user(request, course_id, followed_user_id):
 @login_required
 @permitted
 def unfollow_thread(request, course_id, thread_id):
+    """
+    given a course id and thread id, stop following this thread
+    ajax only
+    """
     user = cc.User.from_django_user(request.user)
     thread = cc.Thread.find(thread_id)
     user.unfollow(thread)
@@ -400,6 +486,10 @@ def unfollow_thread(request, course_id, thread_id):
 @login_required
 @permitted
 def unfollow_commentable(request, course_id, commentable_id):
+    """
+    given a course id and commentable id stop following commentable
+    ajax only
+    """
     user = cc.User.from_django_user(request.user)
     commentable = cc.Commentable.find(commentable_id)
     user.unfollow(commentable)
@@ -410,6 +500,10 @@ def unfollow_commentable(request, course_id, commentable_id):
 @login_required
 @permitted
 def unfollow_user(request, course_id, followed_user_id):
+    """
+    given a course id and user id, stop following this user
+    ajax only
+    """
     user = cc.User.from_django_user(request.user)
     followed_user = cc.User.find(followed_user_id)
     user.unfollow(followed_user)
@@ -420,6 +514,10 @@ def unfollow_user(request, course_id, followed_user_id):
 @login_required
 @permitted
 def update_moderator_status(request, course_id, user_id):
+    """
+    given a course id and user id, check if the user has moderator
+    and send back a user profile
+    """
     is_moderator = request.POST.get('is_moderator', '').lower()
     if is_moderator not in ["true", "false"]:
         return JsonError("Must provide is_moderator as boolean value")
@@ -449,6 +547,10 @@ def update_moderator_status(request, course_id, user_id):
 
 @require_GET
 def search_similar_threads(request, course_id, commentable_id):
+    """
+    given a course id and commentable id, run query given in text get param
+    of request
+    """
     text = request.GET.get('text', None)
     if text:
         query_params = {
@@ -517,11 +619,11 @@ def upload(request, course_id):  # ajax upload file to a question or answer
                 {'file_size': cc_settings.MAX_UPLOAD_FILE_SIZE}
             raise exceptions.PermissionDenied(msg)
 
-    except exceptions.PermissionDenied, e:
+    except exceptions.PermissionDenied, err:
         error = unicode(e)
-    except Exception, e:
-        print e
-        logging.critical(unicode(e))
+    except Exception, err:
+        print err
+        logging.critical(unicode(err))
         error = _('Error uploading file. Please contact the site administrator. Thank you.')
 
     if error == '':