【Hackathon 6th】为 Paddle 框架 API 添加类型提示（Type Hints） #858

megemini · 2024-04-08T14:46:08Z

PR types

Others

PR changes

Docs

Description

【Hackathon 6th】为 Paddle 框架 API 添加类型提示（Type Hints）

请评审！

@SigureMo @zrr1999 @sunzhongkai588 @luotao1

paddle-bot · 2024-04-08T14:46:16Z

你的PR提交成功，感谢你对开源项目的贡献!
请检查PR提交格式和内容是否完备，具体请参考示例和模版。
Your PR has been submitted. Thanks for your contribution!
Please check its format and content. For this, you can refer to Template and Demo.

megemini · 2024-04-10T10:28:53Z

@Asthestarsfalll @gsq7474741 请帮忙看看～～～

gsq7474741 · 2024-04-12T12:41:28Z

@Asthestarsfalll @gsq7474741 请帮忙看看～～～

LGTM

SigureMo

非常棒的 RFC！不过有一些问题想要确认下：

是否考虑引入 typing_extension，是否使用 PEP 563？根据个人 type hints 最佳开发实践，typing_extension、PEP 563、if TYPE_CHECKING 的结合可以大大减少版本兼容性考虑，允许在低版本部分场景使用高版本的类型提示特性，虽然 PEP 563 终将在 Python 3.13 被 PEP 649 所替代，但距离 Python 3.13 成为最低支持版本还有很多年呢，PEP 563 是一个不错的选择
在前期将一些主要的模块标记完之后，是否考虑组织一次分享，向社区其他同学分享类型提示标注的经验，因为了解类型提示的人非常少，真正掌握一些高级用法的人更是基本没有
需要考虑在类型提示标注时的一些原则，虽然现在可能没有太多经验考虑不到，但在初期标注积累经验后应当整理成文档，如：
- 对于 dict 参数，如可能，应标记为 TypedDict，以提供更精准的类型信息
- 等等，其实我暂时也想不到太多，这些可以考虑记录在文档里

唔，暂时也想不到太多，感觉稍微修改下就可以准备开工了～

SigureMo · 2024-04-13T10:37:07Z

rfcs/Docs/【Hackathon 6th】为 Paddle 框架 API 添加类型提示.md

