name and mode attributes only documented for io.FileIO but exist for TextIOWrapper, BufferedReader, and BufferedWriter as well

[smheidrich]

Documentation

The facts

The io docs only list a name attribute for io.FileIO, which represents a raw (= unbuffered) binary stream backed by a file.

open returns an instance of io.TextIOWrapper, io.BufferedReader, or io.BufferedWriter unless called with buffering=0 in which case it does return a FileIO instance. But this is rare so these 3 classes are much more common than FileIO in everyday Python.

A name attribute isn't documented for any of these classes, despite the fact that their CPython implementations define name properties that delegate to the underlying streams:

_BufferedIOMixin, the parent of BufferedReader and BufferedWriter, delegates name to its underlying raw (= unbuffered) stream:

cpython/Lib/_pyio.py

Lines 834 to 836 in 9d8f2d8

	@property
	def name(self):
	return self.raw.name

TextIOWrapper delegates name to its underlying binary stream:

cpython/Lib/_pyio.py

Lines 2190 to 2192 in 9d8f2d8

	@property
	def name(self):
	return self.buffer.name

These are not marked as internal or deprecated in any way, so one can only assume they are meant for use by the general public.

Moreover, the docs refer to FileIO.name when it's clear from context that the file object in question doesn't have to be unbuffered (like FileIO necessarily is) at least once, when describing tarfile.gettarinfo:

[...] otherwise, the name is taken from fileobj’s name attribute, [...]

Except for this last one, the same facts hold for the mode attribute.

Making sense of this

While there is no subtype relationship between FileIO and these other classes, it seems to me like they're meant to be understood as "quasi-subtypes" of FileIO at least as far as name and mode are concerned if the underlying stream of an instance is itself an instance of FileIO.

But, unless I missed it, this is never spelled out anywhere in the io docs.

How to fix this

Option 1: Document these attributes in the io docs

Assuming everything I wrote above turns out to be correct and these attributes really are meant to be actually used:

Option 1.1: Add name and mode attribute docs for all 3 classes separately

This would make things very explicit and easy to grasp for users who only skim the docs, but comes at the cost of being a bit repetitious.

Option 1.2: Add a sentence or paragraph explaining the "quasi-subtype" relationship with FileIO

This would be easy to miss for users who only skim the docs, but still better than the current situation.

To avoid repeating the explanation for all 3 classes, it might be put somewhere in the introduction of io's docs, which, however, would make it even easier to miss. An inheritance diagram right at the start like in the pathlib docs might help out here (that might be a good idea regardless and probably deserves its own issue).

Option 2: Document these attributes in typing.IO

The typing.IO interface specifies a name property as well, but it's hard for users to find that out without looking at the typeshed source because its documentation doesn't list any members.

That would have been worthy of an issue of its own, but given that typing.IO seems to be on its way to deprecation anyway (#92877), I guess we can rule it out.

Option 3: Mark these attributes as deprecated/internal/implementation detail

If I'm wrong and these attributes are not meant to be actually used or should be considered CPython implementation details, it might make sense to document that somehow.

I don't know what the process here is, but just adding a docstring or comment in the CPython property implementations I cited above would probably help.

Related issues

• [doc] State clearly that open() 'file' param is "name" attr of the result #62734
  • Not exactly the same as it's about documenting the type of FileIO.name more accurately.
• File object 'name' attribute inconsistent type and not obviously documented #76775
  • Issue about two things: 1. Again the type of name being weird and 2. the fact that name isn't documented in open()'s documentation. Because of (1), got closed as a duplicate of [doc] State clearly that open() 'file' param is "name" attr of the result #62734, even though there is another issue in there.