← Back to branch summary

~barry/mailman/events-and-web

« back to all changes in this revision

Viewing changes to src/mailman/app/docs/bans.rst

  • Committer: Barry Warsaw
  • Date: 2012-10-16 22:40:12 UTC
  • Revision ID: barry@list.org-20121016224012-xxrd5zgkwdrmh9y4
Database
--------
 * The `ban` table now uses list-ids to cross-reference the mailing list,
   since these cannot change even if the mailing list is moved or renamed.

Interfaces
----------
 * The `IBanManager` is no longer a global utility.  Instead, you adapt an
   `IMailingList` to an `IBanManager` to manage the bans for a specific
   mailing list.  To manage the global bans, adapt ``None``.

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/mailman/app/docs/bans.rst
6
6
mailing list or globally within the Mailman system.  Both explicit email
7
7
addresses and email address patterns can be banned.
8
8
 
9
 
Bans are managed through the `Ban Manager`.
 
9
Bans are managed through the `Ban Manager`.  There are ban managers for
 
10
specific lists, and there is a global ban manager.  To get access to the
 
11
global ban manager, adapt ``None``.
10
12
 
11
 
    >>> from zope.component import getUtility
12
13
    >>> from mailman.interfaces.bans import IBanManager
13
 
    >>> ban_manager = getUtility(IBanManager)
14
 
 
15
 
At first, no email addresses are banned, either globally...
16
 
 
17
 
    >>> ban_manager.is_banned('anne@example.com')
 
14
    >>> global_bans = IBanManager(None)
 
15
 
 
16
At first, no email addresses are banned globally.
 
17
 
 
18
    >>> global_bans.is_banned('anne@example.com')
18
19
    False
19
20
 
20
 
...or for a specific mailing list.
21
 
 
22
 
    >>> ban_manager.is_banned('bart@example.com', 'test@example.com')
 
21
To get a list-specific ban manager, adapt the mailing list object.
 
22
 
 
23
    >>> mlist = create_list('test@example.com')
 
24
    >>> test_bans = IBanManager(mlist)
 
25
 
 
26
There are no bans for this particular list.
 
27
 
 
28
    >>> test_bans.is_banned('bart@example.com')
23
29
    False
24
30
 
25
31
 
27
33
=============
28
34
 
29
35
An email address can be banned from a specific mailing list by adding a ban to
30
 
the ban manager.
 
36
the list's ban manager.
31
37
 
32
 
    >>> ban_manager.ban('cris@example.com', 'test@example.com')
33
 
    >>> ban_manager.is_banned('cris@example.com', 'test@example.com')
 
38
    >>> test_bans.ban('cris@example.com')
 
39
    >>> test_bans.is_banned('cris@example.com')
34
40
    True
35
 
    >>> ban_manager.is_banned('bart@example.com', 'test@example.com')
 
41
    >>> test_bans.is_banned('bart@example.com')
36
42
    False
37
43
 
38
44
However, this is not a global ban.
39
45
 
40
 
    >>> ban_manager.is_banned('cris@example.com')
 
46
    >>> global_bans.is_banned('cris@example.com')
41
47
    False
42
48
 
43
49
 
47
53
An email address can be banned globally, so that it cannot be subscribed to
48
54
any mailing list.
49
55
 
50
 
    >>> ban_manager.ban('dave@example.com')
51
 
 
52
 
Dave is banned from the test mailing list...
53
 
 
54
 
    >>> ban_manager.is_banned('dave@example.com', 'test@example.com')
55
 
    True
56
 
 
57
 
...and the sample mailing list.
58
 
 
59
 
    >>> ban_manager.is_banned('dave@example.com', 'sample@example.com')
60
 
    True
61
 
 
62
 
Dave is also banned globally.
63
 
 
64
 
    >>> ban_manager.is_banned('dave@example.com')
 
56
    >>> global_bans.ban('dave@example.com')
 
57
 
 
58
Because there is a global ban, Dave is also banned from the mailing list.
 
59
 
 
60
    >>> test_bans.is_banned('dave@example.com')
 
61
    True
 
62
 
 
63
Even when a new mailing list is created, Dave is still banned from this list
 
64
because of his global ban.
 
65
 
 
66
    >>> sample = create_list('sample@example.com')
 
67
    >>> sample_bans = IBanManager(sample)
 
68
    >>> sample_bans.is_banned('dave@example.com')
 
69
    True
 
70
 
 
71
Dave is of course banned globally.
 
72
 
 
73
    >>> global_bans.is_banned('dave@example.com')
65
74
    True
66
75
 
67
76
Cris however is not banned globally.
68
77
 
69
 
    >>> ban_manager.is_banned('cris@example.com')
 
78
    >>> global_bans.is_banned('cris@example.com')
70
79
    False
71
80
 
72
81
Even though Cris is not banned globally, we can add a global ban for her.
73
82
 
74
 
    >>> ban_manager.ban('cris@example.com')
75
 
    >>> ban_manager.is_banned('cris@example.com')
76
 
    True
77
 
 
78
 
Cris is obviously still banned from specific mailing lists.
79
 
 
80
 
    >>> ban_manager.is_banned('cris@example.com', 'test@example.com')
81
 
    True
82
 
    >>> ban_manager.is_banned('cris@example.com', 'sample@example.com')
83
 
    True
84
 
 
85
 
We can remove the global ban to once again just ban her address from the test
86
 
list.
87
 
 
88
 
    >>> ban_manager.unban('cris@example.com')
89
 
    >>> ban_manager.is_banned('cris@example.com', 'test@example.com')
90
 
    True
91
 
    >>> ban_manager.is_banned('cris@example.com', 'sample@example.com')
 
