Merge branch 'dev'

Miguel Barão
2 parents 23b96245 aec96ca5
Showing 4 changed files with 268 additions and 225 deletions Show diff stats
demo/demo.yaml
perguntations/questions.py
perguntations/templates/test.html
perguntations/test.py
@@ -21,7 +21,7 @@ title: Teste de demonstração (tutorial)
 # Duration in minutes.
 # (0 or undefined means infinite time)
-duration: 10
+duration: 2
 autosubmit: true
 # Show points for each question, scale 0-20.
+'''
+Classes the implement several types of questions.
+'''
+
 # python standard library
 import asyncio
+import logging
 import random
 import re
 from os import path
-import logging
 from typing import Any, Dict, NewType
 import uuid
@@ -19,7 +23,7 @@ QDict = NewType(&#39;QDict&#39;, Dict[str, Any])
 class QuestionException(Exception):
-    pass
+    '''Exceptions raised in this module'''
 # ============================================================================
@@ -45,16 +49,18 @@ class Question(dict):
             }))
     def correct(self) -> None:
+        '''default correction (synchronous version)'''
         self['comments'] = ''
         self['grade'] = 0.0
     async def correct_async(self) -> None:
+        '''default correction (async version)'''
         self.correct()
-    def set_defaults(self, d: QDict) -> None:
-        'Add k:v pairs from default dict d for nonexistent keys'
-        for k, v in d.items():
-            self.setdefault(k, v)
+    def set_defaults(self, qdict: QDict) -> None:
+        '''Add k:v pairs from default dict d for nonexistent keys'''
+        for k, val in qdict.items():
+            self.setdefault(k, val)
 # ============================================================================
@@ -74,31 +80,31 @@ class QuestionRadio(Question):
     def __init__(self, q: QDict) -> None:
         super().__init__(q)
-        n = len(self['options'])
+        nopts = len(self['options'])
         self.set_defaults(QDict({
             'text': '',
             'correct': 0,
             'shuffle': True,
             'discount': True,
-            'max_tries': (n + 3) // 4  # 1 try for each 4 options
+            'max_tries': (nopts + 3) // 4  # 1 try for each 4 options
             }))
         # check correct bounds and convert int to list,
         # e.g.  correct: 2 --> correct: [0,0,1,0,0]
         if isinstance(self['correct'], int):
-            if not (0 <= self['correct'] < n):
-                msg = (f'Correct option not in range 0..{n-1} in '
+            if not 0 <= self['correct'] < nopts:
+                msg = (f'Correct option not in range 0..{nopts-1} in '
                        f'"{self["ref"]}"')
                 raise QuestionException(msg)
             self['correct'] = [1.0 if x == self['correct'] else 0.0
-                               for x in range(n)]
+                               for x in range(nopts)]
         elif isinstance(self['correct'], list):
             # must match number of options
