Python 文档示例代码书写规范

显式的输出优于注释

请尽量将用户可能关注的输出，如变量的值、Tensor 的 shape 等，书写或拷贝至示例中。

可以使用 print 输出结果，如：

>>> import paddle
>>> x = paddle.to_tensor([[1, 2], [3, 4]])
>>> y = paddle.to_tensor([[5, 6], [7, 8]])
>>> res = paddle.multiply(x, y)
>>> print(res)
Tensor(shape=[2, 2], dtype=int64, place=Place(cpu), stop_gradient=True,
[[5 , 12],
 [21, 32]])

如无特殊情况，请勿使用 # 的注释方式提供输出值。

如：

>>> res = paddle.multiply(x, y) # shape=[2, 2]

>>> res = paddle.multiply(x, y)
>>> # [[5 , 12],
>>> #  [21, 32]]

等，都是不建议的输出方式。

另外，在书写或拷贝示例代码时，请注意以下几点：

• 输出中请 不要 留有空行。

  如：

  >>> import paddle
  >>> x = paddle.to_tensor([[1, 2], [3, 4]])
  >>> y = paddle.to_tensor([[5, 6], [7, 8]])
  >>> res = paddle.multiply(x, y)
  >>> print(res)
  Tensor(shape=[2, 2], dtype=int64, place=Place(cpu), stop_gradient=True,
  [[5 , 12],
  
  [21, 32]])
  

  请改为：

  >>> import paddle
  >>> x = paddle.to_tensor([[1, 2], [3, 4]])
  >>> y = paddle.to_tensor([[5, 6], [7, 8]])
  >>> res = paddle.multiply(x, y)
  >>> print(res)
  Tensor(shape=[2, 2], dtype=int64, place=Place(cpu), stop_gradient=True,
  [[5 , 12],
   [21, 32]])
  

  对于代码中的多行或复合语句，也 不要 留有空行。

  如：

  >>> class Mnist(nn.Layer):
  ...     def __init__(self):
  
  ...         super().__init__()
  ...
  

  请改为：

  >>> class Mnist(nn.Layer):
  ...     def __init__(self):
  ...
  ...         super().__init__()
  ...
  

  或者：

  >>> class Mnist(nn.Layer):
  ...     def __init__(self):
  ...         super().__init__()
  ...
  

• 输出请统一 左对齐 其上方的 >>> 或 ... 。

  如：

  >>> import paddle
  >>> x = paddle.to_tensor([[1, 2], [3, 4]])
  >>> y = paddle.to_tensor([[5, 6], [7, 8]])
  >>> res = paddle.multiply(x, y)
  >>> print(res)
      Tensor(shape=[2, 2], dtype=int64, place=Place(cpu), stop_gradient=True,
      [[5 , 12],
      [21, 32]])
  

  请改为：

  >>> import paddle
  >>> x = paddle.to_tensor([[1, 2], [3, 4]])
  >>> y = paddle.to_tensor([[5, 6], [7, 8]])
  >>> res = paddle.multiply(x, y)
  >>> print(res)
  Tensor(shape=[2, 2], dtype=int64, place=Place(cpu), stop_gradient=True,
  [[5 , 12],
   [21, 32]])
  

• 适度的空格用于美化输出是允许的。

  如：

  >>> import paddle
  >>> x = paddle.to_tensor([[1, 2], [3, 4]])
  >>> y = paddle.to_tensor([[5, 6], [7, 8]])
  >>> res = paddle.multiply(x, y)
  >>> print(res)
  Tensor(shape=[2, 2], dtype=int64, place=Place(cpu), stop_gradient=True,
  [[5 , 12],
  [21, 32]])
  

  可以对齐其中的方括号为：

  >>> import paddle
  >>> x = paddle.to_tensor([[1, 2], [3, 4]])
  >>> y = paddle.to_tensor([[5, 6], [7, 8]])
  >>> res = paddle.multiply(x, y)
  >>> print(res)
  Tensor(shape=[2, 2], dtype=int64, place=Place(cpu), stop_gradient=True,
  [[5 , 12],
   [21, 32]])
  

