experimenting with some new interfaces

pymap/interfaces.py

@@ -167,6 +167,30 @@ def __init__(self, name):
         #: The name of the mailbox.
         self.name = name
 
+    @asyncio.coroutine
+    def init(self):
+        """For a new object, query the state of the mailbox backend such that
+        all attributes are appropriately set. Once this method returns, changes
+        from external sources will be caught by :meth:`.poll`.
+
+        :returns: The return value from this function is an arbitrary tracker
+                  value will be passed into calls :meth:`.poll`, for use by the
+                  backend.
+
+        """
+        raise NotImplementedError
+
+    @asyncio.coroutine
+    def poll(self, tracker):
+        """Checks the mailbox for any changes. This call should result in this
+        object's attributes being up-to-date.
+
+        :returns: Two-tuple of a new tracker value and a dictionary with
+                  anything that has changed since the last :meth:`.poll`.
+
+        """
+        raise NotImplementedError
+
     @asyncio.coroutine
     def get_messages_by_seq(self, seqs):
         """Get a list of :class:`Message` objects corresponding to given
@@ -184,7 +208,7 @@ def get_messages_by_uid(self, uids):
         """Get a list of :class:`Message` objects corresponding to the given
         UIDs.
 
-        :param seqs: List of items, as described in
+        :param uids: List of items, as described in
                      :class:`~pymap.parsing.specials.SequenceSet`.
         :returns: List of :class:`Message` objects.
 
@@ -264,17 +288,6 @@ def update_flags(self, messages, flag_list, mode='replace'):
         """
         raise NotImplementedError
 
-    @asyncio.coroutine
-    def poll(self):
-        """Checks the mailbox for any changes. This first time this is called
-        on the object, the ``exists`` and ``recent`` keys are always returned.
-
-        :returns: Dictionary with anything that has changed since the last
-                  :meth:`.poll`.
-
-        """
-        raise NotImplementedError
-
 
 class MessageInterface(object):
     """Corresponds to a single message, as it exists in a single mailbox."""