1# Copyright (C) 2007-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"""Interface describing the user management service.""" 19 20from public import public 21from zope.interface import Attribute, Interface 22 23 24@public 25class IUserManager(Interface): 26 """The global user management service.""" 27 28 def create_user(email=None, display_name=None): 29 """Create and return an `IUser`. 30 31 :param email: The text email address for the user being created. 32 :type email: str 33 :param display_name: The display name of the user. 34 :type display_name: str 35 :return: The newly created user, with the given email address and real 36 name, if given. 37 :rtype: `IUser` 38 :raises ExistingAddressError: when the email address is already 39 registered. 40 """ 41 42 def make_user(email, display_name=None): 43 """Create a new user linked to an address object. 44 45 If ``email`` is already associated with an existing `IAddress` 46 object, use that, otherwise create a new `IAddress`. If the 47 address object already points to an `IUser` return it. If a new 48 `IUser` is created, link the address to the user. 49 50 :param email: The email address. 51 :type email: str 52 :param display_name: The display name. 53 :type display_name: str 54 :return: the IUser object that exists or was created. 55 :rtype: IUser 56 """ 57 58 def delete_user(user): 59 """Delete the given user. 60 61 :param user: The user to delete. 62 :type user: `IUser`. 63 """ 64 65 def get_user(email): 66 """Get the user that controls the given email address, or None. 67 68 :param email: The email address to look up. 69 :type email: str 70 :return: The user found or None. 71 :rtype: `IUser`. 72 """ 73 74 def get_user_by_id(user_id): 75 """Get the user associated with the given id. 76 77 :param user_id: The user id. 78 :type user_id: `uuid.UUID` 79 :return: The user found or None. 80 :rtype: `IUser`. 81 """ 82 83 users = Attribute( 84 """An iterator over all the `IUsers` managed by this user manager.""") 85 86 def create_address(email, display_name=None): 87 """Create and return an address unlinked to any user. 88 89 :param email: The text email address for the address being created. 90 :type email: str 91 :param display_name: The display name associated with the address. 92 :type display_name: str 93 :return: The newly created address object, with the given email 94 address and display name, if given. 95 :rtype: `IAddress` 96 :raises ExistingAddressError: when the email address is already 97 registered. 98 """ 99 100 def delete_address(address): 101 """Delete the given `IAddress` object. 102 103 If the `IAddress` is linked to a user, it is first unlinked before it 104 is deleted. 105 106 :param address: The address to delete. 107 :type address: `IAddress`. 108 """ 109 110 def get_address(email): 111 """Find and return the `IAddress` matching an email address. 112 113 :param email: The text email address. 114 :type email: str 115 :return: The matching `IAddress` object, or None if no registered 116 `IAddress` matches the text address. 117 :rtype: `IAddress` or None 118 """ 119 120 addresses = Attribute( 121 """An iterator over all the `IAddresses` managed by this manager.""") 122 123 members = Attribute( 124 """An iterator of all the `IMembers` in the database.""") 125 126 server_owners = Attribute( 127 """An iterator over all the `IUsers` who are server owners.""") 128