📚 PaddleSOT 源码阅读 CRC 快乐喵喵之路 🎉

[Aurelius84]

一、Background 📚

自6月初 PaddleSOT 第一次与各位小伙伴完成技术分享和讨论之后，发布了PaddleSOT 快乐喵喵开源任务，真切感受到了小伙伴们的热情，也陆续收到了 @zrr1999 、@gouzil、@Difers、@GreatV、@NotHaozi 等同学贡献的 PR 👏🏻。

二、Motivation 🚀

为了进一步营造 PaddleSOT 快乐开源的的社区氛围，与各位小伙伴们一同学习、成长，我们计划开启「新·篇章」，即 PaddleSOT 源码阅读 Code Reading and Comment （简称 CRC）快乐喵喵之路。

在这里，小伙伴们可以一起阅读 PaddleSOT 的源码，并鼓励提出自己的疑惑到 Disscussions ，我们会不定期组织答疑分享。我们将以 「✏️ CRC 代码标注赛 ✏️」 的形式来组织：

• 「源码研读」依照自己的兴趣选择某个模块深入研读源码实现 🧐
• 「提出疑惑」在 Code Reading 过程中遇到任何问题可以发布到 Disscussion 🙌
• 「思考沉淀」可以在源码文件里的 Class 或者 Funciton 下贡献自己的「理解注释」，欢迎提交 PR 给 PaddleSOT 🤩

通过 「CRC 快乐喵喵之路」，小伙伴可以：

• 「Committer 资格」对于贡献质量优秀 Comment 的小伙伴，可以获得百度 PaddlePaddle 组织的 Committer 资格 👸🏻，详见飞桨框架代码仓库的角色及权限介绍
• 「飞桨 架构机制」PaddleSOT 是纯 Python 实现，可以由浅入深地了解 Python 底层数据结构以及虚拟机 VM 执行流程，以及 PaddlePaddle 的动态图转静态图的机制

三、 CRC Tasks 🙋🏻‍♀️ （整体进展：37/37）

排名不分先后：@sanbuphy (3) @zrr1999 (6) @jjyaoao (3) @gouzil (10) @GreatV (4) @ccsuzzh (3) @enkilee (3) @Difers (2) @RedContritio (3)

注：

• 部分序号任务可能涉及多个数据结构，可以拆分为多个 PR 提交
• 【重要】docs/design目录有一些核心数据结构设计相关的文档，可以参考。

序号	类别	名称	难度	认领人	提交 PR
1	✅ Function	eval_frame_callback	简单	@sanbuphy	#226
2	✅ Class	InstructionTranslatorCache	中等	@zrr1999	#212
3	✅ Class	Tracker/Dummy/Dangling(tracker.py)	中等	@jjyaoao	#196
4	✅ Class	Dispatcher 相关类	困难	@gouzil	#193
5	✅ Method	FunctionGraph 相关函数	中等	@gouzil	#234
6	✅ Function	make_guard	简单	@gouzil	#293
7	✅ Class	OpcodeExecutorBase	中等	@zrr1999	#212
8	✅ Class	OpcodeExecutor	中等	@zrr1999	#212
9	✅ Class	OpcodeInlineExecutor	中等	@zrr1999	#225
10	✅ Class	VariableBase相关（base.py）	中等	@zrr1999	#205
11	✅Class	PyCodeGen	中等	@zrr1999	#295
12	✅ Function	view_tracker	简单	@GreatV	#192
13	✅ Function	get_instructions	简单	@GreatV	#202
14	✅ Function	modify_instrs 等	简单	@sanbuphy	#227
15	✅ Function	analysis_inputs	中等	@sanbuphy	#228
16	✅ Function	need_skip_path	中等	@gouzil	#189
17	✅ Class	FallbackWrapper	简单	@gouzil	#277
18	✅ Class	CompileSIRCache	简单	@gouzil	#277
20	✅ Class	Interpreter	中等	@GreatV	#223
21	✅ Function	compile_sir	简单	@gouzil	#189
22	✅ Class	Symbol	简单	@GreatV	#223
23	✅ Class	Statement	简单	@ccsuzzh	#211
24	✅ Class	StatementIR	简单	@ccsuzzh	#211
25	✅ Class	StatementIRFactory	简单	@ccsuzzh	#211
26	✅Class	SIRRuntimeCache	简单	@gouzil	#298
27	✅Class	SymbolicTraceContext	中等	@gouzil	#297
28	✅ Class	VariableCreator	简单	@enkilee	#191
29	✅ Class	SpecialInferMeta	简单	@enkilee	#191
30	✅ Function	symbolic_translate	简单	@enkilee	#191
31	✅ Class	Constant/Tensor/Object/Slice(basic.py)	中等	@Difers	#206
32	✅ Class	Module/DygraphTracer/Numpy/Dummy(basic.py）)	中等	@Difers	#206
33	✅ Class	Callable/Function/UDFunction/PaddleAPI(callable.py)	中等	@RedContritio	#296, #313
34	✅ Class	TensorFunction/Method/Layer/UDLayer(callable.py)	中等	@RedContritio	#296, #314
35	✅ Class	Builtin/UDGenerator/PaddleLayer(callable.py)	中等	@RedContritio	#296, #315
36	✅ Class	Container/List/Tuple/Dict（container.py）	中等	@gouzil	#302
37	✅ Class	Local/Global/Builtin(tracker.py)	中等	@jjyaoao	#196
38	✅ Class	Const/GetAttr/Item/Iter(tracker.py)	中等	@jjyaoao	#196

