[Pydispatcher-cvs] dispatch dispatcher.py,1.3,1.4

[<mcf...@us...>]

Update of /cvsroot/pydispatcher/dispatch
In directory sc8-pr-cvs1:/tmp/cvs-serv26311

Modified Files:
	dispatcher.py 
Log Message:
More documentation, created explicit error hierarchy to allow for catching individual error types, and to allow catching general error types without explicitly importing dispatcher.

Index: dispatcher.py
===================================================================
RCS file: /cvsroot/pydispatcher/dispatch/dispatcher.py,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** dispatcher.py	6 Jul 2003 15:00:11 -0000	1.3
--- dispatcher.py	6 Jul 2003 20:30:28 -0000	1.4
***************
*** 11,17 ****
  	Anonymous -- Singleton used to signal "Anonymous Sender"
  		See documentation of the Anonymous object.
! 	DispatcherError -- Raised on use of None as a signal
! 		or attempts to disconnect when there is no current
! 		connection.
  
  Internal attributes:
--- 11,19 ----
  	Anonymous -- Singleton used to signal "Anonymous Sender"
  		See documentation of the Anonymous object.
! 	DispatcherError -- Base class for Dispatcher errors
! 	DispatcherKeyError -- Raised on attempts to disconnect
! 		a connection which doesn't exist
! 	DispatcherTypeError -- Raised on use of None as a signal
! 		during connect/disconnect
  
  Internal attributes:
***************
*** 38,44 ****
  
  
! class DispatcherError(exceptions.Exception):
! 	def __init__(self, args=None):
! 		self.args = args
  
  try:
--- 40,49 ----
  
  
! class DispatcherError(Exception):
! 	"""Base class for all Dispatcher errors"""
! class DispatcherKeyError(KeyError, DispatcherError):
! 	"""Error raised when unknown (sender,signal) set specified"""
! class DispatcherTypeError(TypeError, DispatcherError):
! 	"""Error raised when inappropriate signal-type specified (None)"""
  
  try:
***************
*** 93,97 ****
  	"""Connect receiver to sender for signal
  
! 	receiver -- a callable Python object
  
  		if weak is True, then receiver must be weak-referencable
--- 98,104 ----
  	"""Connect receiver to sender for signal
  
! 	receiver -- a callable Python object which is to receive
! 		messages/signals/events.  Receivers must be hashable
! 		objects.
  
  		if weak is True, then receiver must be weak-referencable
***************
*** 116,120 ****
  	
  		if Any, receiver will receive any signal from the
! 		registered sender.
  		
  		Otherwise must be a hashable Python object other than
--- 123,128 ----
  	
  		if Any, receiver will receive any signal from the
! 		indicated sender (which might also be Any, but is not
! 		necessarily Any).
  		
  		Otherwise must be a hashable Python object other than
***************
*** 123,132 ****
  	sender -- the sender to which the receiver should respond
  	
! 		if Any, receiver will receive registered signals from
! 		any sender.
  		
! 		if Anonymous, receiver will only receive registered
! 		signals which do not specify a sender, or specify
! 		Anonymous explicitly as the sender.
  
  		Otherwise can be any python object.
--- 131,140 ----
  	sender -- the sender to which the receiver should respond
  	
! 		if Any, receiver will receive the indicated signals
! 		from any sender.
  		
! 		if Anonymous, receiver will only receive indicated
! 		signals from send/sendExact which do not specify a
! 		sender, or specify Anonymous explicitly as the sender.
  
  		Otherwise can be any python object.
***************
*** 137,144 ****
  		is false, then strong references will be used.
  
! 	returns None
  	"""
  	if signal is None:
! 		raise DispatcherError, 'signal cannot be None'
  	receiverID = id( receiver )
  	if weak: receiver = saferef.safeRef(receiver, onDelete=_removeReceiver)
--- 145,154 ----
  		is false, then strong references will be used.
  
! 	returns None, may raise DispatcherTypeError
  	"""
  	if signal is None:
! 		raise DispatcherTypeError(
! 			'Signal cannot be None (receiver=%r sender=%r)'%( receiver,sender)
! 		)
  	receiverID = id( receiver )
  	if weak: receiver = saferef.safeRef(receiver, onDelete=_removeReceiver)
***************
*** 172,181 ****
  
  def disconnect(receiver, signal=Any, sender=Any, weak=True):
! 	"""Disconnect receiver from sender for signal.
! 	
! 	Disconnecting is not required. The use of disconnect is the same as for
! 	connect, only in reverse. Think of it as undoing a previous connection."""
  	if signal is None:
! 		raise DispatcherError, 'signal cannot be None'
  	if weak: receiver = saferef.safeRef(receiver)
  	senderkey = id(sender)
