From 601bea2c4efd58440f9a7399b0dfae164703338b Mon Sep 17 00:00:00 2001 From: Manuel de Prada Corral <6536835+manueldeprada@users.noreply.github.com> Date: Fri, 11 Jul 2025 16:36:10 +0200 Subject: [PATCH] Verbose error in fix mode for utils/check_docstrings.py (#38915) * fix ast deprecations for python 3.14: replace node.n by node.value and use `ast.Constant` More verbose exceptions in `fix_docstring` on docstring formatting issues. --- utils/check_docstrings.py | 23 +++++++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/utils/check_docstrings.py b/utils/check_docstrings.py index 35fe662bea..946f678fb3 100644 --- a/utils/check_docstrings.py +++ b/utils/check_docstrings.py @@ -681,8 +681,8 @@ def eval_math_expression(expression: str) -> Optional[Union[float, int]]: def eval_node(node): - if isinstance(node, ast.Num): # - return node.n + if isinstance(node, ast.Constant) and type(node.value) in (int, float, complex): + return node.value elif isinstance(node, ast.BinOp): # return MATH_OPERATORS[type(node.op)](eval_node(node.left), eval_node(node.right)) elif isinstance(node, ast.UnaryOp): # e.g., -1 @@ -941,7 +941,8 @@ def fix_docstring(obj: Any, old_doc_args: str, new_doc_args: str): idx += 1 if idx == len(source): - # Args are not defined in the docstring of this object + # Args are not defined in the docstring of this object. This can happen when the docstring is inherited. + # In this case, we are not trying to fix it on the child object. return # Get to the line where we stop documenting arguments @@ -958,7 +959,21 @@ def fix_docstring(obj: Any, old_doc_args: str, new_doc_args: str): if "".join(source[start_idx:idx])[:-1] != old_doc_args: # Args are not fully defined in the docstring of this object - return + # This can happen due to a mismatch in indentation calculation where the docstring parsing + # in match_docstring_with_signature uses obj.__doc__.split("\n") while here we use + # inspect.getsourcelines(obj) which can have different line endings or indentation. + # See https://github.com/huggingface/transformers/pull/38915/files#r2200675302 for more details. + obj_file = find_source_file(obj) + actual_args_section = "".join(source[start_idx:idx])[:-1] + raise ValueError( + f"Cannot fix docstring of {obj.__name__} in {obj_file} because the argument section in the source code " + f"does not match the expected format. This usually happens when:\n" + f"1. The argument section is not properly indented\n" + f"2. The argument section contains unexpected formatting\n" + f"3. The docstring parsing failed to correctly identify the argument boundaries\n\n" + f"Expected argument section:\n{repr(old_doc_args)}\n\n" + f"Actual argument section found:\n{repr(actual_args_section)}\n\n" + ) obj_file = find_source_file(obj) with open(obj_file, "r", encoding="utf-8") as f: