PyCharm函数文档字符串参数重复显示问题及格式优化诉求

问题描述 #

我编写了如下Python函数：

def convert_lesions(input_lesions: list, output: str) -> list:
    """
    Convert a list of IDs/class names to a list of corresponding IDs, names, or colors.
    Args:
        input_lesions: Either class names or IDs.
        output: Expected output format. Possible values are 'ids', 'names', or 'colors'.
    Returns:
        List of class IDs, names or list of colors corresponding to the input list.
    """
    conversion_map = {
        'ids': lambda lst: [key for key, value in LESIONS['classes'].items() if value in lst],
        'names': lambda lst: [LESIONS['classes'][class_id] for class_id in LESIONS['classes']],
        'colors': lambda lst: [LESIONS['colors'][class_id] for class_id in lst if class_id in LESIONS['colors']]}
    return conversion_map[output](input_lesions)

鼠标悬停函数名时，参数和返回值会重复显示：既在文档字符串的Args/Returns区块展示，又在IDE生成的Params/Returns区域重复出现，显示效果如下：

def convert_lesions(input_lesions: Any,
                    output: Any) -> Any

Convert a list of IDs/class names to a list of corresponding IDs, names, or colors. 

Args: input_lesions: Either class names or IDs. 

output: Expected output format. Possible values are 'ids', 'names', or 'colors'. 

Returns: List of class IDs, names or list of colors corresponding to the input list.

    Params:

input_lesions – Either class names or IDs.

output – Expected output format. Possible values are 'ids', 'names', or 'colors'.

    Returns:

List of class IDs, names or list of colors corresponding to the input list.

期望的显示效果是仅保留函数说明和结构化的Params/Returns区域，不重复显示文档字符串内的Args/Returns文本：

def convert_lesions(input_lesions: Any,
                    output: Any) -> Any

Convert a list of IDs/class names to a list of corresponding IDs, names, or colors. 

    Params:

input_lesions – Either class names or IDs.

output – Expected output format. Possible values are 'ids', 'names', or 'colors'.

    Returns:

List of class IDs, names or list of colors corresponding to the input list.

解决方法 #

方法1：调整文档字符串格式 #

移除文档字符串中显式的Args:和Returns:标签，将参数说明直接对齐到正确缩进位置，让PyCharm仅解析结构化的参数和返回值信息，不重复渲染原始标签内容。修改后的示例：

def convert_lesions(input_lesions: list, output: str) -> list:
    """Convert a list of IDs/class names to a list of corresponding IDs, names, or colors.
    
    input_lesions: Either class names or IDs.
    output: Expected output format. Possible values are 'ids', 'names', or 'colors'.
    
    Returns:
        List of class IDs, names or list of colors corresponding to the input list.
    """
    conversion_map = {
        'ids': lambda lst: [key for key, value in LESIONS['classes'].items() if value in lst],
        'names': lambda lst: [LESIONS['classes'][class_id] for class_id in LESIONS['classes']],
        'colors': lambda lst: [LESIONS['colors'][class_id] for class_id in lst if class_id in LESIONS['colors']]}
    return conversion_map[output](input_lesions)

方法2：修改PyCharm文档字符串解析设置 #

1. 打开设置界面：Windows/Linux路径为File > Settings > Tools > Python Integrated Tools，Mac路径为PyCharm > Settings > Tools > Python Integrated Tools。
2. 在Docstring format下拉菜单中，选择Google或NumPy格式（替换默认的Plain或reStructuredText）。
3. 保存设置后，PyCharm会更智能地解析文档结构，避免重复显示参数和返回值说明。

补充说明 #

截至2025年，JetBrains已在PyCharm后续版本中修复了该重复显示的问题，升级到最新版本也可直接解决此问题。

内容的提问来源于stack exchange，提问作者Dueoksini