1# Copyright (C) 2011-2020 by the Free Software Foundation, Inc. 2# 3# This file is part of GNU Mailman. 4# 5# GNU Mailman is free software: you can redistribute it and/or modify it under 6# the terms of the GNU General Public License as published by the Free 7# Software Foundation, either version 3 of the License, or (at your option) 8# any later version. 9# 10# GNU Mailman is distributed in the hope that it will be useful, but WITHOUT 11# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 12# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for 13# more details. 14# 15# You should have received a copy of the GNU General Public License along with 16# GNU Mailman. If not, see <https://www.gnu.org/licenses/>. 17 18"""Manager of email address bans.""" 19 20from public import public 21from zope.interface import Attribute, Interface 22 23 24@public 25class IBan(Interface): 26 """A specific ban. 27 28 In general, this interface isn't used publicly. Instead, bans are managed 29 through the `IBanManager` interface. 30 """ 31 32 email = Attribute('The banned email address, or pattern.') 33 34 list_id = Attribute( 35 """The list-id of the mailing list the ban applies to. 36 37 Use ``None`` if this is a global ban. 38 """) 39 40 41@public 42class IBanManager(Interface): 43 """The global manager of email address bans. 44 45 To manage bans for a specific mailing list, adapt that `IMailingList` 46 to an `IBanManager`. To manage global bans, adapt ``None``. 47 """ 48 49 bans = Attribute( 50 """A `QuerySequence` over all the banned emails.""") 51 52 def ban(email): 53 """Ban an email address from subscribing to a mailing list. 54 55 When an email address is banned, it will not be allowed to subscribe 56 to the mailing list. This does not affect any email address that may 57 already be subscribed to a mailing list. 58 59 It is also possible to add a 'ban pattern' whereby all email addresses 60 matching a Python regular expression can be banned. This is 61 accomplished by using a `^` as the first character in `email`. 62 63 When an email address is already banned. However, it is possible to 64 extend a ban for a specific mailing list into a global ban; both bans 65 would be in place and they can be removed individually. 66 67 :param email: The text email address being banned or, if the string 68 starts with a caret (^), the email address pattern to ban. 69 :type email: str 70 """ 71 72 def unban(email): 73 """Remove an email address ban. 74 75 This removes a specific or global email address ban, which would have 76 been added with the `ban()` method. If a ban is lifted which did not 77 exist, this method does nothing. 78 79 :param email: The text email address being unbanned or, if the string 80 starts with a caret (^), the email address pattern to unban. 81 :type email: str 82 """ 83 84 def is_banned(email): 85 """Check whether a specific email address is banned. 86 87 `email` must be a text email address; it cannot be a pattern. The 88 given email address is checked against all registered bans, both 89 specific and regular expression, both for the named mailing list (if 90 given), and globally. 91 92 :param email: The text email address being checked. 93 :type email: str 94 :return: A flag indicating whether the given email address is banned 95 or not. 96 :rtype: bool 97 """ 98 99 def __iter__(): 100 """An iterator over all the banned email addresses. 101 102 :return: iterator over `IBan`""" 103