[API Compatibility No.352、377] Add torch-style arg and alias for `std` -part #77006

algorithm1832 · 2025-12-21T08:22:49Z

PR Category

User Experience

PR Types

Improvements

Description

API & Unittest & EN Doc

Use decorator to add arg alias input and dim
Add arg out and correction
Add arg alias notes in EN doc
Add arg description for new args in EN doc
Add more examples in EN doc
Add compatibility test for std
Add arg correction test for std
Fix typo in std tests

Used AI Studio

paddle-bot · 2025-12-21T08:22:59Z

你的PR提交成功，感谢你对开源项目的贡献!
请关注后续CI自动化测试结果，详情请参考Paddle-CI手册。
Your PR has been submitted. Thanks for your contribution!
Please wait for the result of CI firstly. See Paddle CI Manual for details.

algorithm1832 · 2025-12-21T11:17:34Z

/re-run all-failed

codecov-commenter · 2025-12-21T12:17:49Z

Codecov Report

❌ Patch coverage is 93.75000% with 1 line in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (develop@ec01e8a). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
python/paddle/utils/decorator_utils.py	88.88%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             develop   #77006   +/-   ##
==========================================
  Coverage           ?   93.75%           
==========================================
  Files              ?        2           
  Lines              ?       16           
  Branches           ?        0           
==========================================
  Hits               ?       15           
  Misses             ?        1           
  Partials           ?        0

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

python/paddle/tensor/stat.py

Copilot

Pull request overview

This PR enhances the paddle.std function to support PyTorch-style parameter aliases and adds new functionality including the correction parameter and out parameter support. The changes aim to improve API compatibility with PyTorch.

Key Changes

Refactored std function implementation to use *args, **kwargs forwarding to the var function
Added comprehensive test coverage for parameter aliases (input for x, dim for axis), the new correction parameter, and the out parameter
Fixed typos in existing tests (expact_out → expect_out)

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
`test/legacy_test/test_std_layer.py`	Added new test classes for compatibility testing (aliases) and correction parameter testing; fixed typos in variable names
`python/paddle/tensor/stat.py`	Refactored `std` function to forward arguments to `var` and handle the `out` parameter for sqrt operation
`python/paddle/_paddle_docs.py`	Added comprehensive documentation for `std` including alias notes, new parameter descriptions, and usage examples

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-12-26T06:23:22Z

python/paddle/tensor/stat.py

+def std(*args, **kwargs) -> Tensor:
+    variance = var(*args, **kwargs)
+    if 'out' in kwargs:
+        return paddle.sqrt(variance, out=kwargs['out'])


The refactored std function forwards all arguments to var using *args and **kwargs, but this approach has a problem: when the decorator is added to enable parameter aliases, the function needs a proper signature to work correctly with the decorator. The decorator needs to know which parameters to alias, but with *args, **kwargs, there's no explicit signature to decorate. The function should have an explicit signature matching the documented parameters (x, axis, unbiased, keepdim, name, correction, out) similar to the var function, and then be decorated with @ParamAliasDecorator({"x": ["input"], "axis": ["dim"]}) or @param_two_alias(["x", "input"], ["axis", "dim"]).

Suggested change

def std(*args, **kwargs) -> Tensor:

variance = var(*args, **kwargs)

if 'out' in kwargs:

return paddle.sqrt(variance, out=kwargs['out'])

@ParamAliasDecorator({"x": ["input"], "axis": ["dim"]})

def std(

x,

axis=None,

unbiased: bool = True,

keepdim: bool = False,

name: str | None = None,

correction=None,

out=None,

) -> Tensor:

variance = var(

x,

axis=axis,

unbiased=unbiased,

keepdim=keepdim,

name=name,

correction=correction,

out=out,

)

if out is not None:

return paddle.sqrt(variance, out=out)

Copilot · 2025-12-26T06:23:23Z

python/paddle/tensor/stat.py

+    variance = var(*args, **kwargs)
+    if 'out' in kwargs:
+        return paddle.sqrt(variance, out=kwargs['out'])


