← Back to branch summary

~barry/mailman/events-and-web

« back to all changes in this revision

Viewing changes to src/mailman/interfaces/bans.py

  • 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/interfaces/bans.py
17
17
 
18
18
"""Manager of email address bans."""
19
19
 
20
 
from __future__ import absolute_import, unicode_literals
 
20
from __future__ import absolute_import, print_function, unicode_literals
21
21
 
22
22
__metaclass__ = type
23
23
__all__ = [
33
33
class IBan(Interface):
34
34
    """A specific ban.
35
35
 
36
 
    In general, this interface isn't publicly useful.
 
36
    In general, this interface isn't used publicly.  Instead, bans are managed
 
37
    through the `IBanManager` interface.
37
38
    """
38
39
 
39
40
    email = Attribute('The banned email address, or pattern.')
40
41
 
41
 
    mailing_list = Attribute(
42
 
        """The fqdn name of the mailing list the ban applies to.
 
42
    list_id = Attribute(
 
43
        """The list-id of the mailing list the ban applies to.
43
44
 
44
 
        Use None if this is a global ban.
 
45
        Use ``None`` if this is a global ban.
45
46
        """)
46
47
 
47
48
 
48
49
 
49
50
class IBanManager(Interface):
50
 
    """The global manager of email address bans."""
51
 
 
52
 
    def ban(email, mailing_list=None):
 
51
    """The global manager of email address bans.
 
52
 
 
53
        To manage bans for a specific mailing list, adapt that `IMailingList`
 
54
        to an `IBanManager`.  To manage global bans, adapt ``None``.
 
55
        """
 
56
 
 
57
    def ban(email):
53
58
        """Ban an email address from subscribing to a mailing list.
54
59
 
55
60
        When an email address is banned, it will not be allowed to subscribe
56
 
        to a the named mailing list.  This does not affect any email address
57
 
        already subscribed to the mailing list.  With the default arguments,
58
 
        an email address can be banned globally from subscribing to any
59
 
        mailing list on the system.
 
61
        to the mailing list.  This does not affect any email address that may
 
62
        already be subscribed to a mailing list.
60
63
 
61
64
        It is also possible to add a 'ban pattern' whereby all email addresses
62
65
        matching a Python regular expression can be banned.  This is
63
66
        accomplished by using a `^` as the first character in `email`.
64
67
 
65
 
        When an email address is already banned for the given mailing list (or
66
 
        globally), then this method does nothing.  However, it is possible to
 
68
        When an email address is already banned.  However, it is possible to
67
69
        extend a ban for a specific mailing list into a global ban; both bans
68
70
        would be in place and they can be removed individually.
69
71
 
70
72
        :param email: The text email address being banned or, if the string
71
73
            starts with a caret (^), the email address pattern to ban.
72
74
        :type email: str
73
 
        :param mailing_list: The fqdn name of the mailing list to which the
74
 
            ban applies.  If None, then the ban is global.
75
 
        :type mailing_list: string
76
75
        """
77
76
 
78
 
    def unban(email, mailing_list=None):
 
77
    def unban(email):
79
78
        """Remove an email address ban.
80
79
 
81
80
        This removes a specific or global email address ban, which would have
85
84
        :param email: The text email address being unbanned or, if the string
86
85
            starts with a caret (^), the email address pattern to unban.
87
86
        :type email: str
88
 
        :param mailing_list: The fqdn name of the mailing list to which the
89
 
            unban applies.  If None, then the unban is global.
90
 
        :type mailing_list: string
91
87
        """
92
88
 
93
 
    def is_banned(email, mailing_list=None):
 
89
    def is_banned(email):
94
90
        """Check whether a specific email address is banned.
95
91
 
96
92
        `email` must be a text email address; it cannot be a pattern.  The
100
96
 
101
97
        :param email: The text email address being checked.
102
98
        :type email: str
103
 
        :param mailing_list: The fqdn name of the mailing list being checked.
104
 
            Note that if not None, both specific and global bans will be
105
 
            checked.  If None, then only global bans will be checked.
106
 
        :type mailing_list: string
107
99
        :return: A flag indicating whether the given email address is banned
108
100
            or not.
109
101
        :rtype: bool