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