python-decorator

name	python-decorator
description	负责《Paddle API 对齐 PyTorch 项目》中 Step2：API 代码修改，实施 Python 装饰器的代码开发。通过 Python 装饰器，在 Python 层为 Paddle API 提供参数别名、参数顺序、参数类型和参数用法的兼容转换，实现 PyTorch 风格的 API 调用，并保持 Paddle API 的向后兼容性。
context	fork
background	false
verbose	true
disable-model-invocation	false

一、现有装饰器体系

Paddle 现有装饰器统一位于 ${ROOT_DIR}/Paddle/python/paddle/utils/decorator_utils.py，按功能分为两类：

1.1 通用别名装饰器

装饰器	支持参数数量	性能	使用场景	优先级
param_one_alias	1 个	高	单个参数别名（如 x↔input）	⭐⭐⭐
param_two_alias	2 个	高	两个参数别名（如 x↔input, axis↔dim）	⭐⭐⭐
ParamAliasDecorator	3 个及以上	中	复杂参数映射场景	⭐⭐
param_two_alias_one_default	2 个+默认值	低	需要默认值（median 专用）	⭐（不推荐）

1.2 专用装饰器

装饰器	功能描述	关键特性
index_select_decorator	参数别名 + 参数顺序转换	检测第 2 个位置参数是否为 int 来判断不同参数顺序
index_add_decorator	参数别名 + 参数顺序转换	检测第 2 个位置参数是否为 int 来判断不同参数顺序
transpose_decorator	参数别名 + 参数用法转换	通过 dim0/dim1 两个 int 来自动构造 perm 列表
size_args_decorator	参数别名 + 可变参数	合并全部 int 位置参数为 shape 列表
view_decorator	参数别名 + 可变参数	合并全部 int 位置参数为 shape 列表
reshape_decorator	参数别名 + 可变参数	第 1 个参数别名，合并后面多个 int 位置参数为 shape 列表
expand_decorator	参数别名 + 可变参数	第 1 个参数别名，合并后面多个 int 位置参数为 shape 列表
legacy_reduction_decorator	参数别名 + 报错信息增强	检测到 size_average/reduce 用法后，增强报错信息
lp_pool_function_decorator	参数别名 + 参数顺序转换	检测第 5 个位置参数是否为 bool 来判断不同参数顺序

二、标准工作流程

整体流程：Step 1 差异分析与选择装饰器 → Step 2 应用或开发装饰器 → Step 3 添加 out 参数支持 → Step 4 更新函数文档 → Step 5 添加测试用例 → Step 6 编译并运行

Step 1: 差异分析与选择装饰器

根据 PyTorch API 与 Paddle API 的差异分析来区分不同场景，选择合适的装饰器方案。

场景决策表

差异类型	参数顺序	参数个数	参数用法	推荐方案
仅参数名不同	相同	相同	相同	✅ 方式一（通用别名装饰器）
参数名+参数顺序不同	不同	相同	相同	❌ 需要使用方式二（专用装饰器）
参数名+参数个数不同	相同	不同	相同	❌ 需要使用方式二（专用装饰器）
参数名+参数用法不同	相同	相同	不同	❌ 需要使用方式二（专用装饰器）
其他复杂情况	其他	其他	其他	❌ 需要使用方式二（专用装饰器）

判断方法：若上表中任何一列出现"不同"，则需使用方式二开发专用装饰器。

---

1. 仅参数名不同（参数顺序相同）

根据需要映射的参数数量，选择对应的通用别名装饰器：

• 1 个参数 → param_one_alias
• 2 个参数 → param_two_alias
• 3 个及以上参数 → ParamAliasDecorator

使用示例：

# 单个参数别名
## torch.deg2rad(input)
## paddle.deg2rad(x)
from paddle.utils.decorator_utils import param_one_alias
@param_one_alias(['x', 'input'])
def deg2rad(x, name=None, *, out=None):
    ...

