使用 Python 操作 YAML 的完整指南｜從設定檔管理到進階自訂標籤操作

By 佐川 直弘 | Naohiro Sagawa (運営者)

※記事内に広告を含みます。Amazonアソシエイトとして適格販売により収入を得ています。

1. YAML是什麼？

YAML的概要

YAML（YAML Ain’t Markup Language）是一種資料序列化格式，廣泛用於表示結構化數據。它與JSON或XML類似，但YAML的特點是簡潔且可讀性高。特別是，YAML使用縮排來表達階層結構，使其成為人類易於閱讀的格式，這是一大優勢。

與JSON和XML的差異

雖然JSON和XML同樣用於記錄數據，但與這些格式相比，YAML更簡潔，減少了冗長的符號，使其更易於理解。例如，JSON需要使用大括號 {} 和逗號 ,，在處理大型數據時，可讀性可能會降低。而YAML則透過縮排來表示結構，使數據的階層關係更加直觀。

與Python的相容性

Python的語法特點之一是使用縮排來定義程式區塊，這與YAML的格式相當匹配。此外，Python提供了「PyYAML」庫，可以輕鬆讀取和寫入YAML文件，因此在Python專案中，YAML常被用作設定檔格式。

2. 如何在Python中讀寫YAML文件

讀取YAML文件

要在Python中讀取YAML文件，首先需要安裝「PyYAML」庫，然後使用 yaml.safe_load() 函數。這個函數可以將YAML數據安全地轉換為Python的字典或列表。以下是基本的讀取範例：

import yaml

# 開啟YAML文件並讀取內容
with open('config.yaml', 'r') as file:
    data = yaml.safe_load(file)

print(data)

這段程式碼會從YAML文件中讀取數據，並將其作為Python的字典來處理。例如，假設我們要讀取以下YAML文件：

database:
  host: localhost
  port: 3306

在Python中，這將轉換為以下字典：

{'database': {'host': 'localhost', 'port': 3306}}

寫入YAML文件

要將Python數據寫入YAML文件，可以使用 yaml.dump() 函數。以下範例展示如何將Python字典寫入YAML文件：

import yaml

data = {
    'name': 'John Doe',
    'age': 30,
    'city': 'New York'
}

with open('output.yaml', 'w') as file:
    yaml.dump(data, file)

此程式碼會將 data 字典儲存為 output.yaml 文件，輸出的YAML內容如下：

age: 30
city: New York
name: John Doe

處理中文字符

在YAML文件中處理中文時，為了避免文字顯示異常，建議使用 allow_unicode=True 選項。這樣可以確保YAML文件能夠正確顯示中文內容。

yaml.dump(data, file, allow_unicode=True)

3. 進階的YAML操作

建立自訂標籤

YAML不僅支援基本的數據類型（如列表、字典），還可以將Python物件序列化並反序列化。這可以透過自訂標籤來實現。以下範例展示如何將Python類別存儲為YAML格式：

import yaml

class Person:
    def __init__(self, name, age):
        self.name = name
        self.age = age

def person_representer(dumper, data):
    return dumper.represent_mapping('!Person', {'name': data.name, 'age': data.age})

def person_constructor(loader, node):
    values = loader.construct_mapping(node)
    return Person(values['name'], values['age'])

yaml.add_representer(Person, person_representer)
yaml.add_constructor('!Person', person_constructor)

# 將物件轉換為YAML並存儲
person = Person('Alice', 25)
with open('person.yaml', 'w') as file:
    yaml.dump(person, file)

# 從YAML文件重建物件
with open('person.yaml', 'r') as file:
    loaded_person = yaml.load(file, Loader=yaml.FullLoader)

透過這種方式，可以將Python物件以自訂格式存儲到YAML中，並在稍後重新讀取以供使用。

保持鍵值順序

在PyYAML中，預設情況下字典的鍵值順序不會被保留。因此，如果順序對於您的應用程式很重要，建議使用 ruamel.yaml 庫。該庫支援保持鍵值順序，這在處理需要確保配置順序的設定檔時特別有用。

4. YAML的應用範例：設定檔管理

作為設定檔的便利性

YAML被廣泛用於作為設定檔，尤其在Python應用程式中，YAML提供了一種最佳的管理設定數據的方式。由於YAML具有良好的人類可讀性，並能直觀地表達階層結構，因此特別適合用於管理應用程式的配置，例如數據庫連線資訊、日誌設定等。

database:
  host: localhost
  port: 3306
  username: user
  password: pass

logging:
  level: DEBUG
  file: /var/log/app.log

如上所示，YAML允許簡潔地記錄多個設定，使其在視覺上更易於理解。

在實際專案中的應用

YAML在許多Python框架和工具中被廣泛使用，例如Django、Flask、CircleCI、Kubernetes等。這些專案主要使用YAML來進行配置管理與環境變數定義。

Django中的YAML應用：
在Django專案中，可以使用YAML來讀取外部設定檔，使部署與環境配置更加靈活。透過YAML，開發環境與生產環境可以使用不同的設定文件，從而提高維護性。

import yaml

with open('config.yaml', 'r') as file:
    config = yaml.safe_load(file)

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.mysql',
        'NAME': config['database']['name'],
        'USER': config['database']['username'],
        'PASSWORD': config['database']['password'],
        'HOST': config['database']['host'],
        'PORT': config['database']['port'],
    }
}

與JSON和XML的比較

作為設定檔格式，YAML比JSON和XML更加直觀。JSON使用大括號和逗號來組織數據，而XML則需要使用開頭與結尾標籤，這些都會影響可讀性。相比之下，YAML透過縮排來表示階層結構，使設定檔內容更易理解。

JSON與YAML的比較：

{
  "database": {
    "host": "localhost",
    "port": 3306,
    "username": "user",
    "password": "pass"
  },
  "logging": {
    "level": "DEBUG",
    "file": "/var/log/app.log"
  }
}

database:
  host: localhost
  port: 3306
  username: user
  password: pass

logging:
  level: DEBUG
  file: /var/log/app.log

YAML相較於JSON，更加簡潔且容易閱讀。

5. 疑難排解與錯誤處理

常見錯誤及其解決方法

在處理YAML文件時，最常見的錯誤包括「文件不存在」或「文件格式錯誤」。這些錯誤可以透過適當的錯誤處理機制來預防和解決。

例如，當YAML文件解析失敗時，可以使用 yaml.YAMLError 來捕獲異常。另外，若文件不存在，則可以使用 FileNotFoundError 來處理，並向使用者提供適當的錯誤提示。

import yaml

def load_yaml(file_path):
    try:
        with open(file_path, 'r') as file:
            data = yaml.safe_load(file)
    except FileNotFoundError:
        print(f"錯誤：文件 {file_path} 不存在。")
        return None
    except yaml.YAMLError as e:
        print(f"錯誤：無法解析YAML文件。{e}")
        return None
    return data

config = load_yaml('config.yaml')
if config:
    print(config)

錯誤處理的最佳實踐

1. 檢查文件是否存在： 在讀取YAML文件前，應先確認文件是否存在，避免發生讀取錯誤。
2. 處理解析錯誤： 若YAML格式錯誤，應捕獲並顯示詳細的錯誤資訊，幫助用戶找出問題所在。
3. 記錄錯誤日誌： 當發生問題時，應將錯誤訊息記錄到日誌文件，以便後續進行故障排除。

6. 總結

YAML是一種簡潔且可讀性高的數據序列化格式，特別適合用於配置文件管理。在Python中，使用PyYAML庫可以輕鬆讀取與寫入YAML文件，並廣泛應用於各類專案。

除了基本的讀取與寫入操作，YAML還支援自訂標籤、物件序列化、鍵值順序保持等進階功能。透過這些技術，開發者可以更靈活地管理應用程式設定，提升維護效率。

YAML不僅限於配置文件管理，還可以作為數據儲存格式，在不同領域中發揮作用。未來，隨著Python應用的擴展，YAML的使用場景也將持續增加。