src/mailman/interfaces/address.py

   1 # Copyright (C) 2007-2016 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 for email address related information."""
  19
  20 from mailman import public
  21 from mailman.interfaces.errors import MailmanError
  22 from zope.interface import Attribute, Interface
  23
  24
  25 @public
  26 class EmailError(MailmanError):
  27     """A generic text email address-related error occurred."""
  28
  29     def __init__(self, email):
  30         super().__init__()
  31         self.email = email
  32
  33     def __str__(self):
  34         return self.email
  35
  36
  37 @public
  38 class AddressError(MailmanError):
  39     """A generic IAddress-related error occurred."""
  40
  41     def __init__(self, address):
  42         super().__init__()
  43         self.address = address
  44
  45     def __str__(self):
  46         return str(self.address)
  47
  48
  49 @public
  50 class ExistingAddressError(AddressError):
  51     """The given email address already exists."""
  52
  53
  54 @public
  55 class AddressAlreadyLinkedError(AddressError):
  56     """The address is already linked to a user."""
  57
  58
  59 @public
  60 class AddressNotLinkedError(AddressError):
  61     """The address is not linked to the user."""
  62
  63
  64 @public
  65 class InvalidEmailAddressError(EmailError):
  66     """Email address is invalid."""
  67
  68
  69 @public
  70 class AddressVerificationEvent:
  71     """Triggered when an address gets verified or unverified."""
  72
  73     def __init__(self, address):
  74         self.address = address
  75
  76     def __str__(self):
  77         return '<{} {} {}>'.format(
  78             self.__class__.__name__,
  79             self.address.email,
  80             ('unverified' if self.address.verified_on is None
  81              else self.address.verified_on))
  82
  83
  84 @public
  85 class IAddress(Interface):
  86     """Email address related information."""
  87
  88     email = Attribute(
  89         """Read-only text email address.""")
  90
  91     original_email = Attribute(
  92         """Read-only original case-preserved email address.
  93
  94         For almost all intents and purposes, email addresses in Mailman are
  95         case insensitive, however because RFC 2821 allows for case sensitive
  96         local parts, Mailman preserves the case of the original email address
  97         when delivering a message to the user.
  98
  99         `original_email` will be the same as `email` if the original email
 100         address was all lower case.  Otherwise `original_email` will be the
 101         case preserved email address; `email` will always be lower case.
 102         """)
 103
 104     display_name = Attribute(
 105         """Optional display name associated with the email address.""")
 106
 107     registered_on = Attribute(
 108         """The date and time at which this email address was registered.
 109
 110         Registeration is really the date at which this address became known to
 111         us.  It may have been explicitly registered by a user, or it may have
 112         been implicitly registered, e.g. by showing up in a nonmember
 113         posting.""")
 114
 115     verified_on = Attribute(
 116         """The date and time at which this email address was validated, or
 117         None if the email address has not yet been validated.  The specific
 118         method of validation is not defined here.""")
 119
 120     preferences = Attribute(
 121         """This address's preferences.""")
 122
 123
 124 @public
 125 class IEmailValidator(Interface):
 126     """An email validator."""
 127
 128     def is_valid(email):
 129         """Check if an email address if valid.
 130
 131         :param email: A text email address.
 132         :type email: str
 133         :return: A flag indicating whether the email address is okay or not.
 134         :rtype: bool
 135         """
 136
 137     def validate(email):
 138         """Validate an email address.
 139
 140         :param email: A text email address.
 141         :type email: str
 142         :raise InvalidEmailAddressError: when `email` is deemed invalid.
 143         """