# 两个参数别名
## torch.squeeze(input, dim)
## paddle.squeeze(x, axis)
from paddle.utils.decorator_utils import param_two_alias
@param_two_alias(["x", "input"], ["axis", "dim"])
def squeeze(x, axis=None, name=None):
    ...

# 多个参数别名
## torch.nn.functional.normalize(input, p, dim, eps)
## paddle.nn.functional.normalize(x, p, axis, epsilon)
from paddle.utils.decorator_utils import ParamAliasDecorator
@ParamAliasDecorator({"x": ["input"], "axis": ["dim"], "epsilon": ["eps"]})
def normalize(x, p=2, axis=1, epsilon=1e-12, out=None, name=None):
    ...

2. 参数名不同 + 可变参数

开发新的专用装饰器，可参考size_args_decorator、reshape_decorator、expand_decorator、view_decorator

使用示例：

# torch.reshape(x, 2, 5)  # shape 支持可变参数用法
# paddle.reshape(x, [2, 5])
from paddle.utils.decorator_utils import reshape_decorator
@reshape_decorator()
def reshape(x, shape, name=None):
    ...

3. 参数名不同 + 参数顺序不同

开发新的专用装饰器

示例：

# torch.index_select(input, dim, index)
# paddle.index_select(x, index, axis)
from paddle.utils.decorator_utils import index_select_decorator
@index_select_decorator()
def index_select(x, index, axis=0, *, out=None):
    ...

4. 参数名不同 + 参数用法不同

开发新的专用装饰器

示例：

# torch.transpose(x, dim0, dim1)  # 交换两个维度，
# paddle.transpose(x, perm)
from paddle.utils.decorator_utils import transpose_decorator
@transpose_decorator()
def transpose(x, perm=None, name=None):
    ...

Step 2: 应用或开发装饰器

根据Step1中的不同场景：

• 场景 1（仅参数名不同）：请进入 方式一（通用别名装饰器）。
• 场景 2 & 3 & 4（可变参数、参数顺序不同、参数用法不同及其他情况）：请进入 方式二（开发新的专用装饰器）。

方式一：通用别名装饰器

1. 在 API 函数文件中导入装饰器
2. 在 API 函数定义前添加装饰器

示例：

from paddle.utils.decorator_utils import param_two_alias

@param_two_alias(["x", "input"], ["axis", "dim"])
def cumsum(x, axis=None, dtype=None, name=None):
    ...

方式二：开发新的专用装饰器

1. 在${ROOT_DIR}/Paddle/python/paddle/utils/decorator_utils.py中定义新装饰器
2. 按照以下模板和要点实现
3. 在 API 函数上使用新装饰器

装饰器模板：

import functools
import inspect

def custom_decorator():
    """
    装饰器功能说明

    Usage Example:
        PyTorch: torch.api(arg1, arg2)
        Paddle: paddle.api(arg2, arg1)  # 或其他映射关系
    """

    def decorator(func):
        @functools.wraps(func)  # 保持原函数的__name__, __doc__等元信息
        def wrapper(*args, **kwargs):
            # 1. 参数别名映射
            if "input" in kwargs and "x" not in kwargs:
                kwargs["x"] = kwargs.pop("input")

            # 2. 参数顺序转换或其他特殊处理
            # 根据需要调整 args

            # 3. 调用原函数
            return func(*args, **kwargs)

        wrapper.__signature__ = inspect.signature(func)  # 保持函数签名
        return wrapper

    return decorator

关键实现要点：

1. 关键字参数别名

if "input" in kwargs and "x" not in kwargs:
    kwargs["x"] = kwargs.pop("input")

2. 位置参数类型检测（用于判断参数顺序）

if len(args) >= 2 and isinstance(args[1], int):
    # 检测 args 第 2 个值是否为 int，从而判断是 torch 用法还是 paddle 用法，并根据不同的 args 顺序统一匹配为 kwargs
    ## torch.index_select(input, dim, index)
    ## paddle.index_select(x, index, axis)
    kwargs["x"] = args[0]
    kwargs["axis"] = args[1]
    args = args[2:]

