[](https://gitpod.io/#https://github.com/pearmaster/jacobs-json-doc)
[](https://coveralls.io/github/pearmaster/jacobs-json-doc?branch=master)
[](https://app.circleci.com/pipelines/github/pearmaster/jacobs-json-doc)
# jacobs-json-doc
A JSON/YAML loader for Python3.
[PyYAML](https://pyyaml.org/) or [ruamel.yaml](https://sourceforge.net/projects/ruamel-yaml/) do a good job at parsing YAML or JSON into a Python object. This package wraps ruamel.yaml to provide a little bit of extra functionality.
### Line Numbers
If you're trying to do use parts of a JSON/YAML document, and you find that the structure of the document didn't conform to a schema or expectations, then you might want to display an error saying something like "On line 123, the value of foo was missing." This package allows easier access to the YAML/JSON line numbers by accessing the `.line` property.
### Dollar References
JSON Schema, OpenAPI, AsyncAPI, and others have a concept of references like this: `{"$ref": "other.json#/path/to/definition"}`.
The idea here is that instead of the JSON object with the `$ref` you should be able to get a JSON structure from somewhere else. In this example, you should find a document called `other.json` and pull out a structure at `/path/to/definition`.
#### Loader
A **loader object** (inherits from `jacobsjsondoc.loader.LoaderBaseClass`) is able to get the JSON/YAML source. The loader can be different if you are loading from a database, filesystem, http, etc.
#### Reference Modes
Given a loader, jacobs-json-doc can deal with dollar references. There are two modes for how it can deal with references:
* Use `DocReference` objects. Anywhere in the document tree where there is a `$ref` reference, a `DocReference` object is created.
* Automatic resolution. Anywhere in the document tree where there is a `$ref` reference, the reference is automatically resolved and the `$ref`s are replaced with the structures that they were referencing.
## Examples
The [test_document.py](./tests/test_document.py) file is a good source for examples.
A very brief example is:
```py
from jacobsjsondoc.document import create_document
my_document = "/path/to/example.yaml"
doc = create_document(uri=my_document)
print(doc['a']['b'])
print(doc['a']['b'].line)
```
If you are loading a single bit of data, without any `$ref` references, you can do it like this:
```py
import jacobsjsondoc
text_data = '{"hello":"world"}'
doc = jacobsjsondoc.parse(text_data)
```
## License
[GPLv2](./LICENSE)
Raw data
{
"_id": null,
"home_page": "https://github.com/pearmaster/jacobs-json-doc",
"name": "jacobs-json-doc",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "conversion",
"author": "Jacob Brunson",
"author_email": "pypi@jacobbrunson.com",
"download_url": "https://files.pythonhosted.org/packages/eb/bb/ba370a013a4e6685cce46658eae7e2951d115ce56091d018000bf5187460/jacobs-json-doc-0.16.3.tar.gz",
"platform": null,
"description": "[](https://gitpod.io/#https://github.com/pearmaster/jacobs-json-doc)\n[](https://coveralls.io/github/pearmaster/jacobs-json-doc?branch=master)\n[](https://app.circleci.com/pipelines/github/pearmaster/jacobs-json-doc)\n\n# jacobs-json-doc\nA JSON/YAML loader for Python3.\n\n[PyYAML](https://pyyaml.org/) or [ruamel.yaml](https://sourceforge.net/projects/ruamel-yaml/) do a good job at parsing YAML or JSON into a Python object. This package wraps ruamel.yaml to provide a little bit of extra functionality. \n\n### Line Numbers\n\nIf you're trying to do use parts of a JSON/YAML document, and you find that the structure of the document didn't conform to a schema or expectations, then you might want to display an error saying something like \"On line 123, the value of foo was missing.\" This package allows easier access to the YAML/JSON line numbers by accessing the `.line` property.\n\n### Dollar References\n\nJSON Schema, OpenAPI, AsyncAPI, and others have a concept of references like this: `{\"$ref\": \"other.json#/path/to/definition\"}`.\n\nThe idea here is that instead of the JSON object with the `$ref` you should be able to get a JSON structure from somewhere else. In this example, you should find a document called `other.json` and pull out a structure at `/path/to/definition`. \n\n#### Loader\n\nA **loader object** (inherits from `jacobsjsondoc.loader.LoaderBaseClass`) is able to get the JSON/YAML source. The loader can be different if you are loading from a database, filesystem, http, etc.\n\n#### Reference Modes\n\nGiven a loader, jacobs-json-doc can deal with dollar references. There are two modes for how it can deal with references:\n\n* Use `DocReference` objects. Anywhere in the document tree where there is a `$ref` reference, a `DocReference` object is created. \n* Automatic resolution. Anywhere in the document tree where there is a `$ref` reference, the reference is automatically resolved and the `$ref`s are replaced with the structures that they were referencing.\n\n## Examples\n\nThe [test_document.py](./tests/test_document.py) file is a good source for examples.\n\nA very brief example is:\n\n```py\nfrom jacobsjsondoc.document import create_document\n\nmy_document = \"/path/to/example.yaml\"\ndoc = create_document(uri=my_document)\nprint(doc['a']['b'])\nprint(doc['a']['b'].line)\n```\n\nIf you are loading a single bit of data, without any `$ref` references, you can do it like this:\n\n```py\nimport jacobsjsondoc\ntext_data = '{\"hello\":\"world\"}'\ndoc = jacobsjsondoc.parse(text_data)\n```\n\n## License\n\n[GPLv2](./LICENSE)\n\n\n\n",
"bugtrack_url": null,
"license": "GPLv2",
"summary": "A JSON/YAML loader",
"version": "0.16.3",
"project_urls": {
"Homepage": "https://github.com/pearmaster/jacobs-json-doc"
},
"split_keywords": [
"conversion"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e40e805344f4bd68259e191453d144b107dbf37652e0770d54089bf17b99ac52",
"md5": "4239f24f2919f824b2ae988a5f7cdd58",
"sha256": "e62d02c818d21d1168fb8ac8d7ce48ec83d011d9aa215ea9b15b57ee987c2d3a"
},
"downloads": -1,
"filename": "jacobs_json_doc-0.16.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4239f24f2919f824b2ae988a5f7cdd58",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 24515,
"upload_time": "2023-10-17T21:54:24",
"upload_time_iso_8601": "2023-10-17T21:54:24.645205Z",
"url": "https://files.pythonhosted.org/packages/e4/0e/805344f4bd68259e191453d144b107dbf37652e0770d54089bf17b99ac52/jacobs_json_doc-0.16.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ebbbba370a013a4e6685cce46658eae7e2951d115ce56091d018000bf5187460",
"md5": "ac2685ecf67682fdf7a3a5563cd369ad",
"sha256": "d948feca007d07ecd5b11296bc46b87af4bfd580ab586e2b1bcf24906423365c"
},
"downloads": -1,
"filename": "jacobs-json-doc-0.16.3.tar.gz",
"has_sig": false,
"md5_digest": "ac2685ecf67682fdf7a3a5563cd369ad",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 20318,
"upload_time": "2023-10-17T21:54:25",
"upload_time_iso_8601": "2023-10-17T21:54:25.800576Z",
"url": "https://files.pythonhosted.org/packages/eb/bb/ba370a013a4e6685cce46658eae7e2951d115ce56091d018000bf5187460/jacobs-json-doc-0.16.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-17 21:54:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pearmaster",
"github_project": "jacobs-json-doc",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"circle": true,
"requirements": [
{
"name": "ruamel.yaml",
"specs": [
[
"==",
"0.17.17"
]
]
}
],
"lcname": "jacobs-json-doc"
}
JSON
