一天一个Python库：annotated-types - 增强类型提示的元数据

annotated-types - 增强类型提示的元数据

一、什么是annotated-types？

annotated-types 是一个用于为 Python 类型提示添加额外元数据的库。 它可以帮助你：

• 在类型提示中嵌入约束、说明或其他信息，而不仅仅是表达类型。
• 更好地与数据验证库和工具集成，例如 Pydantic 或 msgspec。
• 提高代码的可读性和可维护性，通过更丰富的类型声明。

二、应用场景

annotated-types 广泛应用于以下实际场景：

• 数据验证: 在数据模型中定义字段的类型和验证规则，例如一个整数必须大于0，一个字符串的最大长度不能超过255。
• API设计: 为API请求和响应的模型定义更精确的类型和约束，便于自动生成文档或进行校验。
• 配置管理: 为应用程序的配置项定义类型和预期值范围，防止无效配置。

三、如何安装

1. 使用 pip 安装

pip install annotated-types

# 如果安装慢的话，推荐使用国内镜像源
pip install annotated-types -i 

2. 使用 PythonRun 在线运行代码（无需本地安装）

四、示例代码

定义一个整数，并使用 annotated-types 来表示它必须大于0。

from typing import Annotated
from annotated_types import Gt # Gt 表示 Greater than (大于)

def process_positive_number(value: Annotated[int, Gt(0)]) -> str:
    """
    处理一个必须大于0的整数。
    """
    if value > 0:
        return f"处理了一个正数: {value}"
    else:
        # 实际上，由于类型提示，理论上函数接收到的值会大于0，
        # 但我们仍然可以包含条件判断以增强鲁棒性或在没有严格校验时提供反馈。
        return f"错误：输入值 {value} 不符合预期 (>0)。"

# 示例调用
number_one = 10
result_one = process_positive_number(number_one)
print(result_one)

number_two = -5 # 理论上类型检查工具会发出警告，但Python运行时仍会执行
result_two = process_positive_number(number_two)
print(result_two)

# 另一个正数
number_three = 1
if number_three >= 1: # 额外的条件判断
    print(f"输入值为 {number_three}，可以继续处理。")
else:
    print(f"输入值为 {number_three}，不符合 >= 1 的条件。")

使用 PythonRun 在线运行这段代码，结果如下：

处理了一个正数: 10
错误：输入值 -5 不符合预期 (>0)。
输入值为 1，可以继续处理。

使用 MermaidGo 绘制示例代码的流程图，结果如下：

五、学习资源

1. 开源项目：annotated-types
2. 中文自述：REMDME
3. 在线运行：PythonRun