README

   1 ``pygrader`` is a directory-based grade database for grading course
   2 assignments.  Besides tracking grades locally, you can also use it to
   3 automatically mail grades to students and professors associated with
   4 the course.  For secure communication, PGP_ can be used to sign and/or
   5 encrypt any of these emails.
   6
   7 Installation
   8 ============
   9
  10 Packages
  11 --------
  12
  13 Gentoo
  14 ~~~~~~
  15
  16 I've packaged ``pygrader`` for Gentoo_.  You need layman_ and
  17 my `wtk overlay`_.  Install with::
  18
  19   # emerge -av app-portage/layman
  20   # layman --add wtk
  21   # emerge -av dev-python/pygrader
  22
  23 Dependencies
  24 ------------
  25
  26 ``pygrader`` is a simple package.  The only external dependency
  27 outside the Python 3 standard library is my `pgp-mime`_ package.
  28
  29 Installing by hand
  30 ------------------
  31
  32 ``pygrader`` is available as a Git_ repository::
  33
  34   $ git clone git://tremily.us/pygrader.git
  35
  36 See the homepage_ for details.  To install the checkout, run the
  37 standard::
  38
  39   $ python setup.py install
  40
  41 Usage
  42 =====
  43
  44 Pygrader will help keep you organized in a course where the students
  45 submit homework via email, or the homework submissions are otherwise
  46 digital (i.e. scanned in after submission).  There is currently no
  47 support for multiple graders, although I will likely add this in the
  48 future.  In the following sections, I'll walk you through
  49 administering the homework for the ``test`` course.
  50
  51 All of the processing involves using the ``pg.py`` command.  Run::
  52
  53   $ pg.py --help
  54
  55 for details.
  56
  57 Sending email
  58 -------------
  59
  60 Pygrader receives submissions and assigns grades via email.  In order
  61 to send email, it needs to connect to an SMTP_ server.  See the
  62 pgp-mime documentation for details on configuring you SMTP connection.
  63 You can test your SMTP configuration by sending yourself a test
  64 message::
  65
  66   $ pg.py -VVV smtp -a rincewind@uu.edu -t rincewind@uu.edu
  67
  68 Defining the course
  69 -------------------
  70
  71 Once you've got email submission working, you need to configure the
  72 course you'll be grading.  Each course lives in its own directory, and
  73 the basic setup looks like the ``test`` example distributed with
  74 pygrader.  The file that you need to get started is the config file in
  75 the course directory::
  76
  77   $ cat test/course.conf
  78   [course]
  79   assignments: Attendance 1, Attendance 2, Attendance 3, Attendance 4,
  80     Attendance 5, Attendance 6, Attendance 7, Attendance 8, Attendance 9,
  81     Assignment 1, Assignment 2, Exam 1, Exam 2
  82   professors: Gandalf
  83   assistants: Sauron
  84   students: Bilbo Baggins, Frodo Baggins, Aragorn
  85
  86   [Attendance 1]
  87   points: 1
  88   weight: 0.1/9
  89   due: 2011-10-03
  90
  91   [Attendance 2]
  92   points: 1
  93   weight: 0.1/9
  94   due: 2011-10-04
  95
  96   …
  97
  98   [Exam 2]
  99   points: 10
 100   weight: 0.4/2
 101   due: 2011-10-17
 102
 103   [Gandalf]
 104   nickname: G-Man
 105   emails: g@grey.edu
 106   pgp-key: 4332B6E3
 107
 108   [Sauron]
 109   emails: eye@tower.edu
 110
 111   [Bilbo Baggins]
 112   nickname: Bill
 113   emails: bb@shire.org, bb@greyhavens.net
 114
 115   …
 116
 117 The format is a bit wordy, but it is also explicit and easily
 118 extensible.  The time it takes to construct this configuration file
 119 should be a small portion of the time you will spend grading
 120 submissions.
 121
 122 If a person has the ``pgp-key`` option set, that key will be used to
 123 encrypt messages to that person and sign messages from that person
 124 with PGP_.  It will also be used to authenticate ownership of incoming
 125 emails.  You'll need to have GnuPG_ on your local host for this to
 126 work, and the user running pygrader should have the associated keys in
 127 their keychain.  The ``pgp-fingerprint`` option is used when verifying
 128 that signed emails are signed by the appropriate person.  You can
 129 extract the fingerprint for the PGP key using GnuPG::
 130
 131   $ gpg --fingerprint 4332B6E3
 132   pub   2048R/4332B6E3 2012-03-21
 133         Key fingerprint = B2ED BE0E 771A 4B87 08DD  16A7 511A EDA6 4332 B6E3
 134   uid                  pgp-mime-test (http://blog.tremily.us/posts/pgp-mime/) <pgp-mime@invalid.com>
 135
 136 Processing submissions
 137 ----------------------
 138
 139 As the due date approaches, student submissions will start arriving in
 140 your inbox.  Use ``pg.py``'s ``mailpipe`` command to sort them into
 141 directories.  This will also extract any files that were attached to
 142 the emails and place them in that persons assignment directory::
 143
 144   $ pg.py -d test mailpipe -m maildir -i ~/.maildir -o ./mail-old
 145
 146 Use ``pg.py``'s ``todo`` command to check for ungraded submissions::
 147
 148   $ pg.py -d test todo mail grade
 149
 150 To see how everyone's doing, you can print a table of grades with
 151 ``pg.py``'s ``tabulate`` command::
 152
 153   $ pg.py -d test tabulate -s
 154
 155 When you want to notify students of their grades, you can send them
 156 all out with ``pg.py``'s ``email`` command::
 157
 158   $ pg.py -d test email assignment 'Exam 1'
 159
 160 Testing
 161 =======
 162
 163 Run the internal unit tests using nose_::
 164
 165   $ nosetests --with-doctest --doctest-tests pygrader
 166
 167 If a Python-3-version of ``nosetests`` is not the default on your
 168 system, you may need to try something like::
 169
 170   $ nosetests-3.2 --with-doctest --doctest-tests pygrader
 171
 172 Licence
 173 =======
 174
 175 This project is distributed under the `GNU General Public License
 176 Version 3`_ or greater.
 177
 178 Author
 179 ======
 180
 181 W. Trevor King
 182 wking@drexel.edu
 183
 184 Related work
 185 ============
 186
 187 For a similar project, see `Alex Heitzmann pygrade`_, which keeps the
 188 grade history in a single log file and provides more support for using
 189 graphical interfaces.
 190
 191
 192 .. _PGP: http://en.wikipedia.org/wiki/Pretty_Good_Privacy
 193 .. _Gentoo: http://www.gentoo.org/
 194 .. _layman: http://layman.sourceforge.net/
 195 .. _wtk overlay: http://blog.tremily.us/posts/Gentoo_overlay/
 196 .. _pgp-mime: http://blog.tremily.us/posts/pgp-mime/
 197 .. _Git: http://git-scm.com/
 198 .. _homepage: http://blog.tremily.us/posts/pygrader/
 199 .. _SMTP: http://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol
 200 .. _GnuPG: http://www.gnupg.org/
 201 .. _nose: http://readthedocs.org/docs/nose/en/latest/
 202 .. _GNU General Public License Version 3: http://www.gnu.org/licenses/gpl.html
 203 .. _Alex Heitzmann's pygrade: http://code.google.com/p/pygrade/