四、Comment 规范 🌲

4.1 Class 的注释

对于核心模块的 Class ，一般可以考虑从如下几个维度来添加注解：

class MyClass:
   """
   {类的作用、或角色。一般2~3句英文表述。}

   {类的设计原理，或设计的背景、技术考虑（可选），无句数限制}

   {类的特别标注，即 NOTE: (可选)}
   """

如下是框架的一个参考样例：

class Program:
    """
    Create Python Program.  It has at least one :ref:`api_guide_Block_en`, when the
    control flow op like conditional_block, while :ref:`api_paddle_fluid_layers_While` is included,
    it will contain nested block.

    Please reference the
    `framework.proto <https://github.com/PaddlePaddle/Paddle/blob/develop/paddle/fluid/framework/framework.proto>`_
    for details.

    A set of Program usually contains startup program and main program.
    A startup program is set to contain some initial work, eg. initialize the ``Parameter``, and the main
    program will contain the network structure and vars for train.

    A set of Program can be used for test or train, in train program ,
    Paddle will contain all content to build a train network,  in test
    program Paddle will prune some content which is irrelevant to test, eg.
    backward ops and vars.

    **Notes**:
        **we have** :ref:`api_paddle_fluid_framework_default_startup_program` **and** :ref:`api_paddle_fluid_framework_default_main_program`
        **by default, a pair of them will shared the parameters. The** :ref:`api_paddle_fluid_framework_default_startup_program` **only run once to initialize parameters,**
        :ref:`api_paddle_fluid_framework_default_main_program` **run in every mini batch and adjust the weights.**
    """

4.2 函数的注释

对于核心模块的Function 或者类的 method，一般从如下几个维度来添加注释：

def my_function(x, y):
    """
    {函数的作用、或角色。一般2~3句表述}

    {类的特别标注，即 NOTE: (可选)}

    {Returns 类型标注}
    """

如下是框架的一个参考样例：

    def prune_with_input(self, feeded_var_names, targets):
        """
        Prune operators and variables which are not needed to generate
        :code:`targets`. Prune operators and variables which are needed
        to generate feeded_var

        Notes: This is a very low level API. Users should not use this API
        directly. This API is in flux and not stable.

        Args:
            feeded_var_names(list|str): A list of variable names from where
                pruning start. If it is set as [], this API works just like _prune()
            targets(list|Variable|Operator): A list of variables, operators, or variable names
                need to be pruned

        Returns:
            Program:  A new, pruned program.
        """

4.3 类型提示

我们代码里已经包含了大量的类型提示，但是部分早期的代码类型提示信息仍然不完整，因此希望在完善注释的同时完善类型提示信息：

- def foo(x, y):
+ def foo(x: str, y: list[int]) -> bool:
      ...

应当注意仅类型提示的第一方模块在引用时应尽可能放在 if TYPE_CHECKING: 下，以消除运行时影响，降低循环依赖的可能性，比如：

PaddleSOT/sot/opcode_translator/executor/opcode_inline_executor.py

Lines 13 to 15 in d0ede5e

	if TYPE_CHECKING:
	from .pycode_generator import PyCodeGen
	from .variables import FunctionVariable

如非必要应当尽可能使用 list 等容器类型而非 List，使用不带引号的类别名而非带引号的类别名：

+ from __future__ import annotations # enable PEP 563 Postponed Evaluation of Annotations

- from typing import List, Dict
- def foo(x: List[int], Dict[str, int]) -> "Bar":
+ def foo(x: list[int], dict[str, int]) -> Bar:
      ...

  class Bar:
      ...

详情可参考 typing docs、PEP 484

Note

• 相关 PR 标题请以 [CRC] 作为前缀
• 相关 PR 描述请链接本 PR #186
• 关于文档规范，详情可参考 API 文档书写规范，如上述示例与该规范有冲突，以该规范为准

[sanbuphy]

认领 1、14、15

[enkilee]

28 29 30

[gouzil]

认领21、16

[ccsuzzh]

认领 23 24 25

[mrcangye]

认领6.11

[mrcangye]

认领26

[zrr1999]

认领7-10

[zrr1999]

认领11

[gouzil]

认领36

[SigureMo]

PaddleSOT 源码阅读 CRC 快乐喵喵之路任务已全部完成，感谢参与的小喵喵们！（就夹带私货）

按完成时间顺序，排名不分先后： @sanbuphy (3) @zrr1999 (6) @jjyaoao (3) @gouzil (10) @GreatV (4) @ccsuzzh (3) @enkilee (3) @Difers (2) @RedContritio (3)

欢迎继续参与快乐开源的其他任务！