id	summary	reporter	owner	description	type	status	priority	milestone	component	resolution	keywords	cc	branch	branch_author	launchpad_bug
3455	CONNECTION_LOST not an Integer...	mforbes		"Several docstrings, notably those for the writeSomeData() method of t.i.a.FileDescriptor, claim that the return value is an integer reporting the number of bytes sent, or a negative integer reporting that the connection was lost.

The implementations, however, return t.i.main.CONNECTION_LOST which is an exception, not an integer.

Apart from the incorrect docstrings, returning an exception makes it quite difficult to test for errors.  For example:

{{{
bytes_sent = self.connection.writeSomeData(...)
if 0 < bytes_sent:
    Still get here, even if connection is lost.
}}}

One has to check if the return value is explicitly CONNECTION_LOST, or if it is an instance of int etc.

Suggestion: Have writeSomeData throw the exception, or revert back to using an integer...

A quick grep indicates that this would require changes in the following files.

./Twisted/twisted/internet/_javaserialport.py
./Twisted/twisted/internet/_posixserialport.py
./Twisted/twisted/internet/abstract.py
./Twisted/twisted/internet/fdesc.py
./Twisted/twisted/internet/process.py
./Twisted/twisted/internet/tcp.py
./Twisted/twisted/protocols/htb.py
./Twisted/twisted/protocols/pcp.py
./Twisted/twisted/test/test_internet.py
./Twisted/twisted/test/test_pcp.py
"	defect	closed	normal		core	fixed	documentation	thijs	branches/writesomedata-docs-3455	exarkun