[Question] Tensor inplace-api 的使用方式与文档展示

[ooooo-create]

请提出你的问题 Please ask your question

参照 issue63054,此 issue 展示了中文 api 文档下的 paddle.flatten_ 无法使用的问题。透露出两个问题，一个是 api 文档对于 inplace-api 是如何进行展示的，以及 inplace-api 是否需要暴露在 paddle 下。

api 文档现状（对于Tensor 相关）

中文 api 文档，通过 rst 文件手动撰写 api 文档。其中对于 paddle 下的 api (包括 inplace-api)，都是存放在 paddle 目录下。

- paddle
    - amp
        - ...
    - ...
    - add_cn.rst
    - add__cn.rst
    - ...
    - Tensor_cn.rst
    - ...
# 所有 inplace-api 在文档中都是暴露在 paddle 下

而英文 api 文档目前通过不同模块和文件中的 _all_ 属性中的元素进行公开文档展示(添加到 _all_ 才会展示在官网中)

python模块中的__all__，用于模块导入时限制，如：from module import *。paddle 借用此进行公开 api 管理

<Paddle\python\paddle\__init__.py>
...
_all_ = [
    'iinfo',
    ...
    'cos',
    'add',
    ...
]
...
# 导入 __init__.py（以及没有导入） 却没有加入 _all_ 的 api 文档展示在 paddle.Tensor 下

inpalce-api 使用方式

通过 dir(paddle) 以及 dir(paddle.Tensor) 发现些许 inplace-api 并没有暴露到 paddle 下（没有导入在 paddle 的 __init__.py 中）.

>>> import paddle
>>> a = paddle.to_tensor([1])
>>> paddle.add_(a,20)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
AttributeError: module 'paddle' has no attribute 'add_'. Did you mean: 'add'?

如果需要暴露，是不是所有 inpalce-api 都需要暴露到 paddle 下（需要补全未暴露的）

pytorch 的 inplace-api 是不会通过 torch.[inplace-api] 使用的

问题

1. inplace-api 的使用方式
2. 以及文档展示的 inplace-api 使用方式

api 列表

tensor inplace api	英文文档是否展示在paddle下	paddle.[inplace]是否可以使用
acosh_	❌	✅
add_	❌	❌
apply_	❌	❌
asin_	❌	✅
asinh_	❌	✅
atanh_	❌	✅
ceil_	❌	❌
clip_	❌	❌
copy_	❌	❌
cosh_	❌	✅
detach_	❌	❌
erfinv_	❌	❌
exp_	❌	❌
exponential_	❌	❌
fill_	❌	❌
fill_diagonal_	❌	❌
fill_diagonal_tensor_	❌	❌
flatten_	❌	❌
floor_	❌	❌
grad_	❌	❌
lerp_	❌	❌
log1p_	❌	✅
logical_xor_	❌	✅
not_equal_	❌	✅
put_along_axis_	❌	❌
reciprocal_	❌	❌
reconstruct_from_	❌	❌
round_	❌	❌
rsqrt_	❌	❌
scale_	❌	❌
sigmoid_	❌	❌
sqrt_	❌	❌
subtract_	❌	❌
uniform_	❌	❌
zero_	❌	❌

[GGBond8488]

感谢你的意见，从inplace 语义的角度出发，Tensor.xxx_ 形式的api 更合适，我们将会在后面的版本中将paddle.xxx_ 公开API转为非公开API，原有的调用路径也仍然保留。

[ooooo-create]

感谢你的意见，从inplace 语义的角度出发，Tensor.xxx_ 形式的api 更合适，我们将会在后面的版本中将paddle.xxx_ 公开API转为非公开API，原有的调用路径也仍然保留。

❤️感谢答复~
还有几个问题想问问~

1. 那中文文档里的 inplace api文档现在是不是就可以统一放在paddle.Tensor下了
2. 调用路径保留的话，目前还有些 inplace-api （统计在issue中）不能通过 paddle.xxx_ 调用，比如 paddle.add_，这些还需不需要补充到paddle下呢（因为观察到许多paddle资料，确实写了paddle.add_这种用法，但是 paddle 下却没有 add_ 方法）

https://github.com/PaddlePaddle/community/blob/e71c523c5580cf9755fb29e78755a58e372b5cd8/pfcc/paddle-code-reading/Inplace/inplace_introduction.md?plain=1#L22-L23

https://github.com/PaddlePaddle/community/blob/e71c523c5580cf9755fb29e78755a58e372b5cd8/rfcs/Article/20240321_guide_to_using_Inplace.md?plain=1#L40

[GGBond8488]

感谢你的意见，从inplace 语义的角度出发，Tensor.xxx_ 形式的api 更合适，我们将会在后面的版本中将paddle.xxx_ 公开API转为非公开API，原有的调用路径也仍然保留。

❤️感谢答复~ 还有几个问题想问问~

1. 那中文文档里的 inplace api文档现在是不是就可以统一放在paddle.Tensor下了
2. 调用路径保留的话，目前还有些 inplace-api （统计在issue中）不能通过 paddle.xxx_ 调用，比如 paddle.add_，这些还需不需要补充到paddle下呢（因为观察到许多paddle资料，确实写了paddle.add_这种用法，但是 paddle 下却没有 add_ 方法）

https://github.com/PaddlePaddle/community/blob/e71c523c5580cf9755fb29e78755a58e372b5cd8/pfcc/paddle-code-reading/Inplace/inplace_introduction.md?plain=1#L22-L23

https://github.com/PaddlePaddle/community/blob/e71c523c5580cf9755fb29e78755a58e372b5cd8/rfcs/Article/20240321_guide_to_using_Inplace.md?plain=1#L40

1.是的，中文文档里面的可以统一放在paddle.Tensor下了
2. 这些语料可能是当时审核不够仔细，后续也不会新增paddle.add_的调用方式，上述错误的地方你可以提pr改正

[ooooo-create]

1.是的，中文文档里面的可以统一放在paddle.Tensor下了

这个中文文档是统一放在 https://github.com/PaddlePaddle/docs/blob/develop/docs/api/paddle/Tensor_cn.rst 这单一文件里吗，（这样可能会导致官网搜索 inplace api 搜不到、并且此文档太长）

同时英文文档对于 Tensor 方法的展示除了在 paddle.Tensor 单一文件下，还有 paddle.Tensor 这一目录下，进行展示，这样是不是重复了（虽然加了 paddle.Tensor 这一目录可以方便用户搜索 inplace_api，但是此目录似乎用处不大，因为目前只会显示那些没有暴露到 paddle.xxx 中的 Tensor 方法），中文文档该对齐哪一种方式呢？

2. 我们将会在后面的版本中将paddle.xxx_ 公开API转为非公开API

是否需要由社区开发者来屏蔽paddle.{inplace} 这个路径