python/typeshed

`tarfile.TarFile` has several missing overloads

Open

#14,168 创建于 2025年5月27日

在 GitHub 查看
 (2 评论) (1 反应) (0 负责人)Python (3,436 star) (1,483 fork)batch import
help wantedstubs: false negative

描述

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.

贡献者指南

技术栈
python
领域
developer experiencetooling
议题类型
bug
难度面向新贡献者的预计实现难度，1 表示很小改动，5 表示专家级工作。
3
预计时间有经验贡献者完成调查、实现、测试并准备 pull request 的粗略时间范围。
1-3 hours
活动状态议题当前的可参与程度：新鲜、活跃、陈旧、阻塞或等待维护者输入。
fresh
清晰度议题是否清楚说明期望改动、验收标准和下一步。
mostly clear
前置要求
Basic knowledge of Python type hintsUnderstanding of function overloads
新手友好度1-100 的估计分数，表示该议题对首次贡献者的友好程度。
50
研究方向
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.