classification
Title: io.FileIO closefd parameter is not documented nor shown in repr
Type: enhancement Stage: resolved
Components: Documentation, IO, Library (Lib) Versions: Python 3.5
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Arfrever, BreamoreBoy, docs@python, pitrou, python-dev, r.david.murray, rbcollins, serhiy.storchaka
Priority: normal Keywords: patch

Created on 2013-03-12 03:12 by rbcollins, last changed 2014-12-03 07:28 by serhiy.storchaka. This issue is now closed.

Files
File name Uploaded Description Edit
issue17401.patch rbcollins, 2014-09-08 19:56
io_fileio_repr_closefd.patch serhiy.storchaka, 2014-10-20 08:02 review
io_fileio_repr_closefd_2.patch serhiy.storchaka, 2014-10-20 10:48 review
Messages (13)
msg184003 - (view) Author: Robert Collins (rbcollins) * (Python committer) Date: 2013-03-12 03:12
the docs (http://docs.python.org/3.x/library/io.html#io.FileIO) do not document closefd, and AFAICT it isn't possible to tell if closefd is set after the object is created. Specifically it does not show up in the repr().

>>> import sys
>>> sys.stdout
<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>
>>> sys.stdout.buffer
<_io.BufferedWriter name='<stdout>'>
>>> sys.stdout.buffer.raw
<_io.FileIO name='<stdout>' mode='wb'>

If one wants to reopen sys.std in non-buffered mode, the right thing to do according to a recent thread on python-ideas is to use fdopen - e.g.

mystream = io.open(sys.stdout.fileno(), 'wt', 0) 
but this will set closefd to True in the new object, which results in hilarity when it gets garbage collected. And you cannot tell or compare that to the original stdout because of the lack of exposure of this attribute and it's implications. (Does it close the fd on __del__? After each operation? On close() being called on the FileIO object?)
msg223429 - (view) Author: Mark Lawrence (BreamoreBoy) * Date: 2014-07-18 20:00
From the 3.5 docs.

io.open(file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, closefd=True, opener=None)
This is an alias for the builtin open() function.

There is a description for closefd at the open() function link.  So how about adding to the sentence above " where all the above parameters are described" ?
msg226603 - (view) Author: Robert Collins (rbcollins) * (Python committer) Date: 2014-09-08 19:39
Its more than just a docs issue - "AFAICT it isn't possible to tell if closefd is set after the object is created."

The presence of the parameter in the signature is there, but it isn't documented *where the bulk of the FileIO parameters are* - there are docs for mode for instance. Why would we force users to follow breadcrumbs for one parameter but not other ones?
msg226607 - (view) Author: Robert Collins (rbcollins) * (Python committer) Date: 2014-09-08 19:56
Oh - the the 'open' function docs are fine - they are just a pointer. I was specifically referring to the class docs around line 513 of Doc/library/io.rst.

Attached is a patch that changes repr to show this attribute and extends the docs to document this as part of FileIO.
msg229596 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-10-17 19:54
I think the information from the following line of the 'open' docs should be added to the doc patch:

"If a filename is given closefd has no effect and must be True (the default)."

Otherwise it looks fine to me.
msg229624 - (view) Author: Roundup Robot (python-dev) Date: 2014-10-18 00:39
New changeset a1500e4a159a by Robert Collins in branch 'default':
Issue #17401: document closefd in io.FileIO docs and add to repr
https://hg.python.org/cpython/rev/a1500e4a159a
msg229719 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2014-10-20 08:02
FileIO repr now looks confusing:

>>> sys.stdout.buffer.raw
<_io.FileIO name='<stdout>' mode='wb' closefd='0'>

The closefd attribute is not a string '0' or '1', it is boolean value True or False. Here is a patch which fixes a repr.

And I think that documentation part of the patch should be backported.
msg229720 - (view) Author: Robert Collins (rbcollins) * (Python committer) Date: 2014-10-20 08:20
Yeah thats nicer. I'll apply that later unless you can.
msg229722 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2014-10-20 10:48
May be include closefd in the repr only when it is False? By default closefd is True and in common case the repr will be more compact.
msg229742 - (view) Author: Robert Collins (rbcollins) * (Python committer) Date: 2014-10-20 21:39
Showing it only when False would have higher cognitive load. Showing it always is simple and clear.
msg232050 - (view) Author: Roundup Robot (python-dev) Date: 2014-12-02 21:41
New changeset fd80195b920f by Serhiy Storchaka in branch 'default':
Issue #17401: Output the closefd attribute as boolean.
https://hg.python.org/cpython/rev/fd80195b920f
msg232051 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2014-12-02 21:44
Committed the first patch (showing closefd always) with additional test from second path.
msg232069 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2014-12-03 07:28
Arfrever have suggested on IRC to backport documentation part of the patch to 3.4.
History
Date User Action Args
2014-12-03 07:28:46serhiy.storchakasetmessages: + msg232069
2014-12-02 21:58:49serhiy.storchakasetstatus: open -> closed
resolution: fixed
stage: commit review -> resolved
2014-12-02 21:44:07serhiy.storchakasetmessages: + msg232051
versions: - Python 3.4
2014-12-02 21:41:55python-devsetmessages: + msg232050
2014-10-21 00:35:33berker.peksagsetstage: patch review -> commit review
2014-10-20 21:39:42rbcollinssetmessages: + msg229742
2014-10-20 14:22:52Arfreversetnosy: + Arfrever
2014-10-20 10:48:46serhiy.storchakasetfiles: + io_fileio_repr_closefd_2.patch

messages: + msg229722
2014-10-20 08:20:39rbcollinssetmessages: + msg229720
2014-10-20 08:02:29serhiy.storchakasetstatus: closed -> open
files: + io_fileio_repr_closefd.patch

versions: + Python 3.5, - Python 3.2, Python 3.3
nosy: + serhiy.storchaka

messages: + msg229719
resolution: fixed -> (no value)
stage: patch review
2014-10-19 23:13:05rbcollinssetstatus: open -> closed
resolution: fixed
2014-10-18 00:39:21python-devsetnosy: + python-dev
messages: + msg229624
2014-10-17 19:54:55r.david.murraysetnosy: + r.david.murray
messages: + msg229596
2014-09-08 19:56:44rbcollinssetfiles: + issue17401.patch
keywords: + patch
messages: + msg226607
2014-09-08 19:39:44rbcollinssetmessages: + msg226603
2014-07-18 20:00:49BreamoreBoysetnosy: + BreamoreBoy
messages: + msg223429
2013-03-12 03:13:33ezio.melottisetversions: - Python 3.5
nosy: + docs@python, pitrou

assignee: docs@python
components: + Documentation, Library (Lib), IO
type: enhancement
2013-03-12 03:12:07rbcollinscreate