使用 Pydantic 从 JSON、JSONL、CSV、TOML、YAML、XML 与 INI 文件中验证数据【免费下载链接】pydanticData validation using Python type hints项目地址: https://gitcode.com/GitHub_Trending/py/pydantic本文是 Pydantic 处理各类文件数据的实战指南。围绕仓库中的 docs/examples/files.md 展开系统讲解如何用同一个Person模型从 JSON、JSONL、CSV、TOML、YAML、XML、INI 七种常见文件格式中读取并验证数据同时深入model_validate_json、TypeAdapter、model_validate的源码实现帮助你掌握文件 → 数据 → 强类型模型的完整链路并学会在批量数据中精确定位错误记录。读完本文你将能够针对任意一种常见文件格式写出可复制的验证代码并理解其背后的校验机制与参数细节。!!! note 配置文件场景的进阶选择 如果你的目标是用上述文件格式解析配置 / 设置而非业务数据可以考虑使用pydantic-settings库它为这类数据提供了内置解析支持如.env、.toml等来源。JSON 文件从字符串到模型的model_validate_json.json文件是以人类可读形式存储键值数据的最常见方式。假设存在如下person.json{ name: John Doe, age: 30, email: johnexample.com }验证这段数据只需两步用pathlib读取文件内容再调用类方法model_validate_jsonimport pathlib from pydantic import BaseModel, EmailStr, PositiveInt class Person(BaseModel): name: str age: PositiveInt email: EmailStr json_string pathlib.Path(person.json).read_text() person Person.model_validate_json(json_string) print(person) # nameJohn Doe age30 emailjohnexample.com这里PositiveInt保证年龄必须为正整数EmailStr要求字段是合法邮箱格式它们在验证阶段共同起作用。验证失败ValidationError聚合全部问题如果文件数据不合法Pydantic 会抛出ValidationError。例如以下person.json{ age: -30, email: not-an-email-address }这份数据存在三处问题缺少name字段age为负数email不是合法邮箱地址。Pydantic 会一次性聚合所有错误并抛出import pathlib from pydantic import BaseModel, EmailStr, PositiveInt, ValidationError class Person(BaseModel): name: str age: PositiveInt email: EmailStr json_string pathlib.Path(person.json).read_text() try: person Person.model_validate_json(json_string) except ValidationError as err: print(err) 3 validation errors for Person name Field required [typemissing, input_value{age: -30, email: not-an-email-address}, input_typedict] For further information visit https://errors.pydantic.dev/2/v/missing age Input should be greater than 0 [typegreater_than, input_value-30, input_typeint] For further information visit https://errors.pydantic.dev/2/v/greater_than email value is not a valid email address: An email address must have an -sign. [typevalue_error, input_valuenot-an-email-address, input_typestr] 每条错误都包含字段位置name/age/email、错误类型码missing、greater_than、value_error、被拒绝的输入值input_value与输入类型input_type便于程序化处理。深入源码model_validate_json的签名与底层调用model_validate_json定义在 pydantic/main.py其完整签名如下classmethod def model_validate_json( cls, json_data: str | bytes | bytearray, *, strict: bool | None None, extra: ExtraValues | None None, context: Any | None None, by_alias: bool | None None, by_name: bool | None None, ) - Self:json_dataJSON 数据支持str、bytes、bytearray三种输入直接对接文件read_bytes()场景strict是否强制严格类型校验覆盖模型的全局配置extra对额外字段是ignore、allow还是forbid对应ConfigDict.extracontext传递给校验器的额外上下文变量可配合带info.context的校验器使用by_alias/by_name是否按字段别名 / 字段名匹配输入数据二者不能同时为False否则抛出PydanticUserError代码validate-by-alias-and-name-false。在实现上该方法最终委托给cls.__pydantic_validator__.validate_json(...)pydantic/main.py即 Pydantic 底层用 Rust 实现的pydantic-core校验器这也是其高性能的来源。仓库测试 tests/test_main.py 中的test_model_validate_json_strict验证了strict参数对宽松/严格模型的覆盖行为strictNone时沿用模型配置strictFalse允许字符串1转为intstrictTrue则要求输入本身就是整数。批量 JSON 记录用TypeAdapter验证list[Person]实际生产中一个.json文件往往包含大量同类数据例如一个人员列表[ { name: John Doe, age: 30, email: johnexample.com }, { name: Jane Doe, age: 25, email: janeexample.com } ]此时应使用TypeAdapter针对list[Person]这个单个类型进行验证import pathlib from pydantic import BaseModel, EmailStr, PositiveInt, TypeAdapter class Person(BaseModel): name: str age: PositiveInt email: EmailStr person_list_adapter TypeAdapter(list[Person]) # (1)! json_string pathlib.Path(people.json).read_text() people person_list_adapter.validate_json(json_string) print(people) # [Person(nameJohn Doe, age30, emailjohnexample.com), Person(nameJane Doe, age25, emailjaneexample.com)]使用TypeAdapter验证Person对象列表。TypeAdapter是 Pydantic 中用于针对单一类型执行验证与序列化的构造为没有实例方法的类型如原始类型、列表、dataclass 等暴露了BaseModel的一部分能力见 pydantic/type_adapter.py。大文件流水线中的错误定位只有两条记录时找出坏数据很容易但当流水线处理包含数千条记录的文件时ValidationError的loc错误位置会给出出问题记录的下标。如果流水线无人值守Logfire 会记录失败的验证及其字段位置和拒绝值使你在运行结束后仍能定位到出问题的记录。相关的排查细节参见 troubleshooting 文档。JSON Lines.jsonl文件.jsonl文件是一系列以换行符分隔的 JSON 对象验证方式与列表 JSON 类似。考虑如下people.jsonl{name: John Doe, age: 30, email: johnexample.com} {name: Jane Doe, age: 25, email: janeexample.com}逐行读取并调用model_validate_jsonimport pathlib from pydantic import BaseModel, EmailStr, PositiveInt class Person(BaseModel): name: str age: PositiveInt email: EmailStr json_lines pathlib.Path(people.jsonl).read_text().splitlines() people [Person.model_validate_json(line) for line in json_lines] print(people) # [Person(nameJohn Doe, age30, emailjohnexample.com), Person(nameJane Doe, age25, emailjaneexample.com)]相比一次性加载整个 JSON 列表.jsonl的优势在于可以逐行流式处理面对超大文件时用for line in f遍历文件对象逐行验证避免把整个文件读入内存。此时loc中的下标即对应文件行号从 0 计便于回查源文件。需要说明的是TypeAdapter.validate_json还提供实验性的experimental_allow_partial参数取值False/off、True/on、trailing-strings可开启流式分块输入的部分验证partial validation能力详见 pydantic/type_adapter.py。CSV 文件csv.DictReadermodel_validateCSV 是存储表格数据最常见的格式之一。Pydantic 本身不解析 CSV而是推荐配合 Python 标准库csv模块读取再交给模型验证。考虑如下people.csvname,age,email John Doe,30,johnexample.com Jane Doe,25,janeexample.com验证代码import csv from pydantic import BaseModel, EmailStr, PositiveInt class Person(BaseModel): name: str age: PositiveInt email: EmailStr with open(people.csv) as f: reader csv.DictReader(f) people [Person.model_validate(row) for row in reader] print(people) # [Person(nameJohn Doe, age30, emailjohnexample.com), Person(nameJane Doe, age25, emailjaneexample.com)]要点csv.DictReader把每一行转成以表头为键的dict其键名与模型字段名一致时可直接model_validate由于age在 CSV 中本质是字符串30PositiveInt在宽松模式下会自动完成字符串到整数的转换——这正是model_validate走 Python 对象验证路径而非 JSON 字符串路径的典型场景若表头与字段名不一致可借助字段别名Field(alias...)或先对行做键名映射。TOML 文件tomllib解析后验证TOML 因其简洁易读常被用于配置文件。考虑如下person.tomlname John Doe age 30 email johnexample.com验证代码tomllib是 Python 3.11 标准库import tomllib from pydantic import BaseModel, EmailStr, PositiveInt class Person(BaseModel): name: str age: PositiveInt email: EmailStr with open(person.toml, rb) as f: data tomllib.load(f) person Person.model_validate(data) print(person) # nameJohn Doe age30 emailjohnexample.com注意tomllib.load要求以二进制模式rb打开文件这是该 API 的硬性约束。TOML 的嵌套表结构天然对应嵌套模型例如[database]段可映射为嵌套的Database子模型。YAML 文件PyYAMLsafe_load后验证YAML 是常用于配置文件的、人类可读的数据序列化格式。考虑如下person.yamlname: John Doe age: 30 email: johnexample.com验证代码依赖 PyYAML 库pip install pyyamlimport yaml from pydantic import BaseModel, EmailStr, PositiveInt class Person(BaseModel): name: str age: PositiveInt email: EmailStr with open(person.yaml) as f: data yaml.safe_load(f) person Person.model_validate(data) print(person) # nameJohn Doe age30 emailjohnexample.com务必使用yaml.safe_load而非yaml.loadsafe_load只解析标准 YAML 标签避免反序列化任意 Python 对象带来的安全风险。解析结果同样是以字符串为主的普通 dictPydantic 的宽松模式会完成后续类型转换。XML 文件ElementTree提取后验证XML 是一种既人类可读又机器可读的标记语言。考虑如下person.xml?xml version1.0? person nameJohn Doe/name age30/age emailjohnexample.com/email /person使用标准库xml.etree.ElementTree解析将子标签名映射为字典键后再验证import xml.etree.ElementTree as ET from pydantic import BaseModel, EmailStr, PositiveInt class Person(BaseModel): name: str age: PositiveInt email: EmailStr tree ET.parse(person.xml).getroot() data {child.tag: child.text for child in tree} person Person.model_validate(data) print(person) # nameJohn Doe age30 emailjohnexample.com这里的核心技巧是{child.tag: child.text for child in tree}把 XML 子元素变成{标签: 文本}字典从而复用model_validate的对象验证路径。更复杂的 XML 结构嵌套元素、属性可据此扩展为递归转换函数。同时应注意解析不可信的 XML 输入时需防范 XXE外部实体注入风险可考虑使用禁用外部实体的解析方式。INI 文件configparser节映射后验证INI 是使用节section与键值对的简单配置文件格式常见于 Windows 应用与较老软件。考虑如下person.ini[PERSON] name John Doe age 30 email johnexample.com验证代码import configparser from pydantic import BaseModel, EmailStr, PositiveInt class Person(BaseModel): name: str age: PositiveInt email: EmailStr config configparser.ConfigParser() config.read(person.ini) person Person.model_validate(config[PERSON]) print(person) # nameJohn Doe age30 emailjohnexample.com关键点config[PERSON]返回的是SectionProxy对象它实现了映射接口__getitem__/keys()等因此可以直接传给model_validate。若配置文件中存在多个节也可以将整个config转换为普通字典后按需选取对应节进行验证。七种文件格式速查对照文件格式解析方式标准库/三方读取模式验证入口核心要点JSONpathlib.read_text文本model_validate_json/TypeAdapter.validate_json直接传 JSON 字符串性能最高JSONL文件逐行 /splitlines文本逐行model_validate_json可流式处理大文件loc对应行号CSVcsv.DictReader文本model_validate表头作键字符串自动转类型TOMLtomllib.load二进制rbmodel_validate嵌套表对应嵌套模型YAMLyaml.safe_loadPyYAML文本model_validate必须用safe_load防安全风险XMLxml.etree.ElementTree文本model_validate先转{tag: text}字典INIconfigparser.ConfigParser文本model_validateSectionProxy天然是映射对象实践小结与验证闭环本文所有示例均来自仓库文档 docs/examples/files.md且这些示例会被仓库的文档测试机制tests/test_docs.py 中的pytest_examples驱动执行与断言因此具备可复现性。在实际项目中建议按以下模式组织文件验证逻辑用标准库或轻量三方库把文件解析为纯 Python 对象dict / list用model_validatePython 对象或model_validate_jsonJSON 字符串完成强类型校验与类型转换批量场景用TypeAdapter包裹容器类型如list[Person]并在except ValidationError中利用err.errors()的loc定位出错记录无人值守流水线可结合 Logfire 与 troubleshooting 方案记录失败验证的完整输入与位置。这样无论数据来自哪种文件格式你的业务代码始终面对的是经过验证的强类型模型从而把数据是否可信的问题统一收敛到 Pydantic 的验证层。【免费下载链接】pydanticData validation using Python type hints项目地址: https://gitcode.com/GitHub_Trending/py/pydantic创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
