元数据与 Annotated：Python 类型系统的新视角

什么是元数据？

元数据（Metadata）是描述其他数据的数据。它提供了关于数据的上下文信息，可以帮助解释数据的内容、来源、结构、质量、含义、管理方式以及如何使用等。元数据可以应用于各种类型的数据，包括文本、图像、音频、视频、数据库记录等。

有哪些常见的元数据

在不同的领域和应用中，元数据的具体含义和用途可能有所不同。以下是一些常见的元数据应用示例：

图书馆学和信息科学：图书、期刊文章、研究报告等通常都有元数据，包括标题、作者、出版日期、ISBN/ISSN 编号、摘要、关键词等。

计算机文件：文件的元数据可能包括文件名、创建日期、修改日期、文件大小、文件类型、创建者等。

数据库：数据库中的元数据描述了数据库的结构，如表名、字段名、数据类型、索引、约束条件等。

数字媒体：图片、音频和视频文件可能包含元数据，如拍摄日期、相机设置、版权信息、地理标签（GPS 坐标）等。

HTML 和 XML：网页和 XML 文档的元数据通常包含在头部（head）区域，使用 标签定义，如页面描述、关键词、作者、最后修改日期等。

HTTP 响应：HTTP 响应头包含元数据，如内容类型、服务器信息、缓存控制指令等。

APIs：APIs 的元数据可能包括端点描述、参数信息、请求和响应格式、认证要求等。

源代码：编程语言中的元数据可以用来描述函数、变量、类等的额外信息，例如使用装饰器或特定的注释语法。

元数据与数据的区别

数据是实际的信息内容，而元数据是关于这些数据的描述和背景信息。两者相辅相成，元数据的存在使得数据更加易于理解和使用。

Annotated 是 Python 3.9 版本中引入的一个新的类型构造函数，它允许你为类型注解添加元数据。元数据可以是任何 Python 对象，通常用于提供关于类型的额外信息，这些信息可以被类型检查器、IDE、或者其他工具使用。

Annotated跟元数据的关系

Annotated 的主要作用是允许你将元数据与类型注解关联起来，而不是改变类型本身的语义。这在以下情况下非常有用：

1. 为类型添加文档或说明：你可以使用 Annotated 来为函数参数或返回值添加文档字符串之外的额外说明。
2. 自定义类型检查：你可以定义自定义的类型检查逻辑，这些逻辑可以在运行时或静态类型检查时使用。
3. 为类型添加约束：你可以使用 Annotated 来为类型添加额外的约束条件，这些条件可以用于类型检查或验证。

Annotated 的用法

使用 Annotated 时，你需要提供一个类型和一个元数据对象。元数据对象可以是任何 Python 对象，包括但不限于字符串、枚举、自定义对象等。

from typing import Annotated, Optional

# 定义一个元数据对象
class MyMetadata:
    def __init__(self, value):
        self.value = value

# 使用 Annotated 添加元数据
def process_data(data: Annotated[int, MyMetadata("这是一个整数")]):
    print(f"处理整数: {data}")

# 调用函数
process_data(42)

在这个例子中，我们定义了一个名为 MyMetadata 的类作为元数据，并使用 Annotated 将这个元数据与整数类型关联起来。这允许我们在类型注解中添加额外的信息，这些信息可以在类型检查或文档生成时使用。

示例：使用 Annotated 进行自定义类型检查

from typing import Annotated, List

# 定义一个自定义的类型检查函数
def is_positive(n: int) -> bool:
    return n > 0

# 使用 Annotated 添加自定义的类型检查
PositiveInt = Annotated[int, is_positive]

# 定义一个函数，要求参数是正整数
def add_positive_numbers(numbers: List[PositiveInt]):
    return sum(numbers)

# 调用函数
print(add_positive_numbers([1, 2, 3]))  # 输出: 6

在这个例子中，我们定义了一个名为 PositiveInt 的类型，它是一个整数类型，但要求值必须是正数。我们通过 Annotated 将一个自定义的类型检查函数 is_positive 与整数类型关联起来。然后，我们定义了一个函数 add_positive_numbers，它接受一个正整数列表作为参数。这个示例展示了如何使用 Annotated 进行自定义类型检查。

总结

Annotated 是一个强大的工具，它允许你在类型注解中添加额外的元数据，而不会改变类型的语义。这可以用于提供额外的文档、定义自定义类型检查逻辑，或者为类型添加额外的约束条件。使用 Annotated 可以提高代码的可读性和类型安全性，尤其是在复杂的项目中。