Address PEP257 violations

.landscape.yml

@@ -1,12 +1,25 @@
 doc-warnings: true
 test-warnings: false
 strictness: veryhigh
+
 uses:
   - django
 python-targets:
   - 3
-pep8:
-  full: true
-max-line-length: 119
+
 ignore-paths:
+  - manage.py
+  - runserver
+ignore-patterns:
   - ^openach/migrations/.*\.py$
+
+requirements:
+  - requirements.txt
+autodetect: true
+
+max-line-length: 119
+pep8:
+  full: true
+pep257:
+    disable:
+        - D203

conf.py

@@ -1,2 +1,7 @@
+"""Configuration for the gunicorn server.
+
+For more information, please see:
+    http://docs.gunicorn.org/en/stable/configure.html#configuration-file
+"""
 import gunicorn
 gunicorn.SERVER_SOFTWARE = 'gunicorn'

manage.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python
-""" Django's command-line utility for administrative tasks
+"""Django's command-line utility for administrative tasks.
 
 For more information, please see:
     https://docs.djangoproject.com/en/1.10/ref/django-admin/

openach/__init__.py

@@ -0,0 +1 @@
+"""Analysis of Competing Hypotheses Django application module."""

openach/admin.py

@@ -1,4 +1,4 @@
-"""openach Admin Dashboard Configuration
+"""openach Admin Dashboard Configuration.
 
 For more information, please see:
     https://docs.djangoproject.com/en/1.10/ref/contrib/admin/
@@ -9,19 +9,22 @@
 
 
 class HypothesisInline(admin.StackedInline):
-    """Inline editor for an ACH board's hypotheses"""
+    """Inline editor for an ACH board's hypotheses."""
+
     model = Hypothesis
     extra = 2
 
 
 class EvidenceInline(admin.StackedInline):
-    """Inline editor for an ACH board's evidence"""
+    """Inline editor for an ACH board's evidence."""
+
     model = Evidence
     extra = 2
 
 
 class BoardAdmin(admin.ModelAdmin):
-    """Admin interface for editing ACH boards"""
+    """Admin interface for editing ACH boards."""
+
     inlines = [HypothesisInline, EvidenceInline]
 
 

openach/apps.py

@@ -1,4 +1,4 @@
-"""openach Application Configuration
+"""openach Application Configuration.
 
 For more information, please see:
     https://docs.djangoproject.com/en/1.10/ref/applications/
