refactor: Rename arguments to parameters

src/griffe/dataclasses.py

@@ -131,14 +131,14 @@ def as_dict(self, full: bool = False, docstring_parser: Parser = Parser.google,
         return base
 
 
-class Argument:
-    """This class represent a function argument.
+class Parameter:
+    """This class represent a function parameter.
 
     Attributes:
-        name: The argument name.
-        annotation: The argument annotation, if any.
-        kind: The argument kind (see [`inspect.Parameter.kind`][]).
-        default: The argument default, if any.
+        name: The parameter name.
+        annotation: The parameter annotation, if any.
+        kind: The parameter kind (see [`inspect.Parameter.kind`][]).
+        default: The parameter default, if any.
     """
 
     def __init__(
@@ -149,17 +149,20 @@ def __init__(
         kind: ParameterKind | None = None,
         default: str | None = None,
     ) -> None:
-        """Initialize the argument.
+        """Initialize the parameter.
 
         Parameters:
+            name: The parameter name.
+            annotation: The parameter annotation, if any.
+            kind: The parameter kind (see [`inspect.Parameter.kind`][]).
+            default: The parameter default, if any.
         """
         self.name: str = name
         self.annotation: str | None = annotation
         self.kind: ParameterKind | None = kind
         self.default: str | None = default
 
-    def as_dict(self, **kwargs) -> dict[str, Any]:
-        """Return this argument's data as a dictionary.
+        """Return this parameter's data as a dictionary.
 
         Parameters:
             **kwargs: Additional serialization options.
@@ -175,46 +178,48 @@ def as_dict(self, **kwargs) -> dict[str, Any]:
         }
 
 
-class Arguments:
-    """This class is a container for arguments.
+class Parameters:
+    """This class is a container for parameters.
 
-    It allows to get arguments using their position (index) or their name.
+    It allows to get parameters using their position (index) or their name.
     """
 
-    def __init__(self, *arguments: Argument) -> None:
-        """Initialize the arguments container.
+    def __init__(self, *parameters: Parameter) -> None:
+        """Initialize the parameters container.
 
         Parameters:
+            *parameters: The initial parameters to add to the container.
         """
-        self._arguments_list: list[Argument] = []
-        self._arguments_dict: dict[str, Argument] = {}
-        for argument in arguments:
-            self.add(argument)
+        self._parameters_list: list[Parameter] = []
+        self._parameters_dict: dict[str, Parameter] = {}
+        for parameter in parameters:
+            self.add(parameter)
 
-    def __getitem__(self, name_or_index: int | str) -> Argument:
+    def __getitem__(self, name_or_index: int | str) -> Parameter:
         if isinstance(name_or_index, int):
-            return self._arguments_list[name_or_index]
-        return self._arguments_dict[name_or_index]
+            return self._parameters_list[name_or_index]
+        return self._parameters_dict[name_or_index]
 
     def __len__(self):
-        return len(self._arguments_list)
+        return len(self._parameters_list)
 
     def __iter__(self):
-        return iter(self._arguments_list)
+        return iter(self._parameters_list)
 
-    def add(self, argument: Argument) -> None:
-        """Add an argument to the container.
+    def add(self, parameter: Parameter) -> None:
+        """Add a parameter to the container.
 
         Parameters:
+            parameter: The function parameter to add.
 
         Raises:
-            ValueError: When an argument with the same name is already present.
+            ValueError: When a parameter with the same name is already present.
         """
-        if argument.name not in self._arguments_dict:
-            self._arguments_dict[argument.name] = argument
-            self._arguments_list.append(argument)
+        if parameter.name not in self._parameters_dict:
+            self._parameters_dict[parameter.name] = parameter
+            self._parameters_list.append(parameter)
         else:
-            raise ValueError(f"argument {argument.name} already present")
+            raise ValueError(f"parameter {parameter.name} already present")
 
 
 class Kind(enum.Enum):
@@ -545,8 +550,7 @@ class Function(Object):
 
     def __init__(
         self,
-        *args,
-        arguments: Arguments | None = None,
+        parameters: Parameters | None = None,
         returns: str | None = None,
         decorators: list[Decorator] | None = None,
         **kwargs,
@@ -555,13 +559,13 @@ def __init__(
 
         Parameters:
             *args: See [`griffe.dataclasses.Object`][].
-            arguments: The function arguments.
+            parameters: The function parameters.
             returns: The function return annotation.
             decorators: The function decorators, if any.
             **kwargs: See [`griffe.dataclasses.Object`][].
         """
         super().__init__(*args, **kwargs)
