Google Python风格指南ValueError未写入Raises段原因及使用合理性问询

一、规定背后的核心逻辑 #

• 区分API契约承诺与开发期校验行为：文档Raises章节列出的异常属于API公开契约的一部分，代表官方承诺只要触发对应场景就一定会抛出该类异常，调用方可以合法依赖该行为做异常捕获处理。而示例中的ValueError是对调用方违反参数前置规则（Args中已经明确要求minimum≥1024）的误用校验，这类校验行为不属于需要对外承诺的稳定行为：未来版本迭代中可能调整校验规则、合并异常类型、甚至增加自动容错逻辑，不需要保证永远抛出ValueError，因此不需要写入Raises避免调用方错误依赖非契约行为。
• 避免文档冗余：如果要求把所有参数校验类的异常都写入Raises，会导致文档信息过载——如果函数有多个参数、每个参数有多重校验规则，Raises章节会充斥大量本应由调用方自行遵守参数规则就能避免的异常说明，反而会稀释真正需要调用方关注的、正常调用下也可能出现的异常信息（比如示例中的ConnectionError）。

二、是否意味着该场景不该使用ValueError？ #

不是，这个场景下抛出ValueError完全符合Python异常的设计规范：ValueError本身就用于指代「参数类型合法，但取值不符合要求」的错误场景，抛出该异常可以在开发阶段快速定位调用方的参数错误，避免非法值流入后续逻辑引发更难排查的问题。
该规定仅限制「不将这类API误用的异常写入文档的Raises章节」，完全没有禁止抛出对应异常。

示例代码中文翻译 #

def connect_to_next_port(self, minimum: int) -> int:
    """连接到下一个可用端口。

    参数:
      minimum: 大于等于1024的端口值。

    返回:
      新的最小可用端口。

    抛出:
      ConnectionError: 未找到可用端口时抛出。
    """
    if minimum < 1024:
        # 注意：此处抛出的ValueError没有标注在文档字符串的「抛出:」章节中，
        # 因为对API误用的这种特定行为响应作出保证是不合适的。
        raise ValueError(f'端口最小值必须至少为1024，输入值为{minimum}。')
    port = self._find_next_open_port(minimum)
    if not port:
        raise ConnectionError(
            f'无法连接到{minimum}及以上端口的服务。')
    assert port >= minimum, (
        f'最小端口要求为{minimum}时返回了意外的端口值{port}。')
    return port

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