[*.py] Rename "Arguments:" to "Args:" (pytorch#49736)

Summary:
I've written custom parsers and emitters for everything from docstrings to classes and functions. However, I recently came across an issue when I was parsing/generating from the TensorFlow codebase: inconsistent use of `Args:` and `Arguments:` in its docstrings.

```sh
(pytorch#c348fae)$ for name in 'Args:' 'Arguments:'; do
    printf '%-10s %04d\n' "$name" "$(rg -IFtpy --count-matches "$name" | paste -s -d+ -- | bc)"; done
Args:      1095
Arguments: 0336
```

It is easy enough to extend my parsers to support both variants, however it looks like `Arguments:` is wrong anyway, as per:

  - https://google.github.io/styleguide/pyguide.html#doc-function-args @ [`ddccc0f`](https://github.com/google/styleguide/blob/ddccc0f/pyguide.md)

  - https://chromium.googlesource.com/chromiumos/docs/+/master/styleguide/python.md#describing-arguments-in-docstrings @ [`9fc0fc0`](https://chromium.googlesource.com/chromiumos/docs/+/9fc0fc0/styleguide/python.md)

  - https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html @ [`c0ae8e3`](https://github.com/sphinx-contrib/napoleon/blob/c0ae8e3/docs/source/example_google.rst)

Therefore, only `Args:` is valid. This PR replaces them throughout the codebase.

PS: For related PRs, see tensorflow/tensorflow/pull/45420

PPS: The trackbacks automatically appearing below are sending the same changes to other repositories in the [PyTorch](https://github.com/pytorch) organisation.

Pull Request resolved: pytorch#49736

Reviewed By: albanD

Differential Revision: D25710534

Pulled By: soumith

fbshipit-source-id: 61e8ff01abb433e9f78185c2d1d0cbd7c22c1619

Author: SamuelMarks

benchmarks/functional_autograd_benchmark/torchvision_models.py

@@ -247,7 +247,7 @@ class IntermediateLayerGetter(nn.ModuleDict):
     Additionally, it is only able to query submodules that are directly
     assigned to the model. So if `model` is passed, `model.feature1` can
     be returned, but not `model.feature1.layer2`.
-    Arguments:
+    Args:
         model (nn.Module): model on which we will extract the features
         return_layers (Dict[name, new_name]): a dict containing the names
             of the modules for which the activations will be returned as
@@ -324,7 +324,7 @@ def forward(self, x):
 class FCN(_SimpleSegmentationModel):
     """
     Implements a Fully-Convolutional Network for semantic segmentation.
-    Arguments:
+    Args:
         backbone (nn.Module): the network used to compute the features for the model.
             The backbone should return an OrderedDict[Tensor], with the key being
             "out" for the last feature map used, and "aux" if an auxiliary classifier
@@ -509,7 +509,7 @@ def box_area(boxes):
     """
     Computes the area of a set of bounding boxes, which are specified by its
     (x1, y1, x2, y2) coordinates.
-    Arguments:
+    Args:
         boxes (Tensor[N, 4]): boxes for which the area will be computed. They
             are expected to be in (x1, y1, x2, y2) format
     Returns:

caffe2/python/data_parallel_model.py

@@ -1056,7 +1056,7 @@ def sumN(*dev_indices):
         """Create a Sum op for 2 or more blobs on different devices.
         Saves the result on the first device.
 
-        Arguments:
+        Args:
         dev_indices -- a list of device indices, which can be translated into
                        CUDA identifiers with model._devices
         """

caffe2/python/layers/merge_id_lists.py

@@ -16,7 +16,7 @@
 class MergeIdLists(ModelLayer):
     """Merge multiple ID_LISTs into a single ID_LIST
 
-    Arguments:
+    Args:
         model: A layer model instance
         input_record: Tuple (Struct) of ID_LIST features to be
         merged

caffe2/python/net_builder.py

@@ -13,7 +13,7 @@
 class NetBuilder(context.Managed):
     """
     Scope-driven mechanism for building nets, loops and conditional blocks.
-    Arguments:
+    Args:
       name: NetBuilder's name
       initial_scope: list of blobs that are available for reading/writing
     Example:

docs/source/onnx.rst

@@ -755,7 +755,7 @@ but intuitively the interface they provide looks like this::
       ONNX outputs whose values correspond to the original PyTorch return values
       of the autograd Function (or None if an output is not supported by ONNX).
 
-      Arguments:
+      Args:
         g (Graph): graph to write the ONNX representation into
         inputs (Value...): list of values representing the variables which contain
             the inputs for this function
@@ -782,7 +782,7 @@ but intuitively the interface they provide looks like this::
         The set of operators and the inputs/attributes they take
         is documented at https://github.com/onnx/onnx/blob/master/docs/Operators.md
 
-        Arguments:
+        Args:
             opname (string): The ONNX operator name, e.g., `Abs` or `Add`.
             args (Value...): The inputs to the operator; usually provided
                 as arguments to the `symbolic` definition.

test/onnx/pytorch_helper.py

@@ -23,7 +23,7 @@ def PyTorchModule(helper, model, sample_arguments, caffe2_inputs, prefix_name=No
     """
     Embed an ONNX-exportable PyTorch Model into a Caffe2 model being built.
 
-    Arguments:
+    Args:
         helper (caffe2.python.core.ModelHelder): the model helper where
             this imported network should be inserted
         model (torch.nn.Module): the model to be exported

test/onnx/verify.py

@@ -246,7 +246,7 @@ def verify(model, args, backend, verbose=False, training=torch.onnx.TrainingMode
     For reproducibility, we recommend explicitly setting PyTorch's seed before
     invoking this function.
 
-    Arguments:
+    Args:
         model (torch.nn.Module): the model to be exported and verified
         args (tuple of arguments): the inputs to
             the model, e.g., such that ``model(*args)`` is a valid

test/run_test.py

@@ -617,7 +617,7 @@ def find_test_index(test, selected_tests, find_last_index=False):
     If :attr:`test`='torch' and :attr:`find_last_index`=False, result should be **2**.
     If :attr:`test`='torch' and :attr:`find_last_index`=True, result should be **4**.
 
-    Arguments:
+    Args:
         test (str): Name of test to lookup
         selected_tests (list): List of tests
         find_last_index (bool, optional): should we lookup the index of first or last

tools/setup_helpers/cmake.py

@@ -32,7 +32,7 @@ def _mkdir_p(d):
 def convert_cmake_value_to_python_value(cmake_value, cmake_type):
     r"""Convert a CMake value in a string form to a Python value.
 
-    Arguments:
+    Args:
       cmake_value (string): The CMake value in a string form (e.g., "ON", "OFF", "1").
       cmake_type (string): The CMake type of :attr:`cmake_value`.
 
@@ -56,7 +56,7 @@ def convert_cmake_value_to_python_value(cmake_value, cmake_type):
 def get_cmake_cache_variables_from_file(cmake_cache_file):
     r"""Gets values in CMakeCache.txt into a dictionary.
 
-    Arguments:
+    Args:
       cmake_cache_file: A CMakeCache.txt file object.
     Returns:
       dict: A ``dict`` containing the value of cached CMake variables.

tools/setup_helpers/env.py

@@ -43,7 +43,7 @@ class BuildType(object):
     is ``None``, then the build type will be inferred from ``CMakeCache.txt``. If ``CMakeCache.txt`` does not exist,
     os.environ['CMAKE_BUILD_TYPE'] will be used.
 
-    Arguments:
+    Args:
       cmake_build_type_env (str): The value of os.environ['CMAKE_BUILD_TYPE']. If None, the actual build type will be
         inferred.
 

torch/_classes.py

@@ -40,7 +40,7 @@ def load_library(self, path):
         ``torch.classes.loaded_libraries`` attribute, a set that may be inspected
         for the paths of all libraries loaded using this function.
 
-        Arguments:
+        Args:
             path (str): A path to a shared library to load.
         """
         torch.ops.load_library(path)

torch/_jit_internal.py

@@ -254,7 +254,7 @@ def get_type_hint_captures(fn):
     for the literal annotations on 'fn'. These are not considered to be closed-over by fn
     and must be obtained separately (e.g. using this function).
 
-    Arguments:
+    Args:
         fn: A callable.
     Returns:
         A Dict[str, Any] containing a mapping from the literal annotations used on

torch/_lobpcg.py

@@ -76,7 +76,7 @@ def _polynomial_value(poly, x, zero_power, transition):
     """
     A generic method for computing poly(x) using the Horner's rule.
 
-    Arguments:
+    Args:
       poly (Tensor): the (possibly batched) 1D Tensor representing
                      polynomial coefficients such that
                      poly[..., i] = (a_{i_0}, ..., a{i_n} (==1)), and
@@ -384,7 +384,7 @@ def lobpcg(A: Tensor,
       we do the following symmetrization map: `A -> (A + A.t()) / 2`.
       The map is performed only when the `A` requires gradients.
 
-    Arguments:
+    Args:
 
       A (Tensor): the input tensor of size :math:`(*, m, m)`
 
@@ -925,7 +925,7 @@ def _get_rayleigh_ritz_transform(self, S):
           matrix product `D M` with element-wise product `M *
           d`. Also, creating the diagonal matrix `D` is avoided.
 
-        Arguments:
+        Args:
         S (Tensor): the matrix basis for the search subspace, size is
                     :math:`(m, n)`.
 
@@ -957,7 +957,7 @@ def _get_svqb(self,
                   modification of the corresponding algorithm
                   introduced in [StathopolousWu2002].
 
-        Arguments:
+        Args:
 
           U (Tensor) : initial approximation, size is (m, n)
           drop (bool) : when True, drop columns that
@@ -1023,7 +1023,7 @@ def _get_ortho(self, U, V):
         .. note:: If all U columns are B-collinear to V then the
                   returned tensor U will be empty.
 
-        Arguments:
+        Args:
 
           U (Tensor) : initial approximation, size is (m, n)
           V (Tensor) : B-orthogonal external basis, size is (m, k)

torch/_lowrank.py

@@ -37,7 +37,7 @@ def get_approximate_basis(A,        # type: Tensor
     .. note:: To obtain repeatable results, reset the seed for the
               pseudorandom number generator
 
-    Arguments::
+    Args::
         A (Tensor): the input tensor of size :math:`(*, m, n)`
 
         q (int): the dimension of subspace spanned by :math:`Q`
@@ -103,7 +103,7 @@ def svd_lowrank(A, q=6, niter=2, M=None):
               will be useful for huge sparse matrices that
               ``torch.svd`` cannot handle.
 
-    Arguments::
+    Args::
         A (Tensor): the input tensor of size :math:`(*, m, n)`
 
         q (int, optional): a slightly overestimated rank of A.
@@ -211,7 +211,7 @@ def pca_lowrank(A, q=None, center=True, niter=2):
     .. note:: To obtain repeatable results, reset the seed for the
               pseudorandom number generator
 
-    Arguments:
+    Args:
 
         A (Tensor): the input tensor of size :math:`(*, m, n)`
 

torch/_ops.py

@@ -94,7 +94,7 @@ def load_library(self, path):
         ``torch.ops.loaded_libraries`` attribute, a set that may be inspected
         for the paths of all libraries loaded using this function.
 
-        Arguments:
+        Args:
             path (str): A path to a shared library to load.
         """
         path = torch._utils_internal.resolve_library_path(path)

torch/_torch_docs.py

@@ -3738,7 +3738,7 @@ def merge_dicts(*dicts):
     Complex values are infinite when their real or imaginary part is
     infinite.
 
-    Arguments:
+    Args:
         {input}
 
     Returns:
@@ -3823,7 +3823,7 @@ def merge_dicts(*dicts):
 Real values are finite when they are not NaN, negative infinity, or infinity.
 Complex values are finite when both their real and imaginary parts are finite.
 
-    Arguments:
+    Args:
         {input}
 
     Returns:

torch/_utils.py

@@ -248,7 +248,7 @@ def _flatten_dense_tensors(tensors):
     buffer. Element-wise operation on this buffer will be equivalent to
     operating individually.
 
-    Arguments:
+    Args:
         tensors (Iterable[Tensor]): dense tensors to flatten.
 
     Returns:
@@ -264,7 +264,7 @@ def _flatten_sparse_tensors(tensors):
     """Flatten sparse tensors into two contiguous 1D buffers, one of indices and
     one of values. Assume tensors are of same sparse type.
 
-    Arguments:
+    Args:
         tensors (Iterable[Tensor]): sparse tensors to flatten.
 
     Returns:
@@ -280,7 +280,7 @@ def _unflatten_dense_tensors(flat, tensors):
     """View a flat buffer using the sizes of tensors. Assume that tensors are of
     same dense type, and that flat is given by _flatten_dense_tensors.
 
-    Arguments:
+    Args:
         flat (Tensor): flattened dense tensors to unflatten.
         tensors (Iterable[Tensor]): dense tensors whose sizes will be used to
           unflatten flat.
@@ -303,7 +303,7 @@ def _unflatten_sparse_tensors(flat, tensors):
     tensors. Assume that tensors are of same sparse type, and that flat is given
     by _flatten_sparse_tensors.
 
-    Arguments:
+    Args:
         flat (tuple(Tensor, Tensor)): flattened indices and values of sparse
           tensors to unflatten.
         tensors (Iterable[Tensor]): sparse tensors whose sizes will be used to
@@ -327,7 +327,7 @@ def _reorder_tensors_as(tensors, ordered_tensors):
     types, e.g., from _take_tensors. Reorder them to be of same order as
     ordered_tensors.
 
-    Arguments:
+    Args:
         tensors (Iterable[Tensor]): tensors to be reordered. They should be of
           the same order as ordered_tensors within their own types.
         ordered_tensors (Iterable[Tensor]): tensors whose order will be the

torch/autograd/__init__.py

@@ -102,7 +102,7 @@ def backward(
         in a user-specified CUDA stream context, see
         :ref:`Stream semantics of backward passes<bwd-cuda-stream-semantics>`.
 
-    Arguments:
+    Args:
         tensors (sequence of Tensor): Tensors of which the derivative will be
             computed.
         grad_tensors (sequence of (Tensor or None)): The "vector" in the Jacobian-vector
@@ -174,7 +174,7 @@ def grad(
         in a user-specified CUDA stream context, see
         :ref:`Stream semantics of backward passes<bwd-cuda-stream-semantics>`.
 
-    Arguments:
+    Args:
         outputs (sequence of Tensor): outputs of the differentiated function.
         inputs (sequence of Tensor): Inputs w.r.t. which the gradient will be
             returned (and not accumulated into ``.grad``).

torch/autograd/anomaly_mode.py

@@ -89,7 +89,7 @@ class set_detect_anomaly(object):
 
     See ``detect_anomaly`` above for details of the anomaly detection behaviour.
 
-    Arguments:
+    Args:
         mode (bool): Flag whether to enable anomaly detection (``True``),
                      or disable (``False``).
 

torch/autograd/grad_mode.py

@@ -172,7 +172,7 @@ class set_grad_enabled(object):
     This context manager is thread local; it will not affect computation
     in other threads.
 
-    Arguments:
+    Args:
         mode (bool): Flag whether to enable grad (``True``), or disable
                      (``False``). This can be used to conditionally enable
                      gradients.

torch/autograd/profiler.py

@@ -172,7 +172,7 @@ def self_cpu_time_total(self):
     def table(self, sort_by=None, row_limit=100, max_src_column_width=75, header=None, top_level_events_only=False):
         """Prints an EventList as a nicely formatted table.
 
-        Arguments:
+        Args:
             sort_by (str, optional): Attribute used to sort entries. By default
                 they are printed in the same order as they were registered.
                 Valid keys include: ``cpu_time``, ``cuda_time``, ``cpu_time_total``,
@@ -203,7 +203,7 @@ def export_chrome_trace(self, path):
 
         The checkpoint can be later loaded and inspected under ``chrome://tracing`` URL.
 
-        Arguments:
+        Args:
             path (str): Path where the trace will be written.
         """
         import os
@@ -288,7 +288,7 @@ def export_stacks(self, path: str, metric: str):
     def key_averages(self, group_by_input_shapes=False, group_by_stack_n=0):
         """Averages all function events over their keys.
 
-        Arguments:
+        Args:
             group_by_input_shapes: group entries by
             (event name, input shapes) rather than just event name.
             This is useful to see which input shapes contribute to the runtime
@@ -345,7 +345,7 @@ class profile(object):
     only report runtime of PyTorch functions.
     Note: profiler is thread local and is automatically propagated into the async tasks
 
-    Arguments:
+    Args:
         enabled (bool, optional): Setting this to False makes this context manager a no-op.
             Default: ``True``.
 
@@ -574,7 +574,7 @@ class record_function(ContextDecorator):
     Python code (or function) when running autograd profiler. It is
     useful when tracing the code profile.
 
-    Arguments:
+    Args:
         name (str): Label assigned to the block of code.
         node_id (int): ID of node, for distributed profiling. Unset in
         non-distributed cases.
@@ -628,7 +628,7 @@ def _call_end_callbacks_on_future(self, fut: Future[Any]) -> Future[Any]:
         once to attach the callback onto the future, and will throw if called multiple
         times.
 
-        Arguments:
+        Args:
             fut: (torch._C.Future): future for which to schedule
             callback for.
 
@@ -666,7 +666,7 @@ class emit_nvtx(object):
         This context manager should not be called recursively, i.e. at most one
         instance should be enabled at any given time.
 
-    Arguments:
+    Args:
         enabled (bool, optional, default=True): Setting ``enabled=False`` makes this context manager a no-op.
             Default: ``True``.
         record_shapes (bool, optional, default=False): If ``record_shapes=True``, the nvtx range wrapping
@@ -761,7 +761,7 @@ def __exit__(self, exc_type, exc_val, exc_tb):
 def load_nvprof(path):
     """Opens an nvprof trace file and parses autograd annotations.
 
-    Arguments:
+    Args:
         path (str): path to nvprof trace
     """
     return EventList(parse_nvprof_trace(path))