← Back to branch summary

~barry/mailman/templatecache

« back to all changes in this revision

Viewing changes to src/mailman/rest/docs/moderation.rst

  • Committer: Barry Warsaw
  • Date: 2012-01-30 15:37:16 UTC
  • Revision ID: barry@list.org-20120130153716-s9qx07i6i0rltyax
 * 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.

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/mailman/rest/docs/moderation.rst
 
1
=======================
 
2
Held message moderation
 
3
=======================
 
4
 
 
5
Held messages can be moderated through the REST API.  A mailing list starts
 
6
out with no held messages.
 
7
 
 
8
    >>> ant = create_list('ant@example.com')
 
9
    >>> transaction.commit()
 
10
    >>> dump_json('http://localhost:9001/3.0/lists/ant@example.com/held')
 
11
    http_etag: "..."
 
12
    start: 0
 
13
    total_size: 0
 
14
 
 
15
When a message gets held for moderator approval, it shows up in this list.
 
16
::
 
17
 
 
18
    >>> msg = message_from_string("""\
 
19
    ... From: anne@example.com
 
20
    ... To: ant@example.com
 
21
    ... Subject: Something
 
22
    ... Message-ID: <alpha>
 
23
    ...
 
24
    ... Something else.
 
25
    ... """)
 
26
 
 
27
    >>> from mailman.app.moderator import hold_message
 
28
    >>> request_id = hold_message(ant, msg, {'extra': 7}, 'Because')
 
29
    >>> transaction.commit()
 
30
 
 
31
    >>> dump_json('http://localhost:9001/3.0/lists/ant@example.com/held')
 
32
    entry 0:
 
33
        data: {u'_mod_subject': u'Something',
 
34
               u'_mod_message_id': u'<alpha>',
 
35
               u'extra': 7,
 
36
               u'_mod_fqdn_listname': u'ant@example.com',
 
37
               u'_mod_hold_date': u'2005-08-01T07:49:23',
 
38
               u'_mod_reason': u'Because',
 
39
               u'_mod_sender': u'anne@example.com'}
 
40
        http_etag: "..."
 
41
        id: 1
 
42
        key: <alpha>
 
43
    http_etag: "..."
 
44
    start: 0
 
45
    total_size: 1
 
46
 
 
47
You can get an individual held message by providing the *request id* for that
 
48
message.  This will include the text of the message.
 
49
 
 
50
    >>> dump_json('http://localhost:9001/3.0/lists/ant@example.com/held/1')
 
51
    data: {u'_mod_subject': u'Something',
 
52
           u'_mod_message_id': u'<alpha>',
 
53
           u'extra': 7,
 
54
           u'_mod_fqdn_listname': u'ant@example.com',
 
55
           u'_mod_hold_date': u'2005-08-01T07:49:23',
 
56
           u'_mod_reason': u'Because',
 
57
           u'_mod_sender': u'anne@example.com'}
 
58
    http_etag: "..."
 
59
    id: 1
 
60
    key: <alpha>
 
61
    msg:
 
62
    From: anne@example.com
 
63
    To: ant@example.com
 
64
    Subject: Something
 
65
    Message-ID: <alpha>
 
66
    X-Message-ID-Hash: GCSMSG43GYWWVUMO6F7FBUSSPNXQCJ6M
 
67
    <BLANKLINE>
 
68
    Something else.
 
69
    <BLANKLINE>
 
70
 
 
71
Individual messages can be moderated through the API by POSTing back to the
 
72
held message's resource.   The POST data requires an action of one of the
 
73
following:
 
74
 
 
75
  * discard - throw the message away.
 
76
  * reject - bounces the message back to the original author.
 
77
  * defer - defer any action on the message (continue to hold it)
 
78
  * accept - accept the message for posting.
 
79
 
 
80
Let's see what happens when the above message is deferred.
 
81
 
 
82
    >>> dump_json('http://localhost:9001/3.0/lists/ant@example.com/held/1', {
 
83
    ...     'action': 'defer',
 
84
    ...     })
 
85
    content-length: 0
 
86
    date: ...
 
87
    server: ...
 
88
    status: 204
 
89
 
 
90
The message is still in the moderation queue.
 
91
 
 
92
    >>> dump_json('http://localhost:9001/3.0/lists/ant@example.com/held/1')
 
93
    data: {u'_mod_subject': u'Something',
 
94
           u'_mod_message_id': u'<alpha>',
 
95
           u'extra': 7,
 
96
           u'_mod_fqdn_listname': u'ant@example.com',
 
97
           u'_mod_hold_date': u'2005-08-01T07:49:23',
 
98
           u'_mod_reason': u'Because',
 
99
           u'_mod_sender': u'anne@example.com'}
 
100
    http_etag: "..."
 
101
    id: 1
 
102
    key: <alpha>
 
103
    msg: From: anne@example.com
 
104
    To: ant@example.com
 
105
    Subject: Something
 
106
    Message-ID: <alpha>
 
107
    X-Message-ID-Hash: GCSMSG43GYWWVUMO6F7FBUSSPNXQCJ6M
 
108
    <BLANKLINE>
 
109
    Something else.
 
110
    <BLANKLINE>
 
111
 
 
112
The held message can be discarded.
 
113
 
 
114
    >>> dump_json('http://localhost:9001/3.0/lists/ant@example.com/held/1', {
 
115
    ...     'action': 'discard',
 
116
    ...     })
 
117
    content-length: 0
 
118
    date: ...
 
119
    server: ...
 
120
    status: 204
 
121
 
 
122
After which, the message is gone from the moderation queue.
 
123
 
 
124
    >>> dump_json('http://localhost:9001/3.0/lists/ant@example.com/held/1')
 
125
    Traceback (most recent call last):
 
126
    ...
 
127
    HTTPError: HTTP Error 404: 404 Not Found
 
128
 
 
129
- Hold another message
 
130
- Show accept
 
131
- Show reject? - probably not as we're just into testing app.moderator