The handling of the out parameter needs careful consideration. The current implementation extracts out from kwargs and passes it to paddle.sqrt. However, the var function is also called with all kwargs including out, which means out would first receive the variance result from var, and then be overwritten with the sqrt result. This could lead to incorrect behavior if the var function tries to assign to out. The implementation should either remove out from kwargs before calling var, or handle this more explicitly in the proper signature-based implementation.

Suggested change

variance = var(*args, **kwargs)

if 'out' in kwargs:

return paddle.sqrt(variance, out=kwargs['out'])

out = kwargs.pop('out', None)

variance = var(*args, **kwargs)

if out is not None:

return paddle.sqrt(variance, out=out)

Copilot · 2025-12-26T06:23:23Z

python/paddle/_paddle_docs.py

+            >>> print(out4.numpy())
+            [[1.721326]]
+
+            >>> out5 = paddle.std(input=x, dim=[0, 1])  # type: ignore[call-arg]


The documentation example on line 3361 contains a type ignore comment that indicates the signature doesn't properly support the alias parameters (input and dim). This is correct given that the implementation is missing the required decorator to enable these aliases. Once the decorator is added to the std function in stat.py, this type ignore comment should be removed as the call will be type-safe.

Suggested change

>>> out5 = paddle.std(input=x, dim=[0, 1]) # type: ignore[call-arg]

>>> out5 = paddle.std(input=x, dim=[0, 1])

zhwesky2010

文档位置不对

python/paddle/tensor/stat.py

zhwesky2010

这两个API不仅仅是参数名不同，涉及到更多的参数差异。

case有点复杂，先跑一下PaConvert，本地先验证PaConvert能通过后，再提交paddle。

zhwesky2010 · 2026-01-07T10:19:30Z

python/paddle/tensor/stat.py

-        )
-    out = var(**locals())
-    return paddle.sqrt(out)
+    variance = var(*args, **kwargs)


看来std、var这两个API不是简单的别名替换。

需要一套参数分发的逻辑，参考group_norm、gather的写法，这里需要处理args/kwargs来判断overload的两种签名。

var是底层的接口，先处理好var，std只需要这么写就行：

return sqrt(var(*args, **kwargs), out=out)

out=None的默认缺省逻辑在各API底层以及下沉后都会有，不需要重复判断。

那个if逻辑可能删不了，out需要从kwargs里面取，取不到的话会报KeyError。目前的实现也不涉及像gather一样新定义一个wrapper。

algorithm1832 · 2026-01-09T16:33:43Z

/re-run all-failed

algorithm1832 · 2026-01-12T06:07:10Z

/re-run all-failed

algorithm1832 · 2026-01-12T06:07:38Z

PaConvert自测通过了

zhwesky2010

LGTM

SigureMo · 2026-01-12T09:13:55Z

python/paddle/tensor/stat.py

+    *,
+    correction: float = 1,
+    out: Tensor | None = None,
+) -> Tensor: ...


只有一种签名？这里用 overload 的意义是什么？

SigureMo · 2026-01-12T09:17:09Z

python/paddle/tensor/stat.py

+) -> Tensor: ...
+
+
+def std(*args: Any, **kwargs: Any) -> Tensor:


这样的话，签名会丢掉

algorithm1832 · 2026-01-12T11:21:02Z

这里用 overload 的意义是什么？

因为使用def std(*args: Any, **kwargs: Any)的形式原有签名就没了，所以加了overload，参考的是paddle.nn.group_norm的实现

不过现在加了overload签名还是没有的话，我可能需要再看一下怎么补上

SigureMo · 2026-01-12T11:29:42Z

因为使用def std(*args: Any, **kwargs: Any)的形式原有签名就没了，所以加了overload，参考的是paddle.nn.group_norm的实现

overload 不影响运行时，是静态检查所用，是为多种类型签名提供的解决方案，对于只有一个签名的函数来说没有意义，也不合法

如果只有一种签名，这个 API 为什么要用 *args, **kwargs？为什么不能写清每个参数？

algorithm1832 · 2026-01-12T11:40:06Z

如果只有一种签名，这个 API 为什么要用 *args, **kwargs？为什么不能写清每个参数？

常规思路是加一层装饰器实现参数别名，但这个对性能影响比较严重，所以现在实现的是不用装饰器的方案

