Python?yaml格式配置文件操作實(shí)戰(zhàn)教程

更新時(shí)間：2025年11月07日 11:23:08 作者：諸神緘默不語

yaml是專門用來寫配置文件的語言,非常簡(jiǎn)潔和強(qiáng)大,用ini也能寫配置文件,看了yaml后,發(fā)現(xiàn)這個(gè)更直觀,更方便,有點(diǎn)類似于json格式,這篇文章主要介紹了Python?yaml格式配置文件操作的相關(guān)資料,需要的朋友可以參考下

1. 引言：為什么選擇 YAML？

在 Python 項(xiàng)目中，我們經(jīng)常需要配置數(shù)據(jù)庫連接、API 密鑰、路徑設(shè)置等參數(shù)。如果將這些信息直接寫在代碼里（硬編碼），會(huì)帶來極大的安全隱患和維護(hù)成本。常見的配置文件格式有 .ini, .json, .xml 和 .yaml/.yml。

與其他格式相比，YAML 的優(yōu)勢(shì)在于：

可讀性極高：采用清晰的縮進(jìn)結(jié)構(gòu)，類似于 Python，即使非技術(shù)人員也能輕松理解。
簡(jiǎn)潔的語法：不需要像 JSON 那樣充斥大量的括號(hào)和引號(hào)，也不像 XML 那樣冗余。
強(qiáng)大的功能：支持注釋、引用、復(fù)雜數(shù)據(jù)類型（列表、字典），甚至可以實(shí)現(xiàn)數(shù)據(jù)序列化。
語言無關(guān)：作為一種數(shù)據(jù)格式，它被多種編程語言廣泛支持。

它特別適合用于：配置文件、數(shù)據(jù)序列化、持續(xù)集成/部署 (CI/CD) 管道（如 GitHub Actions, Docker Compose, Kubernetes）。

2. YAML 基礎(chǔ)語法

YAML 的核心思想是使用縮進(jìn)來表示層級(jí)關(guān)系，禁止使用 Tab 鍵，只能使用空格。

2.1 基本數(shù)據(jù)類型

# 字符串 (通常不需要引號(hào)，除非有特殊字符)
name: John Doe
company: "CSDN & Co." # 包含特殊字符&，建議加引號(hào)
title: This is a title

# 數(shù)字
age: 29
score: 89.5

# 布爾值
is_active: true  # 或 True, TRUE
is_admin: false  # 或 False, FALSE

# 空值
salary: null     # 或 Null, NULL, ~

# 日期和時(shí)間
date: 2023-10-27
datetime: 2023-10-27T15:30:00+08:00

2.2 復(fù)合數(shù)據(jù)類型

列表 (List/Array)

使用短橫線 - 加一個(gè)空格來表示列表項(xiàng)。

fruits:
  - Apple
  - Banana
  - Orange

# 行內(nèi)寫法 (類似JSON數(shù)組)
colors: [red, blue, green]

字典 (Map/Dictionary)

使用 key: value 的形式表示。

person:
  name: Alice
  age: 25
  address: Beijing

# 行內(nèi)寫法 (類似JSON對(duì)象)
coordinates: { x: 12.5, y: -7.2 }

2.3 復(fù)雜結(jié)構(gòu)嵌套

列表和字典可以自由組合，形成復(fù)雜的數(shù)據(jù)結(jié)構(gòu)。

# 一個(gè)列表中包含多個(gè)字典
users:
  - name: John
    id: 1
    hobbies:
      - reading
      - hiking
  - name: Jane
    id: 2
    hobbies:
      - gaming
      - cooking

# 一個(gè)字典中某個(gè)值是列表
server:
  ip: 192.168.1.1
  ports:
    - 80
    - 443
    - 8080

2.4 高級(jí)特性（可選）

YAML 還支持一些高級(jí)特性，如錨點(diǎn) & 和別名 * 用于復(fù)用代碼塊，以及多行字符串。

