python环境搭建 (十) PyYAML核心基本用法

PyYAML==6.0.3 核心基本用法

PyYAML 6.0.3 仅支持 Python3.6+，核心能力是Python原生数据 ↔ YAML字符串/文件的双向转换，且官方强推安全解析/序列化（避免代码注入、格式异常），下面的用法覆盖日常99%的使用场景，直接可复制运行。

前置准备：安装

精准安装指定版本，终端执行：

pipinstallpyyaml==6.0.3

代码中统一导入模块：

importyaml

一、核心基础：Python数据 → YAML字符串（dump）

将Python的字典、列表、基本数据类型（str/int/float/bool/None）序列化为YAML格式的字符串，核心用yaml.safe_dump()（安全序列化，无自定义标签风险，官方推荐）。

1. 基础序列化（字典/列表）

# 1. 序列化Python字典（最常用，对应YAML的键值对）python_dict={"name":"张三","age":25,"is_student":False,"score":98.5,"hobby":["篮球","编程"],"address":None}yaml_str1=yaml.safe_dump(python_dict,sort_keys=False,allow_unicode=True)print("字典转YAML：\n",yaml_str1)# 2. 序列化Python列表python_list=["Python","Java",100,True]yaml_str2=yaml.safe_dump(python_list,allow_unicode=True)print("列表转YAML：\n",yaml_str2)

关键参数（必配，解决中文/排序问题）

• allow_unicode=True：保留中文，避免中文被转成Unicode编码（如\u5f20\u4e09），必加！
• sort_keys=False：不自动对字典的key排序，保留Python字典的原始键顺序（PyYAML默认会按字母排序key）。

输出结果

字典转YAML： name: 张三 age: 25 is_student: false score: 98.5 hobby: - 篮球 - 编程 address: null 列表转YAML： - Python - Java - 100 - true

注意：YAML中false/true/null对应Python的False/True/None，是语法规范。

2. 进阶：格式化输出（指定缩进）

用indent参数指定缩进空格数，让YAML字符串更整洁：

yaml_str=yaml.safe_dump(python_dict,sort_keys=False,allow_unicode=True,indent=4)print(yaml_str)

输出会以4个空格缩进，嵌套结构更清晰。

二、核心基础：YAML字符串 → Python数据（load）

将YAML格式的字符串解析为Python原生数据（字典/列表/基本类型），严禁使用原生yaml.load()（存在代码注入安全风险，6.0版本已弱化该方法），官方唯一推荐yaml.safe_load()（仅解析YAML基础类型，安全无风险）。

1. 基础解析（对应字典/列表的YAML字符串）

# 1. 解析为Python字典的YAML字符串yaml_str_dict=""" name: 李四 age: 30 is_worker: true salary: 15000.5 skill: - Python - SQL address: 北京市 """python_data1=yaml.safe_load(yaml_str_dict)print("YAML转字典：",python_data1)print("获取指定值：",python_data1["name"])# 直接按字典取值print("数据类型：",type(python_data1))# <class 'dict'># 2. 解析为Python列表的YAML字符串yaml_str_list=""" - 苹果 - 香蕉 - 橘子 - 99 """python_data2=yaml.safe_load(yaml_str_list)print("YAML转列表：",python_data2)print("数据类型：",type(python_data2))# <class 'list'>

输出结果

YAML转字典： {'name': '李四', 'age': 30, 'is_worker': True, 'salary': 15000.5, 'skill': ['Python', 'SQL'], 'address': '北京市'} 获取指定值： 李四 数据类型： <class 'dict'> YAML转列表： ['苹果', '香蕉', '橘子', 99] 数据类型： <class 'list'>

2. 特殊情况：空YAML/无效YAML

yaml.safe_load()解析空字符串会返回None，解析语法错误的YAML会抛出yaml.YAMLError异常，建议加异常捕获：

empty_yaml=""print(yaml.safe_load(empty_yaml))# None# 异常捕获示例invalid_yaml="name: 张三: 李四"# 语法错误try:yaml.safe_load(invalid_yaml)exceptyaml.YAMLErrorase:print("YAML解析失败：",e)

三、实际开发常用：读写YAML配置文件

日常项目中，YAML主要用作配置文件（如config.yaml），PyYAML可直接结合文件对象实现读取配置和写入配置，核心还是safe_load()和safe_dump()。

准备工作：新建YAML配置文件

在代码同目录下新建config.yaml，内容如下（含注释、嵌套，典型配置文件格式）：

# 项目配置文件project:name:PyYAML-Demoversion:1.0.0author:张三server:host:127.0.0.1port:8080debug:truedatabase:url:mysql://root:123456@localhost:3306/testpool_size:20

1. 读取YAML配置文件

将配置文件内容解析为Python字典，方便代码中获取配置项：

# 方法1：open() 手动关闭文件（推荐新手）withopen("config.yaml","r",encoding="utf-8")asf:config=yaml.safe_load(f)# 直接传入文件对象# 读取配置项（字典嵌套取值）print("项目名：",config["project"]["name"])print("服务端口：",config["server"]["port"])print("数据库地址：",config["database"]["url"])# 方法2：简化写法（同效果）config=yaml.safe_load(open("config.yaml","r",encoding="utf-8"))

必加encoding="utf-8"：避免读取YAML文件时中文乱码。

输出结果

项目名： PyYAML-Demo 服务端口： 8080 数据库地址： mysql://root:123456@localhost:3306/test

2. 写入YAML配置文件

将Python数据写入YAML文件（覆盖/新建），适合动态生成配置：

# 要写入的配置数据new_config={"project":{"name":"New-Demo","version":"2.0.0"},"server":{"host":"0.0.0.0","port":9090,"debug":False}}# 写入文件（w模式：覆盖原有内容；a模式：追加，不推荐YAML）withopen("new_config.yaml","w",encoding="utf-8")asf:yaml.safe_dump(new_config,stream=f,# 写入到文件流sort_keys=False,allow_unicode=True,indent=4# 缩进4个空格，增强可读性)

执行后，代码同目录会生成new_config.yaml，内容为格式化后的YAML，中文和顺序均保留。

四、拓展用法：批量读取多个YAML文档

YAML支持在一个文件/字符串中写多个文档，用---分隔，解析时用yaml.safe_load_all()，返回一个生成器，可遍历获取每个文档的Python数据。

1. 解析多文档YAML字符串

multi_yaml_str=""" name: 张三 age: 25 --- name: 李四 age: 30 --- name: 王五 age: 35 """# 解析多文档docs=yaml.safe_load_all(multi_yaml_str)# 遍历生成器，获取每个文档的字典fordocindocs:print(doc)

输出结果

{'name': '张三', 'age': 25} {'name': '李四', 'age': 30} {'name': '王五', 'age': 35}

2. 读取多文档YAML文件

新建multi_config.yaml，内容：

# 文档1user1:name:张三age:25---# 文档2user2:name:李四age:30

读取代码：

withopen("multi_config.yaml","r",encoding="utf-8")asf:fordocinyaml.safe_load_all(f):print(doc)

五、避坑指南（6.0.3版本关键注意点）

1. 永远不用yaml.load()：无安全校验，恶意YAML字符串可执行任意Python代码，造成安全漏洞，safe_load()完全满足基础用法；
2. 中文必加allow_unicode=True：dump/写入文件时不加会导致中文转Unicode，可读性极差；
3. 字典顺序必加sort_keys=False：PyYAML默认按字母排序字典key，会打乱业务逻辑的键顺序；
4. 文件操作必指定encoding="utf-8"：读写YAML文件时，不加会在Windows系统中出现中文乱码；
5. YAML语法规范：YAML的键值对用key: 值（冒号后必须加空格），列表项用- 项（横杠后必须加空格），语法错误会触发yaml.YAMLError。

核心用法总结

PyYAML==6.0.3 的基础用法围绕4个核心方法展开，覆盖所有日常场景：

1. yaml.safe_dump(data, ...)：Python数据 → YAML字符串（安全序列化）；
2. yaml.safe_load(yaml_str)：YAML字符串 → Python数据（安全解析）；
3. yaml.safe_dump(data, stream=文件对象, ...)：Python数据 → YAML文件；
4. yaml.safe_load(文件对象)：YAML文件 → Python数据（最常用，读取配置）。

关键参数三板斧：sort_keys=False + allow_unicode=True + encoding="utf-8"，解决90%的格式/编码问题。