python/typeshed

`tarfile.TarFile` has several missing overloads

Open

#14168 opened on May 27, 2025

View on GitHub
 (2 comments) (1 reaction) (0 assignees)Python (3,436 stars) (1,483 forks)batch import
help wantedstubs: false negative

Description

Right now TarFile.__init__ is defined as: https://github.com/python/typeshed/blob/c7e29eccd9759411c0f46580e20727038668b320/stdlib/tarfile.pyi#L128-L132

Which is not exactly right, because there's a case when name and fileobj are both None at the same time. And this will lead to runtime errors:

>>> import tarfile
>>> tarfile.TarFile(None, fileobj=None)
Traceback (most recent call last):
  File "<python-input-2>", line 1, in <module>
    tarfile.TarFile(None, fileobj=None)
    ~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^
  File "/Users/sobolev/Desktop/cpython/Lib/tarfile.py", line 1729, in __init__
    fileobj = bltn_open(name, self._mode)
TypeError: expected str, bytes or os.PathLike object, not NoneType

Right now mypy does not raise any errors for this broken case: https://mypy-play.net/?mypy=latest&python=3.12&gist=7452d274249fafba1f8a16565d5486c6

We need either name or fileobj, they can be both None at the same time. So, we need to add overloads.

There are several other methods that needs to be updated like open and taropen, maybe others.

Contributor guide

Tech stack
python
Domain
developer experiencetooling
Issue type
bug
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-3 hours
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
fresh
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
mostly clear
Prerequisites
Basic knowledge of Python type hintsUnderstanding of function overloads
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
50
Research direction
The issue is that `TarFile. init ` and other methods like `open` and `taropen` need overloads to enforce that at least one of `name` or `fileobj` is provided. Look at the existing stub file at `stdlib/tarfile.pyi` and examine how other overloads are defined in typeshed (e.g., for `open` functions). The goal is to define two overloads: one with `name: str` and `fileobj: None`, another with `name: None` and `fileobj: IO[bytes]`. Ensure the original signature is kept as a fallback. Check the comments on the issue for any additional context.