• 对于多行的输出，可以使用 ... 作为通配符使用。

  如：

  >>> sampler = MySampler(data_source=RandomDataset(100))
  >>> for index in sampler:
  ...     print(index)
  0
  1
  2
  ...
  99
  

固定的输出优于随机

请尽量保证输出为固定值，对于示例中的随机情况，请设置随机种子。

如：

>>> import paddle
>>> paddle.seed(2023)
>>> data = paddle.rand(shape=[2, 3])
>>> print(data)
Tensor(shape=[2, 3], dtype=float32, place=Place(cpu), stop_gradient=True,
[[0.86583614, 0.52014720, 0.25960937],
 [0.90525323, 0.42400089, 0.40641287]])

如果示例中涉及 Python、Numpy 随机数等情况，也需要进行随机种子的设置。

明确的设备优于默认

由于 Tensor 在 CPU、GPU 等设备上面的行为可能不同，请写明具体的设备需求。

如：

>>> # doctest: +REQUIRES(env:GPU)
>>> import paddle
>>> paddle.device.set_device('gpu')
>>> count = paddle.device.cuda.device_count()
>>> print(count)
1

其中：

• 第 1 行是 doctest 检查指令。

• 第 3 行是设备的设置。

CI 中默认使用 CPU 作为检查环境，因此，如无特殊情况，可以 不用 写明 CPU 环境，如：

>>> paddle.device.set_device('cpu') # 可以不写

另外，对于有 GPU、XPU 等设备需求的情况，需要在代码开头添加 doctest 指令，如：

• 需要 GPU 环境

  >>> # doctest: +REQUIRES(env:GPU)
  >>> ...
  

• 需要 XPU 环境

  >>> # doctest: +REQUIRES(env:XPU)
  >>> ...
  

• 需要 GPU、XPU 等多个环境

  >>> # doctest: +REQUIRES(env:GPU, env:XPU)
  >>> ...
  

请注意这里的 大小写 ，其中 doctest 为小写，REQUIRES 为大写，env 为小写，GPU 为大写。

尝试去检查优于跳过

示例代码的检查可以保证其正确性，但并不是所有代码均能够正常或正确的在 CI 环境中运行。

如：

• 依赖外部资源才能运行，如 image、audio 等文件。

• 代码的随机性由系统决定，如 os.walk 等方法。

• 代码不能在 CI 中正常运行，如 inspect.getsourcelines 会抛出 raise OSError('could not get source code')

等情况，此时，可以使用 doctest 的 SKIP 指令跳过检查，如：

>>> # doctest: +SKIP('file not exist')
>>> with open('cat.jpg') as f:
...     im = load_image_bytes(f.read())

SKIP 指令还可以成对使用，如：

>>> # doctest: +SKIP('file not exist')
>>> with open('cat.jpg') as f:
...     im = load_image_bytes(f.read())
>>> # doctest: -SKIP
>>> x = paddle.to_tensor([[1, 2], [3, 4]])
>>> ...

其中，

• +SKIP 表示后面的代码要跳过，-SKIP 表示恢复检查。

• +SKIP 可以加上说明，如 +SKIP('file not exist')

TIMEOUT 指令

directive       ::=  "# doctest: +TIMEOUT(" time ")"
time            ::=  nonzerodigit (digit)*
nonzerodigit    ::=  "1"..."9"
digit           ::=  "0"..."9"

>>> from paddle.vision.datasets import VOC2012
>>> voc2012 = VOC2012()

>>> # doctest: +TIMEOUT(60)
>>> from paddle.vision.datasets import VOC2012
>>> voc2012 = VOC2012()

SOLO 指令

directive       ::=  "# doctest: +SOLO(" reason ")"
reason          ::=  "'" shortstringchar+ "'" | '"' shortstringchar+ '"'
shortstringchar ::=  <any source character except "\" or newline or the quote>

>>> import multiprocessing
>>> p = multiprocessing.Process(
...     target=lambda a, b: a + b,
...     args=(1, 2),
... )
>>> p.start()
>>> p.join()

>>> # doctest: +SOLO('can not use add in multiprocessing')
>>> import multiprocessing
>>> p = multiprocessing.Process(
...     target=lambda a, b: a + b,
...     args=(1, 2),
... )
>>> p.start()
>>> p.join()