[Python-Dev] cpython: Issue #18571: Implementation of the PEP 446: file descriptors and file handles

[Georg Brandl]

On 08/28/2013 01:20 AM, victor.stinner wrote:
> http://hg.python.org/cpython/rev/ef889c3d5dc6
> changeset:   85420:ef889c3d5dc6
> user:        Victor Stinner <victor.stinner at gmail.com>
> date:        Wed Aug 28 00:53:59 2013 +0200
> summary:
>   Issue #18571: Implementation of the PEP 446: file descriptors and file handles
> are now created non-inheritable; add functions os.get/set_inheritable(),
> os.get/set_handle_inheritable() and socket.socket.get/set_inheritable().

> +.. _fd_inheritance:
> +
> +Inheritance of File Descriptors
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +A file descriptor has a inheritable flag which indicates if the file descriptor
> +can be inherited or not in child processes. Since Python 3.4, file descriptors
> +created by Python are non-inheritable by default.
> +
> +On UNIX, non-inheritable file descriptors are closed in child processes at the
> +execution of a new program, other file descriptors are inherited.
> +
> +On Windows, non-inheritable handles and file descriptors are closed in child
> +processes, except standard streams (file descriptors 0, 1 and 2: stdin, stdout
> +and stderr) which are always inherited. Using :func:`os.spawn*` functions,
> +all inheritable handles and all inheritable file descriptors are inherited.
> +Using the :mod:`subprocess` module, all file descriptors except standard
> +streams are closed, inheritable handles are only inherited if the *close_fds*
> +parameter is ``False``.
> +
> +.. versionadded:: 3.4
> +
> +.. function:: get_inheritable(fd)
> +
> +   Get the `inheritable flag <fd_inheritance>`_ of the specified file
> +   descriptor. Return a :class:`bool`.
> +
> +.. function:: set_inheritable(fd, inheritable)
> +
> +   Set the `inheritable flag <fd_inheritance>`_ of the specified file descriptor.
> +
> +.. function:: get_handle_inheritable(handle)
> +
> +   Get the `inheritable flag <fd_inheritance>`_ of the specified handle. Return a :class:`bool`.
> +
> +   Availability: Windows.
> +
> +.. function:: set_handle_inheritable(handle, inheritable)
> +
> +   Set the `inheritable flag <fd_inheritance>`_ of the specified handle.
> +
> +   Availability: Windows.
> +

"Handle" is used nowhere else in the os module documentation.  Do you think it
would make sense to have a brief paragraph on what are possible handles under
Windows (and that file descriptors aren't handles)?

Georg