Handle *args and **kwargs, and show the problematic arguments.

Author: domdfcoding

flake8_params/__init__.py

@@ -33,7 +33,7 @@
 # 3rd party
 import flake8_helper
 
-__all__ = ("Plugin", "Visitor", "get_decorator_names", "check_params")
+__all__ = ("Plugin", "Visitor", "get_decorator_names", "check_params", "get_docstring_args", "get_signature_args")
 
 __author__ = "Dominic Davis-Foster"
 __copyright__ = "2025 Dominic Davis-Foster"
@@ -42,8 +42,8 @@
 __email__ = "dominic@davis-foster.co.uk"
 
 PRM001 = "PRM001 Docstring parameters in wrong order."
-PRM002 = "PRM002 Missing parameters in docstring."
-PRM003 = "PRM003 Extra parameters in docstring."
+PRM002 = "PRM002 Missing parameters in docstring"
+PRM003 = "PRM003 Extra parameters in docstring"
 # TODO: class-specific codes?
 
 deco_allowed_attr_names = {
@@ -124,14 +124,58 @@ def check_params(
 		return PRM001
 	elif signature_set - docstring_set:
 		# Extras in signature
-		return PRM002
+		return PRM002 + ": " + ' '.join(sorted(signature_set - docstring_set))
 	elif docstring_set - signature_set:
 		# Extras in docstrings
-		return PRM003
+		return PRM003 + ": " + ' '.join(sorted(docstring_set - signature_set))
 
 	return None  # pragma: no cover
 
 
+def get_signature_args(function: Union[ast.FunctionDef, ast.AsyncFunctionDef]) -> Iterator[str]:
+	"""
+	Extract arguments from the function signature.
+
+	:param function:
+
+	:rtype:
+
+	..versionadded:: 0.2.0
+	"""
+
+	for arg in function.args.posonlyargs:
+		yield arg.arg
+
+	for arg in function.args.args:
+		yield arg.arg
+
+	if function.args.vararg:
+		yield '*' + function.args.vararg.arg
+
+	for arg in function.args.kwonlyargs:
+		yield arg.arg
+
+	if function.args.kwarg:
+		yield "**" + function.args.kwarg.arg
+
+
+def get_docstring_args(docstring: str) -> Iterator[str]:
+	"""
+	Extract arguments from the docstring.
+
+	:param docstring:
+
+	:rtype:
+
+	..versionadded:: 0.2.0
+	"""
+
+	for line in docstring.split('\n'):
+		line = line.strip()
+		if line.startswith(":param"):
+			yield line[6:].split(':', 1)[0].strip().replace(r"\*", '*')
+
+
 class Visitor(flake8_helper.Visitor):
 	"""
 	AST node visitor for identifying mismatches between function signatures and docstring params.
@@ -154,14 +198,8 @@ def _visit_function(self, node: Union[ast.FunctionDef, ast.AsyncFunctionDef]) ->
 			self.generic_visit(node)
 			return
 
-		docstring_args = []
-		for line in docstring.split('\n'):
-			line = line.strip()
-			if line.startswith(":param"):
-				docstring_args.append(line[6:].split(':', 1)[0].strip())
-
-		signature_args = [a.arg for a in node.args.args]
-
+		docstring_args = list(get_docstring_args(docstring))
+		signature_args = list(get_signature_args(node))
 		decorators = list(get_decorator_names(node))
 
 		error = check_params(signature_args, docstring_args, decorators)
@@ -184,20 +222,15 @@ def visit_ClassDef(self, node: ast.ClassDef) -> None:  # noqa: D102
 			self.generic_visit(node)
 			return
 
-		docstring_args = []
-		for line in docstring.split('\n'):
-			line = line.strip()
-			if line.startswith(":param"):
-				docstring_args.append(line[6:].split(':', 1)[0].strip())
-
+		docstring_args = list(get_docstring_args(docstring))
 		decorators = list(get_decorator_names(node))
 
 		signature_args = []
 		functions_in_body: List[ast.FunctionDef] = [n for n in node.body if isinstance(n, ast.FunctionDef)]
 
 		for function in functions_in_body:
 			if function.name == "__init__":
-				signature_args = [a.arg for a in function.args.args]
+				signature_args = list(get_signature_args(function))
 				break
 		else:
 			# No __init__; maybe it comes from a base class.

tests/example_code.py

@@ -287,3 +287,61 @@ async def missing_in_signature_with_classmethod(cls, foo, baz):
 
 async def no_docstring_async(foo, bar, baz):
 	pass
+
+
+def missing_args(foo, bar, *baz):
+	"""
+	Does something.
+
+	:param foo:
+	:param bar:
+	"""
+
+
+def has_args(foo, bar, *baz):
+	r"""
+	Does something.
+
+	:param foo:
+	:param bar:
+	:param \*baz:
+	"""
+
+
+def missing_kwargs(foo, bar, **baz):
+	"""
+	Does something.
+
+	:param foo:
+	:param bar:
+	"""
+
+
+def has_kwargs(foo, bar, **baz):
+	r"""
+	Does something.
+
+	:param foo:
+	:param bar:
+	:param \*\*baz:
+	"""
+
+
+def keyword_only(foo, bar, *, baz=None):
+	"""
+	Does something.
+
+	:param foo:
+	:param bar:
+	:param baz:
+	"""
+
+
+def positional_only(foo, /, bar, baz):
+	"""
+	Does something.
+
+	:param foo:
+	:param bar:
+	:param baz:
+	"""

tests/test_flake8_params_/test_plugin.txt

@@ -1,17 +1,19 @@
-1:0: PRM002 Missing parameters in docstring.
-20:0: PRM002 Missing parameters in docstring.
+1:0: PRM002 Missing parameters in docstring: baz
+20:0: PRM002 Missing parameters in docstring: foo
 29:0: PRM001 Docstring parameters in wrong order.
-39:0: PRM003 Extra parameters in docstring.
-49:0: PRM003 Extra parameters in docstring.
-59:0: PRM002 Missing parameters in docstring.
-81:1: PRM002 Missing parameters in docstring.
-90:1: PRM003 Extra parameters in docstring.
-112:0: PRM003 Extra parameters in docstring.
+39:0: PRM003 Extra parameters in docstring: baz
+49:0: PRM003 Extra parameters in docstring: baz
+59:0: PRM002 Missing parameters in docstring: baz
+81:1: PRM002 Missing parameters in docstring: bar
+90:1: PRM003 Extra parameters in docstring: bar
+112:0: PRM003 Extra parameters in docstring: baz
 125:0: PRM001 Docstring parameters in wrong order.
-195:0: PRM002 Missing parameters in docstring.
-214:0: PRM002 Missing parameters in docstring.
+195:0: PRM002 Missing parameters in docstring: baz
+214:0: PRM002 Missing parameters in docstring: foo
 223:0: PRM001 Docstring parameters in wrong order.
-233:0: PRM003 Extra parameters in docstring.
-243:0: PRM003 Extra parameters in docstring.
-269:1: PRM002 Missing parameters in docstring.
-278:1: PRM003 Extra parameters in docstring.
+233:0: PRM003 Extra parameters in docstring: baz
+243:0: PRM003 Extra parameters in docstring: baz
+269:1: PRM002 Missing parameters in docstring: bar
+278:1: PRM003 Extra parameters in docstring: bar
+292:0: PRM002 Missing parameters in docstring: *baz
+311:0: PRM002 Missing parameters in docstring: **baz