# 錨點(diǎn)(&)和別名(*) - 避免重復(fù)
defaults: &defaults
  adapter: postgres
  host: localhost

development:
  <<: *defaults  # 合并defaults的內(nèi)容
  database: dev_db

test:
  <<: *defaults
  database: test_db

# 多行字符串
description: |
  This is a long text
  that spans multiple
  lines.           # 保留換行符

signature: >
  This will fold
  into a single
  line.            # 將換行折疊為空格

3. Python 操作 YAML 文件

Python 操作 YAML 文件主要使用第三方庫 PyYAML。

3.1 安裝 PyYAML

通過 pip 即可安裝：

pip install pyyaml

3.2 讀取 YAML 文件 (yaml.safe_load())

假設(shè)我們有一個(gè) config.yml 文件：

# config.yml
database:
  host: localhost
  port: 3306
  username: admin
  password: secret123
  db_name: my_app

logging:
  level: INFO
  file: /var/log/my_app.log
  rotation: 5

features:
  enable_upload: true
  allowed_file_types:
    - .jpg
    - .png
    - .pdf

在 Python 中讀取這個(gè)文件：

import yaml
import pathlib

# 推薦使用 pathlib 處理路徑
config_path = pathlib.Path('config.yml')

# 使用 safe_load() 而不是 load() 以避免安全風(fēng)險(xiǎn)！
with config_path.open('r', encoding='utf-8') as f:
    config_data = yaml.safe_load(f)

# 現(xiàn)在可以像操作普通字典一樣訪問配置
print(config_data['database']['host'])  # 輸出: localhost
print(config_data['features']['enable_upload'])  # 輸出: True

# 獲取日志配置
log_level = config_data['logging']['level']
print(f"日志級(jí)別是: {log_level}")

3.3 寫入 YAML 文件 (yaml.safe_dump())

將 Python 對(duì)象（字典、列表）寫回 YAML 文件。

import yaml

# 要寫入的 Python 數(shù)據(jù)
data_to_write = {
    'project': 'Awesome Project',
    'author': 'CSDN Blogger',
    'tags': ['python', 'tutorial', 'yaml'],
    'config': {
        'timeout': 30,
        'retries': 3
    }
}

# 寫入文件
with open('output.yml', 'w', encoding='utf-8') as f:
    # safe_dump() 同樣比 dump() 更安全
    # allow_unicode: 確保中文等字符正確顯示
    # indent: 指定縮進(jìn)空格數(shù)，讓文件更美觀
    yaml.safe_dump(
        data_to_write,
        f,
        allow_unicode=True,
        indent=2 # 可選，使用2空格縮進(jìn)，更美觀
    )

# 也可以直接生成一個(gè)YAML字符串
yaml_string = yaml.safe_dump(data_to_write, allow_unicode=True)
print(yaml_string)

運(yùn)行后生成的 output.yml 文件內(nèi)容如下：

author: CSDN Blogger
config:
  retries: 3
  timeout: 30
project: Awesome Project
tags:
- python
- tutorial
- yaml

4. 實(shí)戰(zhàn)：一個(gè)完整的配置管理示例

讓我們創(chuàng)建一個(gè)更實(shí)際的例子，模擬一個(gè)應(yīng)用的配置加載過程。

項(xiàng)目結(jié)構(gòu):

my_app/
├── config.yml
└── app.py

1. 創(chuàng)建配置文件 config.yml

# config.yml
app:
  name: My Python Application
  version: 1.0.0
  environment: development # production / staging

database:
  url: mysql+pymysql://user:pass@localhost:3306/dev_db
  pool_size: 5
  echo_sql: false

api:
  endpoint: https://api.example.com/v1
  timeout_seconds: 10
  retries: 2
  api_key: YOUR_API_KEY_HERE # 切記不要在代碼中提交真實(shí)密鑰！

logging:
  level: DEBUG
  format: "%(asctime)s - %(name)s - %(levelname)s - %(message)s"

2. 創(chuàng)建主程序 app.py

# app.py
import yaml
import pathlib
import logging
from typing import Dict, Any

def load_config(config_file: pathlib.Path) -> Dict[str, Any]:
    """加載YAML配置文件"""
    if not config_file.exists():
        raise FileNotFoundError(f"配置文件 {config_file} 未找到！")
    
    with config_file.open('r', encoding='utf-8') as f:
        config = yaml.safe_load(f)
    return config

def setup_logging(logging_config: Dict[str, Any]):
    """根據(jù)配置設(shè)置日志"""
    logging.basicConfig(
        level=getattr(logging, logging_config['level']),
        format=logging_config['format']
    )
    logging.info("日志系統(tǒng)初始化成功！")

def main():
    # 1. 加載配置
    try:
        config = load_config(pathlib.Path('config.yml'))
    except Exception as e:
        print(f"加載配置失敗: {e}")
        return

    # 2. 讀取應(yīng)用配置
    app_config = config['app']
    print(f"啟動(dòng)應(yīng)用: {app_config['name']} (版本: {app_config['version']})")

    # 3. 設(shè)置日志
    setup_logging(config['logging'])

    # 4. 模擬使用其他配置
    db_url = config['database']['url']
    api_endpoint = config['api']['endpoint']
    # ... 這里可以繼續(xù)初始化數(shù)據(jù)庫連接、API客戶端等 ...

    logging.debug(f"數(shù)據(jù)庫URL: {db_url}")
    logging.info(f"API端點(diǎn): {api_endpoint}")
    logging.warning("這是一個(gè)警告信息！")
    print("應(yīng)用初始化完成，開始運(yùn)行...")

if __name__ == "__main__":
    main()

運(yùn)行結(jié)果:

啟動(dòng)應(yīng)用: My Python Application (版本: 1.0.0)
應(yīng)用初始化完成，開始運(yùn)行...

同時(shí)，在日志中你會(huì)看到相應(yīng)的調(diào)試和信息輸出。

5. 安全警告與最佳實(shí)踐

始終使用 safe_load() 和 safe_dump()：
yaml.load() 和 yaml.dump() 功能強(qiáng)大，但可以執(zhí)行任意 Python 代碼，如果加載來自不可信源的 YAML 文件，會(huì)帶來嚴(yán)重的代碼注入安全風(fēng)險(xiǎn)。safe_load() 和 safe_dump() 將其限制為僅加載標(biāo)準(zhǔn)的 YAML 標(biāo)簽，因此是絕對(duì)安全的選擇。
敏感信息處理：
永遠(yuǎn)不要將真正的密碼、API 密鑰等敏感信息直接提交到代碼倉庫。應(yīng)該：
- 使用環(huán)境變量（如 os.getenv('DB_PASSWORD')）。
- 或者使用 .env 文件并通過 python-dotenv 庫加載，然后在 YAML 配置中通過變量引用。
- 專門的文件來管理密鑰。
- 對(duì).env文件和python-dotenv包的使用請(qǐng)參考我撰寫的另一篇博文：python-dotenv：用.env儲(chǔ)存系統(tǒng)變量并在Python3代碼中調(diào)用
配置默認(rèn)值和驗(yàn)證：
對(duì)于可選的配置項(xiàng)，應(yīng)在代碼中提供合理的默認(rèn)值?？梢允褂孟?Pydantic 或 marshmallow 這樣的庫來驗(yàn)證加載的配置數(shù)據(jù)結(jié)構(gòu)是否正確，避免缺少必要的配置項(xiàng)導(dǎo)致運(yùn)行時(shí)錯(cuò)誤。

6. 常見錯(cuò)誤

一個(gè)從老版本轉(zhuǎn)換為新版本時(shí)會(huì)遇到的問題：TypeError: load() missing 1 required positional argument: 'Loader' in Google Colab
解決方案：將load()改為safe_load()¹