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