3. 可变参数处理

# 合并多个 int 位置参数为列表
if len(args) >= 2 and all(isinstance(arg, int) for arg in args[1:]):
    kwargs["shape"] = list(args[1:])
    args = args[:1]

完整示例：

def index_select_decorator():
    def decorator(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            # 1. 参数别名映射
            if "input" in kwargs and "x" not in kwargs:
                kwargs["x"] = kwargs.pop("input")
            if "dim" in kwargs and "axis" not in kwargs:
                kwargs["axis"] = kwargs.pop("dim")

            # 2. PyTorch 参数顺序匹配：识别不同的 args 顺序，统一处理为 kwargs
            if len(args) >= 2 and isinstance(args[1], int):
                # PyTorch 顺序: (input, dim, index) → Paddle 顺序: (x, index, axis)
                kwargs["x"] = args[0]
                kwargs["axis"] = args[1]
                if len(args) > 2:
                    kwargs["index"] = args[2]
                args = ()

            return func(*args, **kwargs)

        wrapper.__signature__ = inspect.signature(func)
        return wrapper

    return decorator

注意事项：

1. 尽可能参考 ${ROOT_DIR}/Paddle/python/paddle/utils/decorator_utils.py 中已有的专用装饰器来实现，在风格和逻辑上保持尽可能一致
2. 如果两者 API 对应参数的顺序不同，则装饰器需要通过位置参数(args)类型检测来区分两者，并分别匹配不同的参数顺序
3. 专用装饰器应该尽可能逻辑简单（单个函数控制在 30 行以内），只假定存在 Paddle 签名+PyTorch 签名两种用法，其他情况无需判断，提升性能
4. overload 注解：专用装饰器需添加 overload 注解（通用别名装饰器无需注解），需针对 Paddle 签名、PyTorch 签名分别添加 overload 注解（Paddle 在前，PyTorch 在后）。导入方式：from typing import overload

@overload
def gather(
    x: Tensor,
    index: Tensor,
    axis: Tensor | int | None = None,
    name: str | None = None,
    out: Tensor | None = None,
) -> Tensor: ...

@overload
def gather(
    input: Tensor,
    dim: int,
    index: Tensor,
    out: Tensor | None = None,
) -> Tensor: ...

Step 3: 添加 out 参数支持

仅支持新增 out 参数，新增其他参数则需方案 3（修改 API 智能体）来开展。

方式一：直接指定 out（推荐）

适用条件：

1. 情况 1：API 最后一个逻辑是调用_C_ops；情况 2：API 调用了其他 API，调用的最后一个其他 API 也支持 out
2. out 参数只有一个 Tensor

示例：

# 情况 1：API 最后一个逻辑是调用`_C_ops`
@param_two_alias(["x", "input"], ["y", "other"])
def less_than(x, y, name=None, *, out=None) -> Tensor:
    """
    Keyword args:
        ...
        out (Tensor|None, optional): The output tensor. Default: None.
    """
    if in_dynamic_or_pir_mode():
        return _C_ops.less_than(x, y, out=out)
    else:
        ...

# 情况 2：API 调用的最后一个其他 API 也支持 out
@param_two_alias(["x", "input"], ["axis", "dim"])
def fft(x, n=None, axis=-1, norm="backward", name=None, *, out=None) -> Tensor:
    """
    Args:
        ...

    Keyword args:
        out (Tensor|None, optional): The output tensor. Default: None.
    """
    if is_integer(x) or is_floating_point(x):
        return fft_r2c(
            x, n, axis, norm, forward=True, onesided=False, name=name, out=out
        )
    else:
        return fft_c2c(x, n, axis, norm, forward=True, name=name, out=out)

方式二：通过 assign 实现

适用条件：不符合方式一的情况

示例：

def func(x, axis=None, name=None, *, out: Tensor | None = None):
    """
    Args:
        ...

    Keyword args:
        out (Tensor|None, optional): The output tensor. Default: None.
    """
    # case1: 只有 1 个 out 的情况
    ret = <计算逻辑>
    if out is not None:
        paddle.assign(ret, out)
        return out
    return ret

    # case2: 有多个 out 的情况
    ret1, ret2 = <计算逻辑>
    if out is not None:
        paddle.assign(ret1, out[0])
        paddle.assign(ret2, out[1])
        return out
    return ret1, ret2

注意：

1. 需在 API 签名中增加 out 参数，out参数需与 Pytorch 用法一致，一般情况下 out 均是 keyword-only 参数（使用*,分隔），少数情况下 out 是位置参数。
2. 处理 out 参数时，仅需处理 in_dynamic_or_pir_mode()分支下的逻辑，老静态图（LayerHelper）分支无需处理 out 参数。

Step 4: 更新函数文档字符串

如果使用的是通用别名装饰器，则在文档的 Args 部分为有别名的参数添加 Alias Support 说明，如下：

注：Alias 说明应放在该参数描述的末尾，格式为: Alias: alias_name ，多个 Alias 描述为: Alias: alias_name1 or alias_name2

@param_two_alias(["x", "input"], ["axis", "dim"])
def fft(
    x: Tensor,
    n: int | None = None,
    axis: int = -1,
    norm: _NormalizeMode = "backward",
    name: str | None = None,
    *,
    out: Tensor | None = None,
) -> Tensor:
    """
    Calculate one-dimensional discrete Fourier transform.

    Args:
        x (Tensor): The input data. It's a Tensor type. It's a complex.
            Alias: ``input``.
        n (int|None, optional): The length of the output transform axis.
        axis (int, optional): Axis used to calculate FFT.
            Alias: ``dim``.
        norm (str, optional): Indicates which direction to scale the `forward` or `backward` transform
            pair and what normalization factor to use.
        name (str|None, optional): The default value is None.

    Keyword args:
        out(Tensor, optional): The output tensor.
    """

如果使用的是专用装饰器，则表明 API 支持了签名重载，需要分别描述两种签名，可以参考代码中的@overload 注解，如下：

注：只需在文档正文中阐述两种签名（Paddle 在前，Pytorch 在后），文档其他位置如 Args/Returns 仍以 Paddle 风格签名为准

@overload
def broadcast_tensors(input: Sequence[Tensor], name: str | None = None) -> list[Tensor]: ...

@overload
def broadcast_tensors(*tensors: Tensor) -> list[Tensor]: ...

@variadic_tensor_decorator('input')
def broadcast_tensors(input: Sequence[Tensor], name: str | None = None) -> list[Tensor]:
    """
    This API has two signatures:

    1. ``paddle.broadcast_tensors(input, name=None)`` (Paddle-style):
        Broadcast a list of tensors following broadcast semantics.

    2. ``paddle.broadcast_tensors(*tensors)`` (PyTorch-style):
        Broadcast variadic tensor arguments following broadcast semantics.

    Args:
        ...

    Returns:
        ...
    """

如果支持了 out 参数，必须在 API 文档中描述 out 参数，out 为 keyword-only 参数（*后面）时注意增加Keyword Args:，并在此部分描述。out 为位置参数时直接在 Args 部分描述。如下：

# out 为 keyword-only 参数
def func(x, name=None, *, out=None):
    """
    ...

    Args:
        ...

    Keyword Args:
        out (Tensor|optional): The output tensor. Default: None.

    Returns:
        ...
    """

# out 为位置参数
def func(x, out=None, name=None):
    """
    ...

    Args:
        x (Tensor): Input of Atan operator.
        out (Tensor, optional): The output Tensor. Default: None.
        name (str|None, optional): Name for the operation.

    Returns:
        ...
    """

注意事项：

• Tensor 类方法（如 paddle.Tensor.abs）没有文档，无需处理，请勿与普通方法（如 paddle.abs）混淆
• Inplace 方法（如 paddle.abs_等下划线 API），只需要更新 API 签名，不需要修改文档

Step 5: 添加测试用例

不要新建任何测试文件，直接在 test/legacy_test/test_api_compatibility[1-9]\.py(数字最大的) 中添加测试。严格按以下模板来编写：

测试模板：

class Test<APIName>API(unittest.TestCase):
    def setUp(self):
        # If not use random seed, remove setUp
        np.random.seed(2025)
        self.np_x = np.random.rand(...).astype(...)

    def test_dygraph_Compatibility(self):
        paddle.disable_static()
        x = paddle.to_tensor(self.np_x)

        # 1. Paddle Positional arguments
        out1 = paddle.<api_name>(x, ...)

        # 2. Paddle keyword arguments
        out2 = paddle.<api_name>(x=x, ...)

        # 3. Pytorch Positional arguments (only if order different with paddle args)
        out3 = paddle.<api_name>(x, ...)

        # 4. PyTorch keyword arguments (alias)
        out4 = paddle.<api_name>(input=x, dim=...)

        # 5. Mixed arguments
        out5 = paddle.<api_name>(x, axis=...)

        # 6. out parameter test (only if supported)
        out6 = paddle.empty_like(x)
        out7 = paddle.<api_name>(x, ..., out=out6)

        # 7. Tensor method - args (only if supported)
        out8 = x.<api_name>(...)

        # 8. Tensor method - kwargs (only if supported)
        out9 = x.<api_name>(axis=...)

        # Verify all outputs
        for out in [out1, out2, out3, out4, out5, out6, out7, out8, out9]:
            np.testing.assert_allclose(out.numpy(), ...)

        paddle.enable_static()

    def test_static_Compatibility(self):
        paddle.enable_static()
        main = paddle.static.Program()
        startup = paddle.static.Program()
        with paddle.static.program_guard(main, startup):
            x = paddle.static.data(name="x", shape=self.shape, dtype=self.dtype)

            # Create multiple outputs
            out1 = paddle.<api_name>(x, ...)
            out2 = paddle.<api_name>(x=x, ...)
            out3 = paddle.<api_name>(input=x, dim=...)

            exe = paddle.static.Executor()
            fetches = exe.run(
                main,
                feed={"x": self.np_x},
                fetch_list=[out1, out2, out3],
            )

            # Verify all outputs
            for out in fetches:
                np.testing.assert_allclose(out, ...)

测试规范： 动态图模式：

1. ✅ Paddle 位置参数（全部位置参数）
2. ✅ Paddle 关键字参数（全部关键字参数）
3. ✅ PyTorch 位置参数（如果 Pytorch 与 Paddle 参数顺序不同）
4. ✅ PyTorch 关键字参数（使用参数别名）
5. ✅ 混合参数（如果参数量>=2，位置+关键字）
6. ✅ out 参数（如果 API 支持，inplace 无需测）
7. ✅ 类方法 Pytorch 位置参数（如果有类方法）
8. ✅ 类方法 Pytorch 关键字参数（如果有类方法）

静态图模式：（inplace 无需测）

1. ✅ Paddle 位置参数（全部位置参数）
2. ✅ Paddle 关键字参数（全部关键字参数）
3. ✅ PyTorch 位置参数（如果 Pytorch 与 Paddle 参数顺序不同）
4. ✅ PyTorch 关键字参数（使用参数别名）
5. ✅ 类方法 Pytorch 位置参数（如果有类方法）
6. ✅ 类方法 Pytorch 关键字参数（如果有类方法）

注意：

1. 有些测试项是可选的，需要自行判断是否需要添加。
2. 添加测试项需要遵循上述顺序，不要打乱。
3. 输出结果序号需要保持连贯，每一个输出结果均需要检验，尽可能循环检验减少行数。
4. 比对测试项，对于内容相同的测试项，不要重复添加。

完整测试示例，请参考 ${ROOT_DIR}/Paddle/test/legacy_test/test_api_compatibility[1-9]\.py 中已有的测试类结构。

Step 6: 编译与运行

单测编写完成后，按以下命令验证执行（不可修改）：

1. 重新编译项目：

   cd ${ROOT_DIR}/Paddle/build
   cmake ..
   make -j$(nproc)
   

2. 运行单测文件：

   python <所修改的单测文件名>
   

3. 问题排查：根据报错信息调整代码或测试用例，确保所有测试用例通过。注意每次修改 Paddle 源码后，必须重新编译方可生效。

编译注意事项：

• 无需重装，直接生效（勿执行 setup/install 等安装操作）
• 勿删除 build 目录（否则增量编译失效，编译时间极长）

三、技术背景知识

3.1 Paddle API 分层结构

Paddle API 架构（5 层）：

1. Python 层：Python 函数定义（本方案修改层）
2. Pybind 层：Python 与 C++绑定（自动生成）
3. Dygraph 层：动态图前反向传播组合（自动生成）
4. C++ API 层：Kernel 选择调度（自动生成）
5. Kernel 层：实际计算逻辑实现（C++）

本方案修改范围：

• ✅ 仅修改第 1 层（Python 层）
• ❌ 第 2~4 层通过 yaml 配置自动生成，无需手动修改
• ❌ 第 5 层涉及 C++实现，不在本方案范围内

3.2 Python 装饰器原理

装饰器基本结构

import functools
import inspect

def decorator(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        # 参数处理逻辑
        return func(*args, **kwargs)

    wrapper.__signature__ = inspect.signature(func)
    return wrapper

关键点：

• @functools.wraps(func)：保持原函数的__name__、__doc__等元信息
• wrapper.__signature__：保持函数签名，支持 IDE 的参数提示
• 装饰器必须返回 wrapper 函数

参数处理模式

kwargs 别名映射

if "input" in kwargs and "x" not in kwargs:
    kwargs["x"] = kwargs.pop("input")

位置参数类型检测

if len(args) >= 2 and isinstance(args[1], int):
    kwargs["x"] = args[0]
    kwargs["shape"] = list(args[1:])
    args = ()

3.3 装饰器特点与注意事项

装饰器特点

• 零侵入性：无需修改 API 的实现代码
• 适用面广：支持灵活处理各种 API 签名重载情况，如参数名不同、参数顺序不同、参数个数不同、参数类型不同、参数用法不同等
• 向后兼容：保持 Paddle 原有 API 调用方式
• 开发效率：相比 C++下沉方案，修改更快速直接

四、注意事项

1. 严格按标准工作流程执行，杜绝自行臆断和跳过步骤
2. 所有路径使用 ${ROOT_DIR} 变量表示根目录，需自行替换为实际路径
3. 不要修改 sparse 目录下的 API
4. 确保不破坏现有功能，保持向后兼容性
5. 开发专用装饰器时参考现有实现
6. 代码中不允许提交中文，代码注释采用英文
7. 复盘记忆中的历史易错点，避免重复犯错

五、常见问题处理

Q1：类型转换错误

错误现象：

TypeError: expected Tensor as argument, got numpy.ndarray

解决方法：

# 确保输入是 Tensor 类型
tensor_input = paddle.to_tensor(numpy_input)
paddle.api(tensor_input, ...)

---

Q2：装饰器参数处理错误

错误现象：装饰器内参数转换失败或逻辑异常

解决方法：

1. 检查位置参数（args）与关键字参数（kwargs）的转换逻辑是否正确
2. 确保参数别名映射完整（包括所有别名情况）
3. 使用调试技巧进行追踪：

在装饰器中添加日志进行调试：

import logging
logging.basicConfig(level=logging.DEBUG)

# 在装饰器中添加日志
def wrapper(*args, **kwargs):
    logging.debug(f"Before: args={args}, kwargs={kwargs}")
    # 处理逻辑...
    logging.debug(f"After: args={args}, kwargs={kwargs}")
    return func(*args, **kwargs)

# 或使用打印调试
def wrapper(*args, **kwargs):
    print(f"[DEBUG] args={args}, kwargs={kwargs}")
    # ...

---