src/mailman/interfaces/domain.py

   1 # Copyright (C) 2007-2015 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 <http://www.gnu.org/licenses/>.
  17
  18 """Interface representing domains."""
  19
  20 __all__ = [
  21     'BadDomainSpecificationError',
  22     'DomainCreatedEvent',
  23     'DomainCreatingEvent',
  24     'DomainDeletedEvent',
  25     'DomainDeletingEvent',
  26     'IDomain',
  27     'IDomainManager',
  28     ]
  29
  30
  31 from mailman.core.errors import MailmanError
  32 from zope.interface import Interface, Attribute
  33
  34
  35 \f
  36 class BadDomainSpecificationError(MailmanError):
  37     """The specification of a virtual domain is invalid or duplicated."""
  38
  39     def __init__(self, domain):
  40         super(BadDomainSpecificationError, self).__init__(domain)
  41         self.domain = domain
  42
  43
  44 class DomainCreatingEvent:
  45     """A domain is about to be created."""
  46
  47     def __init__(self, mail_host):
  48         self.mail_host = mail_host
  49
  50
  51 class DomainCreatedEvent:
  52     """A domain was created."""
  53
  54     def __init__(self, domain):
  55         self.domain = domain
  56
  57
  58 class DomainDeletingEvent:
  59     """A domain is about to be deleted."""
  60
  61     def __init__(self, domain):
  62         self.domain = domain
  63
  64
  65 class DomainDeletedEvent:
  66     """A domain was deleted."""
  67
  68     def __init__(self, mail_host):
  69         self.mail_host = mail_host
  70
  71
  72 \f
  73 class IDomain(Interface):
  74     """Interface representing domains."""
  75
  76     mail_host = Attribute('The host name for email for this domain.')
  77
  78     url_host = Attribute(
  79         'The host name for the web interface for this domain.')
  80
  81     base_url = Attribute("""\
  82     The base url for the Mailman server at this domain, which includes the
  83     scheme and host name.""")
  84
  85     scheme = Attribute(
  86         """The protocol scheme used to contact this list's server.""")
  87
  88     description = Attribute(
  89         'The human readable description of the domain name.')
  90
  91     owners = Attribute("""\
  92         The relationship with the user database representing domain owners.""")
  93
  94     mailing_lists = Attribute(
  95         """All mailing lists for this domain.
  96
  97         The mailing lists are returned in order sorted by list-id.
  98         """)
  99
 100     def confirm_url(token=''):
 101         """The url used for various forms of confirmation.
 102
 103         :param token: The confirmation token to use in the url.
 104         :type token: string
 105         :return: The confirmation url.
 106         :rtype: string
 107         """
 108
 109
 110 \f
 111 class IDomainManager(Interface):
 112     """The manager of domains."""
 113
 114     def add(mail_host, description=None, base_url=None, owners=None):
 115         """Add a new domain.
 116
 117         :param mail_host: The email host name for the domain.
 118         :type mail_host: string
 119         :param description: The description of the domain.
 120         :type description: string
 121         :param base_url: The base url, including the scheme for the web
 122             interface of the domain.  If not given, it defaults to
 123             http://`mail_host`/
 124         :type base_url: string
 125         :param owners: Sequence of owners of the domain, defaults to None,
 126             meaning the domain does not have owners.
 127         :type owners: sequence of `IUser` or string emails.
 128         :return: The new domain object.
 129         :rtype: `IDomain`
 130         :raises `BadDomainSpecificationError`: when the `mail_host` is
 131             already registered.
 132         """
 133
 134     def remove(mail_host):
 135         """Remove the domain.
 136
 137         :param mail_host: The email host name of the domain to remove.
 138         :type mail_host: string
 139         :raises KeyError: if the named domain does not exist.
 140         """
 141
 142     def __getitem__(mail_host):
 143         """Return the named domain.
 144
 145         :param mail_host: The email host name of the domain to remove.
 146         :type mail_host: string
 147         :return: The domain object.
 148         :rtype: `IDomain`
 149         :raises KeyError: if the named domain does not exist.
 150         """
 151
 152     def get(mail_host, default=None):
 153         """Return the named domain.
 154
 155         :param mail_host: The email host name of the domain to remove.
 156         :type mail_host: string
 157         :param default: What to return if the named domain does not exist.
 158         :type default: object
 159         :return: The domain object or None if the named domain does not exist.
 160         :rtype: `IDomain`
 161         """
 162
 163     def __iter__():
 164         """An iterator over all the domains.
 165
 166         Domains are returned sorted by `mail_host`.
 167
 168         :return: iterator over `IDomain`.
 169         """
 170
 171     def __contains__(mail_host):
 172         """Is this a known domain?
 173
 174         :param mail_host: An email host name.
 175         :type mail_host: string
 176         :return: True if this domain is known.
 177         :rtype: bool
 178         """