-------- Original-Nachricht --------
Betreff: [docs] socket.fileno() documentation
Datum: Thu, 10 Oct 2013 19:27:35 +0200
Von: Vlado Potisk <vlado@poti.sk>
An: docs@python.org

I might be wrong but in my opinion the socket library documentation is not
clear enough regarding the behaviour of the fileno() method in a case of a
failure.

In the Python 3.2 socket library documentation there is:
----
exception socket.error

    A subclass of IOError, this exception is raised for socket-related errors.
-----
 socket.close()

    Close the socket. All future operations on the socket object will fail.
----
 socket.fileno()

    Return the socket’s file descriptor (a small integer).
----

Based on the information quoted above, I wrote a test if a socket is active or
if it has been closed already:

try:
	sock.fileno()
except socket.error:
	return False
return True

But is doesn't work. I have found out that fileno() returns -1 on a closed
socket. Replacing fileno() with e.g. getsockname() fixes the code.

It looks like a fileno's failure - unlike to getsockname's failure - is not
expressed by raising an exception, but by returning -1. However this seems to
be not documented and that's why I'm unsure if I may rely on this.

See also issue 19154.  For consistency with the rest of Python it should probably raise ValueError.  But at this point it has done what it does for a long time (which is to return what the underlying posix function returns), so we should probably just document it.

Indeed, this should probably be documented as-is - or, if we want to change the behaviour, discussed on python-dev first.

Adds more lines to explain the behavior of socket.fileno() in  case of error.

I think the additions are redundant; pick one or the other.  The first should be sufficient.

New changeset d83007ab69e2 by Kushal Das in branch '3.5':
Issue #19234: Documents socket.fileno() returns -1 on failure
https://hg.python.org/cpython/rev/d83007ab69e2

New changeset 3c745b656dca by Kushal Das in branch 'default':
Issue #19234: Merge from 3.5
https://hg.python.org/cpython/rev/3c745b656dca

This looks fixed.