src/mailman/interfaces/pending.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 """Interfaces for the pending database.
  19
  20 The pending database contains events that must be confirmed by the user.  It
  21 maps these events to a unique hash that can be used as a token for end user
  22 confirmation.
  23 """
  24
  25 __all__ = [
  26     'IPendable',
  27     'IPended',
  28     'IPendedKeyValue',
  29     'IPendings',
  30     ]
  31
  32
  33 from zope.interface import Interface, Attribute
  34
  35
  36 \f
  37 class IPendable(Interface):
  38     """A pendable object."""
  39
  40     def keys():
  41         """The keys of the pending event data, all of which are strings."""
  42
  43     def values():
  44         """The values of the pending event data, all of which are strings."""
  45
  46     def items():
  47         """The key/value pairs of the pending event data.
  48
  49         Both the keys and values must be strings.
  50         """
  51
  52
  53 \f
  54 class IPended(Interface):
  55     """A pended event, tied to a token."""
  56
  57     token = Attribute("""The pended token.""")
  58
  59     expiration_date = Attribute("""The expiration date of the pended event.""")
  60
  61
  62 \f
  63 class IPendedKeyValue(Interface):
  64     """A pended key/value pair."""
  65
  66     key = Attribute("""The pended key.""")
  67
  68     value = Attribute("""The pended value.""")
  69
  70
  71 \f
  72 class IPendings(Interface):
  73     """Interface to pending database."""
  74
  75     def add(pendable, lifetime=None):
  76         """Create a new entry in the pending database, returning a token.
  77
  78         :param pendable: The IPendable instance to add.
  79         :param lifetime: The amount of time, as a `datetime.timedelta` that
  80             the pended item should remain in the database.  When None is
  81             given, a system default maximum lifetime is used.
  82         :return: A token string for inclusion in urls and email confirmations.
  83         """
  84
  85     def confirm(token, *, expunge=True):
  86         """Return the IPendable matching the token.
  87
  88         :param token: The token string for the IPendable given by the `.add()`
  89             method, or None if there is no record associated with the token.
  90         :param expunge: A flag indicating whether the pendable record should
  91             also be removed from the database or not.
  92         :return: The matching IPendable or None if no match was found.
  93         """
  94
  95     def evict():
  96         """Remove all pended items whose lifetime has expired."""
  97
  98     def __iter__():
  99         """An iterator over all pendables.
 100
 101         Each element is a 2-tuple of the form (token, dict).
 102         """
 103
 104     count = Attribute('The number of pendables in the pendings database.')