@@ -12,4 +12,5 @@ class OpenachConfig(AppConfig):
     For more information, please see:
         https://docs.djangoproject.com/en/1.10/ref/applications/
     """
+
     name = 'openach'

openach/context_processors.py

@@ -1,9 +1,9 @@
-"""Django template context processors"""
+"""Django template context processors."""
 from django.contrib.sites.models import Site
 
 
 def site(dummy_request):
-    """Returns a template context with the current site as 'site'"""
+    """Return a template context with the current site as 'site'."""
     # NOTE: get_current caches the result from the db
     # See: https://docs.djangoproject.com/en/1.10/ref/contrib/sites/#caching-the-current-site-object
     return {'site': Site.objects.get_current()}

openach/decorators.py

@@ -1,5 +1,4 @@
-"""View decorators for managing caching and authorization"""
-
+"""Analysis of Competing Hypotheses View Decorators for managing caching and authorization."""
 from functools import wraps
 
 from django.views.decorators.cache import cache_page
@@ -13,9 +12,10 @@
 
 
 def account_required(function=None, redirect_field_name=REDIRECT_FIELD_NAME, login_url=None):
-    """
-    Decorator for views that checks that (1) the user is logged in or (2) that an account is not required, redirecting
-    to the log-in page if necessary. See also django.contrib.auth.decorators.login_required
+    """Require that the (1) the user is logged in, or (2) that an account is not required to view the page.
+
+    If the user fails the test, redirect the user to the log-in page. See also
+    django.contrib.auth.decorators.login_required
     """
     actual_decorator = user_passes_test(
         lambda u: not ACCOUNT_REQUIRED or u.is_authenticated(),
@@ -28,21 +28,22 @@ def account_required(function=None, redirect_field_name=REDIRECT_FIELD_NAME, log
 
 
 def cache_on_auth(timeout):
-    """
-    Cache the response based on whether or not the user is authenticated. Should NOT be used on pages that have
-    user-specific information, e.g., CSRF tokens.
+    """Cache the response based on whether or not the user is authenticated.
+
+    Do NOT use on views that include user-specific information, e.g., CSRF tokens.
     """
     # https://stackoverflow.com/questions/11661503/django-caching-for-authenticated-users-only
     def _decorator(view_func):
         @wraps(view_func, assigned=available_attrs(view_func))
         def _wrapped_view(request, *args, **kwargs):
-            return cache_page(timeout, key_prefix="_auth_%s_" % request.user.is_authenticated())(view_func)(request, *args, **kwargs)
+            key_prefix = "_auth_%s_" % request.user.is_authenticated()
+            return cache_page(timeout, key_prefix=key_prefix)(view_func)(request, *args, **kwargs)
         return _wrapped_view
     return _decorator
 
 
 def cache_if_anon(timeout):
-    """Cache the page if the user is not authenticated and there are no messages to display."""
+    """Cache the view if the user is not authenticated and there are no messages to display."""
     # https://stackoverflow.com/questions/11661503/django-caching-for-authenticated-users-only
     def _decorator(view_func):
         @wraps(view_func, assigned=available_attrs(view_func))

openach/management/__init__.py

@@ -0,0 +1 @@
+"""Analysis of Competing Hypotheses Django application management features."""

openach/management/commands/__init__.py

@@ -0,0 +1 @@
+"""Analysis of Competing Hypotheses Django application management commands."""

openach/management/commands/createadmin.py

@@ -1,14 +1,19 @@
-"""Django admin command to create an admin account based on environment variables"""
+"""Django admin command to create an admin account based on the project settings."""
 from django.core.management.base import BaseCommand, CommandError
 from django.conf import settings
 from django.contrib.auth.models import User
 
 
 class Command(BaseCommand):
-    """Django admin command to create an admin account based on environment variables"""
+    """Django admin command to create an admin account based on the project settings variables.
+
+    Requires the following settings: ADMIN_USERNAME, ADMIN_PASSWORD, ADMIN_EMAIL_ADDRESS.
+    """
+
     help = 'Automatically create superuser based on environment variables.'
 
     def handle(self, *args, **options):
+        """Handle the command invocation."""
         email = getattr(settings, 'ADMIN_EMAIL_ADDRESS', None)
         username = getattr(settings, 'ADMIN_USERNAME', None)
         password = getattr(settings, 'ADMIN_PASSWORD', None)

openach/management/commands/setname.py

@@ -1,14 +1,23 @@
-"""Django admin command to set the site from the environment"""
+"""Django admin command to set the site from the project settings.
+
+For more information, please see:
+    https://docs.djangoproject.com/en/1.10/ref/contrib/sites/
+"""
 from django.core.management.base import BaseCommand, CommandError
 from django.contrib.sites.models import Site
 from django.conf import settings
 
 
 class Command(BaseCommand):
-    """Django admin command to set the site from the environment"""
+    """Django admin command to set the site from the project settings.
+
+    Requires the following settings: SITE_ID, SITE_NAME, and SITE_DOMAIN.
+    """
+
     help = 'Sets the site name and domain from the environment'
 
     def handle(self, *args, **options):
+        """Handle the command invocation."""
         site_id = getattr(settings, 'SITE_ID', None)
         site_name = getattr(settings, 'SITE_NAME', None)
         site_domain = getattr(settings, 'SITE_DOMAIN', None)

openach/metrics.py

@@ -1,14 +1,14 @@
-"""ACH Board Metrics"""
+"""Analysis of Competing Hypotheses Board Metrics."""
 import statistics
 
 from .util import partition
 from .models import Eval
 
 
 def mean_na_neutral_vote(evaluations):
-    """
-    Returns the mean rating on a 1-5 scale for the given evaluations, or None if there are no evaluations. Treats N/As
-    as a neutral vote.
+    """Return the mean rating on a 1-5 scale for the given evaluation, or None if there are no evaluations.
+
+    Treats N/As as a neutral vote.
     """
     # NOTE: 'map' preferred to list comprehension here because the predicate is complicated
     def _replace_na(eval_):
@@ -17,9 +17,9 @@ def _replace_na(eval_):
 
 
 def calc_disagreement(evaluations):
-    """
-    Determine the disagreement for a set of evaluations. Determined as the max disagreement of (1) N/A and non-N/A
-    responses and (2) non-N/A evaluations
+    """Return the disagreement level for evaluations, or None if no evaluations.
+
+    Calculated as the max disagreement of (1) N/A and non-N/A responses and (2) non-N/A evaluations
     :param evaluations: an iterable of Eval
     """
     if evaluations:
@@ -44,10 +44,11 @@ def calc_disagreement(evaluations):
 
 
 def consensus_vote(evaluations):
-    """
-    Determine the consensus Eval given an iterable of Eval. (1) whether or not the evidence is applicable, and
-    (2) if the evidence is applicable, how consistent the evidence is with the hypothesis. Is conservative, adjusting
-    the result toward Eval.neutral if there is a "tie".
+    """Return the consensus evaluation given a an iterable of evaluations, or None if no evaluations.
+
+    Calculated as (1) whether or not the evidence is applicable, and (2) if the evidence is applicable, how consistent
+    the evidence is with the hypothesis. The calculation is conservative, rounding the result toward Eval.neutral
+    if there is a tie.
     """
     na_it, rated_it = partition(lambda x: x is not Eval.not_applicable, evaluations)
     na_votes = list(na_it)
@@ -63,12 +64,12 @@ def consensus_vote(evaluations):
 
 
 def inconsistency(evaluations):
-    """
-    Calculate a metric for the inconsistency of a hypothesis with respect to a set of evidence. Does not account for
-    the reliability of the evidence (e.g., due to deception). Metric is monotonic in the number of pieces of evidence
-    that have been evaluated. That is, for a given hypothesis, further evidence can only serve to refute it (though
-    it may make the hypothesis more likely relative to the other hypotheses).
-    :param evaluations: an iterable of sets of Eval for the hypothesis
+    """Return the inconsistency of a hypothesis with respect to a set of evidence.
+
+    Calculation does not account for the reliability of the evidence (e.g., due to deception). Metric is monotonic in
+    the number of pieces of evidence that have been evaluated. That is, for a given hypothesis, further evidence can
+    only serve to refute it (though it may make the hypothesis more likely relative to the other hypotheses).
+    :param evaluations: an iterable of iterables of Eval for a hypothesis
     """
     # The "inconsistency" needs to capture the extent to which a hypothesis has been refuted. The approach below
     # computes a metric similar to "sum squared error" for evidence where the consensus is that the hypotheses is
@@ -80,9 +81,9 @@ def inconsistency(evaluations):
 
 
 def diagnosticity(evaluations):
-    """
-    Calculate the diagnosticity of a piece of evidence given its evaluation vs. a set of hypotheses.
-    :param evaluations: an iterable of sets of Eval for a piece of evidence
+    """Return the diagnosticity of a piece of evidence given its evaluations against a set of hypotheses.
+
+    :param evaluations: an iterable of iterables of Eval for a piece of evidence
     """
     # The "diagnosticity" needs to capture how well the evidence separates/distinguishes the hypotheses. If we don't
     # show a preference between consistent/inconsistent, STDDEV captures this intuition OK. However, in the future,