From 9f4d342c3ac542c95d479bf79971b8b44235d4f2 Mon Sep 17 00:00:00 2001 From: Chen Long <1300851984@qq.com> Date: Thu, 19 May 2022 10:23:41 +0800 Subject: [PATCH] Fix API Docs bug (#42816) * update readme test=document_fix * fix api docs;test=document_fix * update logic.py;test=document_fix * update docs;test=document_fix --- python/paddle/tensor/attribute.py | 10 ++-- python/paddle/tensor/creation.py | 24 ++------ python/paddle/tensor/linalg.py | 83 ++++++++++++-------------- python/paddle/tensor/logic.py | 11 +--- python/paddle/tensor/manipulation.py | 27 +++++---- python/paddle/tensor/math.py | 88 ++++++++++++---------------- python/paddle/tensor/search.py | 13 ++-- 7 files changed, 108 insertions(+), 148 deletions(-) diff --git a/python/paddle/tensor/attribute.py b/python/paddle/tensor/attribute.py index 757b93dd88..ca8abdaf4b 100644 --- a/python/paddle/tensor/attribute.py +++ b/python/paddle/tensor/attribute.py @@ -36,10 +36,10 @@ __all__ = [] def rank(input): """ - The OP returns the number of dimensions for a tensor, which is a 0-D int32 Tensor. + Returns the number of dimensions for a tensor, which is a 0-D int32 Tensor. Args: - input (Tensor): The input N-D tensor with shape of :math:`[N_1, N_2, ..., N_k]`, the data type is arbitrary. + input (Tensor): The input Tensor with shape of :math:`[N_1, N_2, ..., N_k]`, the data type is arbitrary. Returns: Tensor, the output data type is int32.: The 0-D tensor with the dimensions of the input Tensor. @@ -246,15 +246,15 @@ def is_integer(x): def real(x, name=None): """ - Returns a new tensor containing real values of the input tensor. + Returns a new Tensor containing real values of the input Tensor. Args: - x (Tensor): the input tensor, its data type could be complex64 or complex128. + x (Tensor): the input Tensor, its data type could be complex64 or complex128. name (str, optional): The default value is None. Normally there is no need for user to set this property. For more information, please refer to :ref:`api_guide_Name` . Returns: - Tensor: a tensor containing real values of the input tensor. + Tensor: a Tensor containing real values of the input Tensor. Examples: .. code-block:: python diff --git a/python/paddle/tensor/creation.py b/python/paddle/tensor/creation.py index ab55ead71e..4580ff708e 100644 --- a/python/paddle/tensor/creation.py +++ b/python/paddle/tensor/creation.py @@ -439,7 +439,6 @@ def full_like(x, fill_value, dtype=None, name=None): .. code-block:: python import paddle - import numpy as np input = paddle.full(shape=[2, 3], fill_value=0.0, dtype='float32', name='input') output = paddle.full_like(input, 2.0) @@ -522,7 +521,7 @@ def ones(shape, dtype=None, name=None): def ones_like(x, dtype=None, name=None): """ - This OP returns a Tensor filled with the value 1, with the same shape and + Returns a Tensor filled with the value 1, with the same shape and data type (use ``dtype`` if ``dtype`` is not None) as ``x``. Args: @@ -540,10 +539,6 @@ def ones_like(x, dtype=None, name=None): Tensor: A Tensor filled with the value 1, with the same shape and data type (use ``dtype`` if ``dtype`` is not None) as ``x``. - Raise: - TypeError: If ``dtype`` is not None and is not bool, float16, float32, - float64, int32 or int64. - Examples: .. code-block:: python @@ -559,7 +554,7 @@ def ones_like(x, dtype=None, name=None): def zeros(shape, dtype=None, name=None): """ - The OP creates a tensor of specified :attr:`shape` and :attr:`dtype`, and fills it with 0. + Creates a tensor of specified :attr:`shape` and :attr:`dtype`, and fills it with 0. Args: shape(tuple|list|Tensor): Shape of the Tensor to be created, the data type of ``shape`` is int32 or int64. @@ -615,9 +610,6 @@ def zeros_like(x, dtype=None, name=None): Tensor: A Tensor filled with the value 0, with the same shape and data type (use ``dtype`` if ``dtype`` is not None) as ``x``. - Raise: - TypeError: If ``dtype`` is not None and is not bool, float16, float32, - float64, int32 or int64. Examples: .. code-block:: python @@ -989,10 +981,6 @@ def triu(x, diagonal=0, name=None): Tensor: Results of upper triangular operation by the specified diagonal of input tensor x, it's data type is the same as x's Tensor. - Raises: - TypeError: diagonal is not a int type. - ValueError: dimension of :attr:`x` is less than 2. - Examples: .. code-block:: python @@ -1037,13 +1025,12 @@ def triu(x, diagonal=0, name=None): def meshgrid(*args, **kwargs): """ - This op takes a list of N tensors as input *args, each of which is 1-dimensional - vector, and creates N-dimensional grids. + Takes a list of N tensors as input *args, each of which is 1-dimensional vector, and creates N-dimensional grids. Args: *args(Tensor|list of Tensor) : tensors (tuple(list) of tensor): the shapes of input k tensors are (N1,), (N2,),..., (Nk,). Support data types: ``float64``, ``float32``, ``int32``, ``int64``. - **kwargs (optional): Currently, we only accept name in **kwargs + **kwargs (optional): Currently, only accept name in **kwargs The default value is None. Normally there is no need for user to set this property. For more information, please refer to :ref:`api_guide_Name`. @@ -1414,7 +1401,7 @@ def empty(shape, dtype=None, name=None): def empty_like(x, dtype=None, name=None): """ - This Op returns a Tensor with uninitialized data which has identical shape of ``x`` and ``dtype``. + Returns a Tensor with uninitialized data which has identical shape of ``x`` and ``dtype``. If the ``dtype`` is None, the data type of Tensor is same with ``x``. Args: @@ -1432,7 +1419,6 @@ def empty_like(x, dtype=None, name=None): .. code-block:: python import paddle - import numpy as np paddle.set_device("cpu") # and use cpu device diff --git a/python/paddle/tensor/linalg.py b/python/paddle/tensor/linalg.py index 303a043827..9ba7ef532f 100644 --- a/python/paddle/tensor/linalg.py +++ b/python/paddle/tensor/linalg.py @@ -178,55 +178,44 @@ def matmul(x, y, transpose_x=False, transpose_y=False, name=None): Examples: - .. code-block:: python - - import paddle - import numpy as np - - # vector * vector - x_data = np.random.random([10]).astype(np.float32) - y_data = np.random.random([10]).astype(np.float32) - x = paddle.to_tensor(x_data) - y = paddle.to_tensor(y_data) - z = paddle.matmul(x, y) - print(z.numpy().shape) - # [1] - - # matrix * vector - x_data = np.random.random([10, 5]).astype(np.float32) - y_data = np.random.random([5]).astype(np.float32) - x = paddle.to_tensor(x_data) - y = paddle.to_tensor(y_data) - z = paddle.matmul(x, y) - print(z.numpy().shape) - # [10] - - # batched matrix * broadcasted vector - x_data = np.random.random([10, 5, 2]).astype(np.float32) - y_data = np.random.random([2]).astype(np.float32) - x = paddle.to_tensor(x_data) - y = paddle.to_tensor(y_data) - z = paddle.matmul(x, y) - print(z.numpy().shape) - # [10, 5] + .. code-block:: python - # batched matrix * batched matrix - x_data = np.random.random([10, 5, 2]).astype(np.float32) - y_data = np.random.random([10, 2, 5]).astype(np.float32) - x = paddle.to_tensor(x_data) - y = paddle.to_tensor(y_data) - z = paddle.matmul(x, y) - print(z.numpy().shape) - # [10, 5, 5] + import paddle - # batched matrix * broadcasted matrix - x_data = np.random.random([10, 1, 5, 2]).astype(np.float32) - y_data = np.random.random([1, 3, 2, 5]).astype(np.float32) - x = paddle.to_tensor(x_data) - y = paddle.to_tensor(y_data) - z = paddle.matmul(x, y) - print(z.numpy().shape) - # [10, 3, 5, 5] + # vector * vector + x = paddle.rand([10]) + y = paddle.rand([10]) + z = paddle.matmul(x, y) + print(z.shape) + # [1] + + # matrix * vector + x = paddle.rand([10, 5]) + y = paddle.rand([5]) + z = paddle.matmul(x, y) + print(z.shape) + # [10] + + # batched matrix * broadcasted vector + x = paddle.rand([10, 5, 2]) + y = paddle.rand([2]) + z = paddle.matmul(x, y) + print(z.shape) + # [10, 5] + + # batched matrix * batched matrix + x = paddle.rand([10, 5, 2]) + y = paddle.rand([10, 2, 5]) + z = paddle.matmul(x, y) + print(z.shape) + # [10, 5, 5] + + # batched matrix * broadcasted matrix + x = paddle.rand([10, 1, 5, 2]) + y = paddle.rand([1, 3, 2, 5]) + z = paddle.matmul(x, y) + print(z.shape) + # [10, 3, 5, 5] """ if in_dygraph_mode(): diff --git a/python/paddle/tensor/logic.py b/python/paddle/tensor/logic.py index 80a5f84824..31d2ec0557 100755 --- a/python/paddle/tensor/logic.py +++ b/python/paddle/tensor/logic.py @@ -333,13 +333,6 @@ def allclose(x, y, rtol=1e-05, atol=1e-08, equal_nan=False, name=None): Returns: Tensor: ${out_comment}. - Raises: - TypeError: The data type of ``x`` must be one of float32, float64. - TypeError: The data type of ``y`` must be one of float32, float64. - TypeError: The type of ``rtol`` must be float. - TypeError: The type of ``atol`` must be float. - TypeError: The type of ``equal_nan`` must be bool. - Examples: .. code-block:: python @@ -718,13 +711,13 @@ def not_equal(x, y, name=None): def is_tensor(x): """ - This function tests whether input object is a paddle.Tensor. + Tests whether input object is a paddle.Tensor. Args: x (object): Object to test. Returns: - A boolean value. True if 'x' is a paddle.Tensor, otherwise False. + A boolean value. True if ``x`` is a paddle.Tensor, otherwise False. Examples: .. code-block:: python diff --git a/python/paddle/tensor/manipulation.py b/python/paddle/tensor/manipulation.py index fd95d5de44..973f870d58 100755 --- a/python/paddle/tensor/manipulation.py +++ b/python/paddle/tensor/manipulation.py @@ -1486,7 +1486,9 @@ def roll(x, shifts, axis=None, name=None): shifts (int|list|tuple): The number of places by which the elements of the `x` tensor are shifted. axis (int|list|tuple, optional): axis(axes) along which to roll. Default: None - name (str, optional): Name for the operation. Default: None + name(str, optional): The default value is None. Normally there is no need for user to set this property. + For more information, please refer to :ref:`api_guide_Name` . + Returns: Tensor: A Tensor with same data type as `x`. @@ -2431,13 +2433,14 @@ def unbind(input, axis=0): import paddle - # input is a variable which shape is [3, 4, 5] - input = paddle.rand([3, 4, 5]).astype('float32') - + # input is a Tensor which shape is [3, 4, 5] + input = paddle.rand([3, 4, 5]) + [x0, x1, x2] = paddle.unbind(input, axis=0) # x0.shape [4, 5] # x1.shape [4, 5] # x2.shape [4, 5] + [x0, x1, x2, x3] = paddle.unbind(input, axis=1) # x0.shape [3, 5] # x1.shape [3, 5] @@ -2582,7 +2585,6 @@ def scatter_(x, index, updates, overwrite=True, name=None): def scatter_nd_add(x, index, updates, name=None): r""" - **Scatter_nd_add Layer** Output is obtained by applying sparse addition to a single value or slice in a Tensor. @@ -2639,15 +2641,16 @@ def scatter_nd_add(x, index, updates, name=None): .. code-block:: python import paddle - import numpy as np x = paddle.rand(shape=[3, 5, 9, 10], dtype='float32') updates = paddle.rand(shape=[3, 9, 10], dtype='float32') - index_data = np.array([[1, 1], - [0, 1], - [1, 3]]).astype(np.int64) - index = paddle.to_tensor(index_data) + index = paddle.to_tensor([[1, 1], + [0, 1], + [1, 3]], dtype='int64') + output = paddle.scatter_nd_add(x, index, updates) + print(output.shape) + # [3, 5, 9, 10] """ if in_dygraph_mode(): op = getattr(_C_ops, 'scatter_nd_add') @@ -3011,7 +3014,7 @@ def expand(x, shape, name=None): Args: - x (Tensor): The input tensor, its data type is bool, float32, float64, int32 or int64. + x (Tensor): The input Tensor, its data type is bool, float32, float64, int32 or int64. shape (list|tuple|Tensor): The result shape after expanding. The data type is int32. If shape is a list or tuple, all its elements should be integers or 1-D Tensors with the data type int32. If shape is a Tensor, it should be an 1-D Tensor with the data type int32. The value -1 in shape means keeping the corresponding dimension unchanged. @@ -3429,7 +3432,7 @@ def strided_slice(x, axes, starts, ends, strides, name=None): result = [ [2], ] Args: - x (Tensor): An N-D ``Tensor``. The data type is ``float32``, ``float64``, ``int32`` or ``int64``. + x (Tensor): An N-D ``Tensor``. The data type is ``bool``, ``float32``, ``float64``, ``int32`` or ``int64``. axes (list|tuple): The data type is ``int32`` . Axes that `starts` and `ends` apply to. It's optional. If it is not provides, it will be treated as :math:`[0,1,...,len(starts)-1]`. starts (list|tuple|Tensor): The data type is ``int32`` . If ``starts`` is a list or tuple, the elements of it should be integers or Tensors with shape [1]. If ``starts`` is an Tensor, it should be an 1-D Tensor. It represents starting indices of corresponding axis in ``axes``. diff --git a/python/paddle/tensor/math.py b/python/paddle/tensor/math.py index 35a16aa5f4..0be79ece01 100644 --- a/python/paddle/tensor/math.py +++ b/python/paddle/tensor/math.py @@ -90,7 +90,7 @@ _supported_float_dtype_ = [ def log(x, name=None): r""" - Calculates the natural log of the given input tensor, element-wise. + Calculates the natural log of the given input Tensor, element-wise. .. math:: @@ -154,7 +154,7 @@ def scale(x, scale=1.0, bias=0.0, bias_after_scale=True, act=None, name=None): name (str, optional): Name for the operation (optional, default is None). For more information, please refer to :ref:`api_guide_Name`. Returns: - Tensor: Output tensor of scale operator, with shape and data type same as input. + Tensor: Output Tensor of scale operator, with shape and data type same as input. Examples: .. code-block:: python @@ -340,7 +340,7 @@ def scale_(x, scale=1.0, bias=0.0, bias_after_scale=True, act=None, name=None): def pow(x, y, name=None): """ - Compute the power of tensor elements. The equation is: + Compute the power of Tensor elements. The equation is: .. math:: out = x^{y} @@ -859,7 +859,7 @@ def maximum(x, y, name=None): def minimum(x, y, name=None): """ - Compare two tensors and returns a new tensor containing the element-wise minima. The equation is: + Compare two tensors and return a new tensor containing the element-wise minima. The equation is: .. math:: out = min(x, y) @@ -873,7 +873,7 @@ def minimum(x, y, name=None): name (str, optional): Name for the operation (optional, default is None). For more information, please refer to :ref:`api_guide_Name`. Returns: - N-D Tensor. A location into which the result is stored. If x, y have different shapes and are "broadcastable", the resulting tensor shape is the shape of x and y after broadcasting. If x, y have the same shape, its shape is the same as x and y. + Tensor. If x, y have different shapes and are "broadcastable", the resulting tensor shape is the shape of x and y after broadcasting. If x, y have the same shape, its shape is the same as x and y. Examples: @@ -2660,7 +2660,6 @@ def clip_(x, min=None, max=None, name=None): def trace(x, offset=0, axis1=0, axis2=1, name=None): """ - **trace** Computes the sum along diagonals of the input tensor x. @@ -3048,7 +3047,7 @@ def isfinite(x, name=None): import paddle x = paddle.to_tensor([float('-inf'), -2, 3.6, float('inf'), 0, float('-nan'), float('nan')]) - out = paddle.tensor.isfinite(x) + out = paddle.isfinite(x) print(out) # [False True True False True False False] """ if in_dygraph_mode(): @@ -3077,8 +3076,9 @@ def isinf(x, name=None): .. code-block:: python import paddle + x = paddle.to_tensor([float('-inf'), -2, 3.6, float('inf'), 0, float('-nan'), float('nan')]) - out = paddle.tensor.isinf(x) + out = paddle.isinf(x) print(out) # [ True False False True False False False] """ if in_dygraph_mode(): @@ -3107,8 +3107,9 @@ def isnan(x, name=None): .. code-block:: python import paddle + x = paddle.to_tensor([float('-inf'), -2, 3.6, float('inf'), 0, float('-nan'), float('nan')]) - out = paddle.tensor.isnan(x) + out = paddle.isnan(x) print(out) # [False False False False False True True] """ if in_dygraph_mode(): @@ -3143,10 +3144,6 @@ def prod(x, axis=None, keepdim=False, dtype=None, name=None): Returns: Tensor, result of product on the specified dim of input tensor. - - Raises: - ValueError: The :attr:`dtype` must be float32, float64, int32 or int64. - TypeError: The type of :attr:`axis` must be int, list or tuple. Examples: .. code-block:: python @@ -3362,38 +3359,32 @@ def all(x, axis=None, keepdim=False, name=None): Returns: Tensor: Results the ``logical and`` on the specified axis of input Tensor `x`, it's data type is bool. - Raises: - ValueError: If the data type of `x` is not bool. - TypeError: The type of :attr:`axis` must be int, list or tuple. - Examples: .. code-block:: python import paddle - import numpy as np - + # x is a bool Tensor with following elements: # [[True, False] # [True, True]] - x = paddle.assign(np.array([[1, 0], [1, 1]], dtype='int32')) + x = paddle.to_tensor([[1, 0], [1, 1]], dtype='int32') print(x) x = paddle.cast(x, 'bool') - + # out1 should be [False] out1 = paddle.all(x) # [False] print(out1) - + # out2 should be [True, False] out2 = paddle.all(x, axis=0) # [True, False] print(out2) - - # keep_dim=False, out3 should be [False, True], out.shape should be (2,) + + # keepdim=False, out3 should be [False, True], out.shape should be (2,) out3 = paddle.all(x, axis=-1) # [False, True] print(out3) - - # keep_dim=True, out4 should be [[False], [True]], out.shape should be (2,1) - out4 = paddle.all(x, axis=1, keepdim=True) - out4 = paddle.cast(out4, 'int32') # [[False], [True]] + + # keepdim=True, out4 should be [[False], [True]], out.shape should be (2,1) + out4 = paddle.all(x, axis=1, keepdim=True) # [[False], [True]] print(out4) """ @@ -3440,7 +3431,7 @@ def all(x, axis=None, keepdim=False, name=None): def any(x, axis=None, keepdim=False, name=None): """ - Computes the ``logical or`` of tensor elements over the given dimension. + Computes the ``logical or`` of tensor elements over the given dimension, and return the result. Args: x (Tensor): An N-D Tensor, the input data type should be `bool`. @@ -3458,39 +3449,34 @@ def any(x, axis=None, keepdim=False, name=None): Returns: Tensor: Results the ``logical or`` on the specified axis of input Tensor `x`, it's data type is bool. - Raises: - ValueError: If the data type of `x` is not bool. - TypeError: The type of :attr:`axis` must be int, list or tuple. - Examples: .. code-block:: python import paddle - import numpy as np - - # x is a bool Tensor with following elements: - # [[True, False] - # [False, False]] - x = paddle.assign(np.array([[1, 0], [1, 1]], dtype='int32')) + + x = paddle.to_tensor([[1, 0], [1, 1]], dtype='int32') + x = paddle.assign(x) print(x) x = paddle.cast(x, 'bool') - + # x is a bool Tensor with following elements: + # [[True, False] + # [True, True]] + # out1 should be [True] out1 = paddle.any(x) # [True] print(out1) - + # out2 should be [True, True] out2 = paddle.any(x, axis=0) # [True, True] print(out2) - - # keep_dim=False, out3 should be [True, True], out.shape should be (2,) + + # keepdim=False, out3 should be [True, True], out.shape should be (2,) out3 = paddle.any(x, axis=-1) # [True, True] print(out3) - - # keep_dim=True, result should be [[True], [True]], out.shape should be (2,1) - out4 = paddle.any(x, axis=1, keepdim=True) - out4 = paddle.cast(out4, 'int32') # [[True], [True]] - print(out4) + + # keepdim=True, result should be [[True], [True]], out.shape should be (2,1) + out4 = paddle.any(x, axis=1, keepdim=True) # [[True], [True]] + print(out4) """ if axis is not None and not isinstance(axis, (list, tuple)): @@ -3566,18 +3552,18 @@ def conj(x, name=None): This function computes the conjugate of the Tensor elementwisely. Args: - x (Tensor): The input tensor which hold the complex numbers. + x (Tensor): The input Tensor which hold the complex numbers. Optional data types are: complex64, complex128, float32, float64, int32 or int64. name (str, optional): Name for the operation (optional, default is None). For more information, please refer to :ref:`api_guide_Name`. Returns: - out (Tensor): The conjugate of input. The shape and data type is the same with input. - If the elements of tensor is real type such as float32, float64, int32 or int64, the out is the same with input. + out (Tensor): The conjugate of input. The shape and data type is the same with input. If the elements of tensor is real type such as float32, float64, int32 or int64, the out is the same with input. Examples: .. code-block:: python import paddle + data=paddle.to_tensor([[1+1j, 2+2j, 3+3j], [4+4j, 5+5j, 6+6j]]) #Tensor(shape=[2, 3], dtype=complex64, place=CUDAPlace(0), stop_gradient=True, # [[(1+1j), (2+2j), (3+3j)], diff --git a/python/paddle/tensor/search.py b/python/paddle/tensor/search.py index f09a532cfd..02a71a80b9 100644 --- a/python/paddle/tensor/search.py +++ b/python/paddle/tensor/search.py @@ -41,7 +41,7 @@ def argsort(x, axis=-1, descending=False, name=None): int32, int64, uint8. axis(int, optional): Axis to compute indices along. The effective range is [-R, R), where R is Rank(x). when axis<0, it works the same way - as axis+R. Default is 0. + as axis+R. Default is -1. descending(bool, optional) : Descending is a flag, if set to true, algorithm will sort by descending order, else sort by ascending order. Default is false. @@ -66,9 +66,10 @@ def argsort(x, axis=-1, descending=False, name=None): [4,7,7,9], [1,7,0,6]]], dtype='float32') - out1 = paddle.argsort(x=x, axis=-1) - out2 = paddle.argsort(x=x, axis=0) - out3 = paddle.argsort(x=x, axis=1) + out1 = paddle.argsort(x, axis=-1) + out2 = paddle.argsort(x, axis=0) + out3 = paddle.argsort(x, axis=1) + print(out1) #[[[0 3 1 2] # [0 1 2 3] @@ -76,6 +77,7 @@ def argsort(x, axis=-1, descending=False, name=None): # [[1 3 2 0] # [0 1 2 3] # [2 0 3 1]]] + print(out2) #[[[0 1 1 1] # [0 0 0 0] @@ -83,6 +85,7 @@ def argsort(x, axis=-1, descending=False, name=None): # [[1 0 0 0] # [1 1 1 1] # [0 0 0 1]]] + print(out3) #[[[1 1 1 2] # [0 0 2 0] @@ -771,7 +774,7 @@ def index_sample(x, index): def masked_select(x, mask, name=None): """ - This OP Returns a new 1-D tensor which indexes the input tensor according to the ``mask`` + Returns a new 1-D tensor which indexes the input tensor according to the ``mask`` which is a tensor with data type of bool. Args: -- GitLab