classification
Title: [doc] State clearly that open() 'file' param is "name" attr of the result
Type: Stage:
Components: Documentation Versions: Python 3.11, Python 3.10, Python 3.9
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: aronacher, docs@python, gvanrossum, ncoghlan, pitrou, serhiy.storchaka, vstinner
Priority: normal Keywords: easy

Created on 2013-07-23 05:06 by ncoghlan, last changed 2021-09-06 16:45 by iritkatriel.

Messages (6)
msg193585 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2013-07-23 05:06
Currently, if a byte sequence is passed to open() as the file name, the resulting file will have that object as its name:

>>> open(os.path.expanduser(b"~/.hgrc"))
<_io.TextIOWrapper name=b'/home/ncoghlan/.hgrc' mode='r' encoding='UTF-8'>
>>> open(os.path.expanduser("~/.hgrc"))
<_io.TextIOWrapper name='/home/ncoghlan/.hgrc' mode='r' encoding='UTF-8'>

As documented in a recent post from Armin Ronacher [1], this causes the "bytes" to leak out to the public API of the file, causing problems since user code can't assume that "f.name" is a string.

When bytes are passed to open() as the filename, os.fsdecode should be used to convert them to a text string before storing them in the name attribute.


[1] http://lucumr.pocoo.org/2013/7/2/the-updated-guide-to-unicode/
msg193602 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2013-07-23 13:55
You can never assume that "name" will be a string:

>>> f = open(0, "r")
>>> f.name
0

This may be a bit of a bad idea API-wise, but changing it now will start breaking code, so I think we should leave it as-is.
msg193616 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2013-07-23 18:36
Seconded Antoine.
msg193625 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2013-07-24 05:18
Ouch, that complicates matters :(

It also occurs to me that given the existence of the "opener" callback,
name could be just about any type :P
msg193695 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2013-07-25 13:02
Switching this to a docs bugs, since http://docs.python.org/3/library/functions.html#open doesn't mention this behaviour at all, and http://docs.python.org/3/library/io.html#io.FileIO.name only notes the fact it may be a file descriptor without mentioning the str/bytes discrepancy.

So, at a bare minimum, we need to clearly describe this behaviour in the docs. We may also want to explicitly point out that using os.fsdecode(name) before passing it to open() will ensure that the name attribute is set to a string rather than a bytes object.
msg305354 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2017-11-01 03:14
Agreed it's too subtle to change the behavior.

> We may also want to explicitly point out that using os.fsdecode(name) before passing it to open() will ensure that the name attribute is set to a string rather than a bytes object.

Not sure. Are there cases where os.fsdecode() fails even if the binary syscall would succeed? (The docs claim that on Windows it uses 'strict'.)

If it doesn't, maybe we can add a new attribute that gives the name as Text? It could be '' if name is an int.
History
Date User Action Args
2021-09-06 16:45:37iritkatrielsetkeywords: + easy
title: State clearly that open() 'file' param is "name" attr of the result -> [doc] State clearly that open() 'file' param is "name" attr of the result
versions: + Python 3.9, Python 3.10, Python 3.11, - Python 3.3, Python 3.4
2018-01-20 15:09:21r.david.murraylinkissue32594 superseder
2017-11-01 03:14:32gvanrossumsetstatus: pending -> open
nosy: + gvanrossum
messages: + msg305354

2017-10-28 12:27:04serhiy.storchakasetstatus: open -> pending
2013-07-25 13:02:03ncoghlansetassignee: docs@python

components: + Documentation
title: File "name" attribute should always be a text string -> State clearly that open() 'file' param is "name" attr of the result
nosy: + docs@python
versions: + Python 3.3, Python 3.4
messages: + msg193695
2013-07-24 05:18:00ncoghlansetmessages: + msg193625
2013-07-23 18:36:45serhiy.storchakasetnosy: + serhiy.storchaka
messages: + msg193616
2013-07-23 13:55:19pitrousetnosy: + aronacher, pitrou
messages: + msg193602
2013-07-23 05:06:58ncoghlancreate