README: document submodule usage

This tells people who didn't read the commit message what to do with
the changes from:

  commit 8e10f59d36ea9c619241efaf3213156406dd74f9
  Author: W. Trevor King <wking@tremily.us>
  Date:   Tue Dec 11 11:30:24 2012 -0500

    dep: add pygrader dependencies as submodules

pg.py: handle command-less invocation cleanly

This avoids:

  Traceback (most recent call last):
    File "/.../pg.py", line 202, in <module>
      func_args = _inspect.getargspec(args.func).args
  AttributeError: 'Namespace' object has no attribute 'func'

dep: add pygrader dependencies as submodules

With the submodules checked out, you can run:

  $ PYTHONPATH=dep ./bin/pg.py ...

to run pygrader without installing any external pacakges on your
system.  With Gentoo's Python 3.3 support still flaky [1,2], this is
less painful than maintaining the dependencies by hand.

Checkout updated submodules with:

  $ git submodule update --init

The jinja2 repository is my local branch, which applies 2to3 directly
to the source (because we are loading jinja2 directly from the
submodule source).  I will rebase my jinja2 branch against new
upstream versions, so don't do any Jinja development based on my
branch.

[1]: https://bugs.gentoo.org/show_bug.cgi?id=437322
[2]: https://bugs.gentoo.org/show_bug.cgi?id=364877

mailpipe: fix _get_message_subject() doctest for "-ascii part".

In both Python 3.2.3 and 3.3 the doctest subject is encoded as

  '=?utf-8?q?unicode_part?= -ascii part'

In Python 3.3, this is now correctly decoded (I think) to retain the
space.  It seems to me that the encoded version should actually be:

  '=?utf-8?q?unicode_part?=-ascii part'

but I don't care enough to track that down ;).

tabulate: fix sval -> return typo in _statistic().

pgp: don't assume protocol/micalg ordering in doctest output.

The Content-Type header is eventually set by Message.add_header(),
which gets extra parameters from **_params and iterates over them with
_params.items().  _params is a dict, so .items() is not sorted.  I
forced the ordering in the pgp-mime doctests, so here I assume the
micalg field is correct and just use ELLIPSIS.

tabulate: fix iterabale -> iterable typo in _statistic().

tabulate: fix stat -> statistic in _statistic().

email: remove `header` option to get_address.

The new function acts like the old one with `header=True`.

Since Python 3.3, formataddr uses RFC 2047 encoding of the realname
(for non-ASCII names), so there's no need for a separate Header call
anymore.

README: mention Jinja dependency for sending email.

README: mention that NumPy is now optional.

tabulate: work around missing NumPy.

.update-copyright.conf: update to pipe separators.

This brings the config file up to speed with the following
update-copyright commit:

  commit 3c68a1a48419d8b2bbc2ce0e7f1700b996ec30e9
  Author: W. Trevor King <wking@tremily.us>
  Date:   Fri Oct 19 21:52:48 2012 -0400

    project: for consistency, also separate ignored paths with pipes

handler: expand kwargs when initializing InvalidAssignmentSubject.

mailpipe: fix course -> error.course in InvalidAssignmentSubject handling.

pg.py: add --continue-after-invalid-message (used to be hardcoded True).

pg.py: make `--version` a stand alone argument (for Python 3.3).

template: remove use_color from template functions.

This catches these functions up with

  commit 2c8c64a90009b50ee9f9708846b29c1f3b53a28f
  Author: W. Trevor King <wking@tremily.us>
  Date:   Sat Sep 1 19:14:12 2012 -0400

    color: add ColoredFormatter for more transparent coloring.

and avoids

  TypeError: send_emails() got an unexpected keyword argument 'use_color'

mailpipe: add trust_admin_from option to _get_message_person().

This allows me to resend troublesome emails on behalf of students.

mailpipe: update fingerprint access for pgp-mime `Key`s.

Catching up with pgp-mime commit

  commit 1048b3045526d355ac0314597cc98713874b4e5d
  Author: W. Trevor King <wking@tremily.us>
  Date:   Sat Oct 6 10:47:52 2012 -0400

    key: flesh out to use KEYLIST's output XML.

model:person: add Person.is_admin() to simplify authorization checks.

model:person: if not given, Person.emails and .groups default to [].

This avoids problems with trying to iterate None.

pygrader: fix pygrade -> pygrader LOG name.

mailpipe: don't raise UnverifiedSignatureMessage for valid signatures.

Before this patch, signatures like:

  ... signature
    summary:
      CRL missing: False
      CRL too old: False
      bad policy: False
      green: True
      key expired: False
      key missing: False
      key revoked: False
      red: False
      signature expired: False
      system error: False
      valid: True
    ...

would raise the exception.  Now they won't.

README: mention Numpy dependency.

mailpipe: don't bail if a message is signed by a subkey.

Also strips off a leading '0x' before matching fingerprint tails.

You should normally be using primary keys in the `pgp_key` field of
the course configuration file.  Before this commit, messages signed by
a subkey would raise WrongSignatureMessage (i.e. we were looking for a
signature by your primary key, but we only got a signature from your
subkey).  Now we look for the listed signature not only in the signing
keys but also in their primaries.

