classification
Title: socket.fromfd() documentation problem
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.1
process
Status: closed Resolution: works for me
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, orsenthil, stutzbach, synapse
Priority: normal Keywords: patch

Created on 2010-10-14 08:42 by synapse, last changed 2010-10-15 14:00 by eric.araujo. This issue is now closed.

Files
File name Uploaded Description Edit
fromfd_doc.patch synapse, 2010-10-14 08:42 socket.fromfd() documentation patch
Messages (5)
msg118637 - (view) Author: Gergely Kálmán (synapse) Date: 2010-10-14 08:42
socket.fromfd()'s behaviour is somewhat counter-intutive and should contain a note to warn the user that it'll leave the original FD open. This is important if someone forgets to manually close the file descriptor as it might lead to FD leaks (and kernel memory leaks). This is especially the case when there is no python object associated with the FD, so no destruction will take place.

patch applies to this:
http://docs.python.org/py3k/archives/python-3.1.2-docs-html.tar.bz2

The only thing it does is that it adds a note section with the following message: "The original file descriptor will not be closed."

synapse
msg118638 - (view) Author: Gergely Kálmán (synapse) Date: 2010-10-14 08:44
Forgot to add that the changes should be applied to all versions if accepted.

synapse
msg118750 - (view) Author: Senthil Kumaran (orsenthil) * (Python committer) Date: 2010-10-15 08:59
I think, the original docs *is* pretty intuitive. It says "Duplicate the file descriptor fd and build a socket object".  No one will think that the this method will close the original fd. Person using this method might of course, explicitly close the original fd in some other part of the code (as he may use it after creating the socket object too).

If at all anything is required, a line may be "The original file descriptor is unaffected", but again that seems redundant to me.
msg118754 - (view) Author: Gergely Kálmán (synapse) Date: 2010-10-15 09:17
You are perfectly right, the docs are pretty clear. Although fromfd means (or at least to me) to "attach object to fd" and not "duplicate then attach to the duplicate". If someone forgets this particular behaviour and thinks that the function works as the name implies they're in trouble.

Gergely Kalman
msg118755 - (view) Author: Senthil Kumaran (orsenthil) * (Python committer) Date: 2010-10-15 09:43
So, I assume that we just leave it as such and close the issue.
I was thinking if anything needs to be updated for function __doc__ but even there 'the duplicate' word is explained.
History
Date User Action Args
2010-10-15 14:00:05eric.araujosetresolution: not a bug -> works for me
2010-10-15 09:43:46orsenthilsetstatus: open -> closed
resolution: not a bug
messages: + msg118755

stage: resolved
2010-10-15 09:17:28synapsesetmessages: + msg118754
2010-10-15 08:59:47orsenthilsetnosy: + orsenthil
messages: + msg118750
2010-10-14 10:53:13stutzbachsetnosy: + stutzbach
2010-10-14 08:44:35synapsesetmessages: + msg118638
2010-10-14 08:42:43synapsecreate