【Hackathon 6th Fundable Projects 1 1-1】Add _typing module to paddle

[Asthestarsfalll]

PR Category

Others

PR Types

New features

Description

大部分般自paddlepaddle-stubs

添加一些常用的以及可能会用到的，如Size1 Shape1D，名称可能还需要再考虑一下；后面还需要调研一下paddle内比较常用的类型提示有哪些

测试结果：

[paddle-bot[bot]]

你的PR提交成功，感谢你对开源项目的贡献! 请关注后续CI自动化测试结果，详情请参考Paddle-CI手册。 Your PR has been submitted. Thanks for your contribution! Please wait for the result of CI firstly. See Paddle CI Manual for details.

[megemini]

注意一下与 paddlepaddle-stubs 不同的是，这里使用 .py 定义，所定义出来的是新的类型，是可能和运行时的类型混淆的（运行时真的有两个不同的 class），需要保证用户使用原有的类型时也是可以的，以及，用户一旦不小心使用了这里的 class 构造了运行时可访问的对象怎么办呢？

比如这里定义了 paddle._typing.dtype，如何保证它和 paddle.dtype（paddle.base.core.DataType）是一样的呢？最佳方式是为 paddle.base.core.DataType 提供 stub file，使其从根本上保持一致

Tensor 等 pybind 数据结构一样，都可以这样考虑

@megemini 觉得呢？

对！大原则参考 RFC 里面说的：

• 非 Python 接口，提供 stub 标注文件
• Python 接口，使用 inline 方式标注

可以这么想，_typing.xxx.py 里面不应该出现 旧 的东西，比如 class dtype ... ，因为，已经有 paddle.dtype 了，如果目前就做静态类型检查，工具是可以检查出 paddle.dtype 的 ～

旧 的东西应该在 pyi 这类 stub 文件里面，需要做的应该有两件事：

• 一对一把接口搬过来，并且做类型标注，比如 Tensor.cast 这类方法
• 补充 docstring，因为 pybind 的接口没法在静态检查的时候提示 docstring

我们无法直接标注 pybind 的接口，并且，目前的检查工具没法提示这类东西的 docstring，因此，需要我们补充 stub ～ 而 paddle.dtype 里面的 DataType 我觉得可以不做，因为，这个东西本身可以当作一个 类，而他的 docstring 没有啥具体作用 (print(paddle.dtype.FP16.__doc__) 没啥东西 ～)。相应的，不需要 _typing 里面增加 dtype 这个类，如果没有 docstring 的需要，那么 paddle.base.core.DataType 的 stub file 也不需要 ～

至于这个 _typing.dtype.py，感觉应该是 _typing._dtype_like.py ，可以参考 numpy 的 numpy/_typing/_dtype_like.py 。这里面只需要增加 Paddle 原来没有的东西，比如 _DTypeLiteral。另外，numpy 有个 numpy/numpy/_typing/_shape.py，这里就不是 _xxx_like.py ，而是 _xxx.py ，因为 numpy 原来没有 shape 这类的东西，因此需要补充，是全 新 的，可以体会一下 _xxx_like.py 和 _xxx.py 的区别 ～

@SigureMo @Asthestarsfalll 帮忙看看这个思路有没有问题?

[megemini]

@Asthestarsfalll 另外，这个任务需要补充 _typing 的测试用例和测试脚本哈 ～ 另起 PR 吗？

[SigureMo]

如果没有 docstring 的需要，那么 paddle.base.core.DataType 的 stub file 也不需要 ～

这个我没有太理解，stub file 更主要提供的是类型信息，docstring 则是次要的，为什么没有 docstring 的需要就可以不用 stub file 了呢？

其实根据 typeshed 的规范^1，stub file 不应该写 docstring 的，当然，这个在社区里也有争议，但这里以是否有 docstring 来评判是否加 stub file 我觉得是颠倒主次关系的

其余感觉没啥问题的～

[megemini]

如果没有 docstring 的需要，那么 paddle.base.core.DataType 的 stub file 也不需要 ～

这个我没有太理解，stub file 更主要提供的是类型信息，docstring 则是次要的，为什么没有 docstring 的需要就可以不用 stub file 了呢？

我的表述有问题 ～～～ 是说这个 DataType 可能不需要 ～ 刚才试了，还是要加！

• 添加 paddle/framework/dtype.pyi

  from enum import Enum
  
  class dtype(Enum):
      FP16 = ...
  

• 添加 paddle/__init__.pyi

  from .framework.dtype import dtype
  __all__ = [
      "dtype",
  ]
  

• 添加 py.typed

再使用 mypy 检查：

import paddle

a = paddle.dtype.FP16
reveal_type(a)

mypy 的输出：

note: Revealed type is "paddle.framework.dtype.dtype"

paddle.dtype 跟 paddle.framework.dtype.dtype 是一个东西，应该没啥问题 ～

这里有两个问题：

• class dtype(Enum): FP16 = ... 这样写行不？还需要把 FP16 也作为单独类？
• 是不是可以在这个 PR 把 dtype.pyi 先加进去，paddle.__init__.pyi 放到后面任务一起加进去？不然，如果 paddle.__init__.pyi 不完整，会影响目前打包的提示功能 ～

其实根据 typeshed 的规范1，stub file 不应该写 docstring 的，当然，这个在社区里也有争议，但这里以是否有 docstring 来评判是否加 stub file 我觉得是颠倒主次关系的

其余感觉没啥问题的～

pybind 的接口如果用了 stub，好像必须得把 docstring 加进去，不然 vscode 我试了，貌似 docstring 的提示就没了?

@SigureMo

[SigureMo]

pybind 的接口如果用了 stub，好像必须得把 docstring 加进去，不然 vscode 我试了，貌似 docstring 的提示就没了?

这是没问题的，因为 pybind API 的 docstring 是运行时才能获取的，VS Code（pylance）当然拿不到

我只是用来佐证「但这里以是否有 docstring 来评判是否加 stub file 我觉得是颠倒主次关系的」哈，没说我们不加，而且我们也会「优先」加 type annotation 而不是 docstring，这是这个任务 title 决定的

paddle.dtype 跟 paddle.framework.dtype.dtype 是一个东西，应该没啥问题 ～

可以看看有没有可能让显示也是 paddle.dtype，会让用户看起来更友好些

开发时可以打开 inlay hints，调试会更方便些

class dtype(Enum): FP16 = ... 这样写行不？还需要把 FP16 也作为单独类？

应该没问题吧……可以试试直接枚举值就是 float16 这种么？FP16 是不暴露给用户侧的

[Asthestarsfalll]

• 补充 docstring，因为 pybind 的接口没法在静态检查的时候提示 docstring

我们无法直接标注 pybind 的接口，并且，目前的检查工具没法提示这类东西的 docstring，因此，需要我们补充 stub ～ 而 paddle.dtype 里面的 DataType 我觉得可以不做，因为，这个东西本身可以当作一个 类，而他的 docstring 没有啥具体作用 (print(paddle.dtype.FP16.__doc__) 没啥东西 ～)。

这里同意

相应的，不需要 _typing 里面增加 dtype 这个类，如果没有 docstring 的需要，那么 paddle.base.core.DataType 的 stub file 也不需要 ～

不加stub的话，我这里类型提示会为unknown

至于这个 _typing.dtype.py，感觉应该是 _typing._dtype_like.py ，可以参考 numpy 的 numpy/_typing/_dtype_like.py 。这里面只需要增加 Paddle 原来没有的东西，比如 _DTypeLiteral。另外，numpy 有个 numpy/numpy/_typing/_shape.py，这里就不是 _xxx_like.py ，而是 _xxx.py ，因为 numpy 原来没有 shape 这类的东西，因此需要补充，是全 新 的，可以体会一下 _xxx_like.py 和 _xxx.py 的区别 ～

这里我明天看下numpy的类型

[Asthestarsfalll]

@Asthestarsfalll 另外，这个任务需要补充 _typing 的测试用例和测试脚本哈 ～ 另起 PR 吗？

想先确定好具体实现，后续再添加

[Asthestarsfalll]

paddle.dtype 跟 paddle.framework.dtype.dtype 是一个东西，应该没啥问题 ～

可以看看有没有可能让显示也是 paddle.dtype，会让用户看起来更友好些

按照这种方法，我这里直接显示 dtype

[Asthestarsfalll]

[paddle-ci-bot[bot]]

Sorry to inform you that dd9e04e's CIs have passed for more than 7 days. To prevent PR conflicts, you need to re-run all CIs manually.

[SigureMo]

test_type_hints.py CI 中没有测试到，应该也需要配置一下 ～

需要配置 CMakeLists.txt 才可以跑，不过我之前说的是确保「运行时」没问题，其实按照上面说的加一个 from . import _typing as _typing 就能测到了，不需要加这些「静态检查」单测，按照之前 RFC 讨论，我们使用示例代码保证静态检查，不再额外设置类型提示单测

因此本 PR 就不涉及 mypy 的添加什么的吧，相关内容不要做重了，mypy 在 #63901 考虑

尤其是 setup

setup.py 我没什么使用经验，我大多使用的是基于 PEP 517 pyproject.toml 的现代化打包方式，这个的话只有测试验证才知道是否可行，如果打包后发现 wheel 包里确实有这些文件，就没问题

[Asthestarsfalll]

@megemini @SigureMo 更新了一下：

• 先移除了测试相关代码，如有需要后续添加
• 添加了 from . import _typing as _typing
• 添加了 framework/init.pyi
• 在setup.py里添加了相关打包内容，但是我编译后安装并没有打包成功

[megemini]

• 添加了 framework/init.pyi

可以不用添加这个吧？ paddle.__init__.py 里面已经有了 ～

• 在setup.py里添加了相关打包内容，但是我编译后安装并没有打包成功

有两个地方要改，

• python/setup.py.in
• setup.py

https://github.com/PaddlePaddle/Paddle/pull/63901

[SigureMo]

我来改一下这个 PR，尽快推动本 PR 合入，以免阻塞整个项目进度

[megemini]

我来改一下这个 PR，尽快推动本 PR 合入，以免阻塞整个项目进度

还有 https://github.com/PaddlePaddle/Paddle/pull/63953 没 review，是不是漏掉了 😂

[SigureMo]

还有 https://github.com/PaddlePaddle/Paddle/pull/63953 没 review，是不是漏掉了 😂

没有哈，现在注意力在这俩上