This requires pgp-mime commit:

  commit eab8b88fe3f4940a9f8285cfb8b88070cd5c0050
  Author: W. Trevor King <wking@tremily.us>
  Date:   Thu Sep 20 12:24:27 2012 -0400

    key: add pgp_mime.key wrapping gpgme-tool's KEYLIST command.

mailpipe: flesh out reponse text for invalid messages and signing errors.

This may be a user's first exposure to PGP, so it's a bad idea to be
cryptic ;).

mailpipe: convert to pgp-mime's new Signature verification.

This brings us up to date with the following pgp-mime commit:

  commit 7d4ff835519e6a8fa4273c364b571c2874bd31d5
  Author: W. Trevor King <wking@tremily.us>
  Date:   Thu Sep 20 10:12:38 2012 -0400

    signature: add Signature class for more Pythonic verification.

    Now verify_bytes() returns a list of `Signature`s instead of XML.
    This should be much easier for callers to handle, and it provides a
    layer of insulation between the gpgme-tool output and Python code.

mailpipe: standardize error responses with 'We got' -> 'We received'.

storage: only try and load grades for students.

storage: make [course] parameters optional (e.g. no assistants).

storage: don't try to load empty names.

This avoids problems with configuration files like:

  [course]
  ...
  assistants:
  ...

where the `assistants` field exists but lists no names.

pg.py: make default --encoding 'utf-8' to avoid clobbering ENCODING with None.

Import pygrader, instead of pygrader.ENCODING.

If your just import ENCODING, changing the value rebinds the local
copy, but other modules will still see the original value.

pg.py: add --encoding to override pygrader.ENCODING if you don't like UTF-8.

Use pygrader.ENCODING when loading ConfigParser files.

py.py: add -s/--syslog to redirect logging to syslog (/dev/log).

This is useful for logging requests spawned by procmail or your MDA.

pg.py: set color.USE_COLOR depending on the --color argument.

Otherwise the course loading and other things that avoid use_color
keyword args will end up getting printed in color by default.

Bump to version 0.3.

test: rename maildir messages to have integer unique portions.

The `:2,S` portion of the filename means the messages have version 2
status flags (2), and the messages have been seen (S).

Ran update-copyright.py.

update-copyright: add */.gitignore so maildir placeholders don't get tweaked.

handler:grade: add new handler for submitting grades.

Now profs and TAs can submit grades (points and comments) via email.

storage: add save_grade (useful for upcoming `grade` handler).

storage: split load_grade out from load_grades.

Also rename _load_grade to parse_grade.

These functions will be useful in the upcoming `grade` handler.

mailpipe|handler: centralize student/course extraction from subjects.

handler: remove TypeError check InvalidSubjectMessage.__init__.

Leftover debugging cruft.

mailpipe: don't double-repr subjects for InvalidHandlerMessage responses.

mailpipe: add extra attributes to errors even if current attribute is None.

With the old impementation, a default value of None would keep the
attribute from being added.  For example, if the error is raised with

  error.subject == None

`mailpipe` and `_parse_message` would not override that with their
known value.  Now they will.

handler:get: sort submission messages chronologically.

mailpipe: use `messages.sort(...)`, not `m = sorted(m, ...)`.

handler:get: skip .gitignore messages a la mailpipe._load_messages.

test:mail-in: request Frodo's assignment 1 (better data).

test:frodo: add a comment and submission emails.

We can use the new data to excercise the 'get submission' handling.

test:mail-in: replace tremily with tower addresses.

handler:get: only add comment to submission response if it exists.

This avoids potentially confusing responses like:

> Assignment 1 grade: 8.0
>
> None

test:mail-in: add test emails excercising `handler.get`.

handler:get: Responses from this handler are complete.

This avoids double-signing emails and other atrocities.

mailpipe|handler: add `complete` option to control Response mangling.

Some handlers may return their emails fully formed, and we won't want
to mess with them.

mailpipe: respond with the fleshed out message, not the original.

We've just added an author, targets, subject, etc.  None of that
matters if you send the original version.

Also print check that the subject is not None before we remove any
subject fields.  This shouldn't matter (del-ing a None subject should
be a no-op), but it seems safer to print the offending message before
messing with it.

handler:get: log email construction to troubleshoot parsing.

mailpipe|handler: raise exceptions during PGP message verification.

This avoids the silly "return None on error" convention and allows for
more detailed handling of unsigned messages (vs. improperly signed
messages).

storage: cleanup StubCourse after load_course doctest.

pg.py|mailpipe: add --trust-email-infrastructure.

pg.py: send_emails (and thus, Responder) no longer takes use_color.

pg.py: fix incomming -> incoming typo for --respond help.

mailpipe: sort messages chronologically before processing.

mailpipe: print error messages when we continue_after_invalid_message.

Since we're not raising the message, we should log it.  Otherwise the
user may not know that something is amiss.

pg.py: default to continue_after_invalid_message=True when calling mailpipe.

