[Zope3-checkins] CVS: Zope3/src/zope/app/interfaces - event.py:1.5

[Steve Alexander]

Update of /cvs-repository/Zope3/src/zope/app/interfaces
In directory cvs.zope.org:/tmp/cvs-serv23130/src/zope/app/interfaces

Modified Files:
	event.py 
Log Message:
Large event service reimplementation.


=== Zope3/src/zope/app/interfaces/event.py 1.4 => 1.5 ===
--- Zope3/src/zope/app/interfaces/event.py:1.4	Mon Jan 27 13:16:16 2003
+++ Zope3/src/zope/app/interfaces/event.py	Mon Feb  3 10:59:14 2003
@@ -143,7 +143,7 @@
     """A subscribable that only works with physically locatable objects,
     or their paths or hubids."""
 
-    def subscribe(subscriber, event_type=IEvent, filter=None):
+    def subscribe(reference, event_type=IEvent, filter=None):
         """Add subscriber to the list of subscribers for the component.
 
         Subscriber must have an ISubscriber adapter, and must be accessible
@@ -166,7 +166,8 @@
         the subscriber.
 
         filter, if supplied, must implement IFilter; subscriber
-        will be notified of events only if they pass.
+        will be notified of events only if they pass. filter must be
+        picklable.
 
         A subscriber may subscribe more than once, even if it has
         already been subscribed with the same event type and
@@ -177,66 +178,93 @@
         will call the subscriber's subscribedTo method.
         """
 
-    def unsubscribe(subscriber, event_type=IEvent, filter=None):
-        """Unsubscribe subscriber from receiving event types from this
-        subscribable.
+    def unsubscribe(reference, event_type, filter=None):
+        '''Removes just one subscription.
 
-        Subscriber must implement ISubscriber, and must be accessible
-        via path.  The reference passed to the method may be a hard 
-        reference, contextually wrapped if appropriate; or a path or
-        hubid that reference the subscriber.
+        This is in parity with subscribe providing just one subscription.
+
+        A filter of None means 'the subscription with no filter' rather
+        than 'a subscription with any filter'.
+
+        A subscriber is determined based on the reference supplied.
+
+        If 'reference' is an object, it must be physically locatable so
+        we can get its path. We try to remove a subscription based on the
+        hubId (if available). If there is no hubId or no such subscription,
+        we try to remove a subscription based on the path.
+
+        If 'reference' is an int, it is interpreted as a hubId. We try to
+        remove a subscription by hubId, and then by path.
+
+        If 'reference' is a string or unicode, it is interpreted as an
+        absolute path. We try to remove a subscription by path, and then
+        by hubId.
+
+        If a subscription is removed, and the subscriber has an
+        ISubscribingAware adapter, the adapter's unsubscribedFrom method
+        is called.
+        If no subscription can be removed, we raise a NotFoundError.
+
+        If a path or hubId is given that no longer resolves to an object,
+        and such a subscription exists, then that subscription will be
+        removed and a warning logged.
+        '''
+
+    def unsubscribeAll(reference, event_type=IEvent):
+        '''Removes all subscriptions for subscriber that match event_type.
+
+        The subscriber is determined from the reference as described in
+        the docstring of the 'unsubscribe' method.
+
+        If a path and hubId can be determined for the subscriber,
+        all subscriptions by both path and hubId that match event_type
+        are removed.
 
-        If the subscriber is a hard reference then it will be
-        unsubscribed on the basis of both hubid, if available for the
-        object, and path; passing the path or the hubid unsubscribes
-        that only.
-
-        unsubscribe must also accept paths and hubids that no longer
-        resolve to an object, but if no subscriptions are found on the
-        basis of the unicode string or integer, a NotFoundError is
-        still raised.
-
-        If event_type is None, the default value, the subscriber is
-        unsubscribed completely for all event types from this
-        subscribable (and its parents, if the subscribable is a placeful
-        service).  The filter argument is ignored in this case.  If no
-        subscriptions for this subscriber are present, no error is
-        raised.
-
-        If event_type is supplied, this method will unsubscribe the
-        subscriber from one subscription exactly matching the
-        event_type/filter pair given (the default filter being None).
-        If other subscriptions are present they will remain.  If the
-        subscription cannot be found and the subscribable is a placeful
-        service, the unsubscription request is passed to parent
-        services.  Raises Zope.Exceptions.NotFound if subscriber wasn't 
-        subscribed as expected.
-
-        If the subscriber has an ISubscribingAware adapter, this function
-        will call the subscriber's unsubscribedFrom method for each
-        individual unsubscribe.
+        Subscriptions are removed only if the event in the subscription
+        is event_type, or extends event_type.
+
+        Returns the number of subscriptions removed.
+        '''
+
+    def resubscribeByHubId(reference):
+        """Change all subscriptions for reference by path into subscriptions
+        by hubId.
+
+        The reference may be a hubId, a path or a physically locatable object.
+
+        Returns the number of subscriptions converted.
         """
 
-    def listSubscriptions(subscriber, event_type=IEvent):
+    def resubscribeByPath(reference):
+        """Change all subscriptions for reference by hubId into subscriptions
+        by path.
+
+        The reference may be a hubId, a path or a physically locatable object.
+
+        Returns the number of subscriptions converted.
+        """
+
+    def iterSubscriptions(reference=None, event_type=IEvent):
         """Returns an iterator of the subscriptions to this channel for
-        the subscriber.
+        the referenced subscriber.
+
+        The reference may be a hubId, a path or a physically locatable object.
+        Subscriptions by hubId and by path are returned.
+        The reference may also be None, meaning that subscriptions for all
+        subscribers are to be returned.
 
-        Subscriber must must be accessible via path.
-        The reference passed to the method may be a hard reference,
-        contextually wrapped if appropriate; or a path or hubid that
-        reference the subscriber.
-
-        If the subscriber is a hard reference then it will return an
-        iterator of subscriptions on the basis of both hubid, if
-        available for the object, and path; passing the path or the
-        hubid lists subscriptions for that only.
-
-        If event_type is supplied, the list is limited
-        to that exact event_type.  If the subscribable is a placeful
-        service, the list will include subscriptions to parent services.
-        No subscriptions returns an empty iterator.  Each subscription is
-        represented as a tuple (event_type, filter)."""
+        If event_type is supplied, only those subscriptions where the
+        event_type of the subscription extends or is equal to the given
+        event_type will be returned.
 
+        Each element of the iteration is a three-tuple:
+
+          (reference, event_type, filter)
+
+        The first element of the tuple will the int or unicode that is
+        subscribed. The second element is the event_type subscribed.
+        The third is the filter subscribed.
+        """
 
 class IObjectEvent(IEvent):
     """Something has happened to an object.