# EnvYAML | Easy configuration file parser for structured data
[](https://pypi.python.org/pypi/envyaml/)
[](https://github.com/thesimj/envyaml/actions/workflows/main.yml)
[](https://coveralls.io/github/thesimj/envyaml?branch=master)
[](https://github.com/psf/black)
[](https://lgtm.com/projects/g/thesimj/envyaml/alerts/)
[](https://lgtm.com/projects/g/thesimj/envyaml/context:python)
[](LICENSE)
### Motivation
Modern configuration files become to be more and more complex, flexible, and readable.
YAML file format is perfect to store configuration but had no option to pass environment variables. They give flexibility, readability and provide an option to store complex data structure.
This project goal is to simplify usage of the YAML file and environment variables as program configuration files with easy config key access.
### Install
```bash
pip install envyaml
```
### Basic usage
Let's assume we had a project with this config file `env.yaml`
```yaml
# env.yaml
project:
name: "${PROJECT_NAME}-${PROJECT_ID}"
database:
host: $DATABASE_HOST
port: 3301
username: username
password: $DATABASE_PASSWORD
database: test
table:
user: table_user
blog: table_blog
query: |-
SELECT * FROM "users" WHERE "user" = $1 AND "login" = $2 AND "pwd" = $3
insert: |-
INSERT INTO "{table}" (user, login) VALUES ($1, $2)
redis:
host: $REDIS_HOST|127.0.0.1
port: 5040
db: $REDIS_DB|3 # with default value
config:
expire: 300
prefix: $REDIS_PREFIX
escaped: $$.extra
empty_env: $NOT_EXIST_ENV_VARIABLE
```
Environment variables set to
```
PROJECT_NAME=simple-hello
PROJECT_ID=42
DATABASE_HOST=xxx.xxx.xxx.xxx
DATABASE_PASSWORD=super-secret-password
REDIS_PREFIX=state
```
Parse file with `EnvYAML`
```python
from envyaml import EnvYAML
# read file env.yaml and parse config
env = EnvYAML('env.yaml')
# access project name
print(env['project.name'])
# >> simple-hello-42
# access whole database section
print(env['database'])
# {
# 'database': 'test',
# 'host': 'xxx.xxx.xxx.xxx',
# 'password': 'super-secret-password',
# 'port': 3301,
# 'table':
# {
# 'blog': 'table_blog',
# 'user': 'table_user'
# },
# 'username': 'username'
# }
# access database host value as key item
print(env['database.host'])
# >> xxx.xxx.xxx.xxx
# access database user table value as key item
print(env['database.table.user'])
# >> table_user
# get sql query with $1,$2,$3 variables
print(env['database.query'])
# >> SELECT * FROM "users" WHERE "user" = $1 AND "login" = $2 AND "pwd" = $3
# using default values if variable not defined
# one example is redis host and redis port, when $REDIS_HOST not set then default value will be used
print(env['redis.host'])
# >> 127.0.0.1
# one example is redis host and redis port, when $REDIS_DB not set then default value will be used
print(env['redis.db'])
# >> 3
# access list items by number
print(env['list_test'][0])
# >> one
# access list items by number as key
print(env['list_test.1'])
# >> two
# test if you have key
print('redis.port' in env)
# >> True
```
Access config with `get` function and default value
```python
print(env.get('not.exist.value', 'default'))
# >> default
print(env.get('empty_env', 'default'))
# >> default
print(env['empty_env'])
# >> None
```
Use `format` function to update placeholder
```python
print(env.format('database.insert', table="users"))
# >> INSERT INTO "users" (user, login) VALUES ($1, $2)
```
### Strict mode
This mode is **enable by default** and prevents from declaring variables that do not exist in `environment variables` or `.env` file. This leads to having runtime `ValueError` exception when variables do not define with message `Strict mode enabled, variable $VAR not defined!`. To disable **strict** mode specify `strict=False` at EnvYAML object initialization. Another option to disable `strict` mode is to define `ENVYAML_STRICT_DISABLE` environment variable before initializing EnvYAML object.
### Escaped variables
In case of usage `$` in env.yaml file as value double `$$` should be used. Example:
Use `escaped` variable
```python
print(env['escaped'])
# >> $.extra
```
### License
MIT licensed. See the [LICENSE](LICENSE) file for more details.
Raw data
{
"_id": null,
"home_page": "https://github.com/thesimj/envyaml",
"name": "envyaml",
"maintainer": "",
"docs_url": null,
"requires_python": ">=2.7",
"maintainer_email": "",
"keywords": "",
"author": "Mykola Bubelich",
"author_email": "m+github@bubelich.com",
"download_url": "https://files.pythonhosted.org/packages/aa/ce/bcc062f1d55368713674cf55851a4d9dfa77835c0258753d0f23dff70743/envyaml-1.10.211231.tar.gz",
"platform": "any",
"description": "# EnvYAML | Easy configuration file parser for structured data\n\n[](https://pypi.python.org/pypi/envyaml/)\n[](https://github.com/thesimj/envyaml/actions/workflows/main.yml)\n[](https://coveralls.io/github/thesimj/envyaml?branch=master)\n\n[](https://github.com/psf/black)\n[](https://lgtm.com/projects/g/thesimj/envyaml/alerts/)\n[](https://lgtm.com/projects/g/thesimj/envyaml/context:python)\n[](LICENSE)\n\n\n### Motivation\nModern configuration files become to be more and more complex, flexible, and readable.\nYAML file format is perfect to store configuration but had no option to pass environment variables. They give flexibility, readability and provide an option to store complex data structure.\nThis project goal is to simplify usage of the YAML file and environment variables as program configuration files with easy config key access.\n\n\n### Install\n```bash\npip install envyaml\n```\n\n\n### Basic usage\nLet's assume we had a project with this config file `env.yaml`\n\n```yaml\n# env.yaml\nproject:\n name: \"${PROJECT_NAME}-${PROJECT_ID}\"\n\ndatabase:\n host: $DATABASE_HOST\n port: 3301\n username: username\n password: $DATABASE_PASSWORD\n database: test\n\n table:\n user: table_user\n blog: table_blog\n\n query: |-\n SELECT * FROM \"users\" WHERE \"user\" = $1 AND \"login\" = $2 AND \"pwd\" = $3\n\n insert: |-\n INSERT INTO \"{table}\" (user, login) VALUES ($1, $2)\n\nredis:\n host: $REDIS_HOST|127.0.0.1\n port: 5040\n db: $REDIS_DB|3 # with default value\n\n config:\n expire: 300\n prefix: $REDIS_PREFIX\n\nescaped: $$.extra\n\nempty_env: $NOT_EXIST_ENV_VARIABLE\n```\n\nEnvironment variables set to\n```\nPROJECT_NAME=simple-hello\nPROJECT_ID=42\nDATABASE_HOST=xxx.xxx.xxx.xxx\nDATABASE_PASSWORD=super-secret-password\nREDIS_PREFIX=state\n```\n\nParse file with `EnvYAML`\n\n```python\nfrom envyaml import EnvYAML\n\n# read file env.yaml and parse config\nenv = EnvYAML('env.yaml')\n\n# access project name\nprint(env['project.name'])\n\n# >> simple-hello-42\n\n# access whole database section\nprint(env['database'])\n\n# {\n# 'database': 'test',\n# 'host': 'xxx.xxx.xxx.xxx',\n# 'password': 'super-secret-password',\n# 'port': 3301,\n# 'table':\n# {\n# 'blog': 'table_blog',\n# 'user': 'table_user'\n# },\n# 'username': 'username'\n# }\n\n# access database host value as key item\nprint(env['database.host'])\n\n# >> xxx.xxx.xxx.xxx\n\n# access database user table value as key item\nprint(env['database.table.user'])\n\n# >> table_user\n\n# get sql query with $1,$2,$3 variables\nprint(env['database.query'])\n\n# >> SELECT * FROM \"users\" WHERE \"user\" = $1 AND \"login\" = $2 AND \"pwd\" = $3\n\n# using default values if variable not defined\n# one example is redis host and redis port, when $REDIS_HOST not set then default value will be used\nprint(env['redis.host'])\n\n# >> 127.0.0.1\n\n# one example is redis host and redis port, when $REDIS_DB not set then default value will be used\nprint(env['redis.db'])\n\n# >> 3\n\n# access list items by number\nprint(env['list_test'][0])\n\n# >> one\n\n# access list items by number as key\nprint(env['list_test.1'])\n\n# >> two\n\n# test if you have key\nprint('redis.port' in env)\n\n# >> True\n\n```\n\nAccess config with `get` function and default value\n```python\nprint(env.get('not.exist.value', 'default'))\n# >> default\n\nprint(env.get('empty_env', 'default'))\n# >> default\n\nprint(env['empty_env'])\n# >> None\n```\n\nUse `format` function to update placeholder\n```python\nprint(env.format('database.insert', table=\"users\"))\n# >> INSERT INTO \"users\" (user, login) VALUES ($1, $2)\n```\n\n### Strict mode\nThis mode is **enable by default** and prevents from declaring variables that do not exist in `environment variables` or `.env` file. This leads to having runtime `ValueError` exception when variables do not define with message `Strict mode enabled, variable $VAR not defined!`. To disable **strict** mode specify `strict=False` at EnvYAML object initialization. Another option to disable `strict` mode is to define `ENVYAML_STRICT_DISABLE` environment variable before initializing EnvYAML object.\n\n\n### Escaped variables\nIn case of usage `$` in env.yaml file as value double `$$` should be used. Example:\nUse `escaped` variable\n```python\nprint(env['escaped'])\n# >> $.extra\n```\n\n\n### License\nMIT licensed. See the [LICENSE](LICENSE) file for more details.\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Simple YAML configuration file parser with easy access for structured data",
"version": "1.10.211231",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "67996612dcf7d494223041c029cc4fa325cb513fe99bf989e6895a1de357f1eb",
"md5": "fe556d5be429c339c74df843874995bf",
"sha256": "8d7a7a6be12587cc5da32a587067506b47b849f4643981099ad148015a72de52"
},
"downloads": -1,
"filename": "envyaml-1.10.211231-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "fe556d5be429c339c74df843874995bf",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=2.7",
"size": 8138,
"upload_time": "2022-01-08T10:56:38",
"upload_time_iso_8601": "2022-01-08T10:56:38.849435Z",
"url": "https://files.pythonhosted.org/packages/67/99/6612dcf7d494223041c029cc4fa325cb513fe99bf989e6895a1de357f1eb/envyaml-1.10.211231-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "aacebcc062f1d55368713674cf55851a4d9dfa77835c0258753d0f23dff70743",
"md5": "d3251f65d7be437ff8f370dc69c78014",
"sha256": "88f8a076159e3c317d3450a5f404132b6ac91aecee4934ea72eac65f911f1244"
},
"downloads": -1,
"filename": "envyaml-1.10.211231.tar.gz",
"has_sig": false,
"md5_digest": "d3251f65d7be437ff8f370dc69c78014",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=2.7",
"size": 7591,
"upload_time": "2022-01-08T10:56:40",
"upload_time_iso_8601": "2022-01-08T10:56:40.010699Z",
"url": "https://files.pythonhosted.org/packages/aa/ce/bcc062f1d55368713674cf55851a4d9dfa77835c0258753d0f23dff70743/envyaml-1.10.211231.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-01-08 10:56:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "thesimj",
"github_project": "envyaml",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [
{
"name": "pyyaml",
"specs": []
},
{
"name": "pytest",
"specs": []
},
{
"name": "pytest-cov",
"specs": []
}
],
"lcname": "envyaml"
}
JSON
