classification
Title: fileno argument to socket.socket() undocumented
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.6, Python 3.4, Python 3.5
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: bar.harel, berker.peksag, docs@python, ezio.melotti, giampaolo.rodola, gvanrossum, hheimbuerger, petri.lehtinen, pitrou, python-dev, sbt, serhiy.storchaka
Priority: normal Keywords: easy, patch

Created on 2012-12-28 16:12 by sbt, last changed 2015-10-08 03:36 by berker.peksag. This issue is now closed.

Files
File name Uploaded Description Edit
issue16802.diff hheimbuerger, 2013-02-23 18:37 Documentation change adding a note on the fileno parameter of socket.socket() review
Issue16802_rev2.patch bar.harel, 2015-10-02 11:47 review
Messages (15)
msg178387 - (view) Author: Richard Oudkerk (sbt) * (Python committer) Date: 2012-12-28 16:12
The actual signature is

    socket.socket(family=AF_INET, type=SOCK_STREAM, proto=0, fileno=None)

but the documented signature is

    socket.socket([family[, type[, proto]]])

Should the fileno argument be documented or is it considered an implementation detail?
msg178659 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2012-12-31 09:58
The fileno parameter was added in the changeset 8e062e572ea4. It was mentioned in comments at the top of Modules/socketmodule.c, but not in the documentation or docstrings (nor for _socket.socket, nor for socket.socket).
msg178665 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2012-12-31 11:16
The "fileno" argument looks like an implementation detail to me.
msg178667 - (view) Author: Richard Oudkerk (sbt) * (Python committer) Date: 2012-12-31 11:40
> The "fileno" argument looks like an implementation detail to me.

It has at least one potential use.  On Windows socket.detach() returns a socket handle but there is no documented way to close it -- os.close() will not work.  The only way to close it that I can see (without resorting to ctypes) is with something like

    socket.socket(fileno=handle).close()
msg178675 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2012-12-31 14:11
> It has at least one potential use.  On Windows socket.detach() returns a
> socket handle but there is no documented way to close it -- os.close()
> will not work.  The only way to close it that I can see (without resorting
> to ctypes) is with something like
> 
>     socket.socket(fileno=handle).close()

There is an alternative (documented) interface:

    socket.fromfd(handle, socket.AF_INET, socket.SOCK_STREAM).close()
msg178682 - (view) Author: Richard Oudkerk (sbt) * (Python committer) Date: 2012-12-31 14:50
> There is an alternative (documented) interface:
> 
>     socket.fromfd(handle, socket.AF_INET, socket.SOCK_STREAM).close()

socket.fromfd() duplicates the handle, so that does not close the original handle.
msg178690 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2012-12-31 15:19
Indeed. In any case, if this idiom is widely used, we can't hide this parameter and should document it (and perhaps document this idiom).

If BDFL not want this parameter was made public, he would not have added it as an keyword argument. However, may be to ask him?
msg178701 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2012-12-31 16:22
I recommend documenting it.

On Monday, December 31, 2012, Serhiy Storchaka wrote:

>
> Serhiy Storchaka added the comment:
>
> Indeed. In any case, if this idiom is widely used, we can't hide this
> parameter and should document it (and perhaps document this idiom).
>
> If BDFL not want this parameter was made public, he would not have added
> it as an keyword argument. However, may be to ask him?
>
> ----------
>
> _______________________________________
> Python tracker <report@bugs.python.org <javascript:;>>
> <http://bugs.python.org/issue16802>
> _______________________________________
>
msg182788 - (view) Author: Henrik Heimbuerger (hheimbuerger) * Date: 2013-02-23 18:37
Here's a suggestion for a documentation addition. Comments on tone and content are welcome, and I'm willing to update it and submit modified patch files.

This adds the following note:
      If a file descriptor *fileno* is specified, the other arguments
      are ignored and and the socket with this file descriptor is returned. Unlike
      :meth:`fromfd`, this does not cause a duplication of the file descriptor
      and therefore supports the special case of closing detached socket handles
      on Windows using ``socket.socket(fileno=handle).close()``.
msg229585 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2014-10-17 17:16
The actual signature is now

    socket.socket(family=AF_INET, type=SOCK_STREAM, proto=0, fileno=None)

but, the fileno argument still needs to be documented.
msg231168 - (view) Author: Petri Lehtinen (petri.lehtinen) * (Python committer) Date: 2014-11-14 19:14
To me, there's also a valid use case on Unix; A parent process forks and execs, wanting to share a socket to the executed child process. The best way for the child to create a socket object is to use the fileno parameter of socket.socket().
msg252108 - (view) Author: Bar Harel (bar.harel) * Date: 2015-10-02 11:47
Here you go.
msg252145 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2015-10-02 16:52
Patch looks good.
msg252508 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2015-10-08 03:35
New changeset f4606117d571 by Berker Peksag in branch '3.4':
Issue #16802: Document fileno parameter of socket.socket()
https://hg.python.org/cpython/rev/f4606117d571

New changeset 1d14675c6050 by Berker Peksag in branch '3.5':
Issue #16802: Document fileno parameter of socket.socket()
https://hg.python.org/cpython/rev/1d14675c6050

New changeset 9115c63cf3d2 by Berker Peksag in branch 'default':
Issue #16802: Document fileno parameter of socket.socket()
https://hg.python.org/cpython/rev/9115c63cf3d2
msg252509 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2015-10-08 03:36
Thanks!
History
Date User Action Args
2015-10-08 03:36:07berker.peksagsetstatus: open -> closed
versions: + Python 3.6
messages: + msg252509

resolution: fixed
stage: patch review -> resolved
2015-10-08 03:35:07python-devsetnosy: + python-dev
messages: + msg252508
2015-10-02 16:52:07gvanrossumsetmessages: + msg252145
2015-10-02 11:47:13bar.harelsetfiles: + Issue16802_rev2.patch
nosy: + bar.harel
messages: + msg252108

2014-11-14 19:14:38petri.lehtinensetnosy: + petri.lehtinen
messages: + msg231168
2014-10-17 17:16:27berker.peksagsetversions: + Python 3.5, - Python 3.2, Python 3.3
nosy: + berker.peksag

messages: + msg229585

stage: needs patch -> patch review
2013-02-23 18:38:00hheimbuergersetfiles: + issue16802.diff

nosy: + hheimbuerger
messages: + msg182788

keywords: + patch
2013-01-26 18:49:10serhiy.storchakasetkeywords: + easy
stage: needs patch
2012-12-31 16:22:29gvanrossumsetmessages: + msg178701
2012-12-31 15:19:13serhiy.storchakasetmessages: + msg178690
2012-12-31 14:50:30sbtsetmessages: + msg178682
2012-12-31 14:11:18serhiy.storchakasetmessages: + msg178675
2012-12-31 11:40:52sbtsetmessages: + msg178667
2012-12-31 11:16:42pitrousetnosy: + gvanrossum
messages: + msg178665
2012-12-31 09:58:52serhiy.storchakasetnosy: + pitrou, serhiy.storchaka, docs@python
messages: + msg178659

assignee: docs@python
components: + Documentation
type: enhancement
2012-12-31 01:13:38ezio.melottisetnosy: + ezio.melotti
2012-12-28 17:10:44giampaolo.rodolasetnosy: + giampaolo.rodola
2012-12-28 16:12:31sbtcreate