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

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:
https://github.com/python/cpython/blob/9d8f2d8e08336695fdade5846da4bbcc3eb5f152/Lib/_pyio.py#L834-L836

TextIOWrapper delegates name to its underlying binary stream:
https://github.com/python/cpython/blob/9d8f2d8e08336695fdade5846da4bbcc3eb5f152/Lib/_pyio.py#L2190-L2192

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 (https://github.com/python/cpython/issues/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

• https://github.com/python/cpython/issues/62734
  • Not exactly the same as it's about documenting the type of FileIO.name more accurately.
• https://github.com/python/cpython/issues/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 https://github.com/python/cpython/issues/62734, even though there is another issue in there.

Linked PRs

• gh-142753

审查 FileIO、TextIOWrapper、BufferedReader 和 BufferedWriter 的 io 文档，以及链接的 gh-142753 pull request。确认 name 和 mode 是公共属性还是实现细节，然后根据该决定调整文档，并验证对 tarfile.gettarinfo 的引用是否准确。