有没有办法用新的/修改的参数自动更新Python自动文档字符串？

Question

我使用 VS Code 作为我的编辑器，使用 autoDocstring 作为 Python 的自动文档字符串生成器扩展。有时我会通过引入新参数或修改它们的名称、默认值等来修改函数的参数。在这种情况下，我需要对文档字符串进行手动更改。

当我更改函数签名时，有什么方法可以自动更新文档字符串吗？至少在文档字符串部分引入了新参数。

Answer 1

因此，大多数自动文档字符串生成工具通常会在首次创建文档字符串时根据函数签名生成一次文档字符串，但后续对参数的更改需要在文档字符串中手动更新。

您可以使用Python的ast模块来解析Pythonk文件，检测函数定义，并根据函数签名更新文档字符串。

import ast
import astor

class DocstringUpdater(ast.NodeTransformer):
    def visit_FunctionDef(self, node):
        #########################################
        # This block of code generates a new docstring
        # for the function definition node. If no docstring
        # exists, it adds one. If a docstring exists, it
        # replaces the existing one with the new docstring.
        #########################################
        new_docstring = self.generate_docstring(node)
        if ast.get_docstring(node) is None:
            #########################################
            # If no docstring exists, add one
            #########################################
            node.body.insert(0, ast.Expr(value=ast.Str(s=new_docstring)))
        else:
            #########################################
            # If docstring exists, replace it
            #########################################
            node.body[0].value.s = new_docstring
        return node

    def generate_docstring(self, node):
        #########################################
        # This function generates a new docstring
        # based on the function's arguments.
        #########################################
        param_docs = []
        for arg in node.args.args:
            param_docs.append(f"    {arg.arg} : type\n        Description")
        
        if param_docs:
            param_docs_str = "\n".join(param_docs)
            return f"""{node.name}
        
    Args:
{param_docs_str}

    Returns:
        type: Description
"""
        else:
            return f"""{node.name}

    Returns:
        type: Description
"""

def update_docstrings(file_path):
    #########################################
    # This function reads a Python file, parses it
    # into an AST, updates the docstrings, and writes
    # the updated AST back to the file.
    #########################################
    with open(file_path, 'r') as file:
        tree = ast.parse(file.read())

    updater = DocstringUpdater()
    updated_tree = updater.visit(tree)

    with open(file_path, 'w') as file:
        file.write(astor.to_source(updated_tree))

#########################################
# Usage example
# Specify the path to your Python file
# and update the docstrings.
#########################################
file_path = 'your_script.py'
update_docstrings(file_path)