如何让deprecated装饰器兼容D212与D213格式的Python文档字符串？

问题核心 #

你的deprecated装饰器当前仅用textwrap.dedent处理文档字符串，无法兼容Ruff默认的D212（短描述直接写在文档字符串首行）和Sphinx常用的D213（短描述在文档字符串首行换行后）两种格式，导致后续处理逻辑出现不一致。

解决方案 #

通过标准化文档字符串的格式，将两种格式统一为短描述开头无空行的结构，具体实现如下：

import textwrap

def normalize_docstring(docstring):
    if not docstring:
        return ""
    # 移除所有行的公共缩进
    dedented = textwrap.dedent(docstring)
    # 按行拆分并过滤开头的空行
    lines = dedented.splitlines()
    while lines and not lines[0].strip():
        lines.pop(0)
    # 重新拼接成标准格式的文档字符串
    return '\n'.join(lines)

# 在装饰器中替换原有逻辑
docstring = normalize_docstring(wrapped.__doc__)
# 后续处理逻辑保持不变

处理逻辑说明 #

1. 移除公共缩进：textwrap.dedent会自动去除所有行的公共缩进，解决D213格式中短描述的缩进问题。
2. 过滤开头空行：D213格式的文档字符串首行是"""后的空行，通过循环移除开头的空行，让短描述直接处于文档字符串的第一行，与D212格式对齐。
3. 统一结构：处理后两种格式的文档字符串结构完全一致，后续提取短描述、解析参数等逻辑无需区分格式。

效果验证 #

• 针对D213格式的文档字符串：
  原始内容：

  """
      one liner
      
      Args: 
          toto
  """
  

  处理后变为：

  one liner
  
  Args: 
      toto
  

• 针对D212格式的文档字符串：
  原始内容：

  """one liner 
  
  Args: 
      toto
  """
  

  处理后变为：

  one liner
  
  Args: 
      toto
  

两种格式最终输出完全一致，装饰器后续处理逻辑可正常兼容。

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