[doc] State clearly that open() 'file' param is "name" attr of the result

[ncoghlan]

BPO	18534
Nosy	@gvanrossum, @ncoghlan, @pitrou, @vstinner, @mitsuhiko, @serhiy-storchaka, @slateny

^{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 = None
created_at = <Date 2013-07-23.05:06:58.278>
labels = ['easy', '3.11', '3.9', '3.10', 'docs']
title = '[doc] State clearly that open() \'file\' param is "name" attr of the result'
updated_at = <Date 2022-03-01.10:09:16.050>
user = 'https://github.com/ncoghlan'

bugs.python.org fields:

activity = <Date 2022-03-01.10:09:16.050>
actor = 'slateny'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2013-07-23.05:06:58.278>
creator = 'ncoghlan'
dependencies = []
files = []
hgrepos = []
issue_num = 18534
keywords = ['easy']
message_count = 7.0
messages = ['193585', '193602', '193616', '193625', '193695', '305354', '414254']
nosy_count = 8.0
nosy_names = ['gvanrossum', 'ncoghlan', 'pitrou', 'vstinner', 'aronacher', 'docs@python', 'serhiy.storchaka', 'slateny']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = None
url = 'https://bugs.python.org/issue18534'
versions = ['Python 3.9', 'Python 3.10', 'Python 3.11']

[ncoghlan]

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/

[pitrou]

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.

[serhiy-storchaka]

Seconded Antoine.

[ncoghlan]

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

[ncoghlan]

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.

[gvanrossum]

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.

[slateny]

Would it be fine to modify FileIO.name like this:

"... given in the constructor. Depending on the type of *name* that was passed into the constructor, this may not necessarily e a string."