-            if len(self['correct']) != n:
-                msg = (f'Incompatible sizes: {n} options vs '
+            if len(self['correct']) != nopts:
+                msg = (f'Incompatible sizes: {nopts} options vs '
                        f'{len(self["correct"])} correct in "{self["ref"]}"')
                 raise QuestionException(msg)
             # make sure is a list of floats
@@ -126,16 +132,16 @@ class QuestionRadio(Question):
         # otherwise, select 1 correct and choose a few wrong ones
         if self['shuffle']:
             # lists with indices of right and wrong options
-            right = [i for i in range(n) if self['correct'][i] >= 1]
-            wrong = [i for i in range(n) if self['correct'][i] < 1]
+            right = [i for i in range(nopts) if self['correct'][i] >= 1]
+            wrong = [i for i in range(nopts) if self['correct'][i] < 1]
             self.set_defaults(QDict({'choose': 1+len(wrong)}))
             # try to choose 1 correct option
             if right:
-                r = random.choice(right)
-                options = [self['options'][r]]
-                correct = [self['correct'][r]]
+                sel = random.choice(right)
+                options = [self['options'][sel]]
+                correct = [self['correct'][sel]]
             else:
                 options = []
                 correct = []
@@ -157,15 +163,15 @@ class QuestionRadio(Question):
         super().correct()
         if self['answer'] is not None:
-            x = self['correct'][int(self['answer'])]  # get grade of the answer
-            n = len(self['options'])
-            x_aver = sum(self['correct']) / n  # expected value of grade
+            grade = self['correct'][int(self['answer'])]  # grade of the answer
+            nopts = len(self['options'])
+            grade_aver = sum(self['correct']) / nopts  # expected value
             # note: there are no numerical errors when summing 1.0s so the
             #       x_aver can be exactly 1.0 if all options are right
-            if self['discount'] and x_aver != 1.0:
-                x = (x - x_aver) / (1.0 - x_aver)
-            self['grade'] = x
+            if self['discount'] and grade_aver != 1.0:
+                grade = (grade - grade_aver) / (1.0 - grade_aver)
+            self['grade'] = grade
 # ============================================================================
@@ -185,16 +191,16 @@ class QuestionCheckbox(Question):
     def __init__(self, q: QDict) -> None:
         super().__init__(q)
-        n = len(self['options'])
+        nopts = len(self['options'])
         # set defaults if missing
         self.set_defaults(QDict({
             'text': '',
-            'correct': [1.0] * n,     # Using 0.0 breaks (right, wrong) options
+            'correct': [1.0] * nopts,  # Using 0.0 breaks (right, wrong)
             'shuffle': True,
             'discount': True,
-            'choose': n,              # number of options
-            'max_tries': max(1, min(n - 1, 3))
+            'choose': nopts,              # number of options
+            'max_tries': max(1, min(nopts - 1, 3))
             }))
         # must be a list of numbers
@@ -203,8 +209,8 @@ class QuestionCheckbox(Question):
             raise QuestionException(msg)
         # must match number of options
-        if len(self['correct']) != n:
-            msg = (f'Incompatible sizes: {n} options vs '
+        if len(self['correct']) != nopts:
+            msg = (f'Incompatible sizes: {nopts} options vs '
                    f'{len(self["correct"])} correct in "{self["ref"]}"')
             raise QuestionException(msg)
@@ -230,7 +236,7 @@ class QuestionCheckbox(Question):
             logger.warning(msg2)
             logger.warning(msg3)
             logger.warning(msg4)
-            logger.warning(f'please fix "{self["ref"]}"')
+            logger.warning('please fix "%s"', self["ref"])
             # normalize to [0,1]
             self['correct'] = [(x+1)/2 for x in self['correct']]
@@ -238,20 +244,19 @@ class QuestionCheckbox(Question):
         # if an option is a list of (right, wrong), pick one
         options = []
         correct = []
-        for o, c in zip(self['options'], self['correct']):
-            if isinstance(o, list):
-                r = random.randint(0, 1)
-                o = o[r]
-                if r == 1:
-                    # c = -c
-                    c = 1.0 - c
-            options.append(str(o))
-            correct.append(c)
+        for option, corr in zip(self['options'], self['correct']):
+            if isinstance(option, list):
+                sel = random.randint(0, 1)
+                option = option[sel]
+                if sel == 1:
+                    corr = 1.0 - corr
+            options.append(str(option))
+            correct.append(corr)
         # generate random permutation, e.g. [2,1,4,0,3]
         # and apply to `options` and `correct`
         if self['shuffle']:
-            perm = random.sample(range(n), k=self['choose'])
+            perm = random.sample(range(nopts), k=self['choose'])
             self['options'] = [options[i] for i in perm]
             self['correct'] = [correct[i] for i in perm]
         else:
@@ -264,18 +269,18 @@ class QuestionCheckbox(Question):
         super().correct()
         if self['answer'] is not None:
-            x = 0.0
+            grade = 0.0
             if self['discount']:
                 sum_abs = sum(abs(2*p-1) for p in self['correct'])
-                for i, p in enumerate(self['correct']):
-                    x += 2*p-1 if str(i) in self['answer'] else 1-2*p
+                for i, pts in enumerate(self['correct']):
+                    grade += 2*pts-1 if str(i) in self['answer'] else 1-2*pts
             else:
                 sum_abs = sum(abs(p) for p in self['correct'])
-                for i, p in enumerate(self['correct']):
-                    x += p if str(i) in self['answer'] else 0.0
+                for i, pts in enumerate(self['correct']):
+                    grade += pts if str(i) in self['answer'] else 0.0
             try:
-                self['grade'] = x / sum_abs
+                self['grade'] = grade / sum_abs
             except ZeroDivisionError:
                 self['grade'] = 1.0   # limit p->0
@@ -306,33 +311,35 @@ class QuestionText(Question):
             # make sure all elements of the list are strings
             self['correct'] = [str(a) for a in self['correct']]
-        for f in self['transform']:
-            if f not in ('remove_space', 'trim', 'normalize_space', 'lower',
-                         'upper'):
-                msg = (f'Unknown transform "{f}" in "{self["ref"]}"')
+        for transform in self['transform']:
+            if transform not in ('remove_space', 'trim', 'normalize_space',
+                                 'lower', 'upper'):
+                msg = (f'Unknown transform "{transform}" in "{self["ref"]}"')
                 raise QuestionException(msg)
         # check if answers are invariant with respect to the transforms
         if any(c != self.transform(c) for c in self['correct']):
-            logger.warning(f'in "{self["ref"]}", correct answers are not '
-                           'invariant wrt transformations => never correct')
+            logger.warning('in "%s", correct answers are not invariant wrt '
+                           'transformations => never correct', self["ref"])
     # ------------------------------------------------------------------------
-    # apply optional filters to the answer
     def transform(self, ans):
-        for f in self['transform']:
-            if f == 'remove_space':  # removes all spaces
+        '''apply optional filters to the answer'''
+
+        for transform in self['transform']:
+            if transform == 'remove_space':  # removes all spaces
                 ans = ans.replace(' ', '')
-            elif f == 'trim':        # removes spaces around
+            elif transform == 'trim':        # removes spaces around
                 ans = ans.strip()
-            elif f == 'normalize_space':  # replaces multiple spaces by one
+            elif transform == 'normalize_space':  # replaces multiple spaces by one
                 ans = re.sub(r'\s+', ' ', ans.strip())
-            elif f == 'lower':       # convert to lowercase
+            elif transform == 'lower':       # convert to lowercase
                 ans = ans.lower()
-            elif f == 'upper':       # convert to uppercase
+            elif transform == 'upper':       # convert to uppercase
                 ans = ans.upper()
             else:
-                logger.warning(f'in "{self["ref"]}", unknown transform "{f}"')
+                logger.warning('in "%s", unknown transform "%s"',
+                               self["ref"], transform)
         return ans
     # ------------------------------------------------------------------------
@@ -381,14 +388,14 @@ class QuestionTextRegex(Question):
         super().correct()
         if self['answer'] is not None:
             self['grade'] = 0.0
-            for r in self['correct']:
+            for regex in self['correct']:
                 try:
-                    if r.match(self['answer']):
+                    if regex.match(self['answer']):
                         self['grade'] = 1.0
                         return
                 except TypeError:
-                    logger.error(f'While matching regex {r.pattern} with '
-                                 f'answer "{self["answer"]}".')
+                    logger.error('While matching regex %s with answer "%s".',
+                                 regex.pattern, self["answer"])
 # ============================================================================
@@ -485,21 +492,21 @@ class QuestionTextArea(Question):
                 )
             if out is None:
-                logger.warning(f'No grade after running "{self["correct"]}".')
+                logger.warning('No grade after running "%s".', self["correct"])
                 self['grade'] = 0.0
             elif isinstance(out, dict):
                 self['comments'] = out.get('comments', '')
                 try:
                     self['grade'] = float(out['grade'])
                 except ValueError:
-                    logger.error(f'Output error in "{self["correct"]}".')
+                    logger.error('Output error in "%s".', self["correct"])
                 except KeyError:
-                    logger.error(f'No grade in "{self["correct"]}".')
+                    logger.error('No grade in "%s".', self["correct"])
             else:
                 try:
                     self['grade'] = float(out)
                 except (TypeError, ValueError):
-                    logger.error(f'Invalid grade in "{self["correct"]}".')
+                    logger.error('Invalid grade in "%s".', self["correct"])
     # ------------------------------------------------------------------------
     async def correct_async(self) -> None:
@@ -514,25 +521,30 @@ class QuestionTextArea(Question):
                 )
             if out is None:
