socket.fileno() documentation

[birkenfeld]

BPO	19234
Nosy	@birkenfeld, @pitrou, @bitdancer, @zware, @kushaldas, @JelleZijlstra
Files	issue19234.patch: Adds more lines to explain the behavior of socket.fileno() in case of error.

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2016-06-05.18:35:46.669>
created_at = <Date 2013-10-12.16:33:57.762>
labels = ['docs']
title = 'socket.fileno() documentation'
updated_at = <Date 2016-06-07.02:38:19.958>
user = 'https://github.com/birkenfeld'

bugs.python.org fields:

activity = <Date 2016-06-07.02:38:19.958>
actor = 'berker.peksag'
assignee = 'docs@python'
closed = True
closed_date = <Date 2016-06-05.18:35:46.669>
closer = 'JelleZijlstra'
components = ['Documentation']
creation = <Date 2013-10-12.16:33:57.762>
creator = 'georg.brandl'
dependencies = []
files = ['43103']
hgrepos = []
issue_num = 19234
keywords = ['patch']
message_count = 7.0
messages = ['199592', '199594', '199646', '266898', '266939', '267283', '267454']
nosy_count = 8.0
nosy_names = ['georg.brandl', 'pitrou', 'r.david.murray', 'docs@python', 'python-dev', 'zach.ware', 'kushal.das', 'JelleZijlstra']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue19234'
versions = ['Python 2.7', 'Python 3.5', 'Python 3.6']

[birkenfeld]

-------- 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.

[bitdancer]

See also bpo-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.

[pitrou]

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

[kushaldas]

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

[zware]

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

[python-dev]

New changeset d83007ab69e2 by Kushal Das in branch '3.5':
Issue bpo-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 bpo-19234: Merge from 3.5
https://hg.python.org/cpython/rev/3c745b656dca

[JelleZijlstra]

This looks fixed.