python-dotenv

Python-dotenv 从文件中读取键值对，.env并可以将它们设置为环境变量。它有助于遵循 12 要素原则开发应用程序。

• 入门
• 其他用例
  • 在不改变环境的情况下加载配置
  • 将配置解析为流
  • 在 IPython 中加载 .env 文件
• 命令行界面
• 文件格式
  • 多行值
  • 变量扩展
• 相关项目
• 致谢

入门

pip install python-dotenv

如果您的应用程序从环境变量中获取配置，例如 12 因素应用程序，那么在开发中启动它不是很实用，因为您必须自己设置这些环境变量。

为了帮助您解决这个问题，您可以将 Python-dotenv 添加到您的应用程序中，使其在.env文件存在时（例如，在开发中）从文件中加载配置，同时通过环境保持可配置性：

from dotenv import load_dotenv

load_dotenv()  # take environment variables from .env.

# Code of your application, which uses environment variables (e.g. from `os.environ` or
# `os.getenv`) as if they came from the actual environment.

默认情况下，load_dotenv不会覆盖现有的环境变量。

要配置开发环境，.env请在项目的根目录中添加：

.
├── .env
└── foo.py

python-dotenv 支持的文件语法.env与 Bash 类似：

# Development settings
DOMAIN=example.org
ADMIN_EMAIL=admin@${DOMAIN}
ROOT_URL=${DOMAIN}/app

如果您在值中使用变量，请确保它们被{和包围}，就像 没有展开${DOMAIN}的裸变量一样。$DOMAIN

您可能想要添加.env到您的.gitignore. 文件中，特别是如果它包含密码之类的秘密。

有关可以在文件中写入的内容的更多信息，请参阅下面的“文件格式”部分 .env。

其他用例

在不改变环境的情况下加载配置

该函数dotenv_values或多或少与 .load_dotenvdict.env

from dotenv import dotenv_values

config = dotenv_values(".env")  # config = {"USER": "foo", "EMAIL": "foo@example.org"}

这尤其支持高级配置管理：

import os
from dotenv import dotenv_values

config = {
    **dotenv_values(".env.shared"),  # load shared development variables
    **dotenv_values(".env.secret"),  # load sensitive variables
    **os.environ,  # override loaded values with environment variables
}

将配置解析为流

load_dotenv并通过他们的 论点dotenv_values接受流。stream因此，可以从文件系统以外的源（例如网络）加载变量。

from io import StringIO

from dotenv import load_dotenv

config = StringIO("USER=foo\nEMAIL=foo@example.org")
load_dotenv(stream=config)

在 IPython 中加载 .env 文件

您可以在 IPython 中使用 dotenv。默认情况下，它将find_dotenv用于搜索 .env文件：

%load_ext dotenv
%dotenv

您还可以指定路径：

%dotenv relative/or/absolute/path/to/.env

可选标志：

• -o覆盖现有变量。
• -v增加冗长。

命令行界面

dotenv还包括一个 CLI 界面，它可以帮助您在.env不手动打开文件的情况下操作文件。

$ pip install "python-dotenv[cli]"
$ dotenv set USER foo
$ dotenv set EMAIL foo@example.org
$ dotenv list
USER=foo
EMAIL=foo@example.org
$ dotenv list --format=json
{
  "USER": "foo",
  "EMAIL": "foo@example.org"
}
$ dotenv run -- python foo.py

运行dotenv --help以获取有关选项和子命令的更多信息。

文件格式

格式没有正式指定，但随着时间的推移仍在改进。话虽如此， .env文件应该大多看起来像 Bash 文件。

键可以不加引号或单引号。值可以不加引号、单引号或双引号。忽略键、等号和值前后的空格。值后面可以跟注释。行可以以export指令开头，这不会影响它们的解释。

允许的转义序列：

• 在单引号值中：\\,\'
• 在双引号中：\\, \', \", \a, \b, \f, \n, \r, \t,\v

多行值

单引号或双引号的值可以跨越多行。以下示例是等效的：

FOO="first line
second line"

FOO="first line\nsecond line"

没有值的变量

变量可以没有值：

FOO

它导致dotenv_values将该变量名称与值相关联None（例如 {"FOO": None}. load_dotenv，另一方面，只是忽略这些变量。

这不应与 混淆FOO=，在这种情况下，变量与空字符串相关联。

变量扩展

Python-dotenv 可以使用 POSIX 变量扩展来插入变量。

使用load_dotenv(override=True)ordotenv_values()时，变量的值是以下列表中定义的第一个值：

• 文件中该变量的值.env。
• 该变量在环境中的值。
• 默认值（如果提供）。
• 空字符串。

使用load_dotenv(override=False)时，变量的值是以下列表中定义的第一个值：

• 该变量在环境中的值。
• 文件中该变量的值.env。
• 默认值（如果提供）。
• 空字符串。

相关项目

• Honcho - 用于管理基于 Procfile 的应用程序。
• django-dotenv
• django环境
• django-environ-2
• django-配置
• 转储环境
• 环境
• 动态会议
• parse_it

致谢

这个项目目前由Saurabh Kumar和 Bertrand Bonnefoy-Claudet 维护，如果没有这些了不起的人的支持，这个项目是不可能实现的。

变更日志

此项目的所有显着更改都将记录在此文件中。

格式基于Keep a Changelog，并且该项目遵循Semantic Versioning。

0.21.0 - 2022-09-03

添加

• CLI：通过“python -m”添加对调用的支持。（@theskumar #395）
• load_dotenv函数现在返回False. （@larsks #388）
• CLI：将 --format= 选项添加到列表命令。（@sammck #407）

固定的

• 删除 Python 3.5 和 3.6 并升级 GA（#393 by @eggplants）
• 使用open而不是io.open. （@rabinadk1 #389）
• 改进没有值的变量的文档（@bbc2 的#390）
• 添加parse_it到相关项目 (#410 by @naorlivne)
• 将 README.md 更新为 (#415 by @harveer07)
• 通过 (#398 by @bbc2) 直接使用 MkDocs 改进文档

0.20.0 - 2022-03-24

添加

• 将encoding( Optional[str]) 参数添加到get_key,set_key和unset_key。（#379 @bbc2）

固定的

• 使用 dict 指定(#376 by @mgorny )的entry_points参数。setuptools.setup
• 不要制造通用轮子（@bbc2的#387 ）。

0.19.2 - 2021-11-11

固定的

• 在set_key中，如有必要，在新条目之前添加缺少的换行符。(#361 @bbc2 )

0.19.1 - 2021-08-09

添加

• 添加对 Python 3.10 的支持。（@theskumar #359 ）

0.19.0 - 2021-07-24

改变了

• 需要 Python 3.5 或更高版本。不再支持 Python 2 和 3.4。（@bbc2的#341 ）。

添加

• and的dotenv_path参数现在有一个类型，而不是只是（#347 by @bbc2）。set_keyunset_keyUnion[str, os.PathLike]os.PathLike
• and的stream参数现在可以是文本流 ( )，其中包括和(#348 by @bbc2 ) 之类的值。load_dotenvdotenv_valuesIO[str]io.StringIO("foo")open("file.env", "r")

0.18.0 - 2021-06-20

改变了

• 提高ValueErrorifquote_mode不是always,auto或neverin set_key(#330 by @bbc2 )。
• set_key使用or将值写入 .env 文件时dotenv set <key> <value>（#330 by @bbc2）：
  • 使用单引号而不是双引号。
  • 不要剥离周围的引号。
  • 在auto模式下，如果值仅由字母数字字符组成（由 确定），则不要添加引号string.isalnum。

0.17.1 - 2021-04-29

固定的

• 修复了依赖于PYTHONPATH（#318 by @befeleme）的构建环境的测试。

0.17.0 - 2021-04-02

改变了

• dotenv get <key>只显示值，而不是key=value（@bbc2的#313 ）。

添加

• 将--override/--no-override选项添加到dotenv run（@zueve和@bbc2的#312 ）。

0.16.0 - 2021-03-27

改变了

• 和的encoding参数的默认值现在代替（@bbc2的#306 ）。load_dotenvdotenv_values"utf-8"None
• override=False使用(#287 by @bbc2 )修复变量扩展中的分辨率顺序。

0.15.0 - 2020-10-28

添加

• 添加--export选项以set使其在绑定之前添加export（ @jadutter的#270 ）。

改变了

• 如果未找到文件，则makeset命令.env在当前目录中创建文件（ @jadutter.env的#270 ）。

固定的

• 修复重复键的潜在空扩展值（@bbc2的#260 ）。
• 修复 Python 3.5.0 和 3.5.1 上的导入错误（#267 by @gongqingkui）。
• 修复包含多个相邻空格或制表符的未引用值的解析（@bbc2的#277， @x-yuri 的评论）。

0.14.0 - 2020-07-03

改变了

• 变量扩展中环境文件中的特权定义（ @elbehery95的#256 ）。

固定的

• 改进找不到文件时的错误消息（@snobu的#245 ）。
• 在包元数据中使用 HTTPS URL（@ekohl的#251 ）。

0.13.0 - 2020-04-16

添加

• 在变量扩展中添加对类似 Bash 的默认值的支持（@bbc2的#248 ）。

0.12.0 - 2020-02-28

改变了

• 使用当前工作目录查找.env何时被 PyInstaller 捆绑（#213 by @gergelyk）。

固定的

• set_key修复由(#236 by @bbc2 )写入的引用值的转义。
• 修复dotenv run没有值的环境变量崩溃（@yannham的#237 ）。
• 当最后一行为空时删除警告（@bbc2的#238 ）。

0.11.0 - 2020-02-07

添加

• 添加interpolate参数load_dotenv并dotenv_values禁用插值（@ulyssessouza的#232 ）。

改变了

• 使用日志记录而不是警告（@bbc2的#231 ）。

固定的

• 修复在非 UTF-8 环境中的安装（#225 by @altendky）。
• 修复 PyPI 分类器（#228 by @bbc2）。

0.10.5 - 2020-01-19

固定的

• 修复格式错误的行和没有值的行的处理（@bbc2的#222 ）：
  • 当键没有值时不要打印警告。
  • 拒绝更多格式错误的行（例如“A: B”、“a='b',c”）。
• 修复仅包含注释的行处理（@bbc2的#224 ）。

0.10.4 - 2020-01-17

添加

• 使输入成为可选（@techalchemy的#179 ）。
• 在格式错误的行上打印警告（@bbc2的#211 ）。
• 支持没有值的键（@ulyssessouza的#220 ）。

0.10.3

• 改进交互模式检测（@andrewsmith）（#183）。
• 重构解析器以修复解析不一致（@bbc2）（#170）。
  • 仅在双引号字符串中将转义解释为控制字符。
  • #仅当前面有空格时才解释为注释的开头。

0.10.2

• 添加类型提示并将其公开给用户（@qnighy）（#172）
• load_dotenv现在dotenv_values接受一个encoding参数，默认为None ( @theskumar )( @earlbread )([#161])
• Python 2 中的修复str/unicode不一致：值总是str现在。( @bbc2 )( #121 )
• 修复 0.10.0 中引入的 Python 2 中的 Unicode 错误。( @bbc2 )( #176 )

0.10.1

• 修复没有值的变量解析 ( @asyncee )( @bbc2 )( #158 )

0.10.0

• 在未引用的值中添加对 UTF-8 的支持 ( @bbc2 )( #148 )
• 添加对尾随注释的支持 ( @bbc2 )( #148 )
• 在值中添加反斜杠支持（@bbc2）（#148）
• 添加对值中换行符的支持（@bbc2）（#148）
• 在 Windows ( @greyli )上使用 Python2 强制环境变量为 str
• 放弃 Python 3.3 支持 ( @greyli )
• 修复 stderr/-out/-in 重定向（@venthur）

0.9.0

• 将--version参数添加到 cli ( @venthur )
• 启用从当前目录加载 ( @cjauvin )
• 添加 'dotenv run' 命令以使用 .env ( @venthur )调用任意 shell 脚本

0.8.1

• 为文档添加测试（@Flimm）
• 使“cli”支持可选。使用pip install python-dotenv[cli]. （@theskumar）

0.8.0

• set_key并且unset_key只修改了受影响的文件而不是解析和重写文件，这会导致注释和其他文件保持原样。
• 在行中添加对export前缀的支持。
• 内部折射（@theskumar）
• 允许load_dotenv并dotenv_values使用StringIO())( @alanjds )( @theskumar )( #78 )

0.7.1

• 删除对 iPython ( @theskumar )的硬依赖

0.7.0

• 添加支持以通过 .env 覆盖系统环境变量。（@milonimrod）（#63）
• 默认禁用“.env not found”警告（@maxkoryukov）（#57）

0.6.5

• 添加对特殊字符的支持\。（@pjona）（#60）

0.6.4

• 修复单引号 ( @Flimm ) ( #52 )的问题

0.6.3

• 在 setup.py ( #46 )中处理 unicode 异常

0.6.2

• 修复 dotenv 列表命令 ( @ticosax )
• 添加 iPython 支持 ( @tillahoffmann )

0.6.0

• 放弃对 Python 2.6 的支持
• 处理引用值中的转义字符和换行符。（感谢 @iameugenejo）
• 删除未引用的键/值周围的任何空格。（感谢 @paulochf）
• 添加了 POSIX 变量扩展。（感谢 @hugochinchilla）

0.5.1

• 修复 find_dotenv - 它现在从调用此函数的文件开始搜索。

0.5.0

• 添加find_dotenv将尝试查找.env文件的方法。（感谢@isms）

0.4.0

• cli：添加-q/--quote了控制.env. （感谢 @hugochinchilla）。
• 改进的测试覆盖率。