-        self.arguments = arguments or Arguments()
+        self.parameters = parameters or Parameters()
         self.returns = returns
         self.decorators = decorators or []
 
@@ -576,7 +580,7 @@ def as_dict(self, **kwargs) -> dict[str, Any]:  # type: ignore
         """
         base = super().as_dict(**kwargs)
         base["decorators"] = [dec.as_dict(**kwargs) for dec in self.decorators]
-        base["arguments"] = [arg.as_dict(**kwargs) for arg in self.arguments]
+        base["parameters"] = [param.as_dict(**kwargs) for param in self.parameters]
         base["returns"] = self.returns
         return base
 

src/griffe/docstrings/dataclasses.py

@@ -10,8 +10,8 @@ class DocstringSectionKind(enum.Enum):
     """The possible section kinds."""
 
     text = "text"
-    arguments = "arguments"
-    keyword_arguments = "keyword arguments"
+    parameters = "parameters"
+    other_parameters = "other parameters"
     raises = "raises"
     warns = "warns"
     returns = "returns"
@@ -183,8 +183,8 @@ def as_dict(self, **kwargs) -> dict[str, Any]:
         return base
 
 
-class DocstringArgument(DocstringNamedElement):
-    """This class represent a documented function argument."""
+class DocstringParameter(DocstringNamedElement):
+    """This class represent a documented function parameter."""
 
 
 class DocstringAttribute(DocstringNamedElement):

src/griffe/docstrings/google.py

@@ -7,9 +7,9 @@
 
 from griffe.docstrings.dataclasses import (
     DocstringAdmonition,
-    DocstringArgument,
     DocstringAttribute,
     DocstringException,
+    DocstringParameter,
     DocstringReceive,
     DocstringReturn,
     DocstringSection,
@@ -25,12 +25,14 @@
 _warn = warning(__name__)
 
 _section_kind = {
-    "args": DocstringSectionKind.arguments,
-    "arguments": DocstringSectionKind.arguments,
-    "params": DocstringSectionKind.arguments,
-    "parameters": DocstringSectionKind.arguments,
-    "keyword args": DocstringSectionKind.keyword_arguments,
-    "keyword arguments": DocstringSectionKind.keyword_arguments,
+    "args": DocstringSectionKind.parameters,
+    "arguments": DocstringSectionKind.parameters,
+    "params": DocstringSectionKind.parameters,
+    "parameters": DocstringSectionKind.parameters,
+    "keyword args": DocstringSectionKind.other_parameters,
+    "keyword parameters": DocstringSectionKind.other_parameters,
+    "other args": DocstringSectionKind.other_parameters,
+    "other parameters": DocstringSectionKind.other_parameters,
     "raises": DocstringSectionKind.raises,
     "exceptions": DocstringSectionKind.raises,
     "returns": DocstringSectionKind.returns,
@@ -137,8 +139,8 @@ def _read_block(docstring: Docstring, offset: int) -> tuple[str, int]:
     return "\n".join(block).rstrip("\n"), index - 1
 
 
-def _read_arguments(docstring: Docstring, offset: int) -> tuple[list[DocstringArgument], int]:  # noqa: WPS231
-    arguments = []
+def _read_parameters(docstring: Docstring, offset: int) -> tuple[list[DocstringParameter], int]:  # noqa: WPS231
+    parameters = []
     type_: str
     annotation: str | None
 
@@ -155,7 +157,7 @@ def _read_arguments(docstring: Docstring, offset: int) -> tuple[list[DocstringAr
 
         description = description.lstrip()
 
-        # use the type given after the argument name, if any
+        # use the type given after the parameter name, if any
         if " " in name_with_type:
             name, type_ = name_with_type.split(" ", 1)
             annotation = type_.strip("()")
@@ -165,40 +167,40 @@ def _read_arguments(docstring: Docstring, offset: int) -> tuple[list[DocstringAr
             name = name_with_type
             # try to use the annotation from the signature
             try:
-                annotation = docstring.parent.arguments[name].annotation  # type: ignore
+                annotation = docstring.parent.parameters[name].annotation  # type: ignore
             except (AttributeError, KeyError):
                 annotation = None
 
         try:
-            default = docstring.parent.arguments[name].default  # type: ignore
+            default = docstring.parent.parameters[name].default  # type: ignore
         except (AttributeError, KeyError):
             default = None
 
         if annotation is None:
-            _warn(docstring, index, f"No type or annotation for argument '{name}'")
+            _warn(docstring, index, f"No type or annotation for parameter '{name}'")
 
-        arguments.append(DocstringArgument(name=name, value=default, annotation=annotation, description=description))
+        parameters.append(DocstringParameter(name=name, value=default, annotation=annotation, description=description))
 
-    return arguments, index
+    return parameters, index
 
 
-def _read_arguments_section(docstring: Docstring, offset: int) -> tuple[DocstringSection | None, int]:
-    arguments, index = _read_arguments(docstring, offset)
+def _read_parameters_section(docstring: Docstring, offset: int) -> tuple[DocstringSection | None, int]:
+    parameters, index = _read_parameters(docstring, offset)
 
-    if arguments:
-        return DocstringSection(DocstringSectionKind.arguments, arguments), index
+    if parameters:
+        return DocstringSection(DocstringSectionKind.parameters, parameters), index
 
-    _warn(docstring, index, f"Empty arguments section at line {offset}")
+    _warn(docstring, index, f"Empty parameters section at line {offset}")
     return None, index
 
 
-def _read_keyword_arguments_section(docstring: Docstring, offset: int) -> tuple[DocstringSection | None, int]:
-    arguments, index = _read_arguments(docstring, offset)
+def _read_other_parameters_section(docstring: Docstring, offset: int) -> tuple[DocstringSection | None, int]:
+    parameters, index = _read_parameters(docstring, offset)
 
-    if arguments:
-        return DocstringSection(DocstringSectionKind.keyword_arguments, arguments), index
+    if parameters:
+        return DocstringSection(DocstringSectionKind.other_parameters, parameters), index
 
-    _warn(docstring, index, f"Empty keyword arguments section at line {offset}")
+    _warn(docstring, index, f"Empty keyword parameters section at line {offset}")
     return None, index
 
 
@@ -453,8 +455,8 @@ def _is_empty_line(line) -> bool:
 
 
 _section_reader = {
-    DocstringSectionKind.arguments: _read_arguments_section,
-    DocstringSectionKind.keyword_arguments: _read_keyword_arguments_section,
+    DocstringSectionKind.parameters: _read_parameters_section,
+    DocstringSectionKind.other_parameters: _read_other_parameters_section,
     DocstringSectionKind.raises: _read_raises_section,
     DocstringSectionKind.warns: _read_warns_section,
     DocstringSectionKind.examples: _read_examples_section,

src/griffe/docstrings/numpy.py

@@ -29,7 +29,7 @@
 - Returns: obviously.
 - Yields: obviously.
 - Receives: less used than Yields, but very natural/Pythonic as well.
-- Other parameters: used here as documentation for keyword arguments.
+- Other parameters: used here as documentation for keyword parameters.
 - Raises: obviously.
 - Warns: less used than Raises, but very natural/Pythonic as well.
 - Examples: obviously. Special handling for non-code-blocks `>>>`.
@@ -43,8 +43,8 @@
 from typing import TYPE_CHECKING, Pattern
 
 from griffe.docstrings.dataclasses import (
-    DocstringArgument,
     DocstringAttribute,
+    DocstringParameter,
     DocstringRaise,
     DocstringReceive,
     DocstringReturn,
@@ -62,8 +62,8 @@
 
 _section_kind = {
     "deprecated": DocstringSectionKind.deprecated,
-    "parameters": DocstringSectionKind.arguments,
-    "other parameters": DocstringSectionKind.keyword_arguments,
+    "parameters": DocstringSectionKind.parameters,
+    "other parameters": DocstringSectionKind.other_parameters,
     "returns": DocstringSectionKind.returns,
     "yields": DocstringSectionKind.yields,
     "receives": DocstringSectionKind.receives,
@@ -190,8 +190,8 @@ def _read_block(docstring: Docstring, offset: int) -> tuple[str, int]:
 )
 
 
-def _read_parameters(docstring: Docstring, offset: int) -> tuple[list[DocstringArgument], int]:  # noqa: WPS231
-    arguments = []
+def _read_parameters(docstring: Docstring, offset: int) -> tuple[list[DocstringParameter], int]:  # noqa: WPS231
+    parameters = []
     annotation: str | None
 
     items, index = _read_block_items(docstring, offset)
@@ -220,7 +220,7 @@ def _read_parameters(docstring: Docstring, offset: int) -> tuple[list[DocstringA
             # try to use the annotation from the signature
             for name in names:
                 try:
-                    annotation = docstring.parent.arguments[name].annotation  # type: ignore
+                    annotation = docstring.parent.parameters[name].annotation  # type: ignore
                     break
                 except (AttributeError, KeyError):
                     pass
@@ -230,32 +230,32 @@ def _read_parameters(docstring: Docstring, offset: int) -> tuple[list[DocstringA
         if default is None:
             for name in names:
                 try:
-                    default = docstring.parent.arguments[name].default  # type: ignore
+                    default = docstring.parent.parameters[name].default  # type: ignore
                     break
                 except (AttributeError, KeyError):
                     pass
 
         for name in names:
-            arguments.append(DocstringArgument(name, value=default, annotation=annotation, description=description))
+            parameters.append(DocstringParameter(name, value=default, annotation=annotation, description=description))
 
-    return arguments, index
+    return parameters, index
 
 
 def _read_parameters_section(docstring: Docstring, offset: int) -> tuple[DocstringSection | None, int]:
-    arguments, index = _read_parameters(docstring, offset)
+    parameters, index = _read_parameters(docstring, offset)
 
-    if arguments:
-        return DocstringSection(DocstringSectionKind.arguments, arguments), index
+    if parameters:
+        return DocstringSection(DocstringSectionKind.parameters, parameters), index
 
     _warn(docstring, index, f"Empty parameters section at line {offset}")
     return None, index
 
 
 def _read_other_parameters_section(docstring: Docstring, offset: int) -> tuple[DocstringSection | None, int]:
-    arguments, index = _read_parameters(docstring, offset)
+    parameters, index = _read_parameters(docstring, offset)
 
-    if arguments:
-        return DocstringSection(DocstringSectionKind.keyword_arguments, arguments), index
+    if parameters:
+        return DocstringSection(DocstringSectionKind.other_parameters, parameters), index
 
     _warn(docstring, index, f"Empty other parameters section at line {offset}")
     return None, index
@@ -464,8 +464,8 @@ def _read_examples_section(docstring: Docstring, offset: int) -> tuple[Docstring
 
 
 _section_reader = {
-    DocstringSectionKind.arguments: _read_parameters_section,
-    DocstringSectionKind.keyword_arguments: _read_other_parameters_section,
+    DocstringSectionKind.parameters: _read_parameters_section,
+    DocstringSectionKind.other_parameters: _read_other_parameters_section,
     DocstringSectionKind.deprecated: _read_deprecated_section,
     DocstringSectionKind.raises: _read_raises_section,
     DocstringSectionKind.warns: _read_warns_section,