简化的环境变量解析
environs的Python项目详细描述
环境:简化的环境变量解析
environs是用于分析环境变量的python库。 它允许您根据 The Twelve-Factor App方法论。
内容
- Features
- Install
- Basic usage
- Supported types
- Reading .env files
- Handling prefixes
- Proxied variables
- Validation
- Serialization
- Defining custom parser behavior
- Usage with Flask
- Usage with Django
- Why...?
- License
功能
安装
pip install environs
基本用法
设置了一些环境变量…
exportGITHUB_USER=sloria exportMAX_CONNECTIONS=100exportSHIP_DATE='1984-06-25'exportTTL=42exportENABLE_LOGIN=trueexportGITHUB_REPOS=webargs,konch,ped exportCOORDINATES=23.3,50.0 exportLOG_LEVEL=DEBUG
用环境分析它们…
fromenvironsimportEnvenv=Env()env.read_env()# read .env file, if it exists# required variablesgh_user=env("GITHUB_USER")# => 'sloria'secret=env("SECRET")# => raises error if not set# castingmax_connections=env.int("MAX_CONNECTIONS")# => 100ship_date=env.date("SHIP_DATE")# => datetime.date(1984, 6, 25)ttl=env.timedelta("TTL")# => datetime.timedelta(0, 42)log_level=env.log_level("LOG_LEVEL")# => logging.DEBUG# providing a default valueenable_login=env.bool("ENABLE_LOGIN",False)# => Trueenable_feature_x=env.bool("ENABLE_FEATURE_X",False)# => False# parsing listsgh_repos=env.list("GITHUB_REPOS")# => ['webargs', 'konch', 'ped']coords=env.list("COORDINATES",subcast=float)# => [23.3, 50.0]
支持的类型
以下是Env
的所有类型转换方法:
env.str
env.bool
env.int
env.float
env.decimal
env.list
(接受可选的subcast
关键字参数)env.dict
(接受可选的subcast
关键字参数)env.json
env.datetime
env.date
env.timedelta
(假设值是以秒为单位的整数)env.url
env.uuid
env.log_level
env.path
(转换为^{} )
正在读取.env
文件
# .envDEBUG=truePORT=4567
在分析变量之前调用Env.read_env
。
fromenvironsimportEnvenv=Env()# Read .env into os.environenv.read_env()env.bool("DEBUG")# => Trueenv.int("PORT")# => 4567
读取特定文件
默认情况下,Env.read_env
将在当前
目录和(如果没有.Env存在于CWD)递归
向上直到找到.env
文件。
您还可以读取特定文件:
fromenvironsimportEnvwithopen(".env.test","w")asfobj:fobj.write("A=foo\n")fobj.write("B=123\n")env=Env()env.read_env(".env.test",recurse=False)assertenv("A")=="foo"assertenv.int("B")==123
处理前缀
# export MYAPP_HOST=lolcathost# export MYAPP_PORT=3000withenv.prefixed("MYAPP_"):host=env("HOST","localhost")# => 'lolcathost'port=env.int("PORT",5000)# => 3000# nested prefixes are also supported:# export MYAPP_DB_HOST=lolcathost# export MYAPP_DB_PORT=10101withenv.prefixed("MYAPP_"):withenv.prefixed("DB_"):db_host=env("HOST","lolcathost")db_port=env.int("PORT",10101)
代理变量
# export MAILGUN_LOGIN=sloria# export SMTP_LOGIN={{MAILGUN_LOGIN}}smtp_login=env("SMTP_LOGIN")# =>'sloria'
验证
# export TTL=-2# export NODE_ENV='invalid'# export EMAIL='^_^'# simple validatorenv.int("TTL",validate=lambdan:n>0)# => Environment variable "TTL" invalid: ['Invalid value.']# using marshmallow validatorsfrommarshmallow.validateimportOneOfenv.str("NODE_ENV",validate=OneOf(["production","development"],error="NODE_ENV must be one of: {choices}"),)# => Environment variable "NODE_ENV" invalid: ['NODE_ENV must be one of: production, development']# multiple validatorsfrommarshmallow.validateimportLength,Emailenv.str("EMAIL",validate=[Length(min=4),Email()])# => Environment variable "EMAIL" invalid: ['Shorter than minimum length 4.', 'Not a valid email address.']
序列化
# serialize to a dictionary of simple types (numbers and strings)env.dump()# {'COORDINATES': [23.3, 50.0],# 'ENABLE_FEATURE_X': False,# 'ENABLE_LOGIN': True,# 'GITHUB_REPOS': ['webargs', 'konch', 'ped'],# 'GITHUB_USER': 'sloria',# 'MAX_CONNECTIONS': 100,# 'MYAPP_HOST': 'lolcathost',# 'MYAPP_PORT': 3000,# 'SHIP_DATE': '1984-06-25',# 'TTL': 42}
定义自定义分析器行为
# export DOMAIN='http://myapp.com'# export COLOR=invalidfromfurlimportfurl# Register a new parser method for paths@env.parser_for("furl")deffurl_parser(value):returnfurl(value)domain=env.furl("DOMAIN")# => furl('https://myapp.com')# Custom parsers can take extra keyword arguments@env.parser_for("enum")defenum_parser(value,choices):ifvaluenotinchoices:raiseenvirons.EnvError("Invalid!")returnvaluecolor=env.enum("COLOR",choices=["black"])# => raises EnvError
与烧瓶一起使用
# myapp/settings.pyfromenvironsimportEnvenv=Env()env.read_env()# Override in .env for local developmentDEBUG=env.bool("FLASK_DEBUG",default=False)# SECRET_KEY is requiredSECRET_KEY=env.str("SECRET_KEY")
初始化应用程序后加载配置。
# myapp/app.pyfromflaskimportFlaskapp=Flask(__name__)app.config.from_object("myapp.settings")
对于本地开发,使用.env
文件覆盖默认值
配置。
# .envDEBUG=trueSECRET_KEY="not so secret"
注意:因为环境依赖于python-dotenv, cli将自动读取.env和.flaskenv文件。
与django一起使用
环境包括许多用于分析连接url的帮助程序。到 使用django支持安装环境::
pip install environs[django]
使用env.dj_db_url
和env.dj_email_url
解析DATABASE_URL
和EMAIL_URL
环境变量。
# myproject/settings.pyfromenvironsimportEnvenv=Env()env.read_env()# Override in .env for local developmentDEBUG=env.bool("DEBUG",default=False)# SECRET_KEY is requiredSECRET_KEY=env.str("SECRET_KEY")# Parse database URLs, e.g. "postgres://localhost:5432/mydb"DATABASES={"default":env.dj_db_url("DATABASE_URL")}# Parse email URLs, e.g. "smtp://"email=env.dj_email_url("EMAIL_URL",default="smtp://")EMAIL_HOST=email["EMAIL_HOST"]EMAIL_PORT=email["EMAIL_PORT"]EMAIL_HOST_PASSWORD=email["EMAIL_HOST_PASSWORD"]EMAIL_HOST_USER=email["EMAIL_HOST_USER"]EMAIL_USE_TLS=email["EMAIL_USE_TLS"]
对于本地开发,使用.env
文件覆盖默认值
配置。
# .envDEBUG=trueSECRET_KEY="not so secret"
有关更完整的示例,请参见
django_example.py
在examples/
目录中。
为什么…?
为什么是Envvars?
参见The 12-factor App部分 configuration。
为什么不os.environ
?
虽然os.environ
对于简单的用例来说已经足够了,但是一个典型的应用程序
需要一种方法来操作和验证原始环境变量。
环境抽象了处理环境变量的常见任务。
环境将帮助您
- 将环境变量转换为正确的类型
- 指定所需的环境变量
- 定义默认值
- 验证环境变量
- 分析列表和dict值
- 分析日期、日期时间和时间增量
- 将配置序列化为json、yaml等。
为什么是另一个图书馆?
有许多伟大的python库用于分析环境变量。 事实上,environs的公共api的大部分功劳都归功于 作者envparse和 django-environ。
environs旨在实现三个附加目标:
- 使扩展解析行为和开发插件变得容易。
- 利用反序列化和验证功能pr产卵的 一个单独的图书馆(棉花糖)。
- 清除冗余API。
见this GitHub issue 它详细说明了与envparse的具体区别。
许可证
麻省理工学院许可。见 LICENSE文件 更多细节。