| Name | rconf JSON |
| Version |
0.0.5
JSON |
| download |
| home_page | |
| Summary | Extensible Python package to resolve references and apply patches in JSON and TOML configurations |
| upload_time | 2024-01-15 17:43:15 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.7 |
| license | MIT License Copyright (c) 2023 Filip Thyssen Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
toml
json
reference
pointer
patch
configuration
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
########################################################################
RConf
########################################################################
************************************************************************
What
************************************************************************
.. from src/__init__.py
Extensible Python package to resolve references and apply patches in
`JSON <https://datatracker.ietf.org/doc/html/rfc8259>`_ and
`TOML <https://toml.io/en/v1.0.0>`_ configurations.
It uses Python's
`json module <https://docs.python.org/3/library/json.html>`_ and
`tomllib module <https://docs.python.org/3/library/tomllib.html>`_ to decode,
handles local and remote reference URLs using
`urllib <https://docs.python.org/3/library/urllib.html>`_,
and resolves document fragments specified through pointers,
optionally applying patches.
- References follow the
`JSON Reference draft <https://datatracker.ietf.org/doc/html/draft-pbryan-zyp-json-ref-03>`_.
- Reference patches are based on
`RFC 6902 <https://datatracker.ietf.org/doc/html/rfc6902>`_,
extended with shorthand notations, an *assign* and a *merge* operation.
- JSON pointers follow
`RFC 6901 <https://datatracker.ietf.org/doc/html/rfc6901>`_.
- TOML pointers are
`TOML keys <https://toml.io/en/v1.0.0#keys>`_
extended with array indices.
It can be used as a drop-in replacement for
- ``json.load`` and ``tomllib.load`` (``rconf.load``),
- ``json.loads`` and ``tomllib.loads`` (``rconf.loads``),
with an additional ``rconf.loadu`` to load URLs and local paths
and ``rconf.loadc`` to load a Python ``dict``.
These functions all resolve references and apply patches.
************************************************************************
Why
************************************************************************
``rconf`` allows a developer to
- not care about configuration location (URLs) and
- not care about configuration format (decoders),
and a user to
- reduce duplication by allowing URLs,
- reduce duplication by allowing references,
- reduce duplication by allowing patches and
- mix and match formats already in use.
************************************************************************
How
************************************************************************
Installation
========================================================================
.. from docs/index.rst
RConf is `pip <https://pip.pypa.io>`_-installable:
.. code-block:: console
$ pip install rconf
Load a URL (with fragment pointer)
========================================================================
This snippet loads a document from a URL,
and resolves the pointer in its fragment:
.. code-block:: python
import json
import rconf
config = rconf.loadu("https://github.com/manifest.json#/icons/0")
print(json.dumps(config, indent=4))
.. code-block:: json
{
"sizes": "114x114",
"src": "https://github.githubassets.com/apple-touch-icon-114x114.png"
}
or, with an explicit pointer,
.. code-block:: python
import json
import rconf
config = rconf.loadu(
"https://raw.githubusercontent.com/pypa/build/main/pyproject.toml",
ptr="project.description",
)
print(json.dumps(config, indent=4))
.. code-block:: json
"A simple, correct Python build frontend"
Load and patch a string
========================================================================
The string (``config``) contains a JSON document with a reference (``$ref``)
and a patch assignment for ``/name``.
.. code-block:: python
import json
import rconf
config = rconf.loads("""
{
"github-icon": {
"$ref": "https://github.com/manifest.json#/icons/0",
"/name": "GitHub icon"
}
}
""")
print(json.dumps(config, indent=4))
.. code-block:: json
{
"github-icon": {
"sizes": "114x114",
"src": "https://github.githubassets.com/apple-touch-icon-114x114.png",
"name": "GitHub icon"
}
}
Mix and patch
========================================================================
Formats can be mixed,
like this JSON document referencing a TOML document,
patched with a ``$patch`` array using both the full and shorthand notations.
.. code-block:: python
import json
import rconf
config = rconf.loads("""
{
"$ref": "data:application/toml;base64,W3Byb2plY3RdCnRpdGxlID0gIlByb2plY3QgdGl0bGUiCmRlc2NyaXB0aW9uID0gIlByb2plY3QgZGVzY3JpcHRpb24iCnJlYWRtZSA9ICJyZWFkbWUubWQiCg==",
"$patch": [
{"op": "move", "path": "/project/name", "from": "/project/title"},
["-", "/project/readme"],
["+", "/project/dynamic", ["version"]]
]
}
""")
print(json.dumps(config, indent=4))
.. code-block:: json
{
"project": {
"description": "Project description",
"name": "Project title",
"dynamic": [
"version"
]
}
}
Command Line Interface
========================================================================
.. from docs/usage.rst
``rconf`` is added as a CLI tool,
to translate JSON and TOML files with (or without) references and patches,
and works with URLs or file paths.
.. code-block:: console
$ rconf dump https://github.com/manifest.json#/icons/0
{
"sizes": "114x114",
"src": "https://github.githubassets.com/apple-touch-icon-114x114.png"
}
``rconf dump`` behavior can be modified with a configuration file.
``rconf config`` can show or create an example.
Those using bash/zsh can activate auto completion,
provided by `argcomplete <https://kislyuk.github.io/argcomplete>`_.
.. code-block:: console
$ pip install rconf[sh]
$ activate-global-python-argcomplete --user
************************************************************************
Definitions
************************************************************************
Definitions can be found on the
`definitions <http://fthyssen.github.io/rconf/definitions.html>`_ page.
************************************************************************
Usage
************************************************************************
A more thorough description can be found on the
`usage <http://fthyssen.github.io/rconf/usage.html>`_ page,
with details in the
`reference <http://fthyssen.github.io/rconf/reference.html>`_.
Raw data
{
"_id": null,
"home_page": "",
"name": "rconf",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "toml,json,reference,pointer,patch,configuration",
"author": "",
"author_email": "Filip Thyssen <filip.thyssen@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/57/64/cdc2a7263310f6b15b7775fe12a3eff55f9d95166e48ff4ee7de875230a7/rconf-0.0.5.tar.gz",
"platform": null,
"description": "########################################################################\nRConf\n########################################################################\n\n************************************************************************\nWhat\n************************************************************************\n\n.. from src/__init__.py\n\nExtensible Python package to resolve references and apply patches in\n`JSON <https://datatracker.ietf.org/doc/html/rfc8259>`_ and\n`TOML <https://toml.io/en/v1.0.0>`_ configurations.\n\nIt uses Python's\n`json module <https://docs.python.org/3/library/json.html>`_ and\n`tomllib module <https://docs.python.org/3/library/tomllib.html>`_ to decode,\nhandles local and remote reference URLs using\n`urllib <https://docs.python.org/3/library/urllib.html>`_,\nand resolves document fragments specified through pointers,\noptionally applying patches.\n\n- References follow the\n `JSON Reference draft <https://datatracker.ietf.org/doc/html/draft-pbryan-zyp-json-ref-03>`_.\n- Reference patches are based on\n `RFC 6902 <https://datatracker.ietf.org/doc/html/rfc6902>`_,\n extended with shorthand notations, an *assign* and a *merge* operation.\n- JSON pointers follow\n `RFC 6901 <https://datatracker.ietf.org/doc/html/rfc6901>`_.\n- TOML pointers are\n `TOML keys <https://toml.io/en/v1.0.0#keys>`_\n extended with array indices.\n\n\nIt can be used as a drop-in replacement for\n\n- ``json.load`` and ``tomllib.load`` (``rconf.load``),\n- ``json.loads`` and ``tomllib.loads`` (``rconf.loads``),\n\nwith an additional ``rconf.loadu`` to load URLs and local paths\nand ``rconf.loadc`` to load a Python ``dict``.\nThese functions all resolve references and apply patches.\n\n\n************************************************************************\nWhy\n************************************************************************\n\n``rconf`` allows a developer to\n\n- not care about configuration location (URLs) and\n- not care about configuration format (decoders),\n\nand a user to\n\n- reduce duplication by allowing URLs,\n- reduce duplication by allowing references,\n- reduce duplication by allowing patches and\n- mix and match formats already in use.\n\n\n************************************************************************\nHow\n************************************************************************\n\nInstallation\n========================================================================\n\n.. from docs/index.rst\n\nRConf is `pip <https://pip.pypa.io>`_-installable:\n\n.. code-block:: console\n\n $ pip install rconf\n\n\nLoad a URL (with fragment pointer)\n========================================================================\n\nThis snippet loads a document from a URL,\nand resolves the pointer in its fragment:\n\n.. code-block:: python\n\n import json\n import rconf\n\n config = rconf.loadu(\"https://github.com/manifest.json#/icons/0\")\n print(json.dumps(config, indent=4))\n\n.. code-block:: json\n\n {\n \"sizes\": \"114x114\",\n \"src\": \"https://github.githubassets.com/apple-touch-icon-114x114.png\"\n }\n\nor, with an explicit pointer,\n\n.. code-block:: python\n\n import json\n import rconf\n\n config = rconf.loadu(\n \"https://raw.githubusercontent.com/pypa/build/main/pyproject.toml\",\n ptr=\"project.description\",\n )\n print(json.dumps(config, indent=4))\n\n\n.. code-block:: json\n\n \"A simple, correct Python build frontend\"\n\n\nLoad and patch a string\n========================================================================\n\nThe string (``config``) contains a JSON document with a reference (``$ref``)\nand a patch assignment for ``/name``.\n\n.. code-block:: python\n\n import json\n import rconf\n\n config = rconf.loads(\"\"\"\n {\n \"github-icon\": {\n \"$ref\": \"https://github.com/manifest.json#/icons/0\",\n \"/name\": \"GitHub icon\"\n }\n }\n \"\"\")\n print(json.dumps(config, indent=4))\n\n.. code-block:: json\n\n {\n \"github-icon\": {\n \"sizes\": \"114x114\",\n \"src\": \"https://github.githubassets.com/apple-touch-icon-114x114.png\",\n \"name\": \"GitHub icon\"\n }\n }\n\n\nMix and patch\n========================================================================\n\nFormats can be mixed,\nlike this JSON document referencing a TOML document,\npatched with a ``$patch`` array using both the full and shorthand notations.\n\n.. code-block:: python\n\n import json\n import rconf\n\n config = rconf.loads(\"\"\"\n {\n \"$ref\": \"data:application/toml;base64,W3Byb2plY3RdCnRpdGxlID0gIlByb2plY3QgdGl0bGUiCmRlc2NyaXB0aW9uID0gIlByb2plY3QgZGVzY3JpcHRpb24iCnJlYWRtZSA9ICJyZWFkbWUubWQiCg==\",\n \"$patch\": [\n {\"op\": \"move\", \"path\": \"/project/name\", \"from\": \"/project/title\"},\n [\"-\", \"/project/readme\"],\n [\"+\", \"/project/dynamic\", [\"version\"]]\n ]\n }\n \"\"\")\n print(json.dumps(config, indent=4))\n\n.. code-block:: json\n\n {\n \"project\": {\n \"description\": \"Project description\",\n \"name\": \"Project title\",\n \"dynamic\": [\n \"version\"\n ]\n }\n }\n\n\nCommand Line Interface\n========================================================================\n\n.. from docs/usage.rst\n\n``rconf`` is added as a CLI tool,\nto translate JSON and TOML files with (or without) references and patches,\nand works with URLs or file paths.\n\n.. code-block:: console\n\n $ rconf dump https://github.com/manifest.json#/icons/0\n {\n \"sizes\": \"114x114\",\n \"src\": \"https://github.githubassets.com/apple-touch-icon-114x114.png\"\n }\n\n``rconf dump`` behavior can be modified with a configuration file.\n``rconf config`` can show or create an example.\n\nThose using bash/zsh can activate auto completion,\nprovided by `argcomplete <https://kislyuk.github.io/argcomplete>`_.\n\n.. code-block:: console\n\n $ pip install rconf[sh]\n $ activate-global-python-argcomplete --user\n\n\n************************************************************************\nDefinitions\n************************************************************************\n\nDefinitions can be found on the\n`definitions <http://fthyssen.github.io/rconf/definitions.html>`_ page.\n\n\n************************************************************************\nUsage\n************************************************************************\n\nA more thorough description can be found on the\n`usage <http://fthyssen.github.io/rconf/usage.html>`_ page,\nwith details in the\n`reference <http://fthyssen.github.io/rconf/reference.html>`_.\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2023 Filip Thyssen Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.",
"summary": "Extensible Python package to resolve references and apply patches in JSON and TOML configurations",
"version": "0.0.5",
"project_urls": {
"Documentation": "http://fthyssen.github.io/rconf",
"Homepage": "https://github.com/fthyssen/rconf",
"Repository": "https://github.com/fthyssen/rconf"
},
"split_keywords": [
"toml",
"json",
"reference",
"pointer",
"patch",
"configuration"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3925e6d75a93975ffbd7cc98987faf8260e205644b54658a1995f86dde27baec",
"md5": "1bf226543c84ac44259deb1d581cae56",
"sha256": "cf49d9635061be269b6f13000100a854baf45c344423e5d8a5b5a509db4d3355"
},
"downloads": -1,
"filename": "rconf-0.0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1bf226543c84ac44259deb1d581cae56",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 35063,
"upload_time": "2024-01-15T17:43:13",
"upload_time_iso_8601": "2024-01-15T17:43:13.494452Z",
"url": "https://files.pythonhosted.org/packages/39/25/e6d75a93975ffbd7cc98987faf8260e205644b54658a1995f86dde27baec/rconf-0.0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5764cdc2a7263310f6b15b7775fe12a3eff55f9d95166e48ff4ee7de875230a7",
"md5": "ebd4c295d9eeab108a2c5642fc5b0f41",
"sha256": "cedb029006c3e61f0a96ad2b5216c056d516e478f6641bbc970674aecc3076f3"
},
"downloads": -1,
"filename": "rconf-0.0.5.tar.gz",
"has_sig": false,
"md5_digest": "ebd4c295d9eeab108a2c5642fc5b0f41",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 40448,
"upload_time": "2024-01-15T17:43:15",
"upload_time_iso_8601": "2024-01-15T17:43:15.231943Z",
"url": "https://files.pythonhosted.org/packages/57/64/cdc2a7263310f6b15b7775fe12a3eff55f9d95166e48ff4ee7de875230a7/rconf-0.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-15 17:43:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "fthyssen",
"github_project": "rconf",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "rconf"
}
