X-Git-Url: http://git.tremily.us/?a=blobdiff_plain;f=README;h=2f7a6049f98af3927348517582027ed9cf252d3a;hb=bda6590fabf2fb41e91e1e92a44362b3e7515a6f;hp=c46d0684bedceb5dc362770d2138ad4b0bb62cfa;hpb=5b19435adb2b7a14d572a2c78fcfadcfa58d2a6c;p=pygrader.git diff --git a/README b/README index c46d068..2f7a604 100644 --- a/README +++ b/README @@ -46,10 +46,12 @@ Usage Pygrader will help keep you organized in a course where the students submit homework via email, or the homework submissions are otherwise -digital (i.e. scanned in after submission). There is currently no -support for multiple graders, although I will likely add this in the -future. In the following sections, I'll walk you through -administering the homework for the ``test`` course. +digital (i.e. scanned in after submission). You can also use it to +assign and `manage any type of grade via email`__. In the following +sections, I'll walk you through local administration for the ``test`` +course. + +__ `Mailpipe details`_ All of the processing involves using the ``pg.py`` command. Run:: @@ -79,9 +81,11 @@ the course directory:: $ 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 @@ -98,11 +102,24 @@ the course directory:: … + [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 @@ -126,23 +143,27 @@ If a person has the ``pgp-key`` option set, that key will be used to encrypt messages to that person and sign messages from that person with PGP_. It will also be used to authenticate ownership of incoming emails. You'll need to have GnuPG_ on your local host for this to -work, and the user running pygrader should have the associated keys in -their keychain. The ``pgp-fingerprint`` option is used when verifying -that signed emails are signed by the appropriate person. You can -extract the fingerprint for the PGP key using GnuPG:: +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). - $ gpg --fingerprint 4332B6E3 - pub 2048R/4332B6E3 2012-03-21 - Key fingerprint = B2ED BE0E 771A 4B87 08DD 16A7 511A EDA6 4332 B6E3 - uid pgp-mime-test (http://blog.tremily.us/posts/pgp-mime/) +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 person's assignment directory:: $ pg.py -d test mailpipe -m maildir -i ~/.maildir -o ./mail-old @@ -150,6 +171,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:: @@ -160,6 +191,85 @@ all out with ``pg.py``'s ``email`` command:: $ pg.py -d test email assignment 'Exam 1' +Mailpipe details +~~~~~~~~~~~~~~~~ + +Besides accepting student submissions from incoming email, +``mailpipe`` also accepts other types of requests, and can be +configured to respond automatically: + +* Incoming student assignment submissions are archived (see the + ``submit`` command). +* Students can check their grades without having to bother anyone (see + the ``get`` commands). +* Professors and teaching assistants can request student submissions + so that they can grade them (see the ``get`` commands). +* Professors and TAs can request the grades for the entire class (see + the ``get`` commands). +* Professors and TAs can assign grades (see the ``grade`` command). + +To enable automatic responses, you'll need to add the ``-r`` or +``--respond`` argument when you call ``pg.py``. + +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 + +``grade`` + professors and TAs can submit a grade for a particular student on a + particular assignment. The body of the (possibly signed or + encrypted) email should be identical to the grade file that the + sender wishes to create. An example subject would be:: + + [grade] 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 ======= @@ -182,14 +292,14 @@ Author ====== W. Trevor King -wking@drexel.edu +wking@tremily.us Related work ============ -For a similar project, see `Alex Heitzmann pygrade`_, which keeps the -grade history in a single log file and provides more support for using -graphical interfaces. +For a similar project, see `Alex Heitzmann's pygrade`_, which keeps +the grade history in a single log file and provides more support for +using graphical interfaces. .. _PGP: http://en.wikipedia.org/wiki/Pretty_Good_Privacy @@ -202,6 +312,7 @@ 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/