Python 常見的組態檔寫法梳理彙總

前言

在本文裡列舉的組態檔型別其複雜性由上到下依次增加：ini < json ≈ toml < yaml，它們之間各有優劣，可以根據自己實際的需求和團隊共同作業要求來具體選擇。

為什麼要寫組態檔

在開發過程中，我們常常會用到一些固定引數或者是常數。對於這些較為固定且常用到的部分，往往會將其寫到一個固定檔案中，避免在不同的模組程式碼中重複出現從而保持核心程式碼整潔。

這個固定檔案我們可以直接寫成一個 .py 檔案，例如 settings.py 或 config.py，這樣的好處就是能夠在同一工程下直接通過 import 來匯入當中的部分；但如果我們需要在其他非 Python 的平臺進行組態檔共用時，寫成單個 .py 就不是一個很好的選擇。

這時我們就應該選擇通用的組態檔型別來作為儲存這些固定的部分。目前常用且流行的組態檔格式型別主要有 ini、json、toml、yaml、xml 等，這些型別的組態檔我們都可以通過標準庫或第三方庫來進行解析。

ini

ini 即 Initialize 初始化之意，早期是在 Windows 上組態檔的儲存格式。ini 檔案的寫法通俗易懂，往往比較簡單，通常由節（Section）、鍵（key）和值（value）組成，就像以下形式：

[localdb]
host     = 127.0.0.1
user     = root
password = 123456
port     = 3306
database = mysql

Python 本身內建的 configparser 標準庫，我們直接就可以用來對 ini 檔案進行解析。如我們將上述內容儲存在一個名為 db.ini 的檔案中，然後使用 read() 方法來進行解析和讀取，最後通過 items() 方法來獲取指定節點下的所有鍵值對。

>>> from configparser import ConfigParser
>>> cfg = ConfigParser()
>>> cfg.read("/Users/Bobot/db.ini")
['/Users/Bobot/db.ini']
>>> cfg.items("localdb")
[('host', '127.0.0.1'), ('user', 'root'), ('password', '123456'), ('port', '3306'), ('database', 'mysql')]

需要注意的是，configparser 預設將值以字串的形式呈現，所以這也就是為什麼我們在 db.ini 檔案中沒有加引號而是直接將字面量寫在上面的原因。

獲取到鍵值對後，我其實直接就將其轉換成字典，然後通過解包的方式進行穿參，保持程式碼簡潔：

#!pip install pymysql
import pymysql
from configparser import ConfigParser
cfg = ConfigParser()
cfg.read("/Users/Bobot/db.ini")
db_cfg = dict(cfg.items("localdb"))
con = pymysql.connect(**db_cfg)

json

json 格式可以說是我們常見的一種檔案形式了，也是目前在網際網路較為流行的一種資料交換格式。除此之外，json 有時也是組態檔的一種。

比如 npm（JavaScript 包管理工具類似 Python 的 pip）、以及微軟出品的目前被廣泛使用的 VSCode 編輯器，都使用 json 編寫設定引數。

和 configparser 一樣，Python 也內建了 json 標準庫，可以通過 load() 和 loads() 方法來匯入檔案式和字串的 json 內容。

{
   "localdb":{
       "host": "127.0.0.1",
       "user": "root",
       "password": "123456",
       "port": 3306,
       "database": "mysql"
   }
}

我們將上述內容儲存為 db.json 後進行讀取和解析，json 庫讀取 json 檔案相對簡單容易，而且很容易解析成 Python 的字典物件。

>>> import json
>>> from pprint import pprint
>>>
>>> with open('/Users/Bobot/db.json') as j:
...     cfg = json.load(j)['localdb']
...
>>> pprint(cfg)
{'database': 'mysql',
'host': '127.0.0.1',
'password': '123456',
'port': 3306,
'user': 'root'}

使用 json 檔案設定的缺點就是語法標準嚴格限制，為人所詬病之一的就是無法在當中寫註釋，除非採取 json 型別的其他超集作為替代方案（VSCode 中能寫註釋的 json 引陣列態檔便是代替方案的一種）；同時存在巢狀過深的問題，容易導致出錯，不宜用來寫過長或複雜的引數設定資訊。

toml

toml 格式（或 tml 格式）是 Github 聯合創始人 Tom Preston-Werner 所提出的一種組態檔格式。根據維基百科的資料，toml 最開始提出時是在 2013年7月份，距今已有七年時間；它在某些方面也與後面要談到的 yaml 檔案有些類似，但如果當你知道 yaml 的規範有幾十頁（沒有錯，真的就是幾十頁……）的時候，可能你真的就不太願意去寫那麼複雜的組態檔，toml 格式則倒是個不錯的選擇。

toml 格式大致如下：

從這裡可以看出 toml 有點類似於前面所講的 ini 檔案。但是它比 ini 擴充套件了更多的內容。

在樣例圖片中我們可以看到，除了基本的字串以外，例如時間戳、布林值、陣列等都進一步支援，而且樣式和 Python 的原生寫法十分類似。

當然這裡不會過多介紹 toml 格式的一些規範說明，有人已經對官方的規範檔案進行了翻譯，有興趣的朋友可以直接查閱。

