mailpipe: fix InvalidHandlerMessage error message construction.
[pygrader.git] / pygrader / mailpipe.py
1 # Copyright (C) 2012 W. Trevor King <wking@drexel.edu>
2 #
3 # This file is part of pygrader.
4 #
5 # pygrader is free software: you can redistribute it and/or modify it under the
6 # terms of the GNU General Public License as published by the Free Software
7 # Foundation, either version 3 of the License, or (at your option) any later
8 # version.
9 #
10 # pygrader is distributed in the hope that it will be useful, but WITHOUT ANY
11 # WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
12 # A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
13 #
14 # You should have received a copy of the GNU General Public License along with
15 # pygrader.  If not, see <http://www.gnu.org/licenses/>.
16
17 "Incoming email processing."
18
19 from __future__ import absolute_import
20
21 from email import message_from_file as _message_from_file
22 from email.header import decode_header as _decode_header
23 from email.mime.text import MIMEText as _MIMEText
24 import mailbox as _mailbox
25 import re as _re
26 import sys as _sys
27
28 import pgp_mime as _pgp_mime
29 from lxml import etree as _etree
30
31 from . import LOG as _LOG
32 from .email import construct_email as _construct_email
33 from .email import construct_response as _construct_response
34 from .model.person import Person as _Person
35
36 from .handler import InvalidMessage as _InvalidMessage
37 from .handler import InvalidSubjectMessage as _InvalidSubjectMessage
38 from .handler import Response as _Response
39 from .handler import UnsignedMessage as _UnsignedMessage
40 from .handler.get import InvalidStudent as _InvalidStudent
41 from .handler.get import run as _handle_get
42 from .handler.submission import InvalidAssignment as _InvalidAssignment
43 from .handler.submission import run as _handle_submission
44
45
46 _TAG_REGEXP = _re.compile('^.*\[([^]]*)\].*$')
47
48
49 class NoReturnPath (_InvalidMessage):
50     def __init__(self, address, **kwargs):
51         if 'error' not in kwargs:
52             kwargs['error'] = 'no Return-Path'
53         super(NoReturnPath, self).__init__(**kwargs)
54
55
56 class UnregisteredAddress (_InvalidMessage):
57     def __init__(self, address, **kwargs):
58         if 'error' not in kwargs:
59             kwargs['error'] = 'unregistered address {}'.format(address)
60         super(UnregisteredAddress, self).__init__(**kwargs)
61         self.address = address
62
63
64 class AmbiguousAddress (_InvalidMessage):
65     def __init__(self, address, people, **kwargs):
66         if 'error' not in kwargs:
67             kwargs['error'] = 'ambiguous address {}'.format(address)
68         super(AmbiguousAddress, self).__init__(**kwargs)
69         self.address = address
70         self.people = people
71
72
73 class SubjectlessMessage (_InvalidSubjectMessage):
74     def __init__(self, **kwargs):
75         if 'error' not in kwargs:
76             kwargs['error'] = 'no subject'
77         super(SubjectlessMessage, self).__init__(**kwargs)
78
79
80 class InvalidHandlerMessage (_InvalidSubjectMessage):
81     def __init__(self, target=None, handlers=None, **kwargs):
82         if 'error' not in kwargs:
83             kwargs['error'] = 'no handler for {!r}'.format(target)
84         super(InvalidHandlerMessage, self).__init__(**kwargs)
85         self.target = target
86         self.handlers = handlers
87
88
89 def mailpipe(basedir, course, stream=None, mailbox=None, input_=None,
90              output=None, continue_after_invalid_message=False, max_late=0,
91              handlers={
92         'get': _handle_get,
93         'submit': _handle_submission,
94         }, respond=None, dry_run=False, **kwargs):
95     """Run from procmail to sort incomming submissions
96
97     For example, you can setup your ``.procmailrc`` like this::
98
99       SHELL=/bin/sh
100       DEFAULT=$MAIL
101       MAILDIR=$HOME/mail
102       DEFAULT=$MAILDIR/mbox
103       LOGFILE=$MAILDIR/procmail.log
104       #VERBOSE=yes
105       PYGRADE_MAILPIPE="pg.py -d $HOME/grades/phys160"
106
107       # Grab all incoming homeworks emails.  This rule eats matching emails
108       # (i.e. no further procmail processing).
109       :0
110       * ^Subject:.*\[phys160:submit]
111       | "$PYGRADE_MAILPIPE" mailpipe
112
113     If you don't want procmail to eat the message, you can use the
114     ``c`` flag (carbon copy) by starting your rule off with ``:0 c``.
115
116     >>> from io import StringIO
117     >>> from pgp_mime.email import encodedMIMEText
118     >>> from .handler import InvalidMessage, Response
119     >>> from .test.course import StubCourse
120
121     >>> course = StubCourse()
122     >>> def respond(message):
123     ...     print('respond with:\\n{}'.format(message.as_string()))
124     >>> def process(message):
125     ...     mailpipe(
126     ...         basedir=course.basedir, course=course.course,
127     ...         stream=StringIO(message.as_string()),
128     ...         output=course.mailbox,
129     ...         continue_after_invalid_message=True,
130     ...         respond=respond)
131     >>> message = encodedMIMEText('The answer is 42.')
132     >>> message['Message-ID'] = '<123.456@home.net>'
133     >>> message['Received'] = (
134     ...     'from smtp.home.net (smtp.home.net [123.456.123.456]) '
135     ...     'by smtp.mail.uu.edu (Postfix) with ESMTP id 5BA225C83EF '
136     ...     'for <wking@tremily.us>; Sun, 09 Oct 2011 11:50:46 -0400 (EDT)')
137     >>> message['From'] = 'Billy B <bb@greyhavens.net>'
138     >>> message['To'] = 'phys101 <phys101@tower.edu>'
139     >>> message['Subject'] = '[submit] assignment 1'
140
141     Messages with unrecognized ``Return-Path``\s are silently dropped:
142
143     >>> process(message)  # doctest: +REPORT_UDIFF, +ELLIPSIS
144     >>> course.print_tree()  # doctest: +REPORT_UDIFF, +ELLIPSIS
145     course.conf
146     mail
147     mail/cur
148     mail/new
149     mail/tmp
150
151     Response to a message from an unregistered person:
152
153     >>> message['Return-Path'] = '<invalid.return.path@home.net>'
154     >>> process(message)  # doctest: +REPORT_UDIFF, +ELLIPSIS
155     respond with:
156     Content-Type: multipart/signed; protocol="application/pgp-signature"; micalg="pgp-sha1"; boundary="===============...=="
157     MIME-Version: 1.0
158     Content-Disposition: inline
159     Date: ...
160     From: Robot101 <phys101@tower.edu>
161     Reply-to: Robot101 <phys101@tower.edu>
162     To: "invalid.return.path@home.net" <invalid.return.path@home.net>
163     Subject: unregistered address invalid.return.path@home.net
164     <BLANKLINE>
165     --===============...==
166     Content-Type: multipart/mixed; boundary="===============...=="
167     MIME-Version: 1.0
168     <BLANKLINE>
169     --===============...==
170     Content-Type: text/plain; charset="us-ascii"
171     MIME-Version: 1.0
172     Content-Transfer-Encoding: 7bit
173     Content-Disposition: inline
174     <BLANKLINE>
175     invalid.return.path@home.net,
176     <BLANKLINE>
177     Your email address is not registered with pygrader for
178     Physics 101.  If you feel it should be, contact your professor
179     or TA.
180     <BLANKLINE>
181     Yours,
182     phys-101 robot
183     <BLANKLINE>
184     --===============...==
185     Content-Type: message/rfc822
186     MIME-Version: 1.0
187     <BLANKLINE>
188     Content-Type: text/plain; charset="us-ascii"
189     MIME-Version: 1.0
190     Content-Transfer-Encoding: 7bit
191     Content-Disposition: inline
192     Message-ID: <123.456@home.net>
193     Received: from smtp.home.net (smtp.home.net [123.456.123.456]) by smtp.mail.uu.edu (Postfix) with ESMTP id 5BA225C83EF for <wking@tremily.us>; Sun, 09 Oct 2011 11:50:46 -0400 (EDT)
194     From: Billy B <bb@greyhavens.net>
195     To: phys101 <phys101@tower.edu>
196     Subject: [submit] assignment 1
197     Return-Path: <invalid.return.path@home.net>
198     <BLANKLINE>
199     The answer is 42.
200     --===============...==--
201     --===============...==
202     MIME-Version: 1.0
203     Content-Transfer-Encoding: 7bit
204     Content-Description: OpenPGP digital signature
205     Content-Type: application/pgp-signature; name="signature.asc"; charset="us-ascii"
206     <BLANKLINE>
207     -----BEGIN PGP SIGNATURE-----
208     Version: GnuPG v2.0.19 (GNU/Linux)
209     <BLANKLINE>
210     ...
211     -----END PGP SIGNATURE-----
212     <BLANKLINE>
213     --===============...==--
214
215     If we add a valid ``Return-Path``, we get the expected delivery:
216
217     >>> del message['Return-Path']
218     >>> message['Return-Path'] = '<bb@greyhavens.net>'
219     >>> process(message)  # doctest: +REPORT_UDIFF, +ELLIPSIS
220     respond with:
221     Content-Type: text/plain; charset="us-ascii"
222     MIME-Version: 1.0
223     Content-Disposition: inline
224     Content-Transfer-Encoding: 7bit
225     <BLANKLINE>
226     Billy,
227     <BLANKLINE>
228     We received your submission for Assignment 1 on Sun, 09 Oct 2011 15:50:46 -0000.
229     <BLANKLINE>
230     Yours,
231     phys-101 robot
232     <BLANKLINE>
233
234     >>> course.print_tree()  # doctest: +REPORT_UDIFF, +ELLIPSIS
235     Bilbo_Baggins
236     Bilbo_Baggins/Assignment_1
237     Bilbo_Baggins/Assignment_1/mail
238     Bilbo_Baggins/Assignment_1/mail/cur
239     Bilbo_Baggins/Assignment_1/mail/new
240     Bilbo_Baggins/Assignment_1/mail/new/...:2,S
241     Bilbo_Baggins/Assignment_1/mail/tmp
242     course.conf
243     mail
244     mail/cur
245     mail/new
246     mail/new/...
247     mail/tmp
248
249     The last ``Received`` is used to timestamp the message:
250
251     >>> del message['Message-ID']
252     >>> message['Message-ID'] = '<abc.def@home.net>'
253     >>> del message['Received']
254     >>> message['Received'] = (
255     ...     'from smtp.mail.uu.edu (localhost.localdomain [127.0.0.1]) '
256     ...     'by smtp.mail.uu.edu (Postfix) with SMTP id 68CB45C8453 '
257     ...     'for <wking@tremily.us>; Mon, 10 Oct 2011 12:50:46 -0400 (EDT)')
258     >>> message['Received'] = (
259     ...     'from smtp.home.net (smtp.home.net [123.456.123.456]) '
260     ...     'by smtp.mail.uu.edu (Postfix) with ESMTP id 5BA225C83EF '
261     ...     'for <wking@tremily.us>; Mon, 09 Oct 2011 11:50:46 -0400 (EDT)')
262     >>> process(message)  # doctest: +REPORT_UDIFF, +ELLIPSIS
263     respond with:
264     Content-Type: text/plain; charset="us-ascii"
265     MIME-Version: 1.0
266     Content-Disposition: inline
267     Content-Transfer-Encoding: 7bit
268     <BLANKLINE>
269     Billy,
270     <BLANKLINE>
271     We received your submission for Assignment 1 on Mon, 10 Oct 2011 16:50:46 -0000.
272     <BLANKLINE>
273     Yours,
274     phys-101 robot
275     <BLANKLINE>
276     >>> course.print_tree()  # doctest: +REPORT_UDIFF, +ELLIPSIS
277     Bilbo_Baggins
278     Bilbo_Baggins/Assignment_1
279     Bilbo_Baggins/Assignment_1/late
280     Bilbo_Baggins/Assignment_1/mail
281     Bilbo_Baggins/Assignment_1/mail/cur
282     Bilbo_Baggins/Assignment_1/mail/new
283     Bilbo_Baggins/Assignment_1/mail/new/...:2,S
284     Bilbo_Baggins/Assignment_1/mail/new/...:2,S
285     Bilbo_Baggins/Assignment_1/mail/tmp
286     course.conf
287     mail
288     mail/cur
289     mail/new
290     mail/new/...
291     mail/new/...
292     mail/tmp
293
294     You can send receipts to the acknowledge incoming messages, which
295     includes warnings about dropped messages (except for messages
296     without ``Return-Path`` and messages where the ``Return-Path``
297     email belongs to multiple ``People``.  The former should only
298     occur with malicious emails, and the latter with improper pygrader
299     configurations).
300
301     Response to a successful submission:
302
303     >>> del message['Message-ID']
304     >>> message['Message-ID'] = '<hgi.jlk@home.net>'
305     >>> process(message)  # doctest: +REPORT_UDIFF, +ELLIPSIS
306     respond with:
307     Content-Type: text/plain; charset="us-ascii"
308     MIME-Version: 1.0
309     Content-Disposition: inline
310     Content-Transfer-Encoding: 7bit
311     <BLANKLINE>
312     Billy,
313     <BLANKLINE>
314     We received your submission for Assignment 1 on Mon, 10 Oct 2011 16:50:46 -0000.
315     <BLANKLINE>
316     Yours,
317     phys-101 robot
318     <BLANKLINE>
319
320     Response to a submission on an unsubmittable assignment:
321
322     >>> del message['Subject']
323     >>> message['Subject'] = '[submit] attendance 1'
324     >>> process(message)  # doctest: +REPORT_UDIFF, +ELLIPSIS
325     respond with:
326     Content-Type: multipart/signed; protocol="application/pgp-signature"; micalg="pgp-sha1"; boundary="===============...=="
327     MIME-Version: 1.0
328     Content-Disposition: inline
329     Date: ...
330     From: Robot101 <phys101@tower.edu>
331     Reply-to: Robot101 <phys101@tower.edu>
332     To: Bilbo Baggins <bb@shire.org>
333     Subject: Received invalid Attendance 1 submission
334     <BLANKLINE>
335     --===============...==
336     Content-Type: multipart/mixed; boundary="===============...=="
337     MIME-Version: 1.0
338     <BLANKLINE>
339     --===============...==
340     Content-Type: text/plain; charset="us-ascii"
341     MIME-Version: 1.0
342     Content-Transfer-Encoding: 7bit
343     Content-Disposition: inline
344     <BLANKLINE>
345     Billy,
346     <BLANKLINE>
347     We received your submission for Attendance 1, but you are not
348     allowed to submit that assignment via email.
349     <BLANKLINE>
350     Yours,
351     phys-101 robot
352     <BLANKLINE>
353     --===============...==
354     Content-Type: message/rfc822
355     MIME-Version: 1.0
356     <BLANKLINE>
357     Content-Type: text/plain; charset="us-ascii"
358     MIME-Version: 1.0
359     Content-Transfer-Encoding: 7bit
360     Content-Disposition: inline
361     From: Billy B <bb@greyhavens.net>
362     To: phys101 <phys101@tower.edu>
363     Return-Path: <bb@greyhavens.net>
364     Received: from smtp.mail.uu.edu (localhost.localdomain [127.0.0.1]) by smtp.mail.uu.edu (Postfix) with SMTP id 68CB45C8453 for <wking@tremily.us>; Mon, 10 Oct 2011 12:50:46 -0400 (EDT)
365     Received: from smtp.home.net (smtp.home.net [123.456.123.456]) by smtp.mail.uu.edu (Postfix) with ESMTP id 5BA225C83EF for <wking@tremily.us>; Mon, 09 Oct 2011 11:50:46 -0400 (EDT)
366     Message-ID: <hgi.jlk@home.net>
367     Subject: [submit] attendance 1
368     <BLANKLINE>
369     The answer is 42.
370     --===============...==--
371     --===============...==
372     MIME-Version: 1.0
373     Content-Transfer-Encoding: 7bit
374     Content-Description: OpenPGP digital signature
375     Content-Type: application/pgp-signature; name="signature.asc"; charset="us-ascii"
376     <BLANKLINE>
377     -----BEGIN PGP SIGNATURE-----
378     Version: GnuPG v2.0.19 (GNU/Linux)
379     <BLANKLINE>
380     ...
381     -----END PGP SIGNATURE-----
382     <BLANKLINE>
383     --===============...==--
384
385     Response to a bad subject:
386
387     >>> del message['Subject']
388     >>> message['Subject'] = 'need help for the first homework'
389     >>> process(message)  # doctest: +REPORT_UDIFF, +ELLIPSIS
390     respond with:
391     Content-Type: multipart/signed; protocol="application/pgp-signature"; micalg="pgp-sha1"; boundary="===============...=="
392     MIME-Version: 1.0
393     Content-Disposition: inline
394     Date: ...
395     From: Robot101 <phys101@tower.edu>
396     Reply-to: Robot101 <phys101@tower.edu>
397     To: Bilbo Baggins <bb@shire.org>
398     Subject: no tag in 'need help for the first homework'
399     <BLANKLINE>
400     --===============...==
401     Content-Type: multipart/mixed; boundary="===============...=="
402     MIME-Version: 1.0
403     <BLANKLINE>
404     --===============...==
405     Content-Type: text/plain; charset="us-ascii"
406     MIME-Version: 1.0
407     Content-Transfer-Encoding: 7bit
408     Content-Disposition: inline
409     <BLANKLINE>
410     Billy,
411     <BLANKLINE>
412     We received an email message from you with an invalid
413     subject.
414     <BLANKLINE>
415     Yours,
416     phys-101 robot
417     <BLANKLINE>
418     --===============...==
419     Content-Type: message/rfc822
420     MIME-Version: 1.0
421     <BLANKLINE>
422     Content-Type: text/plain; charset="us-ascii"
423     MIME-Version: 1.0
424     Content-Transfer-Encoding: 7bit
425     Content-Disposition: inline
426     From: Billy B <bb@greyhavens.net>
427     To: phys101 <phys101@tower.edu>
428     Return-Path: <bb@greyhavens.net>
429     Received: from smtp.mail.uu.edu (localhost.localdomain [127.0.0.1]) by smtp.mail.uu.edu (Postfix) with SMTP id 68CB45C8453 for <wking@tremily.us>; Mon, 10 Oct 2011 12:50:46 -0400 (EDT)
430     Received: from smtp.home.net (smtp.home.net [123.456.123.456]) by smtp.mail.uu.edu (Postfix) with ESMTP id 5BA225C83EF for <wking@tremily.us>; Mon, 09 Oct 2011 11:50:46 -0400 (EDT)
431     Message-ID: <hgi.jlk@home.net>
432     Subject: need help for the first homework
433     <BLANKLINE>
434     The answer is 42.
435     --===============...==--
436     --===============...==
437     MIME-Version: 1.0
438     Content-Transfer-Encoding: 7bit
439     Content-Description: OpenPGP digital signature
440     Content-Type: application/pgp-signature; name="signature.asc"; charset="us-ascii"
441     <BLANKLINE>
442     -----BEGIN PGP SIGNATURE-----
443     Version: GnuPG v2.0.19 (GNU/Linux)
444     <BLANKLINE>
445     ...
446     -----END PGP SIGNATURE-----
447     <BLANKLINE>
448     --===============...==--
449
450     Response to a missing subject:
451
452     >>> del message['Subject']
453     >>> process(message)  # doctest: +REPORT_UDIFF, +ELLIPSIS
454     respond with:
455     Content-Type: multipart/signed; protocol="application/pgp-signature"; micalg="pgp-sha1"; boundary="===============...=="
456     MIME-Version: 1.0
457     Content-Disposition: inline
458     Date: ...
459     From: Robot101 <phys101@tower.edu>
460     Reply-to: Robot101 <phys101@tower.edu>
461     To: Bilbo Baggins <bb@shire.org>
462     Subject: no subject in <hgi.jlk@home.net>
463     <BLANKLINE>
464     --===============...==
465     Content-Type: multipart/mixed; boundary="===============...=="
466     MIME-Version: 1.0
467     <BLANKLINE>
468     --===============...==
469     Content-Type: text/plain; charset="us-ascii"
470     MIME-Version: 1.0
471     Content-Transfer-Encoding: 7bit
472     Content-Disposition: inline
473     <BLANKLINE>
474     Billy,
475     <BLANKLINE>
476     We received an email message from you without a subject.
477     <BLANKLINE>
478     Yours,
479     phys-101 robot
480     <BLANKLINE>
481     --===============...==
482     Content-Type: message/rfc822
483     MIME-Version: 1.0
484     <BLANKLINE>
485     Content-Type: text/plain; charset="us-ascii"
486     MIME-Version: 1.0
487     Content-Transfer-Encoding: 7bit
488     Content-Disposition: inline
489     From: Billy B <bb@greyhavens.net>
490     To: phys101 <phys101@tower.edu>
491     Return-Path: <bb@greyhavens.net>
492     Received: from smtp.mail.uu.edu (localhost.localdomain [127.0.0.1]) by smtp.mail.uu.edu (Postfix) with SMTP id 68CB45C8453 for <wking@tremily.us>; Mon, 10 Oct 2011 12:50:46 -0400 (EDT)
493     Received: from smtp.home.net (smtp.home.net [123.456.123.456]) by smtp.mail.uu.edu (Postfix) with ESMTP id 5BA225C83EF for <wking@tremily.us>; Mon, 09 Oct 2011 11:50:46 -0400 (EDT)
494     Message-ID: <hgi.jlk@home.net>
495     <BLANKLINE>
496     The answer is 42.
497     --===============...==--
498     --===============...==
499     MIME-Version: 1.0
500     Content-Transfer-Encoding: 7bit
501     Content-Description: OpenPGP digital signature
502     Content-Type: application/pgp-signature; name="signature.asc"; charset="us-ascii"
503     <BLANKLINE>
504     -----BEGIN PGP SIGNATURE-----
505     Version: GnuPG v2.0.19 (GNU/Linux)
506     <BLANKLINE>
507     ...
508     -----END PGP SIGNATURE-----
509     <BLANKLINE>
510     --===============...==--
511
512     Response to an insecure message from a person with a PGP key:
513
514     >>> student = course.course.person(email='bb@greyhavens.net')
515     >>> student.pgp_key = '4332B6E3'
516     >>> del message['Subject']
517     >>> process(message)  # doctest: +REPORT_UDIFF, +ELLIPSIS
518     respond with:
519     Content-Type: multipart/encrypted; protocol="application/pgp-encrypted"; micalg="pgp-sha1"; boundary="===============...=="
520     MIME-Version: 1.0
521     Content-Disposition: inline
522     Date: ...
523     From: Robot101 <phys101@tower.edu>
524     Reply-to: Robot101 <phys101@tower.edu>
525     To: Bilbo Baggins <bb@shire.org>
526     Subject: unsigned message <hgi.jlk@home.net>
527     <BLANKLINE>
528     --===============...==
529     MIME-Version: 1.0
530     Content-Transfer-Encoding: 7bit
531     Content-Type: application/pgp-encrypted; charset="us-ascii"
532     <BLANKLINE>
533     Version: 1
534     <BLANKLINE>
535     --===============...==
536     MIME-Version: 1.0
537     Content-Transfer-Encoding: 7bit
538     Content-Description: OpenPGP encrypted message
539     Content-Type: application/octet-stream; name="encrypted.asc"; charset="us-ascii"
540     <BLANKLINE>
541     -----BEGIN PGP MESSAGE-----
542     Version: GnuPG v2.0.19 (GNU/Linux)
543     <BLANKLINE>
544     ...
545     -----END PGP MESSAGE-----
546     <BLANKLINE>
547     --===============...==--
548
549     >>> course.cleanup()
550     """
551     if stream is None:
552         stream = _sys.stdin
553     for original,message,person,subject,target in _load_messages(
554         course=course, stream=stream, mailbox=mailbox, input_=input_,
555         output=output, dry_run=dry_run,
556         continue_after_invalid_message=continue_after_invalid_message,
557         respond=respond):
558         try:
559             handler = _get_handler(handlers=handlers, target=target)
560             handler(
561                 basedir=basedir, course=course, message=message,
562                 person=person, subject=subject,
563                 max_late=max_late, dry_run=dry_run)
564         except _InvalidMessage as error:
565             if not continue_after_invalid_message:
566                 raise
567             if respond:
568                 error.course = course
569                 error.message = original
570                 if person is not None and not hasattr(error, 'person'):
571                     error.person = person
572                 if subject is not None and not hasattr(error, 'subject'):
573                     error.subject = subject
574                 if target is not None and not hasattr(error, 'target'):
575                     error.target = target
576                 response = _get_error_response(error)
577                 respond(response)
578         except _Response as response:
579             if respond:
580                 author = course.robot
581                 target = person
582                 msg = response.message
583                 if isinstance(response.message, _MIMEText):
584                     # Manipulate body (based on pgp_mime.append_text)
585                     original_encoding = msg.get_charset().input_charset
586                     original_payload = str(
587                         msg.get_payload(decode=True), original_encoding)
588                     new_payload = (
589                         '{},\n\n'
590                         '{}\n\n'
591                         'Yours,\n'
592                         '{}\n').format(
593                         target.alias(), original_payload, author.alias())
594                     new_encoding = _pgp_mime.guess_encoding(new_payload)
595                     if msg.get('content-transfer-encoding', None):
596                         # clear CTE so set_payload will set it properly
597                         del msg['content-transfer-encoding']
598                     msg.set_payload(new_payload, new_encoding)
599                 subject = msg['Subject']
600                 del msg['Subject']
601                 assert subject is not None, msg
602                 msg = _construct_email(
603                     author=author, targets=[person], subject=subject,
604                     message=msg)
605                 respond(response.message)
606
607
608 def _load_messages(course, stream, mailbox=None, input_=None, output=None,
609                    continue_after_invalid_message=False, respond=None,
610                    dry_run=False):
611     if mailbox is None:
612         mbox = None
613         messages = [(None,_message_from_file(stream))]
614         if output is not None:
615             ombox = _mailbox.Maildir(output, factory=None, create=True)
616     elif mailbox == 'mbox':
617         mbox = _mailbox.mbox(input_, factory=None, create=False)
618         messages = mbox.items()
619         if output is not None:
620             ombox = _mailbox.mbox(output, factory=None, create=True)
621     elif mailbox == 'maildir':
622         mbox = _mailbox.Maildir(input_, factory=None, create=False)
623         messages = mbox.items()
624         if output is not None:
625             ombox = _mailbox.Maildir(output, factory=None, create=True)
626     else:
627         raise ValueError(mailbox)
628     for key,msg in messages:
629         try:
630             ret = _parse_message(course=course, message=msg)
631         except _InvalidMessage as error:
632             if not continue_after_invalid_message:
633                 raise
634             if respond:
635                 response = _get_error_response(error)
636                 if response is not None:
637                     respond(response)
638             continue
639         if output is not None and dry_run is False:
640             # move message from input mailbox to output mailbox
641             ombox.add(msg)
642             if mbox is not None:
643                 del mbox[key]
644         yield ret
645
646 def _parse_message(course, message):
647     """Parse an incoming email and respond if neccessary.
648
649     Return ``(msg, person, assignment, time)`` on successful parsing.
650     Return ``None`` on failure.
651     """
652     original = message
653     person = subject = target = None
654     try:
655         person = _get_message_person(course=course, message=message)
656         if person.pgp_key:
657             message = _get_decoded_message(
658                 course=course, message=message, person=person)
659         subject = _get_message_subject(message=message)
660         target = _get_message_target(subject=subject)
661     except _InvalidMessage as error:
662         error.course = course
663         error.message = original
664         if person is not None and not hasattr(error, 'person'):
665             error.person = person
666         if subject is not None and not hasattr(error, 'subject'):
667             error.subject = subject
668         if target is not None and not hasattr(error, 'target'):
669             error.target = target
670         raise
671     return (original, message, person, subject, target)
672
673 def _get_message_person(course, message):
674     sender = message['Return-Path']  # RFC 822
675     if sender is None:
676         raise NoReturnPath(message)
677     sender = sender[1:-1]  # strip wrapping '<' and '>'
678     people = list(course.find_people(email=sender))
679     if len(people) == 0:
680         raise UnregisteredAddress(message=message, address=sender)
681     if len(people) > 1:
682         raise AmbiguousAddress(message=message, address=sender, people=people)
683     return people[0]
684
685 def _get_decoded_message(course, message, person):
686     msg = _get_verified_message(message, person.pgp_key)
687     if msg is None:
688         raise _UnsignedMessage(message=message)
689     return msg
690
691 def _get_message_subject(message):
692     """
693     >>> from email.header import Header
694     >>> from pgp_mime.email import encodedMIMEText
695     >>> message = encodedMIMEText('The answer is 42.')
696     >>> message['Message-ID'] = 'msg-id'
697     >>> _get_message_subject(message=message)
698     Traceback (most recent call last):
699       ...
700     pygrader.mailpipe.SubjectlessMessage: no subject
701     >>> del message['Subject']
702     >>> subject = Header('unicode part', 'utf-8')
703     >>> subject.append('-ascii part', 'ascii')
704     >>> message['Subject'] = subject.encode()
705     >>> _get_message_subject(message=message)
706     'unicode part-ascii part'
707     >>> del message['Subject']
708     >>> message['Subject'] = 'clean subject'
709     >>> _get_message_subject(message=message)
710     'clean subject'
711     """
712     if message['Subject'] is None:
713         raise SubjectlessMessage(subject=None, message=message)
714
715     parts = _decode_header(message['Subject'])
716     part_strings = []
717     for string,encoding in parts:
718         if encoding is None:
719             encoding = 'ascii'
720         if not isinstance(string, str):
721             string = str(string, encoding)
722         part_strings.append(string)
723     subject = ''.join(part_strings)
724     _LOG.debug('decoded header {} -> {}'.format(parts[0], subject))
725     return subject.lower().replace('#', '')
726
727 def _get_message_target(subject):
728     """
729     >>> _get_message_target(subject='no tag')
730     Traceback (most recent call last):
731       ...
732     pygrader.handler.InvalidSubjectMessage: no tag in 'no tag'
733     >>> _get_message_target(subject='[] empty tag')
734     Traceback (most recent call last):
735       ...
736     pygrader.handler.InvalidSubjectMessage: empty tag in '[] empty tag'
737     >>> _get_message_target(subject='[abc] empty tag')
738     'abc'
739     >>> _get_message_target(subject='[phys160:abc] empty tag')
740     'abc'
741     """
742     match = _TAG_REGEXP.match(subject)
743     if match is None:
744         raise _InvalidSubjectMessage(
745             subject=subject, error='no tag in {!r}'.format(subject))
746     tag = match.group(1)
747     if tag == '':
748         raise _InvalidSubjectMessage(
749             subject=subject, error='empty tag in {!r}'.format(subject))
750     target = tag.rsplit(':', 1)[-1]
751     _LOG.debug('extracted target {} -> {}'.format(subject, target))
752     return target
753
754 def _get_handler(handlers, target):
755     try:
756         handler = handlers[target]
757     except KeyError as error:
758         raise InvalidHandlerMessage(
759             target=target, handlers=handlers) from error
760     return handler
761
762 def _get_verified_message(message, pgp_key):
763     """
764
765     >>> from pgp_mime import sign, encodedMIMEText
766
767     The student composes a message...
768
769     >>> message = encodedMIMEText('1.23 joules')
770
771     ... and signs it (with the pgp-mime test key).
772
773     >>> signed = sign(message, signers=['pgp-mime-test'])
774
775     As it is being delivered, the message picks up extra headers.
776
777     >>> signed['Message-ID'] = '<01234567@home.net>'
778     >>> signed['Received'] = 'from smtp.mail.uu.edu ...'
779     >>> signed['Received'] = 'from smtp.home.net ...'
780
781     We check that the message is signed, and that it is signed by the
782     appropriate key.
783
784     >>> signed.authenticated
785     Traceback (most recent call last):
786       ...
787     AttributeError: 'MIMEMultipart' object has no attribute 'authenticated'
788     >>> our_message = _get_verified_message(signed, pgp_key='4332B6E3')
789     >>> print(our_message.as_string())  # doctest: +REPORT_UDIFF
790     Content-Type: text/plain; charset="us-ascii"
791     MIME-Version: 1.0
792     Content-Transfer-Encoding: 7bit
793     Content-Disposition: inline
794     Message-ID: <01234567@home.net>
795     Received: from smtp.mail.uu.edu ...
796     Received: from smtp.home.net ...
797     <BLANKLINE>
798     1.23 joules
799     >>> our_message.authenticated
800     True
801
802     If it is signed, but not by the right key, we get ``None``.
803
804     >>> print(_get_verified_message(signed, pgp_key='01234567'))
805     None
806
807     If it is not signed at all, we get ``None``.
808
809     >>> print(_get_verified_message(message, pgp_key='4332B6E3'))
810     None
811     """
812     mid = message['message-id']
813     try:
814         decrypted,verified,result = _pgp_mime.verify(message=message)
815     except (ValueError, AssertionError):
816         _LOG.warning('could not verify {} (not signed?)'.format(mid))
817         return None
818     _LOG.debug(str(result, 'utf-8'))
819     tree = _etree.fromstring(result.replace(b'\x00', b''))
820     match = None
821     for signature in tree.findall('.//signature'):
822         for fingerprint in signature.iterchildren('fpr'):
823             if fingerprint.text.endswith(pgp_key):
824                 match = signature
825                 break
826     if match is None:
827         _LOG.warning('{} is not signed by the expected key'.format(mid))
828         return None
829     if not verified:
830         sumhex = list(signature.iterchildren('summary'))[0].get('value')
831         summary = int(sumhex, 16)
832         if summary != 0:
833             _LOG.warning('{} has an unverified signature'.format(mid))
834             return None
835         # otherwise, we may have an untrusted key.  We'll count that
836         # as verified here, because the caller is explicity looking
837         # for signatures by this fingerprint.
838     for k,v in message.items(): # copy over useful headers
839         if k.lower() not in ['content-type',
840                              'mime-version',
841                              'content-disposition',
842                              ]:
843             decrypted[k] = v
844     decrypted.authenticated = True
845     return decrypted
846
847 def _get_error_response(error):
848     author = error.course.robot
849     target = getattr(error, 'person', None)
850     subject = str(error)
851     if isinstance(error, InvalidHandlerMessage):
852         targets = sorted(error.handlers.keys())
853         if not targets:
854             hint = (
855                 'In fact, there are no available handlers for this\n'
856                 'course!')
857         else:
858             hint = (
859                 'Perhaps you meant to use one of the following:\n'
860                 '  {}').format('\n  '.join(targets))
861         text = (
862             'We got an email from you with the following subject:\n'
863             '  {!r}\n'
864             'which does not match any submittable handler name for\n'
865             '{}.\n'
866             '{}').format(repr(error.subject), error.course.name, hint)
867     elif isinstance(error, SubjectlessMessage):
868         subject = 'no subject in {}'.format(error.message['Message-ID'])
869         text = 'We received an email message from you without a subject.'
870     elif isinstance(error, AmbiguousAddress):
871         text = (
872             'Multiple people match {} ({})'.format(
873                 error.address, ', '.join(p.name for p in error.people)))
874     elif isinstance(error, UnregisteredAddress):
875         target = _Person(name=error.address, emails=[error.address])
876         text = (
877             'Your email address is not registered with pygrader for\n'
878             '{}.  If you feel it should be, contact your professor\n'
879             'or TA.').format(error.course.name)
880     elif isinstance(error, NoReturnPath):
881         return
882     elif isinstance(error, _InvalidSubjectMessage):
883         text = (
884             'We received an email message from you with an invalid\n'
885             'subject.')
886     elif isinstance(error, _UnsignedMessage):
887         subject = 'unsigned message {}'.format(error.message['Message-ID'])
888         text = (
889             'We received an email message from you without a valid\n'
890             'PGP signature.')
891     elif isinstance(error, _InvalidAssignment):
892         text = (
893             'We received your submission for {}, but you are not\n'
894             'allowed to submit that assignment via email.'
895             ).format(error.assignment.name)
896     elif isinstance(error, _InvalidStudent):
897         text = (
898             'We got an email from you with the following subject:\n'
899             '  {!r}\n'
900             'but it matches several students:\n'
901             '  * {}').format(
902             error.subject, '\n  * '.join(s.name for s in error.students))
903     elif isinstance(error, _InvalidMessage):
904         text = subject
905     else:
906         raise NotImplementedError((type(error), error))
907     if target is None:
908         raise NotImplementedError((type(error), error))
909     return _construct_response(
910         author=author,
911         targets=[target],
912         subject=subject,
913         text=(
914             '{},\n\n'
915             '{}\n\n'
916             'Yours,\n'
917             '{}\n'.format(target.alias(), text, author.alias())),
918         original=error.message)