src/mailman/interfaces/user.py

   1 # Copyright (C) 2007-2023 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 """Interface describing the basics of a user."""
  19
  20 from mailman.interfaces.address import AddressError
  21 from public import public
  22 from zope.interface import Attribute, Interface
  23
  24
  25 @public
  26 class UnverifiedAddressError(AddressError):
  27     """Unverified address cannot be used as a user's preferred address."""
  28
  29
  30 @public
  31 class PasswordChangeEvent:
  32     """Event which gets triggered when a user changes their password."""
  33
  34     def __init__(self, user):
  35         self.user = user
  36
  37     def __str__(self):
  38         return '<{} {}>'.format(
  39             self.__class__.__name__, self.user.display_name)
  40
  41
  42 @public
  43 class IUser(Interface):
  44     """A basic user."""
  45
  46     display_name = Attribute(
  47         """This user's display name.""")
  48
  49     password = Attribute(
  50         """This user's password information.""")
  51
  52     user_id = Attribute(
  53         """The user's unique, random identifier as a UUID.""")
  54
  55     created_on = Attribute(
  56         """The date and time at which this user was created.""")
  57
  58     addresses = Attribute(
  59         """An iterator over all the `IAddresses` controlled by this user.""")
  60
  61     preferred_address = Attribute(
  62         """The user's preferred `IAddress`.  This must be validated.""")
  63
  64     memberships = Attribute(
  65         """A roster of this user's memberships.""")
  66
  67     is_server_owner = Attribute(
  68         """Boolean flag indicating whether the user is a server owner.""")
  69
  70     def register(email, display_name=None):
  71         """Register the given email address and link it to this user.
  72
  73         :param email: The text email address to register.
  74         :type email: str
  75         :param display_name: The user's display name.  If not given the empty
  76             string is used.
  77         :type display_name: str
  78         :return: The address object linked to the user.  If the associated
  79             address object already existed (unlinked to a user) then the
  80             `display_name` parameter is ignored.
  81         :rtype: `IAddress`
  82         :raises AddressAlreadyLinkedError: if this `IAddress` is already
  83             linked to another user.
  84         """
  85
  86     def link(address):
  87         """Link this user to the given IAddress.
  88
  89         Raises AddressAlreadyLinkedError if this IAddress is already linked to
  90         another user.
  91         """
  92
  93     def unlink(address):
  94         """Unlink this IAddress from the user.
  95
  96         Raises AddressNotLinkedError if this address is not linked to this
  97         user, either because it's not linked to any user or it's linked to
  98         some other user.
  99         """
 100
 101     def controls(email):
 102         """Determine whether this user controls the given email address.
 103
 104         :param email: The text email address to register.
 105         :type email: str
 106         :return: True if the user controls the given email address.
 107         :rtype: bool
 108         """
 109
 110     preferences = Attribute(
 111         """This user's preferences.""")
 112
 113     def absorb(user):
 114         """Merge the given user to ourself.
 115
 116         All IAddresses linked to `user` are relinked to ourself.  A
 117         memberships associated with `user` are changed to be memberships
 118         with ourself.  See `IPreferences.absorb()`.
 119
 120         The user's `display_name`, `password`, and `is_server_owner` settings
 121         are absorbed into ours, but only if ours is unset and the given user's
 122         values are set.
 123
 124         After being absorbed, the given user and its preferences are
 125         deleted.
 126
 127         It is not an error if `user` is ourself, but it is a no-op.
 128
 129         :param user: The user to merge into ourself.
 130         :type user: IUser
 131         :raises TypeError: if `user` is not a user.
 132         """