-                logger.warning(f'No grade after running "{self["correct"]}".')
+                logger.warning('No grade after running "%s".', self["correct"])
                 self['grade'] = 0.0
             elif isinstance(out, dict):
                 self['comments'] = out.get('comments', '')
                 try:
                     self['grade'] = float(out['grade'])
                 except ValueError:
-                    logger.error(f'Output error in "{self["correct"]}".')
+                    logger.error('Output error in "%s".', self["correct"])
                 except KeyError:
-                    logger.error(f'No grade in "{self["correct"]}".')
+                    logger.error('No grade in "%s".', self["correct"])
             else:
                 try:
                     self['grade'] = float(out)
                 except (TypeError, ValueError):
-                    logger.error(f'Invalid grade in "{self["correct"]}".')
+                    logger.error('Invalid grade in "%s".', self["correct"])
 # ============================================================================
 class QuestionInformation(Question):
+    '''
+    Not really a question, just an information panel.
+    The correction is always right.
+    '''
+
     # ------------------------------------------------------------------------
     def __init__(self, q: QDict) -> None:
         super().__init__(q)
@@ -547,38 +559,38 @@ class QuestionInformation(Question):
 # ============================================================================
-#
-# QFactory is a class that can generate question instances, e.g. by shuffling
-# options, running a script to generate the question, etc.
-#
-# To generate an instance of a question we use the method generate().
-# It returns a question instance of the correct class.
-# There is also an asynchronous version called gen_async(). This version is
-# synchronous for all question types (radio, checkbox, etc) except for
-# generator types which run asynchronously.
-#
-# Example:
-#
-#   # make a factory for a question
-#   qfactory = QFactory({
-#       'type': 'radio',
-#       'text': 'Choose one',
-#       'options': ['a', 'b']
-#       })
-#
-#   # generate synchronously
-#   question = qfactory.generate()
-#
-#   # generate asynchronously
-#   question = await qfactory.gen_async()
-#
-#   # answer one question and correct it
-#   question['answer'] = 42          # set answer
-#   question.correct()               # correct answer
-#   grade = question['grade']        # get grade
-#
-# ============================================================================
-class QFactory(object):
+class QFactory():
+    '''
+    QFactory is a class that can generate question instances, e.g. by shuffling
+    options, running a script to generate the question, etc.
+
+    To generate an instance of a question we use the method generate().
+    It returns a question instance of the correct class.
+    There is also an asynchronous version called gen_async(). This version is
+    synchronous for all question types (radio, checkbox, etc) except for
+    generator types which run asynchronously.
+
+    Example:
+
+      # make a factory for a question
+      qfactory = QFactory({
+          'type': 'radio',
+          'text': 'Choose one',
+          'options': ['a', 'b']
+          })
+
+      # generate synchronously
+      question = qfactory.generate()
+
+      # generate asynchronously
+      question = await qfactory.gen_async()
+
+      # answer one question and correct it
+      question['answer'] = 42          # set answer
+      question.correct()               # correct answer
+      grade = question['grade']        # get grade
+    '''
+
     # Depending on the type of question, a different question class will be
     # instantiated. All these classes derive from the base class `Question`.
     _types = {
@@ -599,44 +611,48 @@ class QFactory(object):
         self.question = qdict
     # ------------------------------------------------------------------------
-    # generates a question instance of QuestionRadio, QuestionCheckbox, ...,
-    # which is a descendent of base class Question.
-    # ------------------------------------------------------------------------
     async def gen_async(self) -> Question:
-        logger.debug(f'generating {self.question["ref"]}...')
+        '''
+        generates a question instance of QuestionRadio, QuestionCheckbox, ...,
+        which is a descendent of base class Question.
+        '''
+
+        logger.debug('generating %s...', self.question["ref"])
         # Shallow copy so that script generated questions will not replace
         # the original generators
-        q = self.question.copy()
-        q['qid'] = str(uuid.uuid4())  # unique for each generated question
+        question = self.question.copy()
+        question['qid'] = str(uuid.uuid4())  # unique for each question
         # If question is of generator type, an external program will be run
         # which will print a valid question in yaml format to stdout. This
         # output is then yaml parsed into a dictionary `q`.
-        if q['type'] == 'generator':
-            logger.debug(f' \\_ Running "{q["script"]}".')
-            q.setdefault('args', [])
-            q.setdefault('stdin', '')
-            script = path.join(q['path'], q['script'])
-            out = await run_script_async(script=script, args=q['args'],
-                                         stdin=q['stdin'])
-            q.update(out)
+        if question['type'] == 'generator':
+            logger.debug(' \\_ Running "%s".', question["script"])
+            question.setdefault('args', [])
+            question.setdefault('stdin', '')
+            script = path.join(question['path'], question['script'])
+            out = await run_script_async(script=script, args=question['args'],
+                                         stdin=question['stdin'])
+            question.update(out)
         # Get class for this question type
         try:
-            qclass = self._types[q['type']]
+            qclass = self._types[question['type']]
         except KeyError:
-            logger.error(f'Invalid type "{q["type"]}" in "{q["ref"]}"')
+            logger.error('Invalid type "%s" in "%s"',
+                         question["type"], question["ref"])
             raise
         # Finally create an instance of Question()
         try:
-            qinstance = qclass(QDict(q))
-        except QuestionException as e:
-            # logger.error(e)
-            raise e
+            qinstance = qclass(QDict(question))
+        except QuestionException:
+            logger.error('Error generating question %s', question['ref'])
+            raise
         return qinstance
     # ------------------------------------------------------------------------
     def generate(self) -> Question:
+        '''generate question (synchronous version)'''
         return asyncio.get_event_loop().run_until_complete(self.gen_async())
@@ -38,10 +38,9 @@
 <!-- My scripts -->
   <script defer src="/static/js/question_disabler.js"></script>
   <script defer src="/static/js/prevent_enter_submit.js"></script>
-
 </head>
 <!-- ===================================================================== -->
-<body id="test">
+<body>
 <!-- ===================================================================== -->
 <nav id="navbar" class="navbar navbar-expand-sm fixed-top navbar-dark bg-dark">
@@ -157,37 +156,32 @@
     $("#clock").html("+\u221e");
   {% else %}
-
-
-  // Update the count down every 1 second
-  var x = setInterval(function() {
-    var now = new Date().getTime();
-    var distance = finishtime - now;
-
-    // Time calculations for days, hours, minutes and seconds
-    var minutes = Math.floor((distance / (1000 * 60)));
-    var seconds = Math.floor((distance % (1000 * 60)) / 1000);
-
-    if (distance >= 1000*60) {
-      $("#clock").html(minutes + ":" + (seconds<10?'0':'') +seconds);
-    }
-    else if (distance >= 0) {
-      $("#navbar").removeClass('bg-dark').addClass("bg-danger");
-      $("#clock").html(seconds);
-    }
-    else {
-      $("#clock").html(0);
-      {% if t['autosubmit'] %}
-        $("#test").submit();
-      {% end %}
-    }
-  }, 1000);
+    // Update the count down every 1 second
+    var x = setInterval(function() {
+      var now = new Date().getTime();
+      var distance = finishtime - now;
+
+      // Time calculations for days, hours, minutes and seconds
+      var minutes = Math.floor((distance / (1000 * 60)));
+      var seconds = Math.floor((distance % (1000 * 60)) / 1000);
+
+      if (distance >= 1000*60) {
+        $("#clock").html(minutes + ":" + (seconds<10?'0':'') +seconds);
+      }
+      else if (distance >= 0) {
+        $("#navbar").removeClass('bg-dark').addClass("bg-danger");
+        $("#clock").html(seconds);
+      }
+      else {
+        $("#clock").html(0);
+        {% if t['autosubmit'] %}
+          $("#test").submit();
+        {% end %}
+      }
+    }, 1000);
   {% end %}
 </script>
-
-
-
 </body>
 </html>
+'''
+TestFactory - generates tests for students
+Test - instances of this class are individual tests
+'''
 # python standard library
@@ -7,7 +11,7 @@ from datetime import datetime
 import logging
 # this project
-from perguntations.questions import QFactory
+from perguntations.questions import QFactory, QuestionException
 from perguntations.tools import load_yaml
 # Logger configuration
@@ -16,7 +20,7 @@ logger = logging.getLogger(__name__)
 # ============================================================================
 class TestFactoryException(Exception):
-    pass
+    '''exception raised in this module'''
 # ============================================================================
@@ -27,7 +31,6 @@ class TestFactory(dict):
     instances of TestFactory(), one for each test.
     '''
-
     # ------------------------------------------------------------------------
     def __init__(self, conf):
         '''
@@ -120,30 +123,29 @@ class TestFactory(dict):
         if qmissing:
             raise TestFactoryException(f'Could not find questions {qmissing}.')
-    # ------------------------------------------------------------------------
-    def sanity_checks(self):
-        '''
-        Checks for valid keys and sets default values.
-        Also checks if some files and directories exist
-        '''
-        # --- ref
+    # ------------------------------------------------------------------------
+    def check_missing_ref(self):
+        '''Test must have a `ref`'''
         if 'ref' not in self:
             raise TestFactoryException('Missing "ref" in configuration!')
-        # --- check database
+    def check_missing_database(self):
+        '''Test must have a database'''
         if 'database' not in self:
             raise TestFactoryException('Missing "database" in configuration')
         if not path.isfile(path.expanduser(self['database'])):
             msg = f'Database "{self["database"]}" not found!'
             raise TestFactoryException(msg)
-        # --- check answers_dir
+    def check_missing_answers_directory(self):
+        '''Test must have a answers directory'''
         if 'answers_dir' not in self:
             msg = 'Missing "answers_dir" in configuration'
             raise TestFactoryException(msg)
-        # --- check if answers_dir is a writable directory
+    def check_answers_directory_writable(self):
+        '''Answers directory must be writable'''
         testfile = path.join(path.expanduser(self['answers_dir']), 'REMOVE-ME')
         try:
             with open(testfile, 'w') as file:
@@ -152,82 +154,105 @@ class TestFactory(dict):
             msg = f'Cannot write answers to directory "{self["answers_dir"]}"'
             raise TestFactoryException(msg)
-        # --- check title
-        if not self['title']:
-            logger.warning('Undefined title!')
-
-        if self['scale_points']:
-            smin, smax = self["scale_min"], self["scale_max"]
-            logger.info('Grades will be scaled to [%g, %g]', smin, smax)
-        else:
-            logger.info('Grades are just the sum of points defined for the '
-                        'questions, not being scaled.')
-
-        # --- questions_dir
+    def check_questions_directory(self):
+        '''Check if questions directory is missing or not accessible.'''
         if 'questions_dir' not in self:
-            logger.warning(f'Missing "questions_dir". '
-                           f'Using "{path.abspath(path.curdir)}"')
+            logger.warning('Missing "questions_dir". Using "%s"',
+                           path.abspath(path.curdir))
             self['questions_dir'] = path.curdir
         elif not path.isdir(path.expanduser(self['questions_dir'])):
             raise TestFactoryException(f'Can\'t find questions directory '
                                        f'"{self["questions_dir"]}"')
-        # --- files
+    def check_import_files(self):
+        '''Check if there are files to import (with questions)'''
         if 'files' not in self:
             msg = ('Missing "files" in configuration with the list of '
                    'question files to import!')
             raise TestFactoryException(msg)
-            # FIXME allow no files and define the questions directly in the test
         if isinstance(self['files'], str):
             self['files'] = [self['files']]
-        # --- questions
+    def check_question_list(self):
+        '''normalize question list'''
         if 'questions' not in self:
-            raise TestFactoryException(f'Missing "questions" in Configuration')
+            raise TestFactoryException('Missing "questions" in configuration')
-        for i, q in enumerate(self['questions']):
+        for i, question in enumerate(self['questions']):
             # normalize question to a dict and ref to a list of references
-            if isinstance(q, str):  # e.g.,    - some_ref
-                q = {'ref': [q]}    # becomes  - ref: [some_ref]
-            elif isinstance(q, dict) and isinstance(q['ref'], str):
-                q['ref'] = [q['ref']]
-            elif isinstance(q, list):
-                q = {'ref': [str(a) for a in q]}
+            if isinstance(question, str):  # e.g.,    - some_ref
+                question = {'ref': [question]}    # becomes  - ref: [some_ref]
+            elif isinstance(question, dict) and isinstance(question['ref'], str):
+                question['ref'] = [question['ref']]
+            elif isinstance(question, list):
+                question = {'ref': [str(a) for a in question]}
-            self['questions'][i] = q
+            self['questions'][i] = question
+
+    def check_missing_title(self):
+        '''Warns if title is missing'''
+        if not self['title']:
+            logger.warning('Title is undefined!')
+
+    def check_grade_scaling(self):
+        '''Just informs the scale limits'''
+        if self['scale_points']:
+            smin, smax = self["scale_min"], self["scale_max"]
+            logger.info('Grades will be scaled to [%g, %g]', smin, smax)
+        else:
+            logger.info('Grades are not being scaled.')
     # ------------------------------------------------------------------------
-    # Given a dictionary with a student dict {'name':'john', 'number': 123}
-    # returns instance of Test() for that particular student
+    def sanity_checks(self):
+        '''
+        Checks for valid keys and sets default values.
+        Also checks if some files and directories exist
+        '''
+        self.check_missing_ref()
+        self.check_missing_database()
+        self.check_missing_answers_directory()
+        self.check_answers_directory_writable()
+        self.check_questions_directory()
+        self.check_import_files()
+        self.check_question_list()
+        self.check_missing_title()
+        self.check_grade_scaling()
+
     # ------------------------------------------------------------------------
     async def generate(self, student):
+        '''
+        Given a dictionary with a student dict {'name':'john', 'number': 123}
+        returns instance of Test() for that particular student
+        '''
+
         # make list of questions
         test = []
-        n = 1     # track question number
+        qnum = 1     # track question number
         nerr = 0  # count errors generating questions
-        for qq in self['questions']:
+        for qlist in self['questions']:
             # choose one question variant
-            qref = random.choice(qq['ref'])
+            qref = random.choice(qlist['ref'])
             # generate instance of question
             try:
-                q = await self.question_factory[qref].gen_async()
-            except Exception:
-                logger.error(f'Can\'t generate question "{qref}". Skipping.')
+                question = await self.question_factory[qref].gen_async()
+            except QuestionException:
+                logger.error('Can\'t generate question "%s". Skipping.', qref)
                 nerr += 1
                 continue
             # some defaults
-            if q['type'] in ('information', 'success', 'warning', 'alert'):
-                q['points'] = qq.get('points', 0.0)
+            if question['type'] in ('information', 'success', 'warning',
+                                    'alert'):
+                question['points'] = qlist.get('points', 0.0)
             else:
-                q['points'] = qq.get('points', 1.0)
-                q['number'] = n  # counter for non informative panels
-                n += 1
+                question['points'] = qlist.get('points', 1.0)
+                question['number'] = qnum  # counter for non informative panels
+                qnum += 1
-            test.append(q)
+            test.append(question)
         # normalize question points to scale
         if self['scale_points']:
@@ -236,11 +261,11 @@ class TestFactory(dict):
                 logger.warning('Can\'t scale, total points in the test is 0!')
             else:
                 scale = (self['scale_max'] - self['scale_min']) / total_points
-                for q in test:
-                    q['points'] *= scale
+                for question in test:
+                    question['points'] *= scale
         if nerr > 0:
-            logger.error(f'{nerr} errors found!')
+            logger.error('%s errors found!', nerr)
         return Test({
             'ref': self['ref'],
@@ -267,9 +292,11 @@ class TestFactory(dict):
 # ============================================================================
-# Each instance Test() is a concrete test of a single student.
-# ============================================================================
 class Test(dict):
+    '''
+    Each instance Test() is a concrete test of a single student.
+    '''
+
     # ------------------------------------------------------------------------
     def __init__(self, d):
         super().__init__(d)
@@ -279,28 +306,33 @@ class Test(dict):
         self['comment'] = ''
     # ------------------------------------------------------------------------
-    # Removes all answers from the test (clean)
     def reset_answers(self):
-        for q in self['questions']:
-            q['answer'] = None
+        '''Removes all answers from the test (clean)'''
+        for question in self['questions']:
+            question['answer'] = None
     # ------------------------------------------------------------------------
-    # Given a dictionary ans={'ref': 'some answer'} updates the answers of the
-    # test. Only affects the questions referred in the dictionary.
     def update_answers(self, ans):
+        '''
+        Given a dictionary ans={'ref': 'some answer'} updates the answers of
+        the test. Only affects the questions referred in the dictionary.
+        '''
         for ref, answer in ans.items():
             self['questions'][ref]['answer'] = answer
     # ------------------------------------------------------------------------
-    # Corrects all the answers of the test and computes the final grade
     async def correct(self):
+        '''Corrects all the answers of the test and computes the final grade'''
+
         self['finish_time'] = datetime.now()
         self['state'] = 'FINISHED'
         grade = 0.0
-        for q in self['questions']:
-            await q.correct_async()
-            grade += q['grade'] * q['points']
-            logger.debug(f'Correcting {q["ref"]:>30}: {q["grade"]*100:4.0f}%')
+        for question in self['questions']:
+            await question.correct_async()
+            grade += question['grade'] * question['points']
+            # logger.debug(f'Correcting {q["ref"]:>30}: {q["grade"]*100:4.0f}%')
+            logger.debug('Correcting %30s: %3g%%',
+                         question["ref"], question["grade"]*100)
         # truncate to avoid negative grade and adjust scale
         self['grade'] = max(0.0, grade) + self['scale_min']
@@ -308,8 +340,9 @@ class Test(dict):
     # ------------------------------------------------------------------------
     def giveup(self):
+        '''Test is marqued as QUIT and is not corrected'''
         self['finish_time'] = datetime.now()
         self['state'] = 'QUIT'
         self['grade'] = 0.0
-        logger.info(f'Student {self["student"]["number"]}:  gave up.')
+        logger.info('Student %s:  gave up.', self["student"]["number"])
         return self['grade']
	@@ -21,7 +21,7 @@ title: Teste de demonstração (tutorial)		@@ -21,7 +21,7 @@ title: Teste de demonstração (tutorial)
21		21
22	# Duration in minutes.	22	# Duration in minutes.
23	# (0 or undefined means infinite time)	23	# (0 or undefined means infinite time)
24	-duration: 10	24	+duration: 2
25	autosubmit: true	25	autosubmit: true
26		26
27	# Show points for each question, scale 0-20.	27	# Show points for each question, scale 0-20.