pandas的类型注解
项目描述
pandas-stubs：pandas的公共类型存根
这是什么？
这些是pandas的公共类型存根，遵循PEP 561中规定的在单独的包中提供存根的约定。存根涵盖了pandas最典型的用法。一般来说，这些存根比pandas可能允许的范围要窄，但遵循建议最佳实践来使用pandas的约定。
在涵盖pandas发布的API方面，存根可能是不完整的。注意：pandas-stubs当前的2.0.x版本不支持pandas 2.0的所有新功能。请参阅此跟踪器了解与2.0版本的当前兼容性。
存根已通过mypy和pyright进行测试，并随Visual Studio Code扩展pylance一起提供。
使用方法
让我们以文件round.py中的这段代码为例
import pandas as pd
decimals = pd.DataFrame({'TSLA': 2, 'AMZN': 1})
prices = pd.DataFrame(data={'date': ['2021-08-13', '2021-08-07', '2021-08-21'],
'TSLA': [720.13, 716.22, 731.22], 'AMZN': [3316.50, 3200.50, 3100.23]})
rounded_prices = prices.round(decimals=decimals)
mypy不会看到任何问题，但在安装pandas-stubs并再次运行后
mypy round.py
我们得到以下错误消息
round.py:6: error: Argument "decimals" to "round" of "DataFrame" has incompatible type "DataFrame"; expected "Union[int, Dict[Any, Any], Series[Any]]" [arg-type]
Found 1 error in 1 file (checked 1 source file)
如果你使用pyright
pyright round.py
你会得到以下错误消息
round.py:6:40 - error: Argument of type "DataFrame" cannot be assigned to parameter "decimals" of type "int | Dict[Unknown, Unknown] | Series[Unknown]" in function "round"
Type "DataFrame" cannot be assigned to type "int | Dict[Unknown, Unknown] | Series[Unknown]"
"DataFrame" is incompatible with "int"
"DataFrame" is incompatible with "Dict[Unknown, Unknown]"
"DataFrame" is incompatible with "Series[Unknown]" (reportGeneralTypeIssues)
在确认文档后，我们可以修复代码
decimals = pd.Series({'TSLA': 2, 'AMZN': 1})
版本编号约定
版本号x.y.z.yymmdd对应于使用pandas版本x.y.z进行的测试，存根在mm/yy/dd的日期发布。预计存根将比pandas发布得更频繁，因为存根预计会因为更多的公开可见性而发展。
在哪里获取
源代码目前托管在GitHub上：https://github.com/pandas-dev/pandas-stubs
最新发布版本的二进制安装程序可在Python包索引（PyPI）和conda-forge上获取。
# conda
conda install pandas-stubs
# or PyPI
pip install pandas-stubs
依赖项
从源代码安装
- 确保已安装
python >= 3.9。 - 安装poetry
# conda
conda install poetry
# or PyPI
pip install 'poetry>=1.2'
- 安装项目依赖项
poetry update -vvv
- 构建和安装发行版
poetry run poe build_dist
poetry run poe install_dist
许可
文档
文档仍在进行中。
背景
这些存根是pandas核心团队领导的一项战略努力的成果，旨在将Microsoft类型存根仓库与VirtusLabs pandas_stubs仓库集成。
这些存根最初是从https://github.com/microsoft/python-type-stubs的Microsoft项目分叉的，自此提交起。
我们感谢Microsoft及其项目提供了初始的公共类型存根。我们还感谢https://github.com/VirtusLab/pandas-stubs上的原始pandas-stubs项目，它为测试存根创建了一个框架。
pandas和pandas-stubs中类型声明之间的差异
https://github.com/pandas-dev/pandas/项目为pandas的一些部分具有类型声明，包括内部和公共API。这些类型声明用于确保pandas代码在内部上是一致的。
《https://github.com/pandas-dev/pandas-stubs/》项目提供了pandas 公共 API的类型声明。这些stub的哲学可以在《https://github.com/pandas-dev/pandas-stubs/blob/main/docs/philosophy.md/》中找到。虽然这个项目中的pyi文件最好是pandas发行版的一部分，但这需要内部类型声明与公共声明之间的一致性，以及创建这种一致性的项目的范围相当大。这是一个长期目标。最后，另一个目标是比pandas更频繁地发布pandas-stubs，以便使stub更实用。
如果发现公共stub存在问题，欢迎提交pull requests来纠正这些问题。此外，欢迎在pandas仓库中对同一问题提交pull requests。然而，由于两个项目的类型化目标不同（内部一致性 vs. 公共使用），在两个项目之间创建一致的类型声明可能是一个挑战。请参阅《https://pandas.ac.cn/docs/development/contributing_codebase.html#type-hints》以了解pandas代码中使用的类型化标准。
寻求帮助
在pandas-stubs仓库上提问和报告问题。
讨论和开发
大多数开发讨论都在pandas-stubs仓库的GitHub上进行。
此外，pandas-dev邮件列表也可用于专门的讨论或设计问题，并有一个Slack频道用于快速回答与开发相关的问题。
还有定期的社区会议对社区开放，以及每月的新贡献者会议以帮助支持新贡献者。
有关通信渠道的更多信息可以在贡献者社区页面上找到。
为pandas-stubs做出贡献
欢迎所有贡献，包括错误报告、错误修复、文档改进、增强功能和想法。请参阅https://github.com/pandas-dev/pandas-stubs/tree/main/docs/以获取说明。
项目详情
下载文件
下载适用于您平台的文件。如果您不确定选择哪个，请了解有关安装包的更多信息。