Unclear documentation for TarFile

Documentation

The tarfile docs does not make it clear how a programmer can read data from a tarfile into memory without doing a round-trip writing it to the file system. As far as I understand, reading partial data from a tar file essentially amounts to the following steps:

import tarfile

with open("myfile.tar") as f:
    tar = tarfile.TarFile(fileobj=f)

    tar_info = next(member for member in f.getmembers() if member.is_file())
    f.seek(tar_info.offset_data)
    data = f.read(tar_info.size)

However, to arrive at this, you either need to be confident enough to read the CPython source code, or you need to know that tar-files stores the byte-contents unchanged, and that TarInfo.size is the size of the data without the file header. Neither of these are obvious for less experienced programmers.

I suggest that we make two changes to the tarfile docs:

1. Expand the documentation for TarInfo.size so it says more than just "Size in bytes". Size of what exactly? The archived file as far as I can tell.
2. Include a minimal example (like I have above, but slightly more pedagogical maybe) to the Reading Examples section.

I can propose a PR with these changes if you think that is useful.

Linked PRs

• gh-146424
• gh-151909

从 tarfile 文档中关于 TarInfo.size 和 Reading Examples 的章节开始，issue 指出这些章节需要修改。完成的标准是，size 的描述说明测量的是什么，并且读取示例包含一个最小的、具有教学意义的内存中示例；开始前检查已链接的 PRs。