Merge branch 'fix-576' into 'master'

Add mailinglist documentation

Closes #576

See merge request !1270

website/mailinglists/admin.py

@@ -5,20 +5,27 @@ from .models import ListAlias, MailingList, VerbatimAddress
 
 
 class VerbatimAddressInline(admin.TabularInline):
+    """Class to inline show the VerbatimAddress."""
+
     model = VerbatimAddress
 
 
 class ListAliasInline(admin.TabularInline):
+    """Class to inline show the ListAlias."""
+
     model = ListAlias
 
 
 @admin.register(MailingList)
 class MailingListAdmin(admin.ModelAdmin):
+    """Class to show the mailing lists in the admin."""
+
     filter_horizontal = ('members',)
     inlines = (VerbatimAddressInline, ListAliasInline)
     list_display = ('name', 'alias_names',)
     search_fields = ['name', 'prefix', 'aliasses__alias']
 
     def alias_names(self, obj):
+        """Return list of aliases of obj."""
         return [x.alias for x in obj.aliasses.all()]
     alias_names.short_description = _('List aliasses')

website/mailinglists/api/permissions.py

@@ -4,11 +4,10 @@ from rest_framework import permissions
 
 
 class MailingListPermission(permissions.BasePermission):
-    """
-    Permission check for mailing list secret key
-    """
+    """Permission check for mailing list secret key."""
 
     def has_permission(self, request, view):
+        """Return whether the user has access to the mailing list api."""
         if request.user.is_superuser:
             return True
 

website/mailinglists/api/serializers.py

@@ -4,7 +4,11 @@ from mailinglists.models import MailingList
 
 
 class MailingListSerializer(serializers.ModelSerializer):
+    """Serializer for serializing mailing lists."""
+
     class Meta:
+        """Meta class for the MailingListSerializer."""
+
         model = MailingList
         fields = ('names', 'prefix', 'archived', 'moderated', 'addresses',
                   'autoresponse_enabled', 'autoresponse_text')
@@ -13,7 +17,9 @@ class MailingListSerializer(serializers.ModelSerializer):
     addresses = serializers.SerializerMethodField('_addresses')
 
     def _names(self, instance):
+        """Return list of names of the the mailing list and its aliases."""
         return [instance.name] + [x.alias for x in instance.aliasses.all()]
 
     def _addresses(self, instance):
+        """Return list of all subscribed addresses."""
         return instance.all_addresses()

website/mailinglists/api/viewsets.py

@@ -7,11 +7,14 @@ from mailinglists.models import MailingList
 
 
 class MailingListViewset(viewsets.ReadOnlyModelViewSet):
+    """Viewswet class for mailing lists."""
+
     permission_classes = [MailingListPermission]
     queryset = MailingList.objects.all()
     serializer_class = MailingListSerializer
 
     def list(self, request, *args, **kwargs):
+        """Return response with a list of serialized mailing lists."""
         response = super().list(request, *args, **kwargs)
         automatic_lists = services.get_automatic_lists()
         if automatic_lists is not None:

website/mailinglists/apps.py

@@ -3,5 +3,7 @@ from django.utils.translation import gettext_lazy as _
 
 
 class MailinglistsConfig(AppConfig):
+    """Appconfig for mailinglist app."""
+
     name = 'mailinglists'
     verbose_name = _('Mailing lists')

website/mailinglists/models.py

@@ -10,6 +10,7 @@ from utils.snippets import datetime_to_lectureyear
 
 
 def get_automatic_mailinglists():
+    """Return mailing list names that should be generated automatically."""
     lectureyear = datetime_to_lectureyear(timezone.now())
     list_names = ['leden', 'members', 'begunstigers', 'benefactors',
                   'ereleden', 'honorary', 'mentors', 'activemembers',
@@ -26,6 +27,8 @@ def get_automatic_mailinglists():
 
 
 class MailingList(models.Model):
+    """Model describing mailing lists."""
+
     name = models.CharField(
         verbose_name=_("Name"),
         max_length=100,
@@ -84,6 +87,7 @@ class MailingList(models.Model):
     )
 
     def all_addresses(self):
+        """Return all addresses subscribed to this mailing list."""
         for member in self.members.all():
             yield member.email
 
@@ -96,6 +100,7 @@ class MailingList(models.Model):
             yield verbatimaddress.address
 
     def clean(self):
+        """Validate the mailing list."""
         super().clean()
         if (ListAlias.objects
                 .filter(alias=self.name).count() > 0 or
@@ -114,10 +119,13 @@ class MailingList(models.Model):
             })
 
     def __str__(self):
+        """Return the name of the mailing list."""
         return self.name
 
 
 class VerbatimAddress(models.Model):
+    """Model that describes an email address subscribed to a mailing list."""
+
     address = models.EmailField(
         verbose_name=_("Email address"),
         help_text=_('Enter an explicit email address to include in the list.'),
@@ -129,14 +137,19 @@ class VerbatimAddress(models.Model):
                                     related_name='addresses')
 
     def __str__(self):
+        """Return the address."""
         return self.address
 
     class Meta:
+        """Meta class for VerbatimAddress."""
+
         verbose_name = _("Verbatim address")
         verbose_name_plural = _("Verbatim addresses")
 
 
 class ListAlias(models.Model):
+    """Model describing an alias of a mailing list."""
+
     alias = models.CharField(
         verbose_name=_("Alternative name"),
         max_length=100,
@@ -153,6 +166,7 @@ class ListAlias(models.Model):
                                     related_name='aliasses')
 
     def clean(self):
+        """Validate the alias."""
         super().clean()
         if (MailingList.objects
                 .filter(name=self.alias).count() > 0 or
@@ -166,10 +180,13 @@ class ListAlias(models.Model):
             })
 
     def __str__(self):
+        """Return a string representation of the alias and mailing list."""
         return (_("List alias {alias} for {list}")
                 .format(alias=self.alias,
                         list=self.mailinglist.name))
 
     class Meta:
+        """Meta class for ListAlias."""
+
         verbose_name = _("List alias")
         verbose_name_plural = _("List aliasses")

website/mailinglists/services.py

@@ -7,6 +7,7 @@ from utils.snippets import datetime_to_lectureyear
 
 
 def get_automatic_lists():
+    """Return list of mailing lists that should be generated automatically."""
     current_committee_chairs = (MemberGroupMembership.active_objects
                                 .filter(group__board=None)
                                 .filter(group__society=None)