Fix lint issues for notifications app (readthedocs#2881)

Author: lordmauve

prospector-more.yml

@@ -6,7 +6,6 @@ ignore-paths:
   - core/
   - doc_builder/
   - donate/
-  - notifications/
   - privacy/
   - projects/
   - redirects/

readthedocs/notifications/__init__.py

@@ -1,4 +1,24 @@
+"""Extensions to Django messages to support notifications to users.
+
+Notifications are important communications to users that need to be as visible
+as possible. We support different backends to make notifications visible in
+different ways. For example, they might be e-mailed to users as well as
+displayed on the site.
+
+This app builds on `django-messages-extends`_ to provide persistent messages
+on the site.
+
+.. _`django-messages-extends`: https://github.com
+                               /AliLozano/django-messages-extends/
+
+"""
 from .notification import Notification
 from .backends import send_notification
 
+__all__ = (
+    'Notification',
+    'send_notification'
+)
+
+
 default_app_config = 'readthedocs.notifications.apps.NotificationsAppConfig'

readthedocs/notifications/apps.py

@@ -1,3 +1,4 @@
+"""Django app configuration for the notifications app."""
 from django.apps import AppConfig
 
 

readthedocs/notifications/backends.py

@@ -1,10 +1,15 @@
-"""Notification to message backends"""
+"""Pluggable backends for the delivery of notifications.
+
+Delivery of notifications to users depends on a list of backends configured in
+Django settings. For example, they might be e-mailed to users as well as
+displayed on the site.
+
+"""
 
 from django.conf import settings
 from django.http import HttpRequest
 from django.utils.module_loading import import_string
 from messages_extends.constants import INFO_PERSISTENT
-from messages_extends import add_message
 
 from readthedocs.core.utils import send_email
 

readthedocs/notifications/forms.py

@@ -1,3 +1,4 @@
+"""HTML forms for sending notifications."""
 from django import forms
 from django.utils.translation import ugettext_lazy as _
 

readthedocs/notifications/notification.py

@@ -1,22 +1,34 @@
+"""Support for templating of notifications."""
+
 from django.conf import settings
 from django.template import Template, Context
 from django.template.loader import render_to_string
 from django.db import models
 
 from .backends import send_notification
-from .constants import INFO, HTML, TEXT
+from . import constants
 
 
 class Notification(object):
 
+    """An unsent notification linked to an object.
+
+    This class provides an interface to construct notification messages by
+    rendering Django templates. The ``Notification`` itself is not expected
+    to be persisted by the backends.
+
+    Call .send() to send the notification.
+
+    """
+
     name = None
     context_object_name = 'object'
-    level = INFO
+    level = constants.INFO
     subject = None
     user = None
 
-    def __init__(self, object, request, user=None):
-        self.object = object
+    def __init__(self, context_object, request, user=None):
+        self.object = context_object
         self.request = request
         self.user = user
         if self.user is None:
@@ -35,22 +47,23 @@ def get_context_data(self):
             )
         }
 
-    def get_template_names(self, backend_name, source_format=HTML):
+    def get_template_names(self, backend_name, source_format=constants.HTML):
         names = []
         if self.object and isinstance(self.object, models.Model):
+            meta = self.object._meta  # pylint: disable=protected-access
             names.append(
                 '{app}/notifications/{name}_{backend}.{source_format}'
                 .format(
-                    app=self.object._meta.app_label,
-                    name=self.name or self.object._meta.model_name,
+                    app=meta.app_label,
+                    name=self.name or meta.model_name,
                     backend=backend_name,
                     source_format=source_format,
                 ))
             return names
         else:
             raise AttributeError()
 
-    def render(self, backend_name, source_format=HTML):
+    def render(self, backend_name, source_format=constants.HTML):
         return render_to_string(
             template_name=self.get_template_names(
                 backend_name=backend_name,

readthedocs/notifications/storages.py

@@ -1,3 +1,5 @@
+"""Customised storage for notifications."""
+
 from django.contrib.messages.storage.base import Message
 from django.utils.safestring import mark_safe
 from messages_extends.storages import FallbackStorage

readthedocs/notifications/views.py

@@ -1,3 +1,4 @@
+"""Django views for the notifications app."""
 from django.views.generic import FormView
 from django.contrib import admin, messages
 from django.http import HttpResponseRedirect
@@ -51,7 +52,7 @@ def form_valid(self, form):
         notification_cls = form.cleaned_data['source']
         for obj in self.get_queryset().all():
             for recipient in self.get_object_recipients(obj):
-                notification = notification_cls(object=obj,
+                notification = notification_cls(context_object=obj,
                                                 request=self.request,
                                                 user=recipient)
                 notification.send()

readthedocs/rtd_tests/tests/test_notifications.py

@@ -33,7 +33,7 @@ class TestNotification(Notification):
 
         build = fixture.get(Build)
         req = mock.MagicMock()
-        notify = TestNotification(object=build, request=req)
+        notify = TestNotification(context_object=build, request=req)
 
         self.assertEqual(notify.get_template_names('email'),
                          ['builds/notifications/foo_email.html'])
@@ -69,7 +69,7 @@ class TestNotification(Notification):
         build = fixture.get(Build)
         req = mock.MagicMock()
         user = fixture.get(User)
-        notify = TestNotification(object=build, request=req, user=user)
+        notify = TestNotification(context_object=build, request=req, user=user)
         backend = EmailBackend(request=req)
         backend.send(notify)
 
@@ -96,7 +96,7 @@ class TestNotification(Notification):
         build = fixture.get(Build)
         user = fixture.get(User)
         req = mock.MagicMock()
-        notify = TestNotification(object=build, request=req, user=user)
+        notify = TestNotification(context_object=build, request=req, user=user)
         backend = SiteBackend(request=req)
         backend.send(notify)
 
@@ -118,7 +118,7 @@ class TestNotification(Notification):
         build = fixture.get(Build)
         user = AnonymousUser()
         req = mock.MagicMock()
-        notify = TestNotification(object=build, request=req, user=user)
+        notify = TestNotification(context_object=build, request=req, user=user)
         backend = SiteBackend(request=req)
 
         self.assertEqual(PersistentMessage.objects.count(), 0)