- new generator question in demo.yaml

- fix grade format in logs - fix many pyyaml warnings - rewrite run_script and run_script_async

- new generator question in demo.yaml
- fix grade format in logs - fix many pyyaml warnings - rewrite run_script and run_script_async
Miguel Barão
1 parent 1323bb4d
Showing 9 changed files with 263 additions and 171 deletions Show diff stats
demo/demo.yaml
demo/questions/generators/generate-question.py
demo/questions/questions-tutorial.yaml
perguntations/app.py
perguntations/initdb.py
perguntations/models.py
perguntations/parser_markdown.py
perguntations/serve.py
perguntations/tools.py
@@ -65,7 +65,7 @@ questions:
   - tut-success
   - tut-warning
   - tut-alert
-
+  - tut-generator
 # test:
 #   - ref1
 #!/usr/bin/env python3
+'''
+Example of a question generator.
+Arguments are read from stdin.
+'''
+
 from random import randint
 import sys
-arg = sys.stdin.read()  # read arguments
+a, b = (int(n) for n in sys.argv[1:])
-a, b = (int(n) for n in arg.split(','))
+x = randint(a, b)
+y = randint(a, b)
+r = x + y
-q = f'''---
-type: checkbox
+print(f"""---
+type: text
+title: Geradores de perguntas
 text: |
-  Indique quais das seguintes adições resultam em overflow quando se considera
-  a adição de números com sinal (complemento para 2) em registos de 8 bits.
+  Existe a possibilidade da pergunta ser gerada por um programa externo.
+  Este programa deve escrever no `stdout` uma pergunta em formato `yaml` como
+  os anteriores. Pode também receber argumentos para parametrizar a geração da
+  pergunta. Aqui está um exemplo de uma pergunta gerada por um script python:
-  Os números foram gerados aleatoriamente no intervalo de {a} a {b}.
-options:
-'''
+  ```python
+      #!/usr/bin/env python3
+
+      from random import randint
+      import sys
+
+      a, b = (int(n) for n in sys.argv[1:])   # argumentos da linha de comando
-correct = []
-for i in range(5):
-    x = randint(a, b)
-    y = randint(a, b)
-    q += f'  - "`{x} + {y}`"\n'
-    correct.append(1 if x + y > 127 else -1)
+      x = randint(a, b)
+      y = randint(a, b)
+      r = x + y
-q += 'correct: ' + str(correct)
+      print(f'''---
+      type: text
+      title: Contas de somar
+      text: |
+        bla bla bla
+      correct: '{{r}}'
+      solution: |
+        A solução é {{r}}.''')
+  ```
-print(q)
+  Este script deve ter permissões para poder ser executado no terminal. Dá
+  jeito usar o comando `gen-somar.py 1 100 | yamllint -` para validar o `yaml`
+  gerado.
+
+  Para indicar que uma pergunta é gerada externamente, esta é declarada com
+
+  ```yaml
+      - type: generator
+        ref: gen-somar
+        script: gen-somar.py
+        # opcional
+        args: [1, 100]
+  ```
+
+  Os argumentos `args` são opcionais e são passados para o programa como
+  argumentos da linha de comando.
+
+  ---
+
+  Calcule o resultado de ${x} + {y}$.
+
+  Os números foram gerados aleatoriamente no intervalo de {a} a {b}.
+correct: '{r}'
+solution: |
+  A solução é {r}.""")
@@ -22,6 +22,7 @@
     # opcional
     duration: 60               # duração da prova em minutos (default: inf)
+    autosubmit: true           # submissão automática (default: false)
     show_points: true          # mostra cotação das perguntas (default: true)
     scale_points: true         # recalcula cotações para [scale_min, scale_max]
     scale_max: 20              # limite superior da escala (default: 20)
@@ -159,11 +160,10 @@
       shuffle: false
     ```
-    Por defeito, as respostas erradas descontam, tendo uma cotação de -1/(n-1)
-    do valor da pergunta, onde n é o número de opções apresentadas ao aluno
-    (a ideia é o valor esperado ser zero quando as respostas são aleatórias e
-    uniformemente distribuídas).
-    Para não descontar acrescenta-se:
+    Por defeito, as respostas erradas descontam, tendo uma cotação de
+    $-1/(n-1)$ do valor da pergunta, onde $n$ é o número de opções apresentadas
+    ao aluno (a ideia é o valor esperado ser zero quando as respostas são
+    aleatórias e uniformemente distribuídas). Para não descontar acrescenta-se:
     ```yaml
       discount: false
@@ -561,3 +561,7 @@
     Indices start at 0.
 # ----------------------------------------------------------------------------
+- type: generator
+  ref: tut-generator
+  script: generators/generate-question.py
+  args: [1, 100]
@@ -193,7 +193,7 @@ class App():
         logger.info('Student %s: %d answers submitted.', uid, len(ans))
         grade = await test.correct()
-        logger.info('Student %s: grade = %.1g points.', uid, grade)
+        logger.info('Student %s: grade = %g points.', uid, grade)
         # --- save test in JSON format
         fields = (uid, test['ref'], str(test['finish_time']))
 #!/usr/bin/env python3
+'''
+Commandline utilizty to initialize and update student database
+'''
+
 # base
 import csv
 import argparse
@@ -16,8 +20,8 @@ from perguntations.models import Base, Student
 # ===========================================================================
-#   Parse command line options
 def parse_commandline_arguments():
+    '''Parse command line options'''
     parser = argparse.ArgumentParser(
         formatter_class=argparse.ArgumentDefaultsHelpFormatter,
         description='Insert new users into a database. Users can be imported '
@@ -65,9 +69,11 @@ def parse_commandline_arguments():
 # ===========================================================================
-# SIIUE names have alien strings like "(TE)" and are sometimes capitalized
-# We remove them so that students dont keep asking what it means
 def get_students_from_csv(filename):
+    '''
+    SIIUE names have alien strings like "(TE)" and are sometimes capitalized
+    We remove them so that students dont keep asking what it means
+    '''
     csv_settings = {
         'delimiter': ';',
         'quotechar': '"',
@@ -75,8 +81,8 @@ def get_students_from_csv(filename):
         }
     try:
-        with open(filename, encoding='iso-8859-1') as f:
-            csvreader = csv.DictReader(f, **csv_settings)
+        with open(filename, encoding='iso-8859-1') as file:
+            csvreader = csv.DictReader(file, **csv_settings)
             students = [{
                 'uid': s['N.º'],
                 'name': capwords(re.sub(r'\(.*\)', '', s['Nome']).strip())
@@ -92,20 +98,22 @@ def get_students_from_csv(filename):
 # ===========================================================================
-# replace password by hash for a single student
-def hashpw(student, pw=None):
+def hashpw(student, password=None):
+    '''replace password by hash for a single student'''
     print('.', end='', flush=True)
-    if pw is None:
+    if password is None:
         student['pw'] = ''
     else:
-        student['pw'] = bcrypt.hashpw(pw.encode('utf-8'), bcrypt.gensalt())
+        student['pw'] = bcrypt.hashpw(password.encode('utf-8'),
+                                      bcrypt.gensalt())
 # ===========================================================================
 def insert_students_into_db(session, students):
+    '''insert list of students into the database'''
     try:
         session.add_all([Student(id=s['uid'], name=s['name'], password=s['pw'])
-                        for s in students])
+                         for s in students])
         session.commit()
     except sa.exc.IntegrityError:
@@ -115,33 +123,33 @@ def insert_students_into_db(session, students):
 # ============================================================================
 def show_students_in_database(session, verbose=False):
-    try:
-        users = session.query(Student).all()
-    except Exception:
-        raise
+    '''get students from database'''
+    users = session.query(Student).all()
+
+    total_users = len(users)
+    print('Registered users:')
+    if total_users == 0:
+        print('  -- none --')
     else:
-        n = len(users)
-        print(f'Registered users:')
-        if n == 0:
-            print('  -- none --')
+        users.sort(key=lambda u: f'{u.id:>12}')  # sort by number
+        if verbose:
+            for user in users:
+                print(f'{user.id:>12}   {user.name}')
         else:
-            users.sort(key=lambda u: f'{u.id:>12}')  # sort by number
-            if verbose:
-                for u in users:
-                    print(f'{u.id:>12}   {u.name}')
-            else:
-                print(f'{users[0].id:>12}   {users[0].name}')
-                if n > 1:
-                    print(f'{users[1].id:>12}   {users[1].name}')
-                if n > 3:
-                    print('           |   |')
-                if n > 2:
-                    print(f'{users[-1].id:>12}   {users[-1].name}')
-        print(f'Total: {n}.')
+            print(f'{users[0].id:>12}   {users[0].name}')
+            if total_users > 1:
+                print(f'{users[1].id:>12}   {users[1].name}')
+            if total_users > 3:
+                print('           |   |')
+            if total_users > 2:
+                print(f'{users[-1].id:>12}   {users[-1].name}')
+    print(f'Total: {total_users}.')
 # ============================================================================
 def main():
+    '''insert, update, show students from database'''
+
     args = parse_commandline_arguments()
     # --- make list of students to insert/update
@@ -162,27 +170,27 @@ def main():
     # --- password hashing
     if students:
-        print(f'Generating password hashes', end='')
+        print('Generating password hashes', end='')
         with ThreadPoolExecutor() as executor:  # hashing in parallel
             executor.map(lambda s: hashpw(s, args.pw), students)
         print()
     # --- database stuff
-    print(f'Using database: ', args.db)
+    print(f'Using database: {args.db}')
     engine = sa.create_engine(f'sqlite:///{args.db}', echo=False)
     Base.metadata.create_all(engine)  # Criates schema if needed
-    Session = sa.orm.sessionmaker(bind=engine)
-    session = Session()
+    SessionMaker = sa.orm.sessionmaker(bind=engine)
+    session = SessionMaker()
     if students:
         print(f'Inserting {len(students)}')
         insert_students_into_db(session, students)
-    for s in args.update:
-        print(f'Updating password of: {s}')
-        u = session.query(Student).get(s)
-        pw = (args.pw or s).encode('utf-8')
-        u.password = bcrypt.hashpw(pw, bcrypt.gensalt())
+    for student_id in args.update:
+        print(f'Updating password of: {student_id}')
+        student = session.query(Student).get(student_id)
+        password = (args.pw or student_id).encode('utf-8')
+        student.password = bcrypt.hashpw(password, bcrypt.gensalt())
         session.commit()
     show_students_in_database(session, args.verbose)
+'''
+Database tables
+'''
+
 from sqlalchemy import Column, ForeignKey, Integer, Float, String
 from sqlalchemy.ext.declarative import declarative_base
@@ -11,6 +15,7 @@ Base = declarative_base()
 # ----------------------------------------------------------------------------
 class Student(Base):
+    '''Student table'''
     __tablename__ = 'students'
     id = Column(String, primary_key=True)
     name = Column(String)
@@ -29,6 +34,7 @@ class Student(Base):
 # ----------------------------------------------------------------------------
 class Test(Base):
+    '''Test table'''
     __tablename__ = 'tests'
     id = Column(Integer, primary_key=True)  # auto_increment
     ref = Column(String)
@@ -61,6 +67,7 @@ class Test(Base):
 # ---------------------------------------------------------------------------
 class Question(Base):
+    '''Question table'''
     __tablename__ = 'questions'
     id = Column(Integer, primary_key=True)  # auto_increment
     ref = Column(String)
+'''
+Parse markdown and generate HTML
+Includes support for LaTeX formulas
+'''
+
+
 # python standard library
 import logging
 import re
@@ -33,18 +39,19 @@ class MathBlockLexer(mistune.BlockLexer):
             rules = MathBlockGrammar()
         super().__init__(rules, **kwargs)
-    def parse_block_math(self, m):
-        """Parse a $$math$$ block"""
+    def parse_block_math(self, math):
+        '''Parse a $$math$$ block'''
         self.tokens.append({
             'type': 'block_math',
-            'text': m.group(1)
+            'text': math.group(1)
         })
-    def parse_latex_environment(self, m):
+    def parse_latex_environment(self, math):
+        '''Parse latex environment in formula'''
         self.tokens.append({
             'type': 'latex_environment',
-            'name': m.group(1),
-            'text': m.group(2)
+            'name': math.group(1),
+            'text': math.group(2)
         })
@@ -62,11 +69,11 @@ class MathInlineLexer(mistune.InlineLexer):
             rules = MathInlineGrammar()
         super().__init__(renderer, rules, **kwargs)
-    def output_math(self, m):
-        return self.renderer.inline_math(m.group(1))
+    def output_math(self, math):
+        return self.renderer.inline_math(math.group(1))
-    def output_block_math(self, m):
-        return self.renderer.block_math(m.group(1))
+    def output_block_math(self, math):
+        return self.renderer.block_math(math.group(1))
 class MarkdownWithMath(mistune.Markdown):
@@ -104,6 +111,7 @@ class HighlightRenderer(mistune.Renderer):
                + header + '</thead><tbody>' + body + '</tbody></table>'
     def image(self, src, title, alt):
+        '''render image'''
         alt = mistune.escape(alt, quote=True)
         if title is not None:
             if title:  # not empty string, show as caption
@@ -124,22 +132,26 @@ class HighlightRenderer(mistune.Renderer):
                 </div>
                 '''
-        else:  # title indefined, show as inline image
-            return f'''
-                <img src="/file?ref={self.qref}&image={src}"
-                     class="figure-img img-fluid" alt="{alt}" title="{title}">
-                '''
+        # title indefined, show as inline image
+        return f'''
+            <img src="/file?ref={self.qref}&image={src}"
+                 class="figure-img img-fluid" alt="{alt}" title="{title}">
+            '''
     # Pass math through unaltered - mathjax does the rendering in the browser
     def block_math(self, text):
+        '''bypass block math'''
         return fr'$$ {text} $$'
     def latex_environment(self, name, text):
+        '''bypass latex environment'''
         return fr'\begin{{{name}}} {text} \end{{{name}}}'
     def inline_math(self, text):
+        '''bypass inline math'''
         return fr'$$$ {text} $$$'
 def md_to_html(qref='.'):
+    '''markdown to html interface'''
     return MarkdownWithMath(HighlightRenderer(qref=qref))
@@ -12,12 +12,10 @@ import sys
 import base64
 import uuid
 import logging.config
-# import argparse
 import mimetypes
 import signal
 import functools
 import json
-# import ssl
 # user installed libraries
 import tornado.ioloop
@@ -30,9 +28,10 @@ from perguntations.parser_markdown import md_to_html
 # ----------------------------------------------------------------------------
-# Web Application. Routes to handler classes.
-# ----------------------------------------------------------------------------
 class WebApplication(tornado.web.Application):
+    '''
+    Web Application. Routes to handler classes.
+    '''
     def __init__(self, testapp, debug=False):
         handlers = [
             (r'/login', LoginHandler),
@@ -73,9 +72,11 @@ def admin_only(func):
 # ----------------------------------------------------------------------------
-# Base handler. Other handlers will inherit this one.
-# ----------------------------------------------------------------------------
 class BaseHandler(tornado.web.RequestHandler):
+    '''
+    Base handler. Other handlers will inherit this one.
+    '''
+
     @property
     def testapp(self):
         '''
@@ -152,8 +153,10 @@ class BaseHandler(tornado.web.RequestHandler):
 #         AdminSocketHandler.send_updates(chat)  # send to clients
-# --- ADMIN ------------------------------------------------------------------
+# ----------------------------------------------------------------------------
 class AdminHandler(BaseHandler):
+    '''Handle /admin'''
+
     # SUPPORTED_METHODS = ['GET', 'POST']
     @tornado.web.authenticated
@@ -209,19 +212,15 @@ class AdminHandler(BaseHandler):
 # ----------------------------------------------------------------------------
-# /login
-# ----------------------------------------------------------------------------
 class LoginHandler(BaseHandler):
+    '''Handle /login'''
+
     def get(self):
-        '''
-        Render login page.
-        '''
+        '''Render login page.'''
         self.render('login.html', error='')
     async def post(self):
-        '''
-        Authenticates student (prefix 'l' are removed) and login.
-        '''
+        '''Authenticates student (prefix 'l' are removed) and login.'''
         uid = self.get_body_argument('uid').lstrip('l')
         password = self.get_body_argument('pw')
@@ -235,14 +234,12 @@ class LoginHandler(BaseHandler):
 # ----------------------------------------------------------------------------
-# /logout
-# ----------------------------------------------------------------------------
 class LogoutHandler(BaseHandler):
+    '''Handle /logout'''
+
     @tornado.web.authenticated
     def get(self):
-        '''
-        Logs out a user.
-        '''
+        '''Logs out a user.'''
         self.clear_cookie('user')
         self.redirect('/')
@@ -251,9 +248,10 @@ class LogoutHandler(BaseHandler):
 # ----------------------------------------------------------------------------
-# handles root / to redirect students to /test and admininistrator to /admin
-# ----------------------------------------------------------------------------
 class RootHandler(BaseHandler):
+    '''
+    Handles / to redirect students and admin to /test and /admin, resp.
+    '''
     @tornado.web.authenticated
     def get(self):
+'''
+This module contains helper functions to:
+- load yaml files and report errors
+- run external programs (sync and async)
+'''
+
 # python standard library
 import asyncio
@@ -15,105 +21,119 @@ logger = logging.getLogger(__name__)
 # ---------------------------------------------------------------------------
-# load data from yaml file
-# ---------------------------------------------------------------------------
 def load_yaml(filename: str, default: Any = None) -> Any:
+    '''load data from yaml file'''
+
     filename = path.expanduser(filename)
     try:
-        f = open(filename, 'r', encoding='utf-8')
-    except Exception as e:
-        logger.error(e)
+        file = open(filename, 'r', encoding='utf-8')
+    except Exception as exc:
+        logger.error(exc)
         if default is not None:
             return default
-        else:
-            raise
+        raise
-    with f:
+    with file:
         try:
-            return yaml.safe_load(f)
-        except yaml.YAMLError as e:
-            logger.error(str(e).replace('\n', ' '))
+            return yaml.safe_load(file)
+        except yaml.YAMLError as exc:
+            logger.error(str(exc).replace('\n', ' '))
             if default is not None:
                 return default
-            else:
-                raise
+            raise
 # ---------------------------------------------------------------------------
-# Runs a script and returns its stdout parsed as yaml, or None on error.
-# The script is run in another process but this function blocks waiting
-# for its termination.
-# ---------------------------------------------------------------------------
 def run_script(script: str,
-               args: List[str] = [],
+               args: List[str],
                stdin: str = '',
-               timeout: int = 2) -> Any:
-
+               timeout: int = 3) -> Any:
+    '''
+    Runs a script and returns its stdout parsed as yaml, or None on error.
+    The script is run in another process but this function blocks waiting
+    for its termination.
+    '''
+    logger.info('run_script "%s"', script)
+
+    output = None
     script = path.expanduser(script)
+    cmd = [script] + [str(a) for a in args]
+
+    # --- run process
     try:
-        cmd = [script] + [str(a) for a in args]
-        p = subprocess.run(cmd,
-                           input=stdin,
-                           stdout=subprocess.PIPE,
-                           stderr=subprocess.STDOUT,
-                           universal_newlines=True,
-                           timeout=timeout,
-                           )
-    except FileNotFoundError:
-        logger.error(f'Can not execute script "{script}": not found.')
-    except PermissionError:
-        logger.error(f'Can not execute script "{script}": wrong permissions.')
+        proc = subprocess.run(cmd,
+                              input=stdin,
+                              stdout=subprocess.PIPE,
+                              stderr=subprocess.STDOUT,
+                              universal_newlines=True,
+                              timeout=timeout,
+                              check=False,
+                              )
     except OSError:
-        logger.error(f'Can not execute script "{script}": unknown reason.')
+        logger.error('Can not execute script "%s".', script)
+        return output
     except subprocess.TimeoutExpired:
-        logger.error(f'Timeout {timeout}s exceeded while running "{script}".')
+        logger.error('Timeout %ds exceeded running "%s".', timeout, script)
+        return output
     except Exception:
-        logger.error(f'An Exception ocurred running {script}.')
-    else:
-        if p.returncode != 0:
-            logger.error(f'Return code {p.returncode} running "{script}".')
-        else:
-            try:
-                output = yaml.safe_load(p.stdout)
-            except Exception:
-                logger.error(f'Error parsing yaml output of "{script}"')
-            else:
-                return output
+        logger.error('An Exception ocurred running "%s".', script)
+        return output
+
+    # --- check return code
+    if proc.returncode != 0:
+        logger.error('Return code %d running "%s".', proc.returncode, script)
+        return output
+
+    # --- parse yaml
+    try:
+        output = yaml.safe_load(proc.stdout)
+    except yaml.YAMLError:
+        logger.error('Error parsing yaml output of "%s".', script)
+
+    return output
-# ----------------------------------------------------------------------------
-# Same as above, but asynchronous
 # ----------------------------------------------------------------------------
 async def run_script_async(script: str,
-                           args: List[str] = [],
+                           args: List[str],
                            stdin: str = '',
-                           timeout: int = 2) -> Any:
+                           timeout: int = 3) -> Any:
+    '''Same as above, but asynchronous'''
     script = path.expanduser(script)
     args = [str(a) for a in args]
+    output = None
-    p = await asyncio.create_subprocess_exec(
-        script, *args,
-        stdin=asyncio.subprocess.PIPE,
-        stdout=asyncio.subprocess.PIPE,
-        stderr=asyncio.subprocess.DEVNULL,
-        )
-
+    # --- start process
     try:
-        stdout, stderr = await asyncio.wait_for(
-            p.communicate(input=stdin.encode('utf-8')),
-            timeout=timeout
+        proc = await asyncio.create_subprocess_exec(
+            script, *args,
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.DEVNULL,
             )
+    except OSError:
+        logger.error('Can not execute script "%s".', script)
+        return output
+
+    # --- send input and wait for termination
+    try:
+        stdout, _ = await asyncio.wait_for(
+            proc.communicate(input=stdin.encode('utf-8')),
+            timeout=timeout)
     except asyncio.TimeoutError:
-        logger.warning(f'Timeout {timeout}s running script "{script}".')
-        return
+        logger.warning('Timeout %ds running script "%s".', timeout, script)
+        return output
-    if p.returncode != 0:
-        logger.error(f'Return code {p.returncode} running "{script}".')
-    else:
-        try:
-            output = yaml.safe_load(stdout.decode('utf-8', 'ignore'))
-        except Exception:
-            logger.error(f'Error parsing yaml output of "{script}"')
-        else:
-            return output
+    # --- check return code
+    if proc.returncode != 0:
+        logger.error('Return code %d running "%s".', proc.returncode, script)
+        return output
+
+    # --- parse yaml
+    try:
+        output = yaml.safe_load(stdout.decode('utf-8', 'ignore'))
+    except yaml.YAMLError:
+        logger.error('Error parsing yaml output of "%s"', script)
+
+    return output
	@@ -65,7 +65,7 @@ questions:		@@ -65,7 +65,7 @@ questions:
65	- tut-success	65	- tut-success
66	- tut-warning	66	- tut-warning
67	- tut-alert	67	- tut-alert
68	-	68	+ - tut-generator
69		69
70	# test:	70	# test:
71	# - ref1	71	# - ref1
1	#!/usr/bin/env python3	1	#!/usr/bin/env python3
2		2
		3	+'''
		4	+Example of a question generator.
		5	+Arguments are read from stdin.
		6	+'''
		7	+
3	from random import randint	8	from random import randint
4	import sys	9	import sys
5		10
6	-arg = sys.stdin.read() # read arguments	11	+a, b = (int(n) for n in sys.argv[1:])
7		12
8	-a, b = (int(n) for n in arg.split(','))	13	+x = randint(a, b)
		14	+y = randint(a, b)
		15	+r = x + y
9		16
10	-q = f'''---
11	-type: checkbox	17	+print(f"""---
		18	+type: text
		19	+title: Geradores de perguntas
