# pyyaml_env_tag
A custom YAML tag for referencing environment variables in YAML files.
## Installation
Install `PyYAML` and the `pyyaml_env_tag` package with pip:
```bash
pip install pyyaml pyyaml_env_tag
```
### Enabling the tag
To enable the tag, import and add the `construct_env_tag` constructor to your YAML
loader of choice.
```python
import yaml
from yaml_env_tag import construct_env_tag
yaml.Loader.add_constructor('!ENV', construct_env_tag)
```
Then you may use the loader as per usual. For example:
```python
yaml.load(data, Loader=yaml.Loader)
```
## Using the tag
Include the tag `!ENV` followed by the name of an environment variable in a YAML
file and the value of the environment variable will be used in its place.
```yaml
key: !ENV SOME_VARIABLE
```
If `SOME_VARIABLE` is set to `A string!`, then the above YAML would result in the
following Python object:
```python
{'key': 'A string!'}
```
The content of the variable is parsed using YAML's implicit scalar types, such as
string, bool, integer, float, datestamp and null. More complex types are not
recognized and simply passed through as a string. For example, if `SOME_VARIABLE`
was set to the string `true`, then the above YAML would result in the following:
```python
{'key': True}
```
If the variable specified is not set, then a `null` value is assigned as a default.
You may define your own default as the last item in a sequence.
```yaml
key: !ENV [SOME_VARIABLE, default]
```
In the above example, if `SOME_VARIABLE` is not defined, the string `default` would
be used instead, as follows:
```python
{'key': 'default'}
```
You may list multiple variables as fallbacks. The first variable which is set is
used. In any sequance with more than one item, the last item must always be a
default value and will not be resolved as an environment variable.
```yaml
key: !ENV [SOME_VARIABLE, FALLBACK, default]
```
As with variable contents, the default is resolved to a Python object of the
implied type (string, bool, integer, float, datestamp and null).
When `SOME_VARIABLE` is not set, all four of the following items will resolve to
the same value (`None`):
```yaml
- !ENV SOME_VARIABLE
- !ENV [SOME_VARIABLE]
- !ENV [SOME_VARIABLE, ~]
- !ENV [SOME_VARIABLE, null]
```
## Related
pyyaml_env_tag was inspired by the Ruby package [yaml-env-tag].
An alternate method of referencing environment variables in YAML files is
implemented by [pyyaml-tags] and [python_yaml_environment_variables].
Each of those libraries use a template string and replace the template tag with
the content of the variable. While this allows a single value to reference
multiple variables and to contain additional content, it restricts all values
to strings only and does not provide a way to define defaults.
[yaml-env-tag]: https://github.com/jirutka/yaml-env-tag
[pyyaml-tags]: https://github.com/meiblorn/pyyaml-tags
[python_yaml_environment_variables]: https://gist.github.com/mkaranasou/ba83e25c835a8f7629e34dd7ede01931
## License
pyyaml_env_tag is licensed under the [MIT License] as defined in `LICENSE`.
[MIT License]: https://opensource.org/licenses/MIT
## Changelog
### Version 0.1 (released 2020-11-11)
The initial release.
Raw data
{
"_id": null,
"home_page": "https://github.com/waylan/pyyaml-env-tag",
"name": "pyyaml_env_tag",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "",
"author": "Waylan Limberg",
"author_email": "waylan.limberg@icloud.com",
"download_url": "https://files.pythonhosted.org/packages/fb/8e/da1c6c58f751b70f8ceb1eb25bc25d524e8f14fe16edcce3f4e3ba08629c/pyyaml_env_tag-0.1.tar.gz",
"platform": "",
"description": "# pyyaml_env_tag\n\nA custom YAML tag for referencing environment variables in YAML files.\n\n## Installation\n\nInstall `PyYAML` and the `pyyaml_env_tag` package with pip:\n\n```bash\npip install pyyaml pyyaml_env_tag\n```\n\n### Enabling the tag\n\nTo enable the tag, import and add the `construct_env_tag` constructor to your YAML\nloader of choice.\n\n```python\nimport yaml\nfrom yaml_env_tag import construct_env_tag\n\nyaml.Loader.add_constructor('!ENV', construct_env_tag)\n```\n\nThen you may use the loader as per usual. For example:\n\n```python\nyaml.load(data, Loader=yaml.Loader)\n```\n\n## Using the tag\n\nInclude the tag `!ENV` followed by the name of an environment variable in a YAML\nfile and the value of the environment variable will be used in its place.\n\n```yaml\nkey: !ENV SOME_VARIABLE\n```\n\nIf `SOME_VARIABLE` is set to `A string!`, then the above YAML would result in the\nfollowing Python object:\n\n```python\n{'key': 'A string!'}\n```\n\nThe content of the variable is parsed using YAML's implicit scalar types, such as\nstring, bool, integer, float, datestamp and null. More complex types are not\nrecognized and simply passed through as a string. For example, if `SOME_VARIABLE`\nwas set to the string `true`, then the above YAML would result in the following:\n\n```python\n{'key': True}\n```\n\nIf the variable specified is not set, then a `null` value is assigned as a default.\nYou may define your own default as the last item in a sequence.\n\n```yaml\nkey: !ENV [SOME_VARIABLE, default]\n```\n\nIn the above example, if `SOME_VARIABLE` is not defined, the string `default` would\nbe used instead, as follows:\n\n```python\n{'key': 'default'}\n```\n\nYou may list multiple variables as fallbacks. The first variable which is set is\nused. In any sequance with more than one item, the last item must always be a\ndefault value and will not be resolved as an environment variable.\n\n```yaml\nkey: !ENV [SOME_VARIABLE, FALLBACK, default]\n```\n\nAs with variable contents, the default is resolved to a Python object of the\nimplied type (string, bool, integer, float, datestamp and null).\n\nWhen `SOME_VARIABLE` is not set, all four of the following items will resolve to\nthe same value (`None`):\n\n```yaml\n- !ENV SOME_VARIABLE\n- !ENV [SOME_VARIABLE]\n- !ENV [SOME_VARIABLE, ~]\n- !ENV [SOME_VARIABLE, null]\n```\n\n## Related\n\npyyaml_env_tag was inspired by the Ruby package [yaml-env-tag].\n\nAn alternate method of referencing environment variables in YAML files is\nimplemented by [pyyaml-tags] and [python_yaml_environment_variables].\nEach of those libraries use a template string and replace the template tag with\nthe content of the variable. While this allows a single value to reference\nmultiple variables and to contain additional content, it restricts all values\nto strings only and does not provide a way to define defaults.\n\n[yaml-env-tag]: https://github.com/jirutka/yaml-env-tag\n[pyyaml-tags]: https://github.com/meiblorn/pyyaml-tags\n[python_yaml_environment_variables]: https://gist.github.com/mkaranasou/ba83e25c835a8f7629e34dd7ede01931\n\n## License\n\npyyaml_env_tag is licensed under the [MIT License] as defined in `LICENSE`.\n\n[MIT License]: https://opensource.org/licenses/MIT\n\n## Changelog\n\n### Version 0.1 (released 2020-11-11)\n\nThe initial release.\n",
"bugtrack_url": null,
"license": "",
"summary": "A custom YAML tag for referencing environment variables in YAML files. ",
"version": "0.1",
"project_urls": {
"Homepage": "https://github.com/waylan/pyyaml-env-tag"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5a66bbb1dd374f5c870f59c5bb1db0e18cbe7fa739415a24cbd95b2d1f5ae0c4",
"md5": "27fa6b84d223d68f0c685bc018564b4e",
"sha256": "af31106dec8a4d68c60207c1886031cbf839b68aa7abccdb19868200532c2069"
},
"downloads": -1,
"filename": "pyyaml_env_tag-0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "27fa6b84d223d68f0c685bc018564b4e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 3911,
"upload_time": "2020-11-12T02:38:24",
"upload_time_iso_8601": "2020-11-12T02:38:24.638742Z",
"url": "https://files.pythonhosted.org/packages/5a/66/bbb1dd374f5c870f59c5bb1db0e18cbe7fa739415a24cbd95b2d1f5ae0c4/pyyaml_env_tag-0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fb8eda1c6c58f751b70f8ceb1eb25bc25d524e8f14fe16edcce3f4e3ba08629c",
"md5": "bb7743fe8e53d8716da6c1bdb7945641",
"sha256": "70092675bda14fdec33b31ba77e7543de9ddc88f2e5b99160396572d11525bdb"
},
"downloads": -1,
"filename": "pyyaml_env_tag-0.1.tar.gz",
"has_sig": false,
"md5_digest": "bb7743fe8e53d8716da6c1bdb7945641",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 5631,
"upload_time": "2020-11-12T02:38:26",
"upload_time_iso_8601": "2020-11-12T02:38:26.239904Z",
"url": "https://files.pythonhosted.org/packages/fb/8e/da1c6c58f751b70f8ceb1eb25bc25d524e8f14fe16edcce3f4e3ba08629c/pyyaml_env_tag-0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2020-11-12 02:38:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "waylan",
"github_project": "pyyaml-env-tag",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pyyaml_env_tag"
}
JSON