This lets us process a whole mailbox without dying on every invalid
message.  Consider an unfiltered, general-purpose mailbox with lots of
unrelated emails, which can be successfully parsed with
`continue_after_invalid_message`.

mailpipe: add a warning message before loading a message from a stream.

This reminds you if you forget to use the `--mailbox` option when
calling `pg.py`, and the process hangs waiting for a message on stdin.

gitignore: add `dist` (created by `setup.py sdist`).

mailpipe: skip `.gitignore` files in Maildir mailboxes.

I use empty `.gitignore` files so Git will create the
`test/mail-in/new` and `test/mail-in/tmp` directories on checkout, but
the Maildir mailbox thinks they are messages.  Since the files are
*not* messages, skip them when constucting the Maildir message list.

I don't foresee any side effects from this (it's an odd filename for
real Maildir delivery), but I log the skipped filenames just in case.

mailpipe: flesh out InvalidMessage attributes before raising exceptions.

This tacks on all the interesting attribute data which the function
that originally raised the exception may not have known about.  We
want this metadata in all cases, not just those where we are
constructing a response message.

mailpipe: fix InvalidHandlerMessage error message construction.

`target` is an explicit argument, not in `**kwargs`.

I also removed the InvalidHandlerMessage error logging, because we're
raising an exception.  The calling function can log the exception if
it catches it.  If it doesn't, the user will see the message in the
traceback.

handler: add InvalidMessage.message_id convenience method.

test:mail-in: add example emails for manual testing.

color: add ColoredFormatter for more transparent coloring.

This way we don't have to pass use_color around all over the place.

mailpipe|handler: with the Response framework, handlers don't need `original`.

mailpipe: replace `respond` callback with exceptions.

Now mailpipe sub-functions will raise Response or InvalidMessage when
they want to respond to the incoming email.  This takes advantage of
Python's exception handling to avoid passing the `respond` callback
all over the place.  It also allows us consolidate error message
construction in `_get_error_response`, which will lead to both simpler
program logic and more consistent response messages.

Other changes to make this cleaner:

* Renamed functions in pygrader.email:
    _construct_email -> construct_email
    construct_email -> construct_text_email
* Pulled _get_assignment out of submission.run.

handler:get: add `get` handler for grade requests.

handler:submission: fix non-lowercase subject assignment matching.

Also accept (and ignore) unrecognized keyword arguments in run().
This will allow interoperability with other handlers which may take
other arguments.

template: add targets argument to construct_student_email.

README: elaborate on grade file format and mailpipe processing.

handler:submission: add doctest to run().

template: remove extra blank lines from construct student email.

By fixing STUDENT_TEMPLATE to remove blank lines due to grades without
comments.

Also remove NORMALIZE_WHITESPACE from template doctests, which had
been there to match tabs (doctest expands hard tab characters to
spaces using 8-column tab stops).  However, with NORMALIZE_WHITESPACE
it was impossible to test for extra blank lines.

mailpipe: clarify the source of missing `Return-Path` (bad email)

mailpipe: add .authenticated attribute to _get_verified_message results.

This will allow message handlers to easily determine if the message
they're processing is from an authenticated user.

mailpipe: add support for multi-part subjects in _get_message_subject.

mailpipe|handler: split mailpipe's submission handler into its own module.

Now you must use a tag target (e.g. `[submit]`) in your email header
to let mailpipe know which handler you want processing your email.
With the new setup, we can easily add additional handlers (e.g. for
grade requests).

mailpipe: split initial _parse_message processing into sub-functions.

New functions:

* _get_message_person_and_subject  (which calls the others internally)
* _get_message_person
* _get_decoded_message
* _get_message_subject

With the previous implementation, all the inline error handling was
making the intended logic of _parse_message difficult to follow.

mailpipe: update doctests now that I'm using GnuPG v2.0.19.

setup.py: explicitly list Python 3.2 and 3.3 as supported.

Bump to version 0.2.

Add MANIFEST.in to distribute COPYING.

Add --respond option to pg.py's mailpipe command.

Finish mailpipe respond() doctests.

Also:
* Add course.name configuration to README example.
* Standardize course.name examples on the more formal `Physics 101`.
* Standardize robot nickname examples on `phys-101 robot`.

Document course.robot and assignment.submittable in the README.

Reject attempted submissions for unsubmittable assignments in mailpipe.

This implements the expected behaviour for the option created by:

  commit 80639ff31b3bc6780659f526d518526cf63fcaec
  Author: W. Trevor King <wking@tremily.us>
  Date:   Tue Apr 24 16:48:56 2012 -0400

    Add Assignment.submittable attribute to configure student submission.

Initial `respond` implementation in the `mailpipe` module.

Add Assignment.submittable attribute to configure student submission.

If `Assignment.submittable` is `True`, mailpipe will accept student
submissions for that assignment.  However, there may also be
assignments where you don't want to accept direct submissions
(e.g. attendance and written, in-class exams).  For these assignments,
you should leave the `submittable` option at its default `False`
value.

Note that `mailpipe` doesn't use this value yet (implementation coming
soon).