83
    >>> global_bans.ban('cris@example.com')
 
84
    >>> global_bans.is_banned('cris@example.com')
 
85
    True
 
86
 
 
87
Cris is now banned from all mailing lists.
 
88
 
 
89
    >>> test_bans.is_banned('cris@example.com')
 
90
    True
 
91
    >>> sample_bans.is_banned('cris@example.com')
 
92
    True
 
93
 
 
94
We can remove the global ban to once again just ban her address from just the
 
95
test list.
 
96
 
 
97
    >>> global_bans.unban('cris@example.com')
 
98
    >>> global_bans.is_banned('cris@example.com')
 
99
    False
 
100
    >>> test_bans.is_banned('cris@example.com')
 
101
    True
 
102
    >>> sample_bans.is_banned('cris@example.com')
92
103
    False
93
104
 
94
105
 
100
111
when an entire domain is a spam faucet.  When using a pattern, the email
101
112
address must start with a caret (^).
102
113
 
103
 
    >>> ban_manager.ban('^.*@example.org', 'test@example.com')
104
 
 
105
 
Now, no one from example.org can subscribe to the test list.
106
 
 
107
 
    >>> ban_manager.is_banned('elle@example.org', 'test@example.com')
108
 
    True
109
 
    >>> ban_manager.is_banned('eperson@example.org', 'test@example.com')
110
 
    True
111
 
    >>> ban_manager.is_banned('elle@example.com', 'test@example.com')
112
 
    False
113
 
 
114
 
They are not, however banned globally.
115
 
 
116
 
    >>> ban_manager.is_banned('elle@example.org', 'sample@example.com')
117
 
    False
118
 
    >>> ban_manager.is_banned('elle@example.org')
 
114
    >>> test_bans.ban('^.*@example.org')
 
115
 
 
116
Now, no one from example.org can subscribe to the test mailing list.
 
117
 
 
118
    >>> test_bans.is_banned('elle@example.org')
 
119
    True
 
120
    >>> test_bans.is_banned('eperson@example.org')
 
121
    True
 
122
 
 
123
example.com addresses are not banned.
 
124
 
 
125
    >>> test_bans.is_banned('elle@example.com')
 
126
    False
 
127
 
 
128
example.org addresses are not banned globally, nor for any other mailing
 
129
list.
 
130
 
 
131
    >>> sample_bans.is_banned('elle@example.org')
 
132
    False
 
133
    >>> global_bans.is_banned('elle@example.org')
119
134
    False
120
135
 
121
136
Of course, we can ban everyone from example.org globally too.
122
137
 
123
 
    >>> ban_manager.ban('^.*@example.org')
124
 
    >>> ban_manager.is_banned('elle@example.org', 'sample@example.com')
 
138
    >>> global_bans.ban('^.*@example.org')
 
139
    >>> sample_bans.is_banned('elle@example.org')
125
140
    True
126
 
    >>> ban_manager.is_banned('elle@example.org')
 
141
    >>> global_bans.is_banned('elle@example.org')
127
142
    True
128
143
 
129
144
We can remove the mailing list ban on the pattern, though the global ban will
130
145
still be in place.
131
146
 
132
 
    >>> ban_manager.unban('^.*@example.org', 'test@example.com')
133
 
    >>> ban_manager.is_banned('elle@example.org', 'test@example.com')
134
 
    True
135
 
    >>> ban_manager.is_banned('elle@example.org', 'sample@example.com')
136
 
    True
137
 
    >>> ban_manager.is_banned('elle@example.org')
 
147
    >>> test_bans.unban('^.*@example.org')
 
148
    >>> test_bans.is_banned('elle@example.org')
 
149
    True
 
150
    >>> sample_bans.is_banned('elle@example.org')
 
151
    True
 
152
    >>> global_bans.is_banned('elle@example.org')
138
153
    True
139
154
 
140
155
But once the global ban is removed, everyone from example.org can subscribe to
141
156
the mailing lists.
142
157
 
143
 
    >>> ban_manager.unban('^.*@example.org')
144
 
    >>> ban_manager.is_banned('elle@example.org', 'test@example.com')
145
 
    False
146
 
    >>> ban_manager.is_banned('elle@example.org', 'sample@example.com')
147
 
    False
148
 
    >>> ban_manager.is_banned('elle@example.org')
 
158
    >>> global_bans.unban('^.*@example.org')
 
159
    >>> test_bans.is_banned('elle@example.org')
 
160
    False
 
161
    >>> sample_bans.is_banned('elle@example.org')
 
162
    False
 
163
    >>> global_bans.is_banned('elle@example.org')
149
164
    False
150
165
 
151
166
 
154
169
 
155
170
It is not an error to add a ban more than once.  These are just ignored.
156
171
 
157
 
    >>> ban_manager.ban('fred@example.com', 'test@example.com')
158
 
    >>> ban_manager.ban('fred@example.com', 'test@example.com')
159
 
    >>> ban_manager.is_banned('fred@example.com', 'test@example.com')
 
172
    >>> test_bans.ban('fred@example.com')
 
173
    >>> test_bans.ban('fred@example.com')
 
174
    >>> test_bans.is_banned('fred@example.com')
160
175
    True
161
176
 
162
177
Nor is it an error to remove a ban more than once.
163
178
 
164
 
    >>> ban_manager.unban('fred@example.com', 'test@example.com')
165
 
    >>> ban_manager.unban('fred@example.com', 'test@example.com')
166
 
    >>> ban_manager.is_banned('fred@example.com', 'test@example.com')
 
179
    >>> test_bans.unban('fred@example.com')
 
180
    >>> test_bans.unban('fred@example.com')
 
181
    >>> test_bans.is_banned('fred@example.com')
167
182
    False