$ cat test/course.conf
[course]
+ name: Physics 101
assignments: Attendance 1, Attendance 2, Attendance 3, Attendance 4,
Attendance 5, Attendance 6, Attendance 7, Attendance 8, Attendance 9,
Assignment 1, Assignment 2, Exam 1, Exam 2
+ robot: Robot101
professors: Gandalf
assistants: Sauron
students: Bilbo Baggins, Frodo Baggins, Aragorn
…
+ [Assignment 1]
+ points: 10
+ weight: 0.4/2
+ due: 2011-10-10
+ submittable: yes
+
+ …
+
[Exam 2]
points: 10
weight: 0.4/2
due: 2011-10-17
+ [Robot101]
+ nickname: phys-101 robot
+ emails: phys101@tower.edu
+ pgp-key: 4332B6E3
+
[Gandalf]
nickname: G-Man
emails: g@grey.edu
work, and the user running pygrader should have the associated keys in
their keychain.
+The ``course.robot`` option defines a dummy person used to sign
+automatically generated emails (e.g. responses to mailpipe-processed
+submissions).
+
+The ``submittable`` option marks assignments that accept direct
+submission from students (e.g. homeworks). You probably don't want to
+set this option for attendance, since it would allow students to mark
+themselves as having attended a class. ``submittable`` default to
+``False``.
+
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
$ 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::
$ 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
+
+``get``
+ request information from the grade database. For students, the
+ remainder of the email subject is irrelevant. Grades and comments
+ for all graded assignments are returned in a single email. An
+ example subject would be::
+
+ [get] my grades
+
+ Professors and TAs may request either a table of all grades for the
+ course (à la ``tabulate``), the full grades for a particular
+ student, or a particular student's submission for a particular
+ assignment. Example subjects are (respectively):
+
+ [get] don't match any student names
+ [get] Bilbo Baggins
+ [get] Bilbo Baggins 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
=======
======
W. Trevor King
-wking@drexel.edu
+wking@tremily.us
Related work
============
.. _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/
projects / pygrader.git / blobdiff