python-decouple：把配置从代码里抽出来

HBNetwork 维护的 python-decouple 是一个 Python 配置管理工具，目前收获了 3,041 个 Star。

这个项目最初为 Django 设计，后来演化成通用库。核心目标只有一个：让配置参数和代码彻底分离，修改参数时无需重新部署应用。

为什么要分离配置

Web 框架的配置文件通常混杂两类参数：项目设置（语言、中间件）和实例设置（数据库地址、密钥、域名）。项目设置随代码走，实例设置应该能随时调整而不触发重新部署。

直接用环境变量也行，但有个坑：os.environ 返回的永远是字符串。设一个 DEBUG=False，在 Python 里判断 if os.environ['DEBUG'] 会得到 True，因为 "False" 是非空字符串。

python-decouple 的做法是提供 config 函数，配合 cast 参数做类型转换：

from decouple import config

SECRET_KEY = config('SECRET_KEY')
DEBUG = config('DEBUG', default=False, cast=bool)
EMAIL_PORT = config('EMAIL_PORT', default=25, cast=int)

config 接收三个来源的数据：环境变量、配置文件、默认值，优先级依次递减。环境变量永远覆盖配置文件中的同名参数，符合 Unix 惯例。

支持的配置格式

python-decouple 支持两种配置文件格式。

.env 文件放在仓库根目录：

DEBUG=True
SECRET_KEY=ARANDOMSECRETKEY
DATABASE_URL=mysql://myuser:mypassword@myhost/mydatabase

settings.ini 放在配置模块旁边：

[settings]
DEBUG=True
SECRET_KEY=ARANDOMSECRETKEY
DATABASE_URL=mysql://myuser:mypassword@myhost/mydatabase

ini 文件支持字符串插值，写 %(DEBUG)s 可以引用同文件的变量。

类型转换

除了基础的 cast=bool 和 cast=int，python-decouple 还内置了两个辅助类。

Csv 用于把逗号分隔的字符串转成列表：

from decouple import Csv

config('ALLOWED_HOSTS', default='127.0.0.1', cast=Csv())

也可以指定元素类型：

config('LIST_OF_INTEGERS', cast=Csv(int))

Choices 用于限制可选值，超出范围直接抛 ValueError：

from decouple import Choices

config('CONNECTION_TYPE', cast=Choices(['eth', 'usb', 'bluetooth']))

默认值与错误策略

如果某个配置项在配置文件和环境变量中都不存在，且调用 config 时没有传 default 参数，python-decouple 会抛出 UndefinedValueError。这种 fail fast 的设计能在部署早期暴露缺失的配置，避免运行时出现奇怪行为。

SECRET_KEY = config('SECRET_KEY')  # 未定义则报错
DEBUG = config('DEBUG', default=False, cast=bool)  # 未定义则取默认值

安装

一条 pip 命令即可：

pip install python-decouple

python-decouple 兼容 Python 2.7 和 Python 3.6+，体量很小，没有额外依赖。

这个库没有花哨的功能，只专注做好一件事：从代码中解耦配置。对于需要管理多环境部署的 Python 项目，它是一个扎实的基础工具。

.7 和 Python 3.6+，体量很小，没有额外依赖。

这个库没有花哨的功能，只专注做好一件事：从代码中解耦配置。对于需要管理多环境部署的 Python 项目，它是一个扎实的基础工具。