From 4fd4ef90d8bb19faa66f2badde6612e39f2fff3f Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Sat, 1 Sep 2012 08:45:50 -0400 Subject: [PATCH] README: elaborate on grade file format and mailpipe processing. --- README | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 54 insertions(+), 2 deletions(-) diff --git a/README b/README index dba015f..7af40ba 100644 --- a/README +++ b/README @@ -159,8 +159,9 @@ Processing submissions As the due date approaches, student submissions will start arriving in your inbox. Use ``pg.py``'s ``mailpipe`` command to sort them into -directories. This will also extract any files that were attached to -the emails and place them in that persons assignment directory:: +directories (using the ``pygrader.handler.submission`` handler). This +will also extract any files that were attached to the emails and place +them in that persons assignment directory:: $ pg.py -d test mailpipe -m maildir -i ~/.maildir -o ./mail-old @@ -168,6 +169,16 @@ Use ``pg.py``'s ``todo`` command to check for ungraded submissions:: $ pg.py -d test todo mail grade +Then create ``grade`` files using your favorite editor. The first +line of the grade file should be the student's grade for that +assigment, expressed in a syntax that Python's ``float()`` understands +(``1``, ``95``, ``2.5``, ``6.022e23``, etc.). If you wish, you may +add additional comment lines after the grade line, offering +suggestions for improvement, etc. This comment (if present) will be +mailed to the student along with the grade itself. There are a number +of example grade files in the ``test`` directory in ``pygrader``'s Git +source. + To see how everyone's doing, you can print a table of grades with ``pg.py``'s ``tabulate`` command:: @@ -178,6 +189,46 @@ all out with ``pg.py``'s ``email`` command:: $ pg.py -d test email assignment 'Exam 1' +Mailpipe details +~~~~~~~~~~~~~~~~ + +Mailpipe is the most complicated part of ``pygrader``, and the place +where things are most likely to get sticky. Since there are several + +If you get tired of filtering your inbox by hand using ``pg.py +mailpipe``, you can (depending on how your mail delivery is setup) use +procmail_ to automatically run ``mailpipe`` automatically on incoming +email. There is an example ``.procmailrc`` in the +``pygrader.mailpipe.mailpipe`` docstring that runs ``mailpipe`` +whenever incoming emails have ``[phys160:submit]`` in their subject +somewhere. + +The use of ``[TARGET]`` tags in the email subject allows users to +unambiguously specify the purpose of their email. Currently supported +targets include (see the ``handlers`` argument to +``pygrader.mailpipe``): + +``submit`` + student assignment submission. The remainder of the email subject + should include the case insensitive name of the assignment being + submitted (see ``pygrader.handler.submission._match_assignment``). + An example subject would be:: + + [submit] assignment 1 + +To allow you to easily sort the email, you can also prefix the target +with additional information (see +``pygrader.mailpipe._get_message_target``). For example, if you were +running several courses from the same email account, you'd want a way +for users to specify which course they were interacting with so you +could filter appropriately in your procmail rules. Everything in the +subject tag before an optional semicolon is ignored by ``mailpipe``, +so the following subjects will be handled identically:: + + [submit] assignment 1 + [phys101:submit] assignment 1 + [phys101:section2:submit] assignment 1 + Testing ======= @@ -220,6 +271,7 @@ using graphical interfaces. .. _homepage: http://blog.tremily.us/posts/pygrader/ .. _SMTP: http://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol .. _GnuPG: http://www.gnupg.org/ +.. _procmail: http://www.procmail.org/ .. _nose: http://readthedocs.org/docs/nose/en/latest/ .. _GNU General Public License Version 3: http://www.gnu.org/licenses/gpl.html .. _Alex Heitzmann's pygrade: http://code.google.com/p/pygrade/ -- 2.26.2