diff --git a/docs/api/paddle/cummax_cn.rst b/docs/api/paddle/cummax_cn.rst index 42536081c56..e9b8c00c6ce 100644 --- a/docs/api/paddle/cummax_cn.rst +++ b/docs/api/paddle/cummax_cn.rst @@ -3,23 +3,35 @@ cummax ------------------------------- -.. py:function:: paddle.cummax(x, axis=None, dtype='int64', name=None) +.. py:function:: paddle.cummax(x, axis=None, dtype='int64', name=None, *, out=None) 沿给定 ``axis`` 计算 Tensor ``x`` 的累积最大值。 +本 API 支持两种调用方式: + +1. **Paddle 风格**: ``paddle.cummax(x, axis=None, dtype='int64', name=None)`` + ``axis`` 参数可选,默认为 ``None``。 + +2. **PyTorch 风格**: ``paddle.cummax(input, dim, *, out=None)`` + ``dim`` 参数必选。参数名 ``input`` 是 ``x`` 的别名,``dim`` 是 ``axis`` 的别名。 + .. note:: 结果的第一个元素和输入的第一个元素相同。 参数 :::::::::: - - **x** (Tensor) - 需要进行累积最大值操作的 Tensor。 - - **axis** (int,可选) - 指明需要累积最大值的维度。-1 代表最后一维。默认:None,将输入展开为一维变量再进行累积最大值计算。 + - **x** (Tensor) - 需要进行累积最大值操作的 Tensor。别名 ``input``。 + - **axis** (int,可选) - 指明需要累积最大值的维度。-1 代表最后一维。默认:None,将输入展开为一维变量再进行累积最大值计算。别名 ``dim``。 - **dtype** (str|paddle.dtype|np.dtype,可选) - 输出 Indices 的数据类型,可以是 int32、int64,默认值为 int64。 - **name** (str,可选) - 具体用法请参见 :ref:`api_guide_Name` ,一般无需设置,默认值为 None。 +关键字参数 +:::::::::: + - **out** (tuple[Tensor, Tensor],可选) - 输出 Tensor 元组,包含两个 Tensor (values, indices)。若不为 ``None``,计算结果将保存在该 Tensor 元组中,默认值为 ``None``。 + 返回 :::::::::: - - ``out`` (Tensor):返回累积最大值操作的结果,累积最大值结果类型和输入 x 相同。 + - ``values`` (Tensor):返回累积最大值操作的结果,累积最大值结果类型和输入 x 相同。 - ``indices`` (Tensor):返回对应累积最大值操作的索引结果。 代码示例 diff --git a/docs/api/paddle/cummin_cn.rst b/docs/api/paddle/cummin_cn.rst index 9590aa836ff..a4e67a67a9d 100644 --- a/docs/api/paddle/cummin_cn.rst +++ b/docs/api/paddle/cummin_cn.rst @@ -3,23 +3,35 @@ cummin ------------------------------- -.. py:function:: paddle.cummin(x, axis=None, dtype='int64', name=None) +.. py:function:: paddle.cummin(x, axis=None, dtype='int64', name=None, *, out=None) 沿给定 ``axis`` 计算 Tensor ``x`` 的累积最小值。 +本 API 支持两种调用方式: + +1. **Paddle 风格**: ``paddle.cummin(x, axis=None, dtype='int64', name=None)`` + ``axis`` 参数可选,默认为 ``None``。 + +2. **PyTorch 风格**: ``paddle.cummin(input, dim, *, out=None)`` + ``dim`` 参数必选。参数名 ``input`` 是 ``x`` 的别名,``dim`` 是 ``axis`` 的别名。 + .. note:: 结果的第一个元素和输入的第一个元素相同。 参数 :::::::::: - - **x** (Tensor) - 需要进行累积最小值操作的 Tensor。 - - **axis** (int,可选) - 指明需要累积最小值的维度。-1 代表最后一维。默认:None,将输入展开为一维变量再进行累积最小值计算。 + - **x** (Tensor) - 需要进行累积最小值操作的 Tensor。别名 ``input``。 + - **axis** (int,可选) - 指明需要累积最小值的维度。-1 代表最后一维。默认:None,将输入展开为一维变量再进行累积最小值计算。别名 ``dim``。 - **dtype** (str|paddle.dtype|np.dtype,可选) - 输出 Indices 的数据类型,可以是 int32、int64,默认值为 int64。 - **name** (str,可选) - 具体用法请参见 :ref:`api_guide_Name` ,一般无需设置,默认值为 None。 +关键字参数 +:::::::::: + - **out** (tuple[Tensor, Tensor],可选) - 输出 Tensor 元组,包含两个 Tensor (values, indices)。若不为 ``None``,计算结果将保存在该 Tensor 元组中,默认值为 ``None``。 + 返回 :::::::::: - - ``out`` (Tensor):返回累积最小值操作的结果,累积最小值结果类型和输入 x 相同。 + - ``values`` (Tensor):返回累积最小值操作的结果,累积最小值结果类型和输入 x 相同。 - ``indices`` (Tensor):返回对应累积最小值操作的索引结果。 代码示例 diff --git a/docs/api/paddle/diagflat_cn.rst b/docs/api/paddle/diagflat_cn.rst index f9d8d61066e..0bd56513fc8 100644 --- a/docs/api/paddle/diagflat_cn.rst +++ b/docs/api/paddle/diagflat_cn.rst @@ -5,7 +5,6 @@ diagflat .. py:function:: paddle.diagflat(x, offset=0, name=None) - 如果 ``x`` 是一维 Tensor,则返回带有 ``x`` 元素作为对角线的二维方阵。 如果 ``x`` 是大于等于二维的 Tensor,则返回一个二维方阵,其对角线元素为 ``x`` 在连续维度展开得到的一维 Tensor 的元素。 @@ -18,8 +17,8 @@ diagflat 参数 ::::::::: - - **x** (Tensor) - 输入的 ``Tensor``。它的形状可以是任意维度。其数据类型应为 float16,float32,float64,int32,int64。 - - **offset** (int,可选) - 对角线偏移量。正值表示上对角线,0 表示主对角线,负值表示下对角线。 + - **x** (Tensor) - 输入的 ``Tensor``。它的形状可以是任意维度。其数据类型应为 float16、float32、float64、int32、int64。别名:``input``。 + - **offset** (int,可选) - 对角线偏移量。正值表示上对角线,0 表示主对角线,负值表示下对角线。默认值为 0。 - **name** (str,可选) - 具体用法请参见 :ref:`api_guide_Name`,一般无需设置,默认值为 None。 返回 diff --git a/docs/api/paddle/diagonal_scatter_cn.rst b/docs/api/paddle/diagonal_scatter_cn.rst index 101c7daa179..0fadc7331d9 100644 --- a/docs/api/paddle/diagonal_scatter_cn.rst +++ b/docs/api/paddle/diagonal_scatter_cn.rst @@ -5,7 +5,6 @@ diagonal_scatter .. py:function:: paddle.diagonal_scatter(x, y, offset=0, axis1=0, axis2=1, name=None) - 根据参数 ``offset``、``axis1``、``axis2``,将张量 ``y`` 填充到张量 ``x`` 的对应位置。 这个函数将会返回一个新的 ``Tensor``。 @@ -25,11 +24,11 @@ diagonal_scatter 参数 :::::::::::: - - **x** (Tensor) - 输入张量,张量的维度至少为 2 维,支持 float16、float32、float64、bfloat16、uint8、int8、int16、int32、int64、bool、complex64、complex128 数据类型。 - - **y** (Tensor) - 嵌入张量,将会被嵌入到输入张量中,支持 float16、float32、float64、bfloat16、uint8、int8、int16、int32、int64、bool、complex64、complex128 数据类型。 + - **x** (Tensor) - 输入张量,张量的维度至少为 2 维,支持 float16、float32、float64、bfloat16、uint8、int8、int16、int32、int64、bool、complex64、complex128 数据类型。别名:``input``。 + - **y** (Tensor) - 嵌入张量,将会被嵌入到输入张量中,支持 float16、float32、float64、bfloat16、uint8、int8、int16、int32、int64、bool、complex64、complex128 数据类型。别名:``src``。 - **offset** (int,可选) - 从指定的二维平面嵌入对角线的位置,默认值为 0,即主对角线。 - - **axis1** (int,可选) - 对角线的第一个维度,默认值为 0。 - - **axis2** (int,可选) - 对角线的第二个维度,默认值为 1。 + - **axis1** (int,可选) - 对角线的第一个维度,默认值为 0。别名:``dim1``。 + - **axis2** (int,可选) - 对角线的第二个维度,默认值为 1。别名:``dim2``。 - **name** (str,可选) - 具体用法请参见 :ref:`api_guide_Name`,一般无需设置,默认值为 None。 返回 diff --git a/docs/api/paddle/erf__cn.rst b/docs/api/paddle/erf__cn.rst index bfe4d836ba4..6e6a56c459f 100644 --- a/docs/api/paddle/erf__cn.rst +++ b/docs/api/paddle/erf__cn.rst @@ -4,6 +4,7 @@ erf\_ ------------------------------- .. py:function:: paddle.erf_(x, name=None) + Inplace 版本的 :ref:`cn_api_paddle_erf` API,对输入 x 采用 Inplace 策略。 更多关于 inplace 操作的介绍请参考 `3.1.3 原位(Inplace)操作和非原位操作的区别`_ 了解详情。 diff --git a/docs/api/paddle/erf_cn.rst b/docs/api/paddle/erf_cn.rst index 422fcac3a3f..49ed3033f29 100644 --- a/docs/api/paddle/erf_cn.rst +++ b/docs/api/paddle/erf_cn.rst @@ -3,13 +3,11 @@ erf ------------------------------- -.. py:function:: paddle.erf(x, name = None) +.. py:function:: paddle.erf(x, name=None) +逐元素计算 Erf 激活函数。 - - -逐元素计算 Erf 激活函数。更多细节请参考 `Error function `_ 。 - +更多细节请参考 `Error function `_。 .. math:: out = \frac{2}{\sqrt{\pi}} \int_{0}^{x}e^{- \eta^{2}}d\eta @@ -17,14 +15,13 @@ erf 参数 :::::::::::: - - **x** (Tensor) - 输入的多维 Tensor,数据类型为 float16、float32 或 float64。 - - **name** (str,可选) - 具体用法请参见 :ref:`api_guide_Name`,一般无需设置,默认值为 None。 + - **x** (Tensor) - 输入 Tensor,数据类型为 float32、float64、uint8、int8、int16、int32、int64。别名: ``input``。 + - **name** (str,可选) - 具体用法请参见 :ref:`api_guide_Name`,一般无需设置,默认值为 ``None``。 返回 :::::::::::: - - 多维 Tensor,数据类型为 float16、float32 或 float64,和输入 x 的数据类型相同,形状和输入 x 相同。 - + Tensor,数据类型为 float32 或 float64(整数类型会自动转换为 float32),形状与输入 ``x`` 相同。 代码示例 :::::::::::: diff --git a/docs/api/paddle/iinfo_cn.rst b/docs/api/paddle/iinfo_cn.rst index c72f59ff500..e3a76d10337 100644 --- a/docs/api/paddle/iinfo_cn.rst +++ b/docs/api/paddle/iinfo_cn.rst @@ -14,7 +14,7 @@ iinfo 参数 ::::::::: - - **dtype** (paddle.dtype|str) - 输入的数据类型,可以是:paddle.uint8、 paddle.int8、 paddle.int16、 paddle.int32、 paddle.int64 或这些类型的字符串形式。 + - **dtype** (paddle.dtype|str) - 输入的数据类型,可以是:paddle.uint8、 paddle.int8、 paddle.int16、 paddle.int32、 paddle.int64 或这些类型的字符串形式。别名 ``type``。 返回 ::::::::: diff --git a/docs/api/paddle/inner_cn.rst b/docs/api/paddle/inner_cn.rst index 2c3941c6706..8c4c83e6830 100644 --- a/docs/api/paddle/inner_cn.rst +++ b/docs/api/paddle/inner_cn.rst @@ -3,8 +3,7 @@ inner ------------------------------- -.. py:function:: paddle.inner(x, y, name=None) - +.. py:function:: paddle.inner(x, y, name=None, *, out=None) 计算两个 Tensor 的内积。 @@ -13,10 +12,15 @@ inner 参数 :::::::::::: - - **x** (Tensor) - 一个 N 维 Tensor 或者标量 Tensor,如果是 N 维 Tensor 最后一个维度长度需要跟 y 保持一致。 - - **y** (Tensor) - 一个 N 维 Tensor 或者标量 Tensor,如果是 N 维 Tensor 最后一个维度长度需要跟 x 保持一致。 + - **x** (Tensor) - 一个 N 维 Tensor 或者标量 Tensor,如果是 N 维 Tensor 最后一个维度长度需要跟 y 保持一致。别名 ``input``。 + - **y** (Tensor) - 一个 N 维 Tensor 或者标量 Tensor,如果是 N 维 Tensor 最后一个维度长度需要跟 x 保持一致。别名 ``other``。 - **name** (str,可选) - 具体用法请参见 :ref:`api_guide_Name`,一般无需设置,默认值为 None。 +关键字参数 +::::::::: + + - **out** (Tensor,可选) - 输出 Tensor,若不为 ``None``,计算结果将保存在该 Tensor 中,默认值为 ``None``。 + 返回 :::::::::::: diff --git a/docs/api/paddle/ldexp_cn.rst b/docs/api/paddle/ldexp_cn.rst index c59534fd605..7aa62943f9f 100644 --- a/docs/api/paddle/ldexp_cn.rst +++ b/docs/api/paddle/ldexp_cn.rst @@ -3,7 +3,7 @@ ldexp ------------------------------- -.. py:function:: paddle.ldexp(x, y, name=None) +.. py:function:: paddle.ldexp(x, y, name=None, *, out=None) 计算 ``x`` 乘以 2 的 ``y`` 次幂 @@ -13,10 +13,14 @@ ldexp 参数 :::::::::::: - - **x** (Tensor) - 多维 Tensor。数据类型为 float32、float64、int32、int64。 - - **y** (Tensor) - 多维 Tensor。通常为整数。 + - **x** (Tensor) - 多维 Tensor。数据类型为 float32、float64、int32、int64。别名:``input``。 + - **y** (Tensor) - 多维 Tensor。通常为整数。别名:``other``。 - **name** (str,可选) - 具体用法请参见 :ref:`api_guide_Name`,一般无需设置,默认值为 None。 +关键字参数 +::::::::: + - **out** (Tensor,可选) - 输出 Tensor,若不为 ``None``,计算结果将保存在该 Tensor 中,默认值为 ``None``。 + 返回 :::::::::::: 输出为 Tensor,如果 ``x``, ``y`` 有不同的形状并且是可广播的,那么产生的张量形状是广播后 x 和 y 的形状。如果 ``x``, ``y`` 有相同的形状,其形状与 ``x``, ``y`` 相同。数据类型是 float32 或 float64。 diff --git a/docs/api/paddle/nanquantile_cn.rst b/docs/api/paddle/nanquantile_cn.rst index 533628d8b07..54a4982d563 100644 --- a/docs/api/paddle/nanquantile_cn.rst +++ b/docs/api/paddle/nanquantile_cn.rst @@ -3,19 +3,23 @@ nanquantile ------------------------------- -.. py:function:: paddle.nanquantile(x, q, axis=None, keepdim=False, interpolation='linear', name=None) +.. py:function:: paddle.nanquantile(x, q, axis=None, keepdim=False, interpolation='linear', name=None, *, out=None) 沿给定的轴 ``axis`` 计算 ``x`` 中元素的分位数, 忽略元素中的 ``NaN`` 。 参数 :::::::::: - - **x** (Tensor) - 输入的 Tensor,数据类型为:bfloat16、float16、float32、float64。 + - **x** (Tensor) - 输入的 Tensor,数据类型为:bfloat16、float16、float32、float64、int32、int64。别名:``input``。 - **q** (int|float|list|Tensor) - 待计算的分位数,需要在符合取值范围[0, 1]。如果 ``q`` 是 List 或者 1-D Tensor,其中的每一个 q 分位数都会被计算,并且输出的首维大小与列表或 Tensor 中元素的数量相同。如果 ``q`` 是 0-D Tensor ,则会被当作 float 和 int 对待。 - - **axis** (int|list,可选) - 指定对 ``x`` 进行计算的轴。``axis`` 可以是 int 或内部元素为 int 类型的 list。``axis`` 值应该在范围[-D, D)内,D 是 ``x`` 的维度。如果 ``axis`` 或者其中的元素值小于 0,则等价于 :math:`axis + D`。如果 ``axis`` 是 list,对给定的轴上的所有元素计算分位数。如果 ``axis`` 是 None,则对 ``x`` 的全部元素计算分位数。默认值为 None。 + - **axis** (int|list,可选) - 指定对 ``x`` 进行计算的轴。``axis`` 可以是 int 或内部元素为 int 类型的 list。``axis`` 值应该在范围[-D, D)内,D 是 ``x`` 的维度。如果 ``axis`` 或者其中的元素值小于 0,则等价于 :math:`axis + D`。如果 ``axis`` 是 list,对给定的轴上的所有元素计算分位数。如果 ``axis`` 是 None,则对 ``x`` 的全部元素计算分位数。默认值为 None。别名:``dim``。 - **keepdim** (bool,可选) - 是否在输出 Tensor 中保留减小的维度。如果 ``keepdim`` 为 True,则输出 Tensor 和 ``x`` 具有相同的维度(减少的维度除外,减少的维度的大小为 1)。否则,输出 Tensor 的形状会在 ``axis`` 上进行 squeeze 操作。默认值为 False。 - **interpolation** (str,可选) - 计算分位数的插值方法,可以是 ``linear`` , ``lower`` , ``higher`` , ``nearest`` 或者 ``midpoint`` 。 默认值为 ``linear`` 。 - **name** (str,可选) - 具体用法请参见 :ref:`api_guide_Name`,一般无需设置,默认值为 None。 +关键字参数 +:::::::::: + - **out** (Tensor,可选) - 输出 Tensor,若不为 ``None``,计算结果将保存在该 Tensor 中,默认值为 ``None``。 + 返回 :::::::::: ``Tensor``,沿着 ``axis`` 进行分位数计算的结果。与输入数据类型一致。 diff --git a/docs/api/paddle/neg_cn.rst b/docs/api/paddle/neg_cn.rst index 87ab8044935..5e140b93e88 100644 --- a/docs/api/paddle/neg_cn.rst +++ b/docs/api/paddle/neg_cn.rst @@ -3,10 +3,7 @@ neg ------------------------------- -.. py:function:: paddle.neg(x, name=None) - - - +.. py:function:: paddle.neg(x, name=None, *, out=None) 计算输入 x 的相反数并返回。 @@ -15,9 +12,13 @@ neg 参数 ::::::::: - - **x** (Tensor) - 输入的 Tensor,数据类型为:bfloat16、float16、float32、float64、int8、int16、int32、int64、uint8、complex64、complex128。 + - **x** (Tensor) - 输入的 Tensor,数据类型为:bfloat16、float16、float32、float64、int8、int16、int32、int64、uint8、complex64、complex128。别名:``input``。 - **name** (str,可选) - 具体用法请参见 :ref:`api_guide_Name`,一般无需设置,默认值为 None。 +关键字参数 +::::::::: + - **out** (Tensor,可选) - 输出 Tensor,若不为 ``None``,计算结果将保存在该 Tensor 中,默认值为 ``None``。 + 返回 ::::::::: 输出 Tensor,与 ``x`` 维度相同、数据类型相同。 diff --git a/docs/api/paddle/positive_cn.rst b/docs/api/paddle/positive_cn.rst index b8c2a996dd9..1b07a5842c6 100644 --- a/docs/api/paddle/positive_cn.rst +++ b/docs/api/paddle/positive_cn.rst @@ -3,7 +3,7 @@ positive ------------------------------- -.. py:function:: paddle.positive(x) +.. py:function:: paddle.positive(x, name=None) 返回输入 Tensor 的本身。 @@ -14,8 +14,8 @@ positive 参数 :::::::::::: - - - **x** (Tensor) - 支持任意维度的 Tensor。数据类型为 uint8、int8、int16、int32、int64、float32、float64、float16、complex64、complex128。 + - **x** (Tensor) - 支持任意维度的 Tensor。数据类型为 uint8、int8、int16、int32、int64、float32、float64、float16、complex64、complex128。别名 ``input``。 + - **name** (str,可选) - 具体用法请参见 :ref:`api_guide_Name`,一般无需设置,默认值为 None。 返回 :::::::::::: diff --git a/docs/api/paddle/rad2deg_cn.rst b/docs/api/paddle/rad2deg_cn.rst index 4474fbcf874..cf50980c08b 100644 --- a/docs/api/paddle/rad2deg_cn.rst +++ b/docs/api/paddle/rad2deg_cn.rst @@ -3,7 +3,7 @@ rad2deg ------------------------------- -.. py:function:: paddle.rad2deg(x, name=None) +.. py:function:: paddle.rad2deg(x, name=None, *, out=None) 将元素从弧度转换为度 @@ -14,9 +14,14 @@ rad2deg 参数 ::::::::: - - **x** (Tensor) - 输入的 Tensor,数据类型为:int32、int64、float32、float64。 + - **x** (Tensor) - 输入的 Tensor,数据类型为:int32、int64、float32、float64。别名 ``input``。 - **name** (str,可选) - 操作的名称(可选,默认值为 None)。更多信息请参见 :ref:`api_guide_Name`。 +关键字参数 +::::::::: + + - **out** (Tensor,可选) - 输出 Tensor,若不为 ``None``,计算结果将保存在该 Tensor 中,默认值为 ``None``。 + 返回 ::::::::: diff --git a/docs/api/paddle/rot90_cn.rst b/docs/api/paddle/rot90_cn.rst index 98687a511a2..9114ccd55ed 100644 --- a/docs/api/paddle/rot90_cn.rst +++ b/docs/api/paddle/rot90_cn.rst @@ -5,8 +5,6 @@ rot90 .. py:function:: paddle.rot90(x, k=1, axes=[0, 1], name=None) - - 沿 axes 指定的平面将 n 维 tensor 旋转 90 度。当 k 为正数,旋转方向为从 axes[0]到 axes[1],当 k 为负数,旋转方向为从 axes[1]到 axes[0],k 的绝对值表示旋转次数。 下图展示了一个形状为 [2,3,4] 的三维张量执行 rot90 操作的示例,其中 axes 为 [0, 1], k 为 1 ,旋转方向为从 axes = 0 到 axes = 1,旋转次数为 1 次。 @@ -18,9 +16,9 @@ rot90 参数 :::::::::: - - **x** (Tensor) - 输入 Tensor。维度为多维,数据类型为 bool, int32, int64, float16, float32 或 float64。float16 只在 gpu 上支持。 + - **x** (Tensor) - 输入 Tensor。维度为多维,数据类型为 bool, int32, int64, float16, float32 或 float64。float16 只在 gpu 上支持。别名 ``input``。 - **k** (int,可选) - 旋转方向和次数,默认值:1。 - - **axes** (list|tuple,可选) - axes 指定旋转的平面,维度必须为 2。默认值为[0, 1]。 + - **axes** (list|tuple,可选) - axes 指定旋转的平面,维度必须为 2。默认值为[0, 1]。别名 ``dims``。 - **name** (str,可选) - 具体用法请参见 :ref:`api_guide_Name`,一般无需设置,默认值为 None。 返回 diff --git a/docs/api/paddle/round_cn.rst b/docs/api/paddle/round_cn.rst index 0988da2738f..f79a2fd1f49 100644 --- a/docs/api/paddle/round_cn.rst +++ b/docs/api/paddle/round_cn.rst @@ -3,10 +3,7 @@ round ------------------------------- -.. py:function:: paddle.round(x, decimals=0, name=None) - - - +.. py:function:: paddle.round(x, decimals=0, name=None, *, out=None) 将输入中的数值四舍五入到最接近的整数数值。 @@ -22,12 +19,14 @@ round 参数 :::::::::::: - - - - **x** (Tensor) - 支持任意维度的 Tensor。数据类型为 int32,int64,float16,bfloat16,float32,float64,complex64 或 complex128。 + - **x** (Tensor) - 支持任意维度的 Tensor。数据类型为 int32,int64,float16,bfloat16,float32,float64,complex64 或 complex128。别名 ``input``。 - **decimals** (int,可选) - 要舍入到的小数点位数。如果 decimals 为负数,则指定小数点左边的位数。默认为 0。 - **name** (str,可选) - 具体用法请参见 :ref:`api_guide_Name`,一般无需设置,默认值为 None。 +关键字参数 +::::::::: + - **out** (Tensor,可选) - 输出 Tensor,若不为 ``None``,计算结果将保存在该 Tensor 中,默认值为 ``None``。 + 返回 :::::::::::: 返回类型为 Tensor,数据类型同输入一致。 diff --git a/docs/dev_guides/coding_agent/api_compatibility/cpp-sink.mdr b/docs/dev_guides/coding_agent/api_compatibility/cpp-sink.mdr index 721b0567f31..97b73481f38 100644 --- a/docs/dev_guides/coding_agent/api_compatibility/cpp-sink.mdr +++ b/docs/dev_guides/coding_agent/api_compatibility/cpp-sink.mdr @@ -130,7 +130,8 @@ def log2( ) ``` -如果支持了out参数,还必须在文档字符串中描述out参数,out为keyword-only参数时在Keyword args部分描述,为位置参数时在Args部分描述,如下: +如果支持了out参数,必须在API文档中描述out参数,out为keyword-only参数(*后面)时注意增加`Keyword Args:`,并在此部分描述。out为位置参数时直接在Args部分描述。如下: + ```python # out为keyword-only参数 """ @@ -177,12 +178,13 @@ from paddle._C_ops import log2 # noqa: F401 ### Step 4:添加测试用例 -不要新建任何测试文件,直接在 `test/legacy_test/test_api_compatibility[1-9]\.py` 中添加测试。严格按以下模板来编写: +不要新建任何测试文件,直接在 `test/legacy_test/test_api_compatibility[1-9]\.py(数字最大的)` 中添加测试。严格按以下模板来编写: **测试模板**: ```python class TestAPI(unittest.TestCase): def setUp(self): + # If not use random seed, remove setUp np.random.seed(2025) self.np_x = np.random.rand(...).astype(...) diff --git a/docs/dev_guides/coding_agent/api_compatibility/python-decorator.md b/docs/dev_guides/coding_agent/api_compatibility/python-decorator.md index 871c2b7f2c0..7d4f7568271 100644 --- a/docs/dev_guides/coding_agent/api_compatibility/python-decorator.md +++ b/docs/dev_guides/coding_agent/api_compatibility/python-decorator.md @@ -337,7 +337,9 @@ def func(x, axis=None, name=None, *, out: Tensor | None = None): return ret1, ret2 ``` -注意在 API 签名中增加 out 参数,`out`参数需与 Pytorch 用法一致,一般情况下 out 均是 keyword-only 参数(使用`*,`分隔),少数情况下 out 是位置参数。 +注意: +1. 需在 API 签名中增加 out 参数,`out`参数需与 Pytorch 用法一致,一般情况下 out 均是 keyword-only 参数(使用`*,`分隔),少数情况下 out 是位置参数。 +2. 处理 out 参数时,仅需处理 in_dynamic_or_pir_mode()分支下的逻辑,老静态图(LayerHelper)分支无需处理 out 参数。 ## Step 4: 更新函数文档字符串 @@ -402,12 +404,13 @@ def broadcast_tensors(input: Sequence[Tensor], name: str | None = None) -> list[ """ ``` -如果支持了 out 参数,必须在 API 文档中描述 out 参数,out 为 keyword-only 参数时在 Keyword args 部分描述,为位置参数时在 Args 部分描述,如下: +如果支持了 out 参数,必须在 API 文档中描述 out 参数,out 为 keyword-only 参数(*后面)时注意增加`Keyword Args:`,并在此部分描述。out 为位置参数时直接在 Args 部分描述。如下: + ```python # out 为 keyword-only 参数 def func(x, name=None, *, out=None): """ - func Operator. + ... Args: ... @@ -422,7 +425,7 @@ def func(x, name=None, *, out=None): # out 为位置参数 def func(x, out=None, name=None): """ - func Operator. + ... Args: x (Tensor): Input of Atan operator. @@ -440,12 +443,13 @@ def func(x, out=None, name=None): ## Step 5: 添加测试用例 -不要新建任何测试文件,直接在 `test/legacy_test/test_api_compatibility[1-9]\.py` 中添加测试。严格按以下模板来编写: +不要新建任何测试文件,直接在 `test/legacy_test/test_api_compatibility[1-9]\.py(数字最大的)` 中添加测试。严格按以下模板来编写: **测试模板**: ```python class TestAPI(unittest.TestCase): def setUp(self): + # If not use random seed, remove setUp np.random.seed(2025) self.np_x = np.random.rand(...).astype(...) @@ -677,31 +681,6 @@ if len(args) >= 2 and isinstance(args[1], int): - 确保装饰器之间不产生冲突 - 不同装饰器的参数处理逻辑应该兼容 -# 六、开发检查清单 - -完成 API 对齐后,请确认以下清单: - -## 代码修改 -- [ ] 已选择合适的装饰器(通用或专用) -- [ ] 装饰器已正确应用到 API 函数 -- [ ] out 参数已添加(如需要) -- [ ] out 参数实现方式正确 -- [ ] 函数签名保持正确(包括__signature__设置) - -## 文档更新 -- [ ] 所有别名的参数都已添加 Alias Support 说明 -- [ ] out 参数已在文档中说明 -- [ ] 文档格式符合规范 - -## 测试覆盖 -- [ ] 动态图测试覆盖所有参数组合 -- [ ] 静态图测试覆盖所有参数组合 -- [ ] Paddle 风格的 API 调用 -- [ ] Pytorch 风格的 API 调用 -- [ ] out 参数测试已添加(如支持) -- [ ] 异常参数测试已添加 -- [ ] 所有测试通过 - # 七、注意事项 1. 不要修改 sparse 目录下的 API