--- 182,214 ----
  
  def disconnect(receiver, signal=Any, sender=Any, weak=True):
! 	"""Disconnect receiver from sender for signal
! 
! 	receiver -- the registered receiver to disconnect
! 	signal -- the registered signal to disconnect
! 	sender -- the registered sender to disconnect
! 	weak -- the weakref state to disconnect
! 
! 	disconnect reverses the process of connect,
! 	the semantics for the individual elements are
! 	logically equivalent to a tuple of
! 	(receiver, signal, sender, weak) used as a key
! 	to be deleted from the internal routing tables.
! 	(The actual process is slightly more complex
! 	but the semantics are basically the same).
! 
! 	Note:
! 		Using disconnect is not required to cleanup
! 		routing when an object is deleted, the framework
! 		will remove routes for deleted objects
! 		automatically.  It's only necessary to disconnect
! 		if you want to stop routing to a live object.
! 		
! 	returns None, may raise DispatcherTypeError or
! 		DispatcherKeyError
! 	"""
  	if signal is None:
! 		raise DispatcherTypeError(
! 			'Signal cannot be None (receiver=%r sender=%r)'%( receiver,sender)
! 		)
  	if weak: receiver = saferef.safeRef(receiver)
  	senderkey = id(sender)
***************
*** 183,195 ****
  		receivers = connections[senderkey][signal]
  	except KeyError:
! 		raise DispatcherError, \
! 			  'No receivers for signal %s from sender %s' % \
! 			  (repr(signal), sender)
  	try:
  		receivers.remove(receiver)
  	except ValueError:
! 		raise DispatcherError, \
! 			  'No connection to receiver %s for signal %s from sender %s' % \
! 			  (receiver, repr(signal), sender)
  	_cleanupConnections(senderkey, signal)
  
--- 216,235 ----
  		receivers = connections[senderkey][signal]
  	except KeyError:
! 		raise DispatcherKeyError(
! 			"""No receivers found for signal %r from sender %r""" %(
! 				signal,
! 				sender
! 			)
! 		)
  	try:
  		receivers.remove(receiver)
  	except ValueError:
! 		raise DispatcherKeyError(
! 			"""No connection to receiver %s for signal %s from sender %s""" %(
! 				receiver,
! 				signal,
! 				sender
! 			)
! 		)
  	_cleanupConnections(senderkey, signal)
  
***************
*** 238,243 ****
  
  	This gets all receivers which should receive
! 	signal from sender, each receiver should exist
! 	only once in the resulting generator
  	"""
  	receivers = {}
--- 278,283 ----
  
  	This gets all receivers which should receive
! 	the given signal from sender, each receiver should
! 	be produced only once by the resulting generator
  	"""
  	receivers = {}
***************
*** 265,275 ****
  	"""Send signal from sender to all connected receivers.
  	
! 	Return a list of tuple pairs [(receiver, response), ... ].
  	
! 	If sender is None, signal is sent anonymously, note that
! 	the default *registration* is for Any sender, not anonymous;
! 	default registration receives default send, but any
! 	registration which specifies a signal does *not* receive the
! 	default anonymous send
  	"""
  	# Call each receiver with whatever arguments it can accept.
--- 305,338 ----
  	"""Send signal from sender to all connected receivers.
  	
! 	signal -- (hashable) signal value, see connect for details
! 
! 	sender -- the sender of the signal
  	
! 		if Any, only receivers registered for Any will receive
! 		the message.
! 
! 		if Anonymous, only receivers registered to receive
! 		messages from Anonymous or Any will receive the message
! 
! 		Otherwise can be any python object (normally one
! 		registered with a connect if you actually want
! 		something to occur).
! 
! 	arguments -- positional arguments which will be passed to
! 		*all* receivers. Note that this may raise TypeErrors
! 		if the receivers do not allow the particular arguments.
! 		Note also that arguments are applied before named
! 		arguments, so they should be used with care.
! 
! 	named -- named arguments which will be filtered according
! 		to the parameters of the receivers to only provide those
! 		acceptable to the receiver.
! 
! 	Return a list of tuple pairs [(receiver, response), ... ]
! 
! 	if any receiver raises an error, the error propagates back
! 	through send, terminating the dispatch loop, so it is quite
! 	possible to not have all receivers called if a raises an
! 	error.
  	"""
  	# Call each receiver with whatever arguments it can accept.
***************
*** 289,293 ****
  	"""Send signal only to those receivers registered for exact message
  
! 	See send for details
  	"""
  	responses = []
--- 352,359 ----
  	"""Send signal only to those receivers registered for exact message
  
! 	sendExact allows for avoiding Any/Anonymous registered
! 	handlers, sending only to those receivers explicitly
! 	registered for a particular signal on a particular
! 	sender.
  	"""
  	responses = []