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

Bắt đầu với các phần tài liệu tarfile về TarInfo.size và Reading Examples, được issue xác định là cần thay đổi. Công việc được xem là hoàn tất khi phần mô tả size giải thích đại lượng được đo là gì và các ví dụ đọc bao gồm một ví dụ tối thiểu, mang tính hướng dẫn, thực hiện trong bộ nhớ; hãy kiểm tra các PRs được liên kết trước khi bắt đầu.