+
+## 1、相关背景
+
+Python 在 3.5 版本通过 [PEP 484 – Type Hints](https://peps.python.org/pep-0484) 正式规范了 `类型提示` 功能，以帮助开发者提高代码质量，Python 目前 (`3.12` 版本) 已经完成的相关 `PEP` 有 `11` 个，具体可以参考 [Typing PEPs](https://peps.python.org/topic/typing/) 。经过前期的几个版本迭代，Python 的 `类型提示` 功能已经受到开发者的广泛认可。Paddle 目前支持的 Python 版本 `3.8` 已经可以较好的支持 `类型提示`，本文旨在阐述 Paddle 引入 `类型提示` 的可行性与具体方案。


Python 目前 (3.12 版本)

严谨地说，「目前」Python 正在开发的是 3.13，应指出「最新发布版本」

已经完成的相关 PEP 有 11 个

11 个是如何得来的呢？Finished PEPs 也不止 11 个呀

Paddle 目前支持的 Python 版本 3.8 已经可以较好的支持 类型提示

目前最低支持

写错了，是 21 个 ... ...

https://peps.python.org/topic/typing/ 中 Finished PEPs (done, with a stable interface)

SigureMo · 2024-04-13T10:37:42Z

rfcs/Docs/【Hackathon 6th】为 Paddle 框架 API 添加类型提示.md

+
+## 2、功能目标
+
+正确完成 Paddle 开放 API 的类型标注，但不声明 Paddle 类型标注的完备性。


Suggested change

正确完成 Paddle 开放 API 的类型标注，但不声明 Paddle 类型标注的完备性。

正确完成 Paddle 公开 API 的类型标注，但不声明 Paddle 类型标注的完备性。

SigureMo · 2024-04-13T10:47:14Z

rfcs/Docs/【Hackathon 6th】为 Paddle 框架 API 添加类型提示.md

+
+### 2.1 typing 模块
+
+此目标为 Paddle 添加 `typing` 模块，并作为开放 API 的一部分。


公开 API 是一件很大的事情，一个 API 一旦公开，那么就需要保证其稳定性，用户不会因为之前版本 import 了一个 API 而在之后版本突然删掉 / 修改行为而挂掉，而我们的 typing 模块明显不具备这一点，我建议目前不考虑公开，并修改命名为 _typing，公开应该在全 Paddle 类型提示全部覆盖后才考虑

而且公开 API 需要考虑到很多事情，比如 Tensor 是否是泛型等等……

因此 _typing 仅限于内部标注使用我觉得是目前更合适的方式

嗯，可以～这样的话，那可以把这部分必要的文档，放到开发指南里面，做为《Paddle 中的类型提示》的一部分～

SigureMo · 2024-04-13T11:03:32Z

rfcs/Docs/【Hackathon 6th】为 Paddle 框架 API 添加类型提示.md

+功能特性类似：
+
+- PyTorch 中的 `torch/types.py`
+- Numpy 中的 [Typing (numpy.typing)](https://numpy.org/devdocs/reference/typing.html)


NumPy 的 Typing 做的真的不错，paddlepaddle-stubs 也是有意参考 NumPy 的实现，之后实现时候可以多学习和参考 NumPy 的实现

SigureMo · 2024-04-13T11:07:03Z

rfcs/Docs/【Hackathon 6th】为 Paddle 框架 API 添加类型提示.md

+- PyTorch 中的 `torch/types.py`
+- Numpy 中的 [Typing (numpy.typing)](https://numpy.org/devdocs/reference/typing.html)
+
+`typing` 模块包含 Paddle 中用到的特殊类型，如 `dtype`，`device` 等，具体实现可参考 @SigureMo 的 [paddle-stubs/_typing](https://github.com/cattidea/paddlepaddle-stubs/tree/main/paddle-stubs/_typing)。


paddle 运行时有自己的 dtype，这一点是与 paddlepaddle-stubs 不同的，要实现的只是类似 DTypeLike 这种的便于标注的类型

另外，Paddle 目前 dtype 底层实现正处于 VarType 向 DataType 的过渡期，此时可以使用 if TYPE_CHECKING guard 下定义专属于类型检查的类型，但在未来消除掉这两者的差异后，直接使用 DataType 应该就可以了

SigureMo · 2024-04-13T12:36:38Z

rfcs/Docs/【Hackathon 6th】为 Paddle 框架 API 添加类型提示.md

+  - `paddle.fft.*`
+
+- `P4`
+  - `paddle.incubate.*`


非常冷门，建议 P5

SigureMo · 2024-04-13T12:36:51Z

rfcs/Docs/【Hackathon 6th】为 Paddle 框架 API 添加类型提示.md

+  - `paddle.sysconfig.*`
+  - `paddle.utils.*`
+  - `paddle.text.*`
+  - `paddle.tensor.*`


非常常用，建议 P2

SigureMo · 2024-04-13T12:37:04Z

rfcs/Docs/【Hackathon 6th】为 Paddle 框架 API 添加类型提示.md

+  - `paddle.profiler.*`
+  - `paddle.nn.quant.*`
+  - `paddle.nn.utils.*`
+  - `paddle.jit.*`


SigureMo · 2024-04-13T12:37:20Z

rfcs/Docs/【Hackathon 6th】为 Paddle 框架 API 添加类型提示.md

+- `P5`
+  - `paddle.inference.*`
+  - `paddle.proto.*`
+  - `paddle.common_ops_import.*`


这里没有函数

SigureMo · 2024-04-13T12:37:50Z

rfcs/Docs/【Hackathon 6th】为 Paddle 框架 API 添加类型提示.md

+  - `paddle.reader.*`
+  - `paddle.hapi.*`
+  - `paddle.framework.*`
+  - `paddle.dataset.*`


这里不要标注了，本就是废弃的

megemini · 2024-04-14T07:11:00Z

是否考虑引入 typing_extension，是否使用 PEP 563？根据个人 type hints 最佳开发实践，typing_extension、PEP 563、if TYPE_CHECKING 的结合可以大大减少版本兼容性考虑，允许在低版本部分场景使用高版本的类型提示特性，虽然 PEP 563 终将在 Python 3.13 被 PEP 649 所替代，但距离 Python 3.13 成为最低支持版本还有很多年呢，PEP 563 是一个不错的选择

必须的～

有一个原则看看可行不：在不违背 Paddle 最低支持版本 3.8 语法的基础上，尽可能使用最新版本 typing 特性。

比如，annotation 中用 | 代替 Union，但是 TypeAlias 中由于语法不支持，仍使用 Union

在前期将一些主要的模块标记完之后，是否考虑组织一次分享，向社区其他同学分享类型提示标注的经验，因为了解类型提示的人非常少，真正掌握一些高级用法的人更是基本没有

可以有～

需要考虑在类型提示标注时的一些原则，虽然现在可能没有太多经验考虑不到，但在初期标注积累经验后应当整理成文档，如：

对于 dict 参数，如可能，应标记为 TypedDict，以提供更精准的类型信息

等等，其实我暂时也想不到太多，这些可以考虑记录在文档里

可以有～参考上面提到的原则～只是，type hint 的东西太多了，best practice 可能得慢慢积累～

SigureMo · 2024-04-14T08:01:11Z

比如，annotation 中用 | 代替 Union，但是 TypeAlias 中由于语法不支持，仍使用 Union

嗯，TypeAlias 从语法角度上只是赋值，PEP 563 只是对类型注释进行延迟计算，不会对赋值节点进行延迟计算，因此低版本语法就不支持的，那就无能为力了，PEP 695 也一样

另外，在类型注释中就算写 Union，Ruff 的 PYI rule 应该也能自动修复成 |，但是这一原则还是需要写在文档的～

只是，type hint 的东西太多了，best practice 可能得慢慢积累～

这个确实

megemini · 2024-04-14T10:50:41Z

Update 20240414

typing 模块改为私有模块 _typing，不创建 API 及中英文文档
删除代理文件的对比
《Paddle 中的类型提示》的内容目录
《Paddle 类型提示 Q&A》需要文档或工具，跟踪类型标注的最佳实践

另外，关于 Tensor 的具体做法，我这里暂时不改了吧～这是个单独的任务，到时候可以两者都试一下，只要别对框架有影响就行～

@SigureMo @zrr1999 @Asthestarsfalll @gsq7474741 @sunzhongkai588 @luotao1 请评审～

SigureMo

一点小的格式建议等，目前没有其他更多内容的建议了～

LGTMeow

SigureMo · 2024-04-14T13:34:41Z

rfcs/Docs/【Hackathon 6th】为 Paddle 框架 API 添加类型提示.md

+
+> **说明**： 类型标注是个循序渐进的过程，且存在较多私有 API 与 c++ 接口，此次任务无法保证完成以上所有接口的类型标注，故此，不做 Paddle 类型标注的完备性说明。
+
+### 2.1 _typing 模块


Suggested change

### 2.1 _typing 模块

### 2.1 `_typing` 模块

SigureMo · 2024-04-14T13:35:17Z

rfcs/Docs/【Hackathon 6th】为 Paddle 框架 API 添加类型提示.md

+- PyTorch 中的 `torch/types.py`
+- Numpy 中的 [Typing (numpy.typing)](https://numpy.org/devdocs/reference/typing.html)
+
+`_typing` 模块包含 Paddle 中用到的特殊类型，如 `dtype`，`device` 等，具体实现可参考 @SigureMo 的 [paddle-stubs/_typing](https://github.com/cattidea/paddlepaddle-stubs/tree/main/paddle-stubs/_typing)。


Suggested change

`_typing` 模块包含 Paddle 中用到的特殊类型，如 `dtype`，`device` 等，具体实现可参考 @SigureMo 的 [paddle-stubs/_typing](https://github.com/cattidea/paddlepaddle-stubs/tree/main/paddle-stubs/_typing)。

`_typing` 模块包含 Paddle 中用到的特殊类型，如 `dtype`、`device` 等，具体实现可参考 @SigureMo 的 [paddle-stubs/_typing](https://github.com/cattidea/paddlepaddle-stubs/tree/main/paddle-stubs/_typing)。

SigureMo · 2024-04-14T13:36:56Z

rfcs/Docs/【Hackathon 6th】为 Paddle 框架 API 添加类型提示.md

+
+1. Paddle 中引入 `_typing` 模块
+
+    **对用户的影响：** 用户可以使用 `_typing` 模块提供的接口


这里不推荐用户用吧，我觉得可以认为对用户无影响

SigureMo · 2024-04-14T13:37:19Z

rfcs/Docs/【Hackathon 6th】为 Paddle 框架 API 添加类型提示.md

+
+    **对开发者的影响：** 开发者可以使用 `_typing` 模块标注 Paddle 内部模块
+
+    **对框架架构的影响：** Paddle 框架中增加 `_typing` 模块与相应接口


Suggested change

**对框架架构的影响：** Paddle 框架中增加 `_typing` 模块与相应接口

**对框架架构的影响：** Paddle 框架中增加 `_typing` 模块

megemini · 2024-04-15T04:09:00Z

一点小的格式建议等，目前没有其他更多内容的建议了～

已修改～看看大家还有啥建议？～

luotao1 · 2024-05-17T03:33:49Z

comment by @jeff41404 整体修改完后，需要进行一个部门评审

1. “意义”（效果/收益）这一章的描述过于概括和抽象，需要清楚和直观一些，比如我们对公开API 都加上类型提示后，“开发体验”上直观的改进效果是什么，比如开发者在什么场景下有更好的感受，最好有一些截图说明优化前和优化后的效果对比，让其它人能够get到这项工作的价值和意义

2. 下面分阶段的工作中，每个阶段要加一句话说明里程碑的意义，并和整体意义（效果/收益）联动，比如第1阶段是完成机制基础，第2阶段就能够达到xxx效果

3. 公开API的数量。2.6版本已经有1800+，develop接近2000

4. “2.3 CI 流水线” 一章中，旧/新 API的意思是“PR中修改的公开API”？

5. “2.4 文档建设”还需要更新 API开发指南，在推进存量修改的同时，确保增量也都有类型提示
6. 文档中对API的用词都统一为：公开API/非公开API，不要描述为“开放 API”、“私有 API ”、“开放接口”等
7. roadmap 里没有 paddle.* (如 paddle.add 等的计划描述)
https://github.com/orgs/cattidea/projects/3/views/1

megemini · 2024-05-18T05:46:53Z

Update 20240518

修改 RFC ，PR ：#904

单独针对上述问题 7. roadmap 里没有 paddle.* (如 paddle.add 等的计划描述) 进行回复：

paddle.xxx 的接口基本都是子模块暴露到顶层，所以，修改子模块即可
另有 monkey_patch_tensor 的接口，已在修改的 RFC 中添加

@luotao1 请评审

jeff41404 · 2024-05-20T10:35:00Z

Update 20240518

修改 RFC ，PR ：#904

单独针对上述问题 7. roadmap 里没有 paddle.* (如 paddle.add 等的计划描述) 进行回复：

paddle.xxx 的接口基本都是子模块暴露到顶层，所以，修改子模块即可

Understood, but does the priority of paddle.tensor.* need to be raised, at least not P4, which includes many commonly used APIs

SigureMo · 2024-05-20T10:39:55Z

Understood, but does the priority of paddle.tensor.* need to be raised, at least not P4, which includes many commonly used APIs

paddle.tensor.* 在 RFC 中是 P2，之前 comment 后改过了的 #858 (comment)

https://github.com/orgs/cattidea/projects/3/views/1 与本任务无关，只是本任务的一个参考项而已

megemini · 2024-05-20T10:43:46Z

paddle.tensor.* 在 RFC 中是 P2，之前 comment 后改过了的 [#858 (comment)]

后来想了想，在 #904 里面把 paddle.tensor.* 改到 P1 了，还是先做这个吧～

megemini added 4 commits April 8, 2024 12:27

rfc part 1

fa6b1cf

rfc part 2

29a88ef

rfc part 3

5cfc9d6

rfc v1

00dd9f7

paddle-bot bot added the contributor label Apr 8, 2024

luotao1 assigned luotao1, SigureMo, zrr1999 and sunzhongkai588 Apr 9, 2024

SigureMo reviewed Apr 13, 2024

View reviewed changes

megemini added 2 commits April 14, 2024 18:31

rfc v1.1

f5aaa2f

rfc v1.1 fix

3de266e

rfc v1.1 fix fix

fba059d

SigureMo approved these changes Apr 14, 2024

View reviewed changes

rfc v1.1 fix fix fix

69fa7c3

luotao1 merged commit 483de7b into PaddlePaddle:master Apr 17, 2024
1 check passed

megemini mentioned this pull request Apr 17, 2024

为 Paddle 框架 API 添加类型提示（Type Hints）Tracking Issue PaddlePaddle/Paddle#63597

Closed

16 tasks

megemini mentioned this pull request May 18, 2024

[Update] 为 Paddle 框架 API 添加类型提示（Type Hints） #904

Merged

megemini mentioned this pull request Jun 10, 2024

[Type Hints] 为公开 API 标注类型提示信息 PaddlePaddle/Paddle#65008

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

【Hackathon 6th】为 Paddle 框架 API 添加类型提示（Type Hints） #858

【Hackathon 6th】为 Paddle 框架 API 添加类型提示（Type Hints） #858

megemini commented Apr 8, 2024

paddle-bot bot commented Apr 8, 2024

megemini commented Apr 10, 2024

gsq7474741 commented Apr 12, 2024

SigureMo left a comment

SigureMo Apr 13, 2024

megemini Apr 14, 2024

SigureMo Apr 13, 2024

SigureMo Apr 13, 2024

megemini Apr 14, 2024

SigureMo Apr 13, 2024

SigureMo Apr 13, 2024

SigureMo Apr 13, 2024

SigureMo Apr 13, 2024

SigureMo Apr 13, 2024

SigureMo Apr 13, 2024

SigureMo Apr 13, 2024

megemini commented Apr 14, 2024

SigureMo commented Apr 14, 2024

megemini commented Apr 14, 2024

SigureMo left a comment

SigureMo Apr 14, 2024

SigureMo Apr 14, 2024

SigureMo Apr 14, 2024

SigureMo Apr 14, 2024

megemini commented Apr 15, 2024

luotao1 commented May 17, 2024

megemini commented May 18, 2024

jeff41404 commented May 20, 2024

Update 20240518

SigureMo commented May 20, 2024

megemini commented May 20, 2024


		## 1、相关背景

		Python 在 3.5 版本通过 [PEP 484 – Type Hints](https://peps.python.org/pep-0484) 正式规范了 `类型提示` 功能，以帮助开发者提高代码质量，Python 目前 (`3.12` 版本) 已经完成的相关 `PEP` 有 `11` 个，具体可以参考 [Typing PEPs](https://peps.python.org/topic/typing/) 。经过前期的几个版本迭代，Python 的 `类型提示` 功能已经受到开发者的广泛认可。Paddle 目前支持的 Python 版本 `3.8` 已经可以较好的支持 `类型提示`，本文旨在阐述 Paddle 引入 `类型提示` 的可行性与具体方案。


		## 2、功能目标

		正确完成 Paddle 开放 API 的类型标注，但不声明 Paddle 类型标注的完备性。

	正确完成 Paddle 开放 API 的类型标注，但不声明 Paddle 类型标注的完备性。
	正确完成 Paddle 公开 API 的类型标注，但不声明 Paddle 类型标注的完备性。


		### 2.1 typing 模块

		此目标为 Paddle 添加 `typing` 模块，并作为开放 API 的一部分。


		> 说明：类型标注是个循序渐进的过程，且存在较多私有 API 与 c++ 接口，此次任务无法保证完成以上所有接口的类型标注，故此，不做 Paddle 类型标注的完备性说明。

		### 2.1 _typing 模块

	`_typing` 模块包含 Paddle 中用到的特殊类型，如 `dtype`，`device` 等，具体实现可参考 @SigureMo 的 [paddle-stubs/_typing](https://github.com/cattidea/paddlepaddle-stubs/tree/main/paddle-stubs/_typing)。
	`_typing` 模块包含 Paddle 中用到的特殊类型，如 `dtype`、`device` 等，具体实现可参考 @SigureMo 的 [paddle-stubs/_typing](https://github.com/cattidea/paddlepaddle-stubs/tree/main/paddle-stubs/_typing)。


		1. Paddle 中引入 `_typing` 模块

		对用户的影响：用户可以使用 `_typing` 模块提供的接口


		对开发者的影响：开发者可以使用 `_typing` 模块标注 Paddle 内部模块

		对框架架构的影响： Paddle 框架中增加 `_typing` 模块与相应接口

	对框架架构的影响： Paddle 框架中增加 `_typing` 模块与相应接口
	对框架架构的影响： Paddle 框架中增加 `_typing` 模块

【Hackathon 6th】为 Paddle 框架 API 添加类型提示（Type Hints） #858

【Hackathon 6th】为 Paddle 框架 API 添加类型提示（Type Hints） #858

Conversation

megemini commented Apr 8, 2024

PR types

PR changes

Description

paddle-bot bot commented Apr 8, 2024

megemini commented Apr 10, 2024

gsq7474741 commented Apr 12, 2024

SigureMo left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

megemini commented Apr 14, 2024

SigureMo commented Apr 14, 2024

megemini commented Apr 14, 2024

Update 20240414

SigureMo left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

megemini commented Apr 15, 2024

luotao1 commented May 17, 2024

megemini commented May 18, 2024

Update 20240518

jeff41404 commented May 20, 2024

Update 20240518

SigureMo commented May 20, 2024

megemini commented May 20, 2024