# yaml-config-tags
[](https://pypi.org/project/yaml-config-tags/)
[](https://pypi.org/project/yaml-config-tags/)
[](https://pypi.org/project/yaml-config-tags/)
Provides a set of custom tags to extend YAML for managing advanced configurations easily within a file.
It supports:
- Environment variables: `!env`
- File includes: `!include`
- Jinja templating: `!jinja`
## Installation
```bash
pip install yaml-config-tags
```
## Usage
Simply load the configuration file using `config_load` and pass a context dictionary to the loader.
```python
config_load(
path: str | Path,
context: dict[str, Any] | None = None,
jinja_settings: dict[str, Any] | None = None,
) -> Any
```
#### Example
```python
from yaml_config import config_load
context = {
'name': 'John Doe'
}
config = config_load('config.yml', context)
```
```yaml
# config.yml
database:
user: !env DB_USER
password: !env DB_PASSWORD
advanced: !include advanced.yaml
greeting: !jinja |
Hello, {{ name }}!
```
## Features
### Environment Variables
You can use environment variables in your configuration file by using the `!env` tag.
There are three ways to use environment variables:
- `!env VAR_NAME` - Load the environment variable `VAR_NAME`. If it is not set, an exception will be raised.
- `!env [VAR_NAME, default_value]` - Load the environment variable `VAR_NAME` with a default value if it is not set.
- `!env [VAR_NAME, FALLBACK_VAR1, .., FALLBACK_VARn, default_value]` - Load the environment variable `VAR_NAME`, if it is not set, try to load the fallback variables in order. If none of them are set, use the default value.
#### Explicit type
Environment variables are converted using implicit yaml types by default, but you can force a specific data type with tag suffix:
- `!env:str VAR_NAME`
- `!env:int VAR_NAME`
Valid type suffix are:
- str
- int
- float
- bool
- timestamp
You can also combine defaults and fallbacks with type suffix:
`!env:str [VAR_NAME, default_value]`
### Includes
You can include other files in your configuration file by using the `!include` tag.
```yaml
# config.yml
advanced: !include advanced.yaml
```
Three types of files are supported, specified as a tag suffix:
- `yaml` - Load the file as a YAML file.
- `json` - Load the file as a JSON file.
- `txt` - Load the file as a plain text file.
If no suffix is specified, the file will be loaded as a YAML file.
```yaml
text_data: !include:txt text.txt
json_data: !include:json data.json
```
Relative paths are resolved relative to the directory of the file that contains the include.
#### Glob Patterns
You can use glob patterns in the file path, and all matching files will be included as a list.
```yaml
files: !include:yaml "data/*.yaml"
```
### Jinja Templating
You can use Jinja templating in your configuration file by using the `!jinja` tag. The context available to the template is passed as an argument to the loader.
```yaml
greeting: !jinja |
Hello, {{ name }}!
```
The `!jinja` tag is a short form for `!jinja:str`, a jinja template rendered as a string.
#### Native objects
In addition to plain text templates, you can also render a template to native objects.
```yaml
connection:
url: !env DB_URL
token_provider: !jinja:obj |
{{token_provider}}
```
When using `!jinja:obj` the template is rendered using _NativeEnvironment_ and the result is evaluated as a native object instead of a string.
Raw data
{
"_id": null,
"home_page": "https://github.com/ianchi/yaml-config-tags",
"name": "yaml-config-tags",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "yaml, config",
"author": "Adrian Panella",
"author_email": "ianchi74@outlook.com",
"download_url": "https://files.pythonhosted.org/packages/3f/32/f46321f368c8c23a29092651aaa3cfea81432a3d42d69985c27a29d7520e/yaml_config_tags-0.3.0.tar.gz",
"platform": null,
"description": "# yaml-config-tags\n\n[](https://pypi.org/project/yaml-config-tags/)\n[](https://pypi.org/project/yaml-config-tags/)\n[](https://pypi.org/project/yaml-config-tags/)\n\nProvides a set of custom tags to extend YAML for managing advanced configurations easily within a file.\nIt supports:\n\n- Environment variables: `!env`\n- File includes: `!include`\n- Jinja templating: `!jinja`\n\n## Installation\n\n```bash\npip install yaml-config-tags\n```\n\n## Usage\n\nSimply load the configuration file using `config_load` and pass a context dictionary to the loader.\n\n```python\nconfig_load(\n path: str | Path,\n context: dict[str, Any] | None = None,\n jinja_settings: dict[str, Any] | None = None,\n) -> Any\n```\n\n#### Example\n\n```python\nfrom yaml_config import config_load\n\ncontext = {\n 'name': 'John Doe'\n}\nconfig = config_load('config.yml', context)\n```\n\n```yaml\n# config.yml\ndatabase:\n user: !env DB_USER\n password: !env DB_PASSWORD\n\nadvanced: !include advanced.yaml\n\ngreeting: !jinja |\n Hello, {{ name }}!\n```\n\n## Features\n\n### Environment Variables\n\nYou can use environment variables in your configuration file by using the `!env` tag.\n\nThere are three ways to use environment variables:\n\n- `!env VAR_NAME` - Load the environment variable `VAR_NAME`. If it is not set, an exception will be raised.\n- `!env [VAR_NAME, default_value]` - Load the environment variable `VAR_NAME` with a default value if it is not set.\n- `!env [VAR_NAME, FALLBACK_VAR1, .., FALLBACK_VARn, default_value]` - Load the environment variable `VAR_NAME`, if it is not set, try to load the fallback variables in order. If none of them are set, use the default value.\n\n#### Explicit type\n\nEnvironment variables are converted using implicit yaml types by default, but you can force a specific data type with tag suffix:\n\n- `!env:str VAR_NAME`\n- `!env:int VAR_NAME`\n\nValid type suffix are:\n\n- str\n- int\n- float\n- bool\n- timestamp\n\nYou can also combine defaults and fallbacks with type suffix:\n`!env:str [VAR_NAME, default_value]`\n\n### Includes\n\nYou can include other files in your configuration file by using the `!include` tag.\n\n```yaml\n# config.yml\nadvanced: !include advanced.yaml\n```\n\nThree types of files are supported, specified as a tag suffix:\n\n- `yaml` - Load the file as a YAML file.\n- `json` - Load the file as a JSON file.\n- `txt` - Load the file as a plain text file.\n\nIf no suffix is specified, the file will be loaded as a YAML file.\n\n```yaml\ntext_data: !include:txt text.txt\njson_data: !include:json data.json\n```\n\nRelative paths are resolved relative to the directory of the file that contains the include.\n\n#### Glob Patterns\n\nYou can use glob patterns in the file path, and all matching files will be included as a list.\n\n```yaml\nfiles: !include:yaml \"data/*.yaml\"\n```\n\n### Jinja Templating\n\nYou can use Jinja templating in your configuration file by using the `!jinja` tag. The context available to the template is passed as an argument to the loader.\n\n```yaml\ngreeting: !jinja |\n Hello, {{ name }}!\n```\n\nThe `!jinja` tag is a short form for `!jinja:str`, a jinja template rendered as a string.\n\n#### Native objects\n\nIn addition to plain text templates, you can also render a template to native objects.\n\n```yaml\nconnection:\n url: !env DB_URL\n token_provider: !jinja:obj |\n {{token_provider}}\n```\n\nWhen using `!jinja:obj` the template is rendered using _NativeEnvironment_ and the result is evaluated as a native object instead of a string.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Custom tags to extend YAML for managing advanced configurations easily within a file. Environment variables, includes, and jinja templating.",
"version": "0.3.0",
"project_urls": {
"Documentation": "https://github.com/ianchi/yaml-config-tags",
"Homepage": "https://github.com/ianchi/yaml-config-tags",
"Repository": "https://github.com/ianchi/yaml-config-tags.git"
},
"split_keywords": [
"yaml",
" config"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d4aa0a9c8389ba24bd6d183f873e120ea9bfeba67c90d1b2fa14b65d1385095e",
"md5": "6e6850e29566f376187d895701ad6320",
"sha256": "b549eae2a3c4b1359de26b28690d3228877319428f704c0ea5cda5da3439225c"
},
"downloads": -1,
"filename": "yaml_config_tags-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6e6850e29566f376187d895701ad6320",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 5266,
"upload_time": "2025-02-07T20:00:51",
"upload_time_iso_8601": "2025-02-07T20:00:51.483282Z",
"url": "https://files.pythonhosted.org/packages/d4/aa/0a9c8389ba24bd6d183f873e120ea9bfeba67c90d1b2fa14b65d1385095e/yaml_config_tags-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3f32f46321f368c8c23a29092651aaa3cfea81432a3d42d69985c27a29d7520e",
"md5": "608cfb1ca58d2da987f965e858833dc7",
"sha256": "a2ff701f6cd506ffac08430892910ef765339feeafb583308e77d70c86477e30"
},
"downloads": -1,
"filename": "yaml_config_tags-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "608cfb1ca58d2da987f965e858833dc7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 6438,
"upload_time": "2025-02-07T20:00:53",
"upload_time_iso_8601": "2025-02-07T20:00:53.086668Z",
"url": "https://files.pythonhosted.org/packages/3f/32/f46321f368c8c23a29092651aaa3cfea81432a3d42d69985c27a29d7520e/yaml_config_tags-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-07 20:00:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ianchi",
"github_project": "yaml-config-tags",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "yaml-config-tags"
}
JSON
