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?

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

The "fileno" argument looks like an implementation detail to me.

> 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()

> 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()

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

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?

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

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()``.

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.

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

Here you go.

Patch looks good.

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

Thanks!