io.FileIO closefd parameter is not documented nor shown in repr

[rbtcollins]

BPO	17401
Nosy	@pitrou, @rbtcollins, @bitdancer, @serhiy-storchaka
Files	issue17401.patch io_fileio_repr_closefd.patch io_fileio_repr_closefd_2.patch

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2014-12-02.21:58:49.687>
created_at = <Date 2013-03-12.03:12:07.328>
labels = ['type-feature', 'library', 'expert-IO', 'docs']
title = 'io.FileIO closefd parameter is not documented nor shown in repr'
updated_at = <Date 2014-12-03.07:28:46.471>
user = 'https://github.com/rbtcollins'

bugs.python.org fields:

activity = <Date 2014-12-03.07:28:46.471>
actor = 'serhiy.storchaka'
assignee = 'docs@python'
closed = True
closed_date = <Date 2014-12-02.21:58:49.687>
closer = 'serhiy.storchaka'
components = ['Documentation', 'Library (Lib)', 'IO']
creation = <Date 2013-03-12.03:12:07.328>
creator = 'rbcollins'
dependencies = []
files = ['36574', '36977', '36979']
hgrepos = []
issue_num = 17401
keywords = ['patch']
message_count = 13.0
messages = ['184003', '223429', '226603', '226607', '229596', '229624', '229719', '229720', '229722', '229742', '232050', '232051', '232069']
nosy_count = 8.0
nosy_names = ['pitrou', 'rbcollins', 'Arfrever', 'r.david.murray', 'docs@python', 'BreamoreBoy', 'python-dev', 'serhiy.storchaka']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue17401'
versions = ['Python 3.5']

[rbtcollins]

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

[BreamoreBoy]

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" ?

[rbtcollins]

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?

[rbtcollins]

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.

[bitdancer]

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.

[python-dev]

New changeset a1500e4a159a by Robert Collins in branch 'default':
Issue bpo-17401: document closefd in io.FileIO docs and add to repr
https://hg.python.org/cpython/rev/a1500e4a159a

[serhiy-storchaka]

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.

[rbtcollins]

Yeah thats nicer. I'll apply that later unless you can.