src/mailman/interfaces/registrar.py

   1 # Copyright (C) 2007-2015 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 describing a user registration service.
  19
  20 This is a higher level interface to user registration, address confirmation,
  21 etc. than the IUserManager.  The latter does no validation, syntax checking,
  22 or confirmation, while this interface does.
  23 """
  24
  25 __all__ = [
  26     'ConfirmationNeededEvent',
  27     'IRegistrar',
  28     ]
  29
  30
  31 from zope.interface import Interface
  32
  33
  34 \f
  35 class ConfirmationNeededEvent:
  36     """Triggered when an address needs confirmation.
  37
  38     Addresses must be verified before they can receive messages or post
  39     to mailing list.  The confirmation message is sent to the user when
  40     this event is triggered.
  41     """
  42     def __init__(self, mlist, token, email):
  43         self.mlist = mlist
  44         self.token = token
  45         self.email = email
  46
  47
  48 \f
  49 class IRegistrar(Interface):
  50     """Interface for subscribing addresses and users.
  51
  52     This is a higher level interface to user registration, email address
  53     confirmation, etc. than the IUserManager.  The latter does no validation,
  54     syntax checking, or confirmation, while this interface does.
  55
  56     To use this, adapt an ``IMailingList`` to this interface.
  57     """
  58
  59     def register(subscriber=None, *,
  60                  pre_verified=False, pre_confirmed=False, pre_approved=False):
  61         """Subscribe an address or user according to subscription policies.
  62
  63         The mailing list's subscription policy is used to subscribe
  64         `subscriber` to the given mailing list.  The subscriber can be
  65         an ``IUser``, in which case the user must have a preferred
  66         address, and that preferred address will be subscribed.  The
  67         subscriber can also be an ``IAddress``, in which case the
  68         address will be subscribed.
  69
  70         The workflow may pause (i.e. be serialized, saved, and
  71         suspended) when some out-of-band confirmation step is required.
  72         For example, if the user must confirm, or the moderator must
  73         approve the subscription.  Use the ``confirm(token)`` method to
  74         resume the workflow.
  75
  76         :param subscriber: The user or address to subscribe.
  77         :type email: ``IUser`` or ``IAddress``
  78         :return: A 3-tuple is returned where the first element is the token
  79             hash, the second element is a ``TokenOwner`, and the third element
  80             is the subscribed member.  If the subscriber got subscribed
  81             immediately, the token will be None and the member will be
  82             an ``IMember``.  If the subscription got held, the token
  83             will be a hash and the member will be None.
  84         :rtype: (str-or-None, ``TokenOwner``, ``IMember``-or-None)
  85         :raises MembershipIsBannedError: when the address being subscribed
  86             appears in the global or list-centric bans.
  87         """
  88
  89     def confirm(token):
  90         """Continue any paused workflow.
  91
  92         Confirmation may occur after the user confirms their
  93         subscription request, or their email address must be verified,
  94         or the moderator must approve the subscription request.
  95
  96         :param token: A token matching a workflow.
  97         :type token: string
  98         :return: A 3-tuple is returned where the first element is the token
  99             hash, the second element is a ``TokenOwner`, and the third element
 100             is the subscribed member.  If the subscriber got subscribed
 101             immediately, the token will be None and the member will be
 102             an ``IMember``.  If the subscription is still being held, the token
 103             will be a hash and the member will be None.
 104         :rtype: (str-or-None, ``TokenOwner``, ``IMember``-or-None)
 105         :raises LookupError: when no workflow is associated with the token.
 106         """
 107
 108     def discard(token):
 109         """Discard the workflow matched to the given `token`.
 110
 111         :param token: A token matching a pending event with a type of
 112             'registration'.
 113         :raises LookupError: when no workflow is associated with the token.
 114         """
 115
 116     def evict():
 117         """Evict all saved workflows which have expired."""