API std 的实现实际上是先调用var再调用sqrt，目前var和sqrt两个API都支持别名，所以直接把std接收到的参数转发给var，就可以省下装饰器

然而如果std原先的签名不进行修改，对于参数别名输入（如input）会报TypeError，而且对于有别名的参数（如x和input）都需要设置成optional否则也会报错。所以最后变成了 *args, **kwargs 的形式

SigureMo · 2026-01-12T11:45:09Z

API std 的实现实际上是先调用var再调用sqrt，目前var和sqrt两个API都支持别名，所以直接把std接收到的参数转发给var，就可以省下装饰器

既然有别名，那为什么会只有一个签名？这不对吧，参考的 paddle.nn.group_norm 也不是只有一个签名啊……

algorithm1832 · 2026-01-12T11:50:24Z

这不对吧

确实不对，理论上最好应该是paddle用法一个签名，torch用法一个签名，这样可以包括所有的参数可能性

不过因为std和var是一起的，var用了装饰器所以只有一个签名，所以std为了保持一致就只写了一个签名。另外，torch用法和paddle用法除了别名以外，其它的好像一样，实现的功能也是一致

要不给torch用法（别名用法）加个签名（?

SigureMo · 2026-01-12T12:29:22Z

要不给torch用法（别名用法）加个签名（?

加，这种才是合理的写法

运行时签名需要单独考虑，可以考虑使用其第一个签名，可以加一个简单的装饰器来实现这一点

from typing import overload, Any, get_overloads, TypeVar
from typing_extensions import ParamSpec
from collections.abc import Callable
import inspect

P = ParamSpec("P")
R = TypeVar("R")


def use_first_signature(fn: Callable[P, R]) -> Callable[P, R]:
    overloads = get_overloads(fn)
    if not overloads:
        return fn
    first_overload = overloads[0]
    sig = inspect.signature(first_overload)
    fn.__signature__ = sig
    return fn


@overload
def fn(x: int) -> int: ...


@overload
def fn(x: str) -> str: ...


@use_first_signature
def fn(*args: Any, **kwargs: Any) -> Any: ...


print(inspect.getfullargspec(fn))

这个装饰器对装饰后的函数没有额外运行时开销，不必担心

目前以 Paddle 签名为主，所以 Paddle 签名写在前面

algorithm1832 · 2026-01-12T13:18:40Z

签名和重载加好了，虽说参数keepdim在paddle和torch中参数类型不同（torch中此参数不可以是位置参数），不过如果从torch迁移，直接修改torch.std为paddle.std不会有任何问题

algorithm1832 · 2026-01-13T02:17:19Z

/re-run all-failed

zhwesky2010

LGTM

algorithm1832 added 2 commits December 21, 2025 16:13

decorate api std, update EN doc, update tests

96560a1

add alias support notes

712c4cf

paddle-bot bot added the contributor External developers label Dec 21, 2025

luotao1 mentioned this pull request Dec 22, 2025

【启航计划】PaddlePaddle API兼容性增强 #76301

Open

zhwesky2010 added the API Compatibility label Dec 22, 2025

zhwesky2010 reviewed Dec 22, 2025

View reviewed changes

python/paddle/tensor/stat.py Show resolved Hide resolved

algorithm1832 added 2 commits December 26, 2025 05:46

attempt use arg forward for std

b20b4c6

Merge branch 'develop' into improvement_20251221_std

6e92cb7

zhwesky2010 reviewed Dec 26, 2025

View reviewed changes

python/paddle/tensor/stat.py Outdated Show resolved Hide resolved

SigureMo requested a review from Copilot December 26, 2025 06:13

Copilot started reviewing on behalf of SigureMo December 26, 2025 06:13 View session

Copilot AI reviewed Dec 26, 2025

View reviewed changes

zhwesky2010 reviewed Jan 5, 2026

View reviewed changes

python/paddle/tensor/stat.py Outdated Show resolved Hide resolved

algorithm1832 added 3 commits January 5, 2026 12:17

move doc and add signature

c594a1e

merge branch develop

df53d56

fix EN doc

e6136e4

zhwesky2010 reviewed Jan 7, 2026

View reviewed changes

algorithm1832 added 2 commits January 9, 2026 10:32

merge branch develop

345ac53

update std signature

e0d2265

