[](https://coveralls.io/github/i386x/vutils-yaml?branch=main)
# vutils-yaml: Working with YAML Format
This package provides tools for loading data from and saving data to the YAML
format. Features:
* It annotates data while loading them from the YAML format. Every object
returned by `vutils.yaml.load.load_yaml` has information about its origin.
This is useful when reporting errors.
Limitations:
* Due to the annotating data, this packages is not suitable for loading YAML
formatted data containing thousands and hundreds of thousands items. For such
amounts of data use [PyYAML](https://pypi.org/project/PyYAML/) or other YAML
parser since it is supposed that large data sets are usually
machine-generated and consistent so further verification is not required.
* When used for the first time, `vutils.yaml.utils.keyloc` function builds a
mapping between `dict` keys and their locations. This can be a bottle-neck
for large dictionaries.
Due to the limitations, this package is suitable for parsing human-written
configurations in YAML format containing at most hundreds of items.
## Installation
```sh
pip install vutils-yaml
```
## How to Use
Topic covered in this short guide is:
* loading annotated YAML data
* API reference
### Loading Annotated YAML Data
To load YAML data with annotations, use the `load_yaml` function from
`vutils.yaml.load`. Example:
```python
from vutils.yaml.load import load_yaml
from vutils.yaml.utils import is_null, keyloc
stream = """
---
food:
fruit:
- apple
- banana
- orange
vegetable:
- potato
- tomato
- carrot
meat: null
"""
data = load_yaml(stream)
food = data["food"]
# `if food["meat"] is None` will not work, `null` is converted to `NullType`
# object to be annotated
if is_null(food["meat"]):
# `keyloc` retrieves the annotated key object from `food` and return its
# location
print(f"{keyloc(food, 'meat')}: At least one kind of meat is required.")
```
Observe the testing if the value is `null` and the retrieving the `meat` key
location to inform a user where the problem with his/her data is.
### API Reference
Module `vutils.yaml.load` provide these functions:
* `load_yaml(stream)` loads YAML data from `stream` and annotates them.
`stream` can be `str`, `bytes`, or a `file`-like object supporting `read`.
Module `vutils.yaml.utils` provide these functions:
* `getloc(obj)` retrieves the location of `obj`
* `keyloc(obj, kobj)` retrieves the location of `kobj`, which is a key of
`dict`-like object `obj`.
* `is_null(obj)` tests whether `obj` is `null`.
* `is_bool(obj)` tests whether `obj` is of the Boolean type.
Raw data
{
"_id": null,
"home_page": "https://github.com/i386x/vutils-yaml",
"name": "vutils-yaml",
"maintainer": "",
"docs_url": null,
"requires_python": "<4,>=3.7",
"maintainer_email": "",
"keywords": "yaml",
"author": "Ji\u0159\u00ed Ku\u010dera",
"author_email": "sanczes@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/9d/df/2c574d916937c59df66cc5314ef467bb5763242fee1c9641c59275e389ab/vutils-yaml-0.1.4.tar.gz",
"platform": "any",
"description": "[](https://coveralls.io/github/i386x/vutils-yaml?branch=main)\n\n\n# vutils-yaml: Working with YAML Format\n\nThis package provides tools for loading data from and saving data to the YAML\nformat. Features:\n* It annotates data while loading them from the YAML format. Every object\n returned by `vutils.yaml.load.load_yaml` has information about its origin.\n This is useful when reporting errors.\n\nLimitations:\n* Due to the annotating data, this packages is not suitable for loading YAML\n formatted data containing thousands and hundreds of thousands items. For such\n amounts of data use [PyYAML](https://pypi.org/project/PyYAML/) or other YAML\n parser since it is supposed that large data sets are usually\n machine-generated and consistent so further verification is not required.\n* When used for the first time, `vutils.yaml.utils.keyloc` function builds a\n mapping between `dict` keys and their locations. This can be a bottle-neck\n for large dictionaries.\n\nDue to the limitations, this package is suitable for parsing human-written\nconfigurations in YAML format containing at most hundreds of items.\n\n## Installation\n\n```sh\npip install vutils-yaml\n```\n\n## How to Use\n\nTopic covered in this short guide is:\n* loading annotated YAML data\n* API reference\n\n### Loading Annotated YAML Data\n\nTo load YAML data with annotations, use the `load_yaml` function from\n`vutils.yaml.load`. Example:\n```python\nfrom vutils.yaml.load import load_yaml\nfrom vutils.yaml.utils import is_null, keyloc\n\nstream = \"\"\"\n---\nfood:\n fruit:\n - apple\n - banana\n - orange\n vegetable:\n - potato\n - tomato\n - carrot\n meat: null\n\"\"\"\n\ndata = load_yaml(stream)\nfood = data[\"food\"]\n# `if food[\"meat\"] is None` will not work, `null` is converted to `NullType`\n# object to be annotated\nif is_null(food[\"meat\"]):\n # `keyloc` retrieves the annotated key object from `food` and return its\n # location\n print(f\"{keyloc(food, 'meat')}: At least one kind of meat is required.\")\n```\nObserve the testing if the value is `null` and the retrieving the `meat` key\nlocation to inform a user where the problem with his/her data is.\n\n### API Reference\n\nModule `vutils.yaml.load` provide these functions:\n* `load_yaml(stream)` loads YAML data from `stream` and annotates them.\n `stream` can be `str`, `bytes`, or a `file`-like object supporting `read`.\n\nModule `vutils.yaml.utils` provide these functions:\n* `getloc(obj)` retrieves the location of `obj`\n* `keyloc(obj, kobj)` retrieves the location of `kobj`, which is a key of\n `dict`-like object `obj`.\n* `is_null(obj)` tests whether `obj` is `null`.\n* `is_bool(obj)` tests whether `obj` is of the Boolean type.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Working with YAML format",
"version": "0.1.4",
"project_urls": {
"Bug Reports": "https://github.com/i386x/vutils-yaml/issues",
"Homepage": "https://github.com/i386x/vutils-yaml",
"Source": "https://github.com/i386x/vutils-yaml"
},
"split_keywords": [
"yaml"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fcd85a40ea31cb33f407f1dd9251ad5781c13f9b408328ab1049fb555d53c10f",
"md5": "c52db17e5e76e55ec8d2dd26004da506",
"sha256": "39cdf59bffbc0e636c88e834ad429144fe99c5b41ff2a714b4c36926fc78f331"
},
"downloads": -1,
"filename": "vutils_yaml-0.1.4-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "c52db17e5e76e55ec8d2dd26004da506",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": "<4,>=3.7",
"size": 9772,
"upload_time": "2023-05-07T20:15:59",
"upload_time_iso_8601": "2023-05-07T20:15:59.951067Z",
"url": "https://files.pythonhosted.org/packages/fc/d8/5a40ea31cb33f407f1dd9251ad5781c13f9b408328ab1049fb555d53c10f/vutils_yaml-0.1.4-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9ddf2c574d916937c59df66cc5314ef467bb5763242fee1c9641c59275e389ab",
"md5": "9c7ae5627e3f57f9d9a2162a0d084729",
"sha256": "268a8d87682529873c627efe3f5f44e0fc60fa12c23f53ced289fd764c44a5c8"
},
"downloads": -1,
"filename": "vutils-yaml-0.1.4.tar.gz",
"has_sig": false,
"md5_digest": "9c7ae5627e3f57f9d9a2162a0d084729",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.7",
"size": 16064,
"upload_time": "2023-05-07T20:16:01",
"upload_time_iso_8601": "2023-05-07T20:16:01.917579Z",
"url": "https://files.pythonhosted.org/packages/9d/df/2c574d916937c59df66cc5314ef467bb5763242fee1c9641c59275e389ab/vutils-yaml-0.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-07 20:16:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "i386x",
"github_project": "vutils-yaml",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "vutils-yaml"
}
JSON
