Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

tarfile's extractfile documentation is misleading #83874

Closed
MojoVampire mannequin opened this issue Feb 20, 2020 · 4 comments
Closed

tarfile's extractfile documentation is misleading #83874

MojoVampire mannequin opened this issue Feb 20, 2020 · 4 comments
Labels
3.9 only security fixes 3.10 only security fixes docs Documentation in the Doc dir easy stdlib Python modules in the Lib dir

Comments

@MojoVampire
Copy link
Mannequin

MojoVampire mannequin commented Feb 20, 2020

BPO 39693
Nosy @akuchling, @ethanfurman, @MojoVampire, @miss-islington, @dorosch
PRs
  • bpo-39693: tarfile extractfile documentation #18639
  • [3.9] bpo-39693: mention KeyError in tarfile extractfile documentation (GH-18639) #22819
  • 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 = <Date 2020-10-20.14:32:18.413>
    created_at = <Date 2020-02-20.07:12:11.437>
    labels = ['easy', 'library', '3.9', '3.10', 'docs']
    title = "tarfile's extractfile documentation is misleading"
    updated_at = <Date 2020-10-20.14:32:18.411>
    user = 'https://github.com/MojoVampire'

    bugs.python.org fields:

    activity = <Date 2020-10-20.14:32:18.411>
    actor = 'akuchling'
    assignee = 'docs@python'
    closed = True
    closed_date = <Date 2020-10-20.14:32:18.413>
    closer = 'akuchling'
    components = ['Documentation', 'Library (Lib)']
    creation = <Date 2020-02-20.07:12:11.437>
    creator = 'josh.r'
    dependencies = []
    files = []
    hgrepos = []
    issue_num = 39693
    keywords = ['patch', 'easy', 'newcomer friendly']
    message_count = 4.0
    messages = ['362298', '379126', '379129', '379130']
    nosy_count = 6.0
    nosy_names = ['akuchling', 'docs@python', 'ethan.furman', 'josh.r', 'miss-islington', 'dorosch']
    pr_nums = ['18639', '22819']
    priority = 'normal'
    resolution = 'fixed'
    stage = 'resolved'
    status = 'closed'
    superseder = None
    type = None
    url = 'https://bugs.python.org/issue39693'
    versions = ['Python 3.9', 'Python 3.10']

    @MojoVampire
    Copy link
    Mannequin Author

    MojoVampire mannequin commented Feb 20, 2020

    The documentation for extractfile ( https://docs.python.org/3/library/tarfile.html#tarfile.TarFile.extractfile ) says:

    "Extract a member from the archive as a file object. member may be a filename or a TarInfo object. If member is a regular file or a link, an io.BufferedReader object is returned. Otherwise, None is returned."

    Before reading further, answer for yourself: What do you think happens when a provided filename doesn't exist, based on that documentation?

    In teaching a Python class that uses tarfile in the final project, and expects students to catch predictable errors (e.g. a random tarball being provided, rather than one produced by a different mode of the program with specific expected files) and convert them to user-friendly error messages, I've found this documentation to confuse students repeatedly (if they actually read it, rather than just guessing and checking interactively).

    Specifically, the documentation:

    1. Says nothing about what happens if member doesn't exist (TarFile.getmember does mention KeyError, but extractfile doesn't describe itself in terms of getmember)
    2. Loosely implies that it should return None in such a scenario "If member is a regular file or a link, an io.BufferedReader object is returned. Otherwise, None is returned." The intent is likely to mean "all other member types are None, and we're saying nothing about non-existent members", but everyone I've taught who has read the docs came away with a different impression until they tested it.

    Perhaps just reword from:

    "If member is a regular file or a link, an io.BufferedReader object is returned. Otherwise, None is returned."

    to:

    "If member is a regular file or a link, an io.BufferedReader object is returned. For all other existing members, None is returned. If member does not appear in the archive, KeyError is raised."

    Similar adjustments may be needed for extract, and/or both of them could be adjusted to explicitly refer to getmember by stating that filenames are converted to TarInfo objects via getmember.

    @MojoVampire MojoVampire mannequin added 3.7 (EOL) end of life 3.8 only security fixes 3.9 only security fixes labels Feb 20, 2020
    @MojoVampire MojoVampire mannequin assigned docspython Feb 20, 2020
    @MojoVampire MojoVampire mannequin added 3.7 (EOL) end of life docs Documentation in the Doc dir stdlib Python modules in the Lib dir 3.8 only security fixes easy 3.9 only security fixes labels Feb 20, 2020
    @MojoVampire MojoVampire mannequin assigned docspython Feb 20, 2020
    @MojoVampire MojoVampire mannequin added docs Documentation in the Doc dir stdlib Python modules in the Lib dir easy labels Feb 20, 2020
    @akuchling
    Copy link
    Member

    New changeset ec42789 by Andrey Doroschenko in branch 'master':
    bpo-39693: mention KeyError in tarfile extractfile documentation (GH-18639)
    ec42789

    @akuchling
    Copy link
    Member

    New changeset b249aea by Miss Skeleton (bot) in branch '3.9':
    bpo-39693: mention KeyError in tarfile extractfile documentation (GH-18639)
    b249aea

    @akuchling
    Copy link
    Member

    Closing after applying the PR. Thanks!

    @akuchling akuchling added 3.10 only security fixes and removed 3.7 (EOL) end of life 3.8 only security fixes labels Oct 20, 2020
    @akuchling akuchling added 3.10 only security fixes and removed 3.7 (EOL) end of life 3.8 only security fixes labels Oct 20, 2020
    @ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Labels
    3.9 only security fixes 3.10 only security fixes docs Documentation in the Doc dir easy stdlib Python modules in the Lib dir
    Projects
    None yet
    Development

    No branches or pull requests

    1 participant