如何让mkdocstrings解析内部变量为实际类型提示且不暴露该变量？

要实现复用内部类型提示变量，同时让mkdocstrings将参数类型解析为实际类型而非变量名，且不把该变量显示在文档中，可以通过以下步骤操作：

1. 规范定义内部类型别名 #

使用typing.TypeAlias标记类型别名，并通过下划线前缀（如_my_str_types）将其标记为内部变量，避免文档收录：

from typing import TypeAlias

# 下划线前缀表示内部变量，默认不会被文档工具收录
_my_str_types: TypeAlias = str | list[str]

def fn(x: _my_str_types):
    """Useless function

    Args:
        x: description

    Returns:
        x
    """
    return x


print(fn("hello"))

2. 配置mkdocstrings展开类型别名 #

在mkdocs.yml中配置mkdocstrings的Python解析器（griffe），开启类型别名展开，并明确排除内部变量：

plugins:
  - mkdocstrings:
      default_handler: python
      handlers:
        python:
          options:
            # 开启注解展开，将类型别名替换为实际类型
            unwrap_annotations: true
            # 过滤掉以下划线开头的内部变量，不显示在文档中
            filters: ["!^_"]

说明 #

• unwrap_annotations: true：让解析器自动将类型别名展开为对应的实际类型，函数参数x的类型会显示为str | list[str]。
• filters: ["!^_"]：通过正则匹配排除所有以下划线开头的变量，确保内部类型别名不会出现在库文档中。
• 如果使用Python 3.9及以下版本，可将str | list[str]替换为Union[str, List[str]]，TypeAlias的用法保持一致。

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