12	text: \|	20	text: \|
13	- Indique quais das seguintes adições resultam em overflow quando se considera
14	- a adição de números com sinal (complemento para 2) em registos de 8 bits.	21	+ Existe a possibilidade da pergunta ser gerada por um programa externo.
		22	+ Este programa deve escrever no `stdout` uma pergunta em formato `yaml` como
		23	+ os anteriores. Pode também receber argumentos para parametrizar a geração da
		24	+ pergunta. Aqui está um exemplo de uma pergunta gerada por um script python:
15		25
16	- Os números foram gerados aleatoriamente no intervalo de {a} a {b}.
17	-options:
18	-'''	26	+ ```python
		27	+ #!/usr/bin/env python3
		28	+
		29	+ from random import randint
		30	+ import sys
		31	+
		32	+ a, b = (int(n) for n in sys.argv[1:]) # argumentos da linha de comando
19		33
20	-correct = []
21	-for i in range(5):
22	- x = randint(a, b)
23	- y = randint(a, b)
24	- q += f' - "`{x} + {y}`"\n'
25	- correct.append(1 if x + y > 127 else -1)	34	+ x = randint(a, b)
		35	+ y = randint(a, b)
		36	+ r = x + y
26		37
27	-q += 'correct: ' + str(correct)	38	+ print(f'''---
		39	+ type: text
		40	+ title: Contas de somar
		41	+ text: \|
		42	+ bla bla bla
		43	+ correct: '{{r}}'
		44	+ solution: \|
		45	+ A solução é {{r}}.''')
		46	+ ```
28		47
29	-print(q)	48	+ Este script deve ter permissões para poder ser executado no terminal. Dá
		49	+ jeito usar o comando `gen-somar.py 1 100 \| yamllint -` para validar o `yaml`
		50	+ gerado.
		51	+
		52	+ Para indicar que uma pergunta é gerada externamente, esta é declarada com
		53	+
		54	+ ```yaml
		55	+ - type: generator
		56	+ ref: gen-somar
		57	+ script: gen-somar.py
		58	+ # opcional
		59	+ args: [1, 100]
		60	+ ```
		61	+
		62	+ Os argumentos `args` são opcionais e são passados para o programa como
		63	+ argumentos da linha de comando.
		64	+
		65	+ ---
		66	+
		67	+ Calcule o resultado de ${x} + {y}$.
		68	+
		69	+ Os números foram gerados aleatoriamente no intervalo de {a} a {b}.
		70	+correct: '{r}'
		71	+solution: \|
		72	+ A solução é {r}.""")
	@@ -193,7 +193,7 @@ class App():		@@ -193,7 +193,7 @@ class App():
193	logger.info('Student %s: %d answers submitted.', uid, len(ans))	193	logger.info('Student %s: %d answers submitted.', uid, len(ans))
194		194
195	grade = await test.correct()	195	grade = await test.correct()
196	- logger.info('Student %s: grade = %.1g points.', uid, grade)	196	+ logger.info('Student %s: grade = %g points.', uid, grade)
197		197
198	# --- save test in JSON format	198	# --- save test in JSON format
199	fields = (uid, test['ref'], str(test['finish_time']))	199	fields = (uid, test['ref'], str(test['finish_time']))