fix EN doc

04a19fb

zhwesky2010 previously approved these changes Jan 12, 2026

View reviewed changes

zhwesky2010 requested a review from SigureMo January 12, 2026 09:08

SigureMo reviewed Jan 12, 2026

View reviewed changes

add torch-style overload and function signature for std

bc34d71

algorithm1832 dismissed zhwesky2010’s stale review via bc34d71 January 12, 2026 13:16

remove unused type:ignore

1bcf808

SigureMo approved these changes Jan 12, 2026

View reviewed changes

zhwesky2010 approved these changes Jan 13, 2026

View reviewed changes

zhwesky2010 merged commit d99f03c into PaddlePaddle:develop Jan 13, 2026
138 of 146 checks passed

This was referenced Jan 18, 2026

[API Compatibility No.352、377] Align torch.std -part PaddlePaddle/PaConvert#804

Open

[API Compatibility No.352、377] Align torch.std PaddlePaddle/docs#7680

Open

-def std(*args, **kwargs) -> Tensor:
-    variance = var(*args, **kwargs)
-    if 'out' in kwargs:
-        return paddle.sqrt(variance, out=kwargs['out'])
+@ParamAliasDecorator({"x": ["input"], "axis": ["dim"]})
+def std(
+    x,
+    axis=None,
+    unbiased: bool = True,
+    keepdim: bool = False,
+    name: str | None = None,
+    correction=None,
+    out=None,
+) -> Tensor:
+    variance = var(
+        x,
+        axis=axis,
+        unbiased=unbiased,
+        keepdim=keepdim,
+        name=name,
+        correction=correction,
+        out=out,
+    )
+    if out is not None:
+        return paddle.sqrt(variance, out=out)

	>>> out5 = paddle.std(input=x, dim=[0, 1]) # type: ignore[call-arg]
	>>> out5 = paddle.std(input=x, dim=[0, 1])

		) -> Tensor: ...


		def std(args: Any, *kwargs: Any) -> Tensor:

[API Compatibility No.352、377] Add torch-style arg and alias for std -part #77006

[API Compatibility No.352、377] Add torch-style arg and alias for std -part #77006

Uh oh!

Conversation

algorithm1832 commented Dec 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Category

PR Types

Description

Uh oh!

paddle-bot bot commented Dec 21, 2025

Uh oh!

algorithm1832 commented Dec 21, 2025

Uh oh!

codecov-commenter commented Dec 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Key Changes

Reviewed changes

Uh oh!

Copilot AI Dec 26, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 26, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 26, 2025

Choose a reason for hiding this comment

Uh oh!

zhwesky2010 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

zhwesky2010 left a comment

Choose a reason for hiding this comment

Uh oh!

zhwesky2010 Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

algorithm1832 Jan 9, 2026

Choose a reason for hiding this comment

Uh oh!

algorithm1832 commented Jan 9, 2026

Uh oh!

algorithm1832 commented Jan 12, 2026

Uh oh!

algorithm1832 commented Jan 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

zhwesky2010 left a comment

Choose a reason for hiding this comment

Uh oh!

SigureMo Jan 12, 2026

Choose a reason for hiding this comment

Uh oh!

SigureMo Jan 12, 2026

Choose a reason for hiding this comment

Uh oh!

algorithm1832 commented Jan 12, 2026

Uh oh!

SigureMo commented Jan 12, 2026

Uh oh!

algorithm1832 commented Jan 12, 2026

Uh oh!

SigureMo commented Jan 12, 2026

Uh oh!

algorithm1832 commented Jan 12, 2026

Uh oh!

SigureMo commented Jan 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

algorithm1832 commented Jan 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

[API Compatibility No.352、377] Add torch-style arg and alias for `std` -part #77006

[API Compatibility No.352、377] Add torch-style arg and alias for `std` -part #77006

algorithm1832 commented Dec 21, 2025 •

edited

Loading

codecov-commenter commented Dec 21, 2025 •

edited

Loading

zhwesky2010 left a comment •

edited

Loading

algorithm1832 commented Jan 12, 2026 •

edited

Loading

SigureMo commented Jan 12, 2026 •

edited

Loading

algorithm1832 commented Jan 12, 2026 •

edited

Loading