這麼契合 Python 方式的組態檔型別已經有開發者造出了相應的「輪子」，目前在 Github 上 Stars 數最多的是則是 uiri/toml 的版本，不過該版本僅通過了 v0.5 版本 toml 規範，但在使用上還是蠻簡潔的，我們可以通過 pip 命令進行安裝

pip install toml

該庫的解析方式很簡單，也有點類似於 json 庫的解析用法，即通過load() 或 loads() 來進行解析；同理轉換並匯出也是同樣類似的用法。

比如我們現在將以下內容寫入到 config.toml 中：

[mysql]
host     = "127.0.0.1"
user     = "root"
port     = 3306
database = "test"
 [mysql.parameters]
 pool_size = 5
 charset   = "utf8"
 [mysql.fields]
 pandas_cols = [ "id", "name", "age", "date"]

緊接著我們就可以通過 toml 庫中的 load() 方法來進行讀取：

>>> import toml
>>> import os
>>> from pprint import pprint
>>> cfg = toml.load(os.path.expanduser("~/Desktop/config.toml"))
>>> pprint(cfg)
{'mysql': {'database': 'test',
          'fields': {'pandas_cols': ['id', 'name', 'age', 'date']},
          'host': '127.0.0.1',
          'parameters': {'charset': 'utf8', 'pool_size': 5},
          'port': 3306,
          'user': 'root'}}

可以看到 toml 檔案被間接地轉化成了字典型別，當然這也就是 json 版的寫法（將單引號替換成雙引號即可），方便我們後續呼叫或者傳參。

yaml

yaml 格式（或 yml 格式）是目前較為流行的一種組態檔，它早在 2001 由一個名為 Clark Evans 的人提出；同時它也是目前被廣泛使用的組態檔型別，典型的就是 Docker 容器裡的 docker-compose.yml 組態檔，如果經常使用 Docker 進行部署的人對此不會陌生。

yaml 檔案的設計從 Python、XML 等地方獲取靈感，所以在使用時能很清楚地看到這些部分的影子。

在上一節 toml 內容裡我曾提到，yaml 的規範內容可以說是冗長和複雜，足足有80頁之多（鬥尊強者，恐怖如斯……）。

yaml規範頁數：

所以感興趣的朋友可以再自行了解相關用法。

YAML 官方早已經提供了相應的 Python 庫進行支援，即 PyYAML；當然也同樣需要我們事先進行安裝：

pip install pyyaml

同 json 庫和 toml 庫一樣，通過 load() 方法來進行載入。

需要注意的是，使用 load() 方法會存在一定的安全隱患，從思科 Talos 的這份報告中我們可以看到，如果載入了未知或不信任的 yaml 檔案，那麼有可能會存在被攻擊的風險和網路安全隱患，因為它能夠直接呼叫相應的 Python 函數來執行為攻擊者所需要的命令，比如說在 yaml 檔案中寫入這麼一段：

# 使用Linux和macOS的朋友不要輕易嘗試
!!python/object/apply:os.system ["rm -rf /"]

因此最好是使用 safe_load() 來代替 load() 方法。

這和 Python 內建的 string 標準庫中 Template 類的 substitute() 模板方法一樣存在著同樣的安全隱患，所以使用 safe_substitute() 來替代是一樣的道理。

如我們現在將之前的一些設定資訊寫入 config.yaml 檔案中：

mysql:
 host: "127.0.0.1"
 port: 3306
 user: "root"
 password: "123456"
 database: "test"
 parameter:
   pool_size: 5
   charset: "utf8"
 fields:
    pandas_cols:
     - id
     - name
     - age
     - date

然後我們通過 safe_load() 方法進行解析：

>>> import os
>>> from pprint import pprint
>>>
>>> with open(os.path.expanduser("~/config.yaml"), "r") as config:
...     cfg = yaml.safe_load(config)
...
>>> pprint(cfg)
{'mysql': {'database': 'test',
          'fields': {'pandas_cols': ['id', 'name', 'age', 'date']},
          'host': '127.0.0.1',
          'parameter': {'charset': 'utf8', 'pool_size': 5},
          'password': '123456',
          'port': 3306,
          'user': 'root'}}

可以看到最後結果和前面的 toml 庫的解析結果基本一致。

結尾

本文列舉了一些主流且常見的組態檔型別及其 Python 的讀取方法，可能有的讀者會發現當中沒有 xml 格式型別的內容。對於 xml 組態檔可能與 Java 系語言打交道的朋友遇見得會多一些，但 xml 檔案的可讀性實在是讓人望而生畏；對 xml 檔案不瞭解的朋友可以使用 Chrome 瀏覽器隨便進入一個網站然後按下 F12 進入開發者後檢視那密密麻麻的 html 元素便是 .xml 的縮影。

除了這些主流的組態檔型別之外，像一些 .cfg、.properties 等都可以作為組態檔，甚至和開頭提到的那樣，你單獨用一個 .py 檔案來書寫各類設定資訊作為組態檔進行匯入都是沒問題，只是在跨語言共用時可能會有些障礙。因此本文就不過多介紹，感興趣的朋友可以進一步自行了解。

在本文裡列舉的組態檔型別其複雜性由上到下依次增加：ini < json ≈ toml < yaml，它們之間各有優劣，可以根據自己實際的需求和團隊共同作業要求來具體選擇。