SF.net SVN: fclient: [326] trunk/sandbox/fcp2/iohandler.py

[<ju...@us...>]

Revision: 326
          http://fclient.svn.sourceforge.net/fclient/?rev=326&view=rev
Author:   jurner
Date:     2008-03-06 10:25:06 -0800 (Thu, 06 Mar 2008)

Log Message:
-----------
added docs and a bit of this and that

Modified Paths:
--------------
    trunk/sandbox/fcp2/iohandler.py

Modified: trunk/sandbox/fcp2/iohandler.py
===================================================================
--- trunk/sandbox/fcp2/iohandler.py	2008-03-06 17:45:43 UTC (rev 325)
+++ trunk/sandbox/fcp2/iohandler.py	2008-03-06 18:25:06 UTC (rev 326)
@@ -43,47 +43,94 @@
 	"""Exception raised when the io connection is closed"""
 
 
-class IOObject(object):
+class IOObjectBase(object):
+	"""Base class for io objects
+	
+	@cvar Timeout: (int) timeout for io operations
+	@cvar BufferSize: (int) buffer size for io operations (must be> 0)
+	
+	@note: implement this class to read / write messages from any device	via L{IOHandler}
+	"""
 	Timeout = 0
 	BufferSize = 4096	
 	
-	def __init__(self, ):
-		pass
+	def __init__(self, **kwargs):
+		"""
+		@param kwargs: any additional keyword arguments passed to L{IOHandler.connect}
+		"""
 	
 	def connect(self, **kwargs):
+		"""Should connect to the io device
+		
+		@return: always None
+		@raise L{IOConnectFailed}: in case something goes wrong
+		"""
 		raise IOConnectFailed('Failed')
 	
 	def read(self, n):
+		"""Should read n bytes from the device
+		
+		@return: always None
+		@raise L{IOBroken}: in case something goes wrong
+		@raise L{IOTimeout}: if the read operation times out
+		"""
 		raise IOBroken('Broken')
 		
 	def write(self, bytes):
+		"""Should write bytes to the device
+		
+		@return: always None
+		@raise L{IOBroken}: in case something goes wrong
+		"""
 		raise IOBroken('Broken')
 
 	def close(self):
+		"""Should close the io device
+		
+		@return: always None
+		@raise L{IOClosed}: if the device is already closed
+		"""
 		raise IOClosed('Closed')
 		
 	def isOpen(self):
+		"""Should check if the device is open
+		
+		@return: (bool) True if so, False otherwise
+		"""
 		return False
 	
 	def setTimeout(self, n):
+		"""Should set the timeout for io operations
+		
+		@return: always None
+		"""
 		pass
 
 #*****************************************************************************
 #
 #*****************************************************************************
-class SocketIO(IOObject):
+class SocketIO(IOObjectBase):
+	"""Handles message io over socket
+	"""
+	
 	Timeout = 0.1
 	BufferSize = 4096
 	
 	def __init__(self):
 		self.socket = None
 		
-	def connect(self, **kwargs):
+	def connect(self, host=None, port=None):
+		"""Conects to socket
+		
+		@param host: (str) host to connect to
+		@param port: (int) port to use
+		"""
+		
 		if self.isOpen():
 			self.close()
 		self.socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
 		try:
-			self.socket.connect((kwargs['host'], kwargs['port']))
+			self.socket.connect((host, port))
 		except socket.error, details:
 			raise IOConnectFailed(details)
 		
@@ -123,25 +170,43 @@
 #
 #*****************************************************************************
 class IOHandler(object):
+	"""Handles message io
+	"""
 	
 	TerminatorEndMessage = '\nEndMessage\n'
 	TerminatorData = '\nData\n'
 	
 	
 	def __init__(self, ioPrototype=SocketIO):
+		"""
+		@paran ioPrototype: (L{IOObjectBase}) derrived class to handle message io 
+		"""
+		
 		self._ioPrototype = ioPrototype
-		self._log = logging.getLogger(consts.LoggerNames.ClientIOHandler)
+		self._log = logging.getLogger(consts.LoggerNames.IOHandler)
 		self._receiveBuffer = ''
 		
 		self.io = None		
 		
 	def connect(self, duration=20, timeout=0.5, **kwargs):
+		"""Connect to the io device
+		
+		@return: (bool) True, if a connection could be established, False otherwise
+		@note: for details see L{iterConnect}
+		"""
 		for result in self.iterConnect(duration=duration, timeout=timeout, **kwargs): pass
 		return result
 		
 		
 	def iterConnect(self, duration=20, timeout=0.5, **kwargs):
+		"""Iterator to connect to the io device
 		
+		@param duration: (int) how long should the handler try to connect to the device?
+		@param timeout: (int) how long dhould the handler wait in between connection attempts
+		@param kwargs: keyword arguments to pass to the contructor of the io object
+		
+		@return: (bool) True, if a connection could be established, False otherwise for the next attempt in turn
+		"""
 		if not duration >= 0: 	
 			raise ValueError('duration must be >= 0')
 		if not timeout >= 0: 	
@@ -175,6 +240,7 @@
 	
 	
 	def close(self):
+		"""Closes the handler"""
 		self._log.debug(consts.LogMessages.Closing) 
 		self._receiveBuffer = ''
 		if self.io is not None and self.io.isOpen():
@@ -183,6 +249,9 @@
 		
 			
 	def isOpen(self):
+		"""Checks if the io connection is open
+		@return: (bool) True if so, False otherwiese
+		"""
 		if self.io is not None:
 			return self.io.isOpen()
 		return False
@@ -209,7 +278,7 @@
 		
 			
 	def readMessage(self):
-		"""Reads the next a message from io
+		"""Reads the next message from io device
 		@return: (Message) next message from the socket
 		
 		@note: if something goes wrong the according exception is raised
@@ -301,12 +370,7 @@
 		@param data: data to atatch to the message
 		@param params: {para-name: param-calue, ...} of parameters to pass along
 		with the message (see freenet protocol)
-		@raise SocketError: if the socket connection to the node dies unexpectedly
-		If an error handler is passed to the client it is called emidiately before the error
-		is raised.
-		
-		@note: you can use this method to send a message to the node, bypassing all
-		track keeping methods of the client		
+		@raise L{IOBroken}: if the connection to the io dies unexpectedly
 		"""
 		return self.sendMessageEx(message.Message(name, data=data, **params))
 			
@@ -315,12 +379,7 @@
 		"""Sends a message to freenet
 		@param msg: (Message) message to send
 		@return: Message
-		@raise SocketError: if the socket connection to the node dies unexpectedly.
-		If an error handler is passed to the client it is called emidiately before the error
-		is raised.
-		
-		@note: you can use this method to send a message to the node, bypassing all
-		track keeping methods of the client		
+		@raise L{IOBroken}: if the connection to the io dies unexpectedly
 		"""
 		self._log.debug(consts.LogMessages.Sending + msg.pprint())
 		try:
@@ -332,13 +391,16 @@
 				
 		
 	def setDebugVerbosity(self, debugVerbosity):
+		"""Adjusts the debug verbosity. See L{consts.DebugVerbosity}
+		"""
 		self._log.setLevel(debugVerbosity)
 
 	
 	def setIOPrototype(self, ioObject):
+		"""Sets the io prototype to be used by the handler
+		
+		@note: if there is a current open connection, the connection is closed in the call
 		"""
-		@note: if the connection is open the connection is closed in the call
-		"""
 		if self.isOpen():
 			self.close()
 		


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.