diff options
Diffstat (limited to 'src/mailman/interfaces')
| -rw-r--r-- | src/mailman/interfaces/address.py | 20 | ||||
| -rw-r--r-- | src/mailman/interfaces/registrar.py | 21 | ||||
| -rw-r--r-- | src/mailman/interfaces/user.py | 34 | ||||
| -rw-r--r-- | src/mailman/interfaces/usermanager.py | 87 |
4 files changed, 87 insertions, 75 deletions
diff --git a/src/mailman/interfaces/address.py b/src/mailman/interfaces/address.py index 89a4c5b3b..72d021ae0 100644 --- a/src/mailman/interfaces/address.py +++ b/src/mailman/interfaces/address.py @@ -60,20 +60,20 @@ class InvalidEmailAddressError(AddressError): class IAddress(Interface): """Email address related information.""" - address = Attribute( + email = Attribute( """Read-only text email address.""") - original_address = Attribute( - """Read-only original case-preserved address. + original_email = Attribute( + """Read-only original case-preserved email address. - For almost all intents and purposes, addresses in Mailman are case - insensitive, however because RFC 2821 allows for case sensitive local - parts, Mailman preserves the case of the original address when - emailing the user. + For almost all intents and purposes, email addresses in Mailman are + case insensitive, however because RFC 2821 allows for case sensitive + local parts, Mailman preserves the case of the original email address + when delivering a message to the user. - `original_address` will be the same as address if the original address - was all lower case. Otherwise `original_address` will be the case - preserved address; `address` will always be lower case. + `original_email` will be the same as `email` if the original email + address was all lower case. Otherwise `original_email` will be the + case preserved email address; `email` will always be lower case. """) real_name = Attribute( diff --git a/src/mailman/interfaces/registrar.py b/src/mailman/interfaces/registrar.py index c85a0103c..fefd13698 100644 --- a/src/mailman/interfaces/registrar.py +++ b/src/mailman/interfaces/registrar.py @@ -35,28 +35,29 @@ from zope.interface import Interface class IRegistrar(Interface): - """Interface for registering and verifying addresses and users. + """Interface for registering and verifying email addresses and users. - This is a higher level interface to user registration, address + This is a higher level interface to user registration, email address confirmation, etc. than the IUserManager. The latter does no validation, syntax checking, or confirmation, while this interface does. """ - def register(mlist, address, real_name=None): + def register(mlist, email, real_name=None): """Register the email address, requesting verification. - No IAddress or IUser is created during this step, but after successful - confirmation, it is guaranteed that an IAddress with a linked IUser - will exist. When a verified IAddress matching address already exists, - this method will do nothing, except link a new IUser to the IAddress - if one is not yet associated with the address. + No `IAddress` or `IUser` is created during this step, but after + successful confirmation, it is guaranteed that an `IAddress` with a + linked `IUser` will exist. When a verified `IAddress` matching + `email` already exists, this method will do nothing, except link a new + `IUser` to the `IAddress` if one is not yet associated with the + email address. In all cases, the email address is sanity checked for validity first. :param mlist: The mailing list that is the focus of this registration. :type mlist: `IMailingList` - :param address: The email address to register. - :type address: str + :param email: The email address to register. + :type email: str :param real_name: The optional real name of the user. :type real_name: str :return: The confirmation token string. diff --git a/src/mailman/interfaces/user.py b/src/mailman/interfaces/user.py index 824f6e99c..21ccc460b 100644 --- a/src/mailman/interfaces/user.py +++ b/src/mailman/interfaces/user.py @@ -33,29 +33,31 @@ class IUser(Interface): """A basic user.""" real_name = Attribute( - """This user's Real Name.""") + """This user's real name.""") password = Attribute( """This user's password information.""") addresses = Attribute( - """An iterator over all the IAddresses controlled by this user.""") + """An iterator over all the `IAddresses` controlled by this user.""") memberships = Attribute( """A roster of this user's memberships.""") - def register(address, real_name=None): + def register(email, real_name=None): """Register the given email address and link it to this user. - In this case, 'address' is a text email address, not an IAddress - object. If real_name is not given, the empty string is used. - - Raises AddressAlreadyLinkedError if this IAddress is already linked to - another user. If the corresponding IAddress already exists but is not - linked, then it is simply linked to the user, in which case - real_name is ignored. - - Return the new IAddress object. + :param email: The text email address to register. + :type email: str + :param real_name: The user's real name. If not given the empty string + is used. + :type real_name: str + :return: The address object linked to the user. If the associated + address object already existed (unlinked to a user) then the + `real_name` parameter is ignored. + :rtype: `IAddress` + :raises AddressAlreadyLinkedError: if this `IAddress` is already + linked to another user. """ def link(address): @@ -73,11 +75,13 @@ class IUser(Interface): some other user. """ - def controls(address): + def controls(email): """Determine whether this user controls the given email address. - 'address' is a text email address. This method returns true if the - user controls the given email address, otherwise false. + :param email: The text email address to register. + :type email: str + :return: True if the user controls the given email address. + :rtype: bool """ preferences = Attribute( diff --git a/src/mailman/interfaces/usermanager.py b/src/mailman/interfaces/usermanager.py index 16c45ebcc..5893d74f3 100644 --- a/src/mailman/interfaces/usermanager.py +++ b/src/mailman/interfaces/usermanager.py @@ -15,7 +15,7 @@ # You should have received a copy of the GNU General Public License along with # GNU Mailman. If not, see <http://www.gnu.org/licenses/>. -"""Interface describing a user manager service.""" +"""Interface describing the user management service.""" from __future__ import absolute_import, unicode_literals @@ -30,67 +30,74 @@ from zope.interface import Interface, Attribute class IUserManager(Interface): - """The interface of a global user manager service. + """The global user management service.""" - Different user managers have different concepts of what a user is, and the - users managed by different IUserManagers are completely independent. This - is how you can separate the user contexts for different domains, on a - multiple domain system. + def create_user(email=None, real_name=None): + """Create and return an `IUser`. - There is one special roster, the null roster ('') which contains all - IUsers in all IRosters. - """ - - def create_user(address=None, real_name=None): - """Create and return an IUser. - - When address is given, an IAddress is also created and linked to the - new IUser object. If the address already exists, an - `ExistingAddressError` is raised. If the address exists but is - already linked to another user, an AddressAlreadyLinkedError is - raised. - - When real_name is given, the IUser's real_name is set to this string. - If an IAddress is also created and linked, its real_name is set to the - same string. + :param email: The text email address for the user being created. + :type email: str + :param real_name: The real name of the user. + :type real_name: str + :return: The newly created user, with the given email address and real + name, if given. + :rtype: `IUser` + :raises ExistingAddressError: when the email address is already + registered. """ def delete_user(user): - """Delete the given IUser.""" + """Delete the given user. - def get_user(address): + :param user: The user to delete. + :type user: `IUser`. + """ + + def get_user(email): """Get the user that controls the given email address, or None. - 'address' is a text email address. + :param email: The email address to look up. + :type email: str + :return: The user found or None. + :rtype: `IUser`. """ users = Attribute( - """An iterator over all the IUsers managed by this user manager.""") + """An iterator over all the `IUsers` managed by this user manager.""") - def create_address(address, real_name=None): - """Create and return an unlinked IAddress object. + def create_address(email, real_name=None): + """Create and return an address unlinked to any user. - address is the text email address. If real_name is not given, it - defaults to the empty string. If the IAddress already exists an - ExistingAddressError is raised. + :param email: The text email address for the address being created. + :type email: str + :param real_name: The real name associated with the address. + :type real_name: str + :return: The newly created address object, with the given email + address and real name, if given. + :rtype: `IAddress` + :raises ExistingAddressError: when the email address is already + registered. """ def delete_address(address): - """Delete the given IAddress object. + """Delete the given `IAddress` object. + + If the `IAddress` is linked to a user, it is first unlinked before it + is deleted. - If this IAddress linked to a user, it is first unlinked before it is - deleted. + :param address: The address to delete. + :type address: `IAddress`. """ - def get_address(address): - """Find and return the `IAddress` matching a text address. + def get_address(email): + """Find and return the `IAddress` matching an email address. - :param address: the text email address - :type address: string + :param email: The text email address. + :type email: str :return: The matching `IAddress` object, or None if no registered - `IAddress` matches the text address + `IAddress` matches the text address. :rtype: `IAddress` or None """ addresses = Attribute( - """An iterator over all the IAddresses managed by this manager.""") + """An iterator over all the `IAddresses` managed by this manager.""") |