[Typing] Rewrite type annotations specification #6836
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
感谢你贡献飞桨文档，文档预览构建中，Docs-New 跑完后即可预览，预览链接：http://preview-pr-6836.paddle-docs-preview.paddlepaddle.org.cn/documentation/docs/zh/api/index_cn.html |
megemini
reviewed
Aug 18, 2024
docs/dev_guides/style_guide_and_references/type_annotations_specification_cn.md
Outdated
Show resolved
Hide resolved
docs/dev_guides/style_guide_and_references/type_annotations_specification_cn.md
Show resolved
Hide resolved
Comment on lines
+9
to
+11
| ## 类型提示标注范围 | ||
|
|
||
| Paddle 是一个大型开源项目，包含了数十万行的 Python 代码，不乏有历史悠久的代码，为全部函数都标注类型提示是不可取的，也是不现实的。因此，我们需要明确界定哪些代码是需要标注类型提示的，哪些代码是不需要标注类型提示的。 |
There was a problem hiding this comment.
是否加一个，如何界定公开与非公开 API ～ 类？函数？枚举？类中的公开方法、私有方法、魔法方法？
There was a problem hiding this comment.
这个我觉得不应该在这里说明，这应该是 开发 API Python 端 的事情
docs/dev_guides/style_guide_and_references/type_annotations_specification_cn.md
Show resolved
Hide resolved
docs/dev_guides/style_guide_and_references/type_annotations_specification_cn.md
Outdated
Show resolved
Hide resolved
docs/dev_guides/style_guide_and_references/type_annotations_specification_cn.md
Outdated
Show resolved
Hide resolved
docs/dev_guides/style_guide_and_references/type_annotations_specification_cn.md
Outdated
Show resolved
Hide resolved
Comment on lines
+175
to
+184
| from typing import TypedDict | ||
|
|
||
| class SaveOptions(TypedDict): | ||
| path: str | ||
| id: int | ||
|
|
||
| def save(options: SaveOptions) -> None: ... | ||
| ``` | ||
|
|
||
| 这样的类型提示不仅能够提示 `options` 是一个字典，还能够提示 `options` 的键值对的类型，这会带来如下几点优点： |
There was a problem hiding this comment.
能不能加一个 TypedDict, total=False 的例子？total=False 的情况更多，之前基本都是用 NotRequired ，感觉太繁琐了 ... ...
There was a problem hiding this comment.
这个我单拉一个对 kwargs 标注的主题来说明，不然会使得这里篇幅过多，抓不到重点
对，这个和代码风格指南是同等地位的，在检查失败时应该引导参考本指南 |
…ecification_cn.md Co-authored-by: megemini <megemini@outlook.com>
16 tasks
Aoraki-Dream
pushed a commit
to Aoraki-Dream/docs
that referenced
this pull request
Sep 4, 2024
--------- Co-authored-by: megemini <megemini@outlook.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
明确类型提示标注规范内容，为其他开发者提供参考
最佳实践大多数内容是通用的，并不仅限于 Paddle，对于非 Paddle 框架开发也有参考价值
preview link: http://preview-pr-6836.paddle-docs-preview.paddlepaddle.org.cn/documentation/docs/zh/dev_guides/style_guide_and_references/type_annotations_specification_cn.html
@megemini @zrr1999 @gouzil @sunzhongkai588