From df6ec9f2960f1de89acc17ec28c3fe170a32e1dd Mon Sep 17 00:00:00 2001 From: Barry Warsaw Date: Mon, 30 Jan 2012 10:37:16 -0500 Subject: * Held messages can now be moderated through the REST API. Mailing list resources now accept a `held` path component. GETing this returns all held messages for the mailing list. POSTing to a specific request id under this url can dispose of the message using `Action` enums. * `IRequests` interface is removed. Now just use adaptation from `IListRequests` directly (which takes an `IMailingList` object). * `handle_message()` now allows for `Action.hold` which is synonymous with `Action.defer` (since the message is already being held). * `IListRequests.get_request()` now takes an optional `request_type` argument to narrow the search for the given request. - also, print_function is now a standard __future__ import. The template has been updated, but add this to modules as you edit them. --- src/mailman/rest/docs/moderation.rst | 131 +++++++++++++++++++++++++++++++++++ 1 file changed, 131 insertions(+) create mode 100644 src/mailman/rest/docs/moderation.rst (limited to 'src/mailman/rest/docs') diff --git a/src/mailman/rest/docs/moderation.rst b/src/mailman/rest/docs/moderation.rst new file mode 100644 index 000000000..44a2183ec --- /dev/null +++ b/src/mailman/rest/docs/moderation.rst @@ -0,0 +1,131 @@ +======================= +Held message moderation +======================= + +Held messages can be moderated through the REST API. A mailing list starts +out with no held messages. + + >>> ant = create_list('ant@example.com') + >>> transaction.commit() + >>> dump_json('http://localhost:9001/3.0/lists/ant@example.com/held') + http_etag: "..." + start: 0 + total_size: 0 + +When a message gets held for moderator approval, it shows up in this list. +:: + + >>> msg = message_from_string("""\ + ... From: anne@example.com + ... To: ant@example.com + ... Subject: Something + ... Message-ID: + ... + ... Something else. + ... """) + + >>> from mailman.app.moderator import hold_message + >>> request_id = hold_message(ant, msg, {'extra': 7}, 'Because') + >>> transaction.commit() + + >>> dump_json('http://localhost:9001/3.0/lists/ant@example.com/held') + entry 0: + data: {u'_mod_subject': u'Something', + u'_mod_message_id': u'', + u'extra': 7, + u'_mod_fqdn_listname': u'ant@example.com', + u'_mod_hold_date': u'2005-08-01T07:49:23', + u'_mod_reason': u'Because', + u'_mod_sender': u'anne@example.com'} + http_etag: "..." + id: 1 + key: + http_etag: "..." + start: 0 + total_size: 1 + +You can get an individual held message by providing the *request id* for that +message. This will include the text of the message. + + >>> dump_json('http://localhost:9001/3.0/lists/ant@example.com/held/1') + data: {u'_mod_subject': u'Something', + u'_mod_message_id': u'', + u'extra': 7, + u'_mod_fqdn_listname': u'ant@example.com', + u'_mod_hold_date': u'2005-08-01T07:49:23', + u'_mod_reason': u'Because', + u'_mod_sender': u'anne@example.com'} + http_etag: "..." + id: 1 + key: + msg: + From: anne@example.com + To: ant@example.com + Subject: Something + Message-ID: + X-Message-ID-Hash: GCSMSG43GYWWVUMO6F7FBUSSPNXQCJ6M + + Something else. + + +Individual messages can be moderated through the API by POSTing back to the +held message's resource. The POST data requires an action of one of the +following: + + * discard - throw the message away. + * reject - bounces the message back to the original author. + * defer - defer any action on the message (continue to hold it) + * accept - accept the message for posting. + +Let's see what happens when the above message is deferred. + + >>> dump_json('http://localhost:9001/3.0/lists/ant@example.com/held/1', { + ... 'action': 'defer', + ... }) + content-length: 0 + date: ... + server: ... + status: 204 + +The message is still in the moderation queue. + + >>> dump_json('http://localhost:9001/3.0/lists/ant@example.com/held/1') + data: {u'_mod_subject': u'Something', + u'_mod_message_id': u'', + u'extra': 7, + u'_mod_fqdn_listname': u'ant@example.com', + u'_mod_hold_date': u'2005-08-01T07:49:23', + u'_mod_reason': u'Because', + u'_mod_sender': u'anne@example.com'} + http_etag: "..." + id: 1 + key: + msg: From: anne@example.com + To: ant@example.com + Subject: Something + Message-ID: + X-Message-ID-Hash: GCSMSG43GYWWVUMO6F7FBUSSPNXQCJ6M + + Something else. + + +The held message can be discarded. + + >>> dump_json('http://localhost:9001/3.0/lists/ant@example.com/held/1', { + ... 'action': 'discard', + ... }) + content-length: 0 + date: ... + server: ... + status: 204 + +After which, the message is gone from the moderation queue. + + >>> dump_json('http://localhost:9001/3.0/lists/ant@example.com/held/1') + Traceback (most recent call last): + ... + HTTPError: HTTP Error 404: 404 Not Found + +- Hold another message +- Show accept +- Show reject? - probably not as we're just into testing app.moderator -- cgit v1.3.1