| single |
# pyyaml_env_tag
A custom YAML tag for referencing environment variables in YAML files.
[![PyPI Version][pypi-image]][pypi-link]
[![Build Status][GHAction-image]][GHAction-link]
[![Coverage Status][codecov-image]][codecov-link]
[pypi-image]: https://img.shields.io/pypi/v/pyyaml-env-tag.svg
[pypi-link]: https://pypi.org/project/pyyaml-env-tag/
[GHAction-image]:
https://github.com/waylan/pyyaml-env-tag/workflows/CI/badge.svg?branch=master&event=push
[GHAction-link]:
https://github.com/waylan/pyyaml-env-tag/actions?query=event%3Apush+branch%3Amaster
[codecov-image]:
https://codecov.io/github/waylan/pyyaml-env-tag/coverage.svg?branch=master
[codecov-link]:
https://codecov.io/github/waylan/pyyaml-env-tag?branch=master
## Installation
Install the `pyyaml_env_tag` package with pip:
`bash
pip install pyyaml_env_tag
`
### Enabling the tag
To enable the tag, pass your loader of choice into the `add_env_tag`
function, which will
return the loader with the construstor added to it.
```python
import yaml
from yaml_env_tag import add_env_tag
myLoader = add_env_tag(yaml.Loader)
```
Then you may use the loader as per usual. For example:
```python
yaml.load(data, Loader=myLoader)
```
The `add_env_tag` is a high level helper function. If you need lower level
access, you may
add the constructor (`yaml_env_tag.construct_env_tag`) to the loader
directly using the
`add_constructor` method of the loader. Note that this requires that the
tag (`!ENV`) be
defined as well.
```python
from yaml_env_tag import construct_env_tag
Loader.add_constructor('!ENV', construct_env_tag)
```
## 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
|