# UCI Parse Library
[](https://pypi.org/project/uciparse/)
[](https://github.com/pronovic/uci-parse/blob/master/LICENSE)
[](https://pypi.org/project/uciparse/)
[](https://pypi.org/project/uciparse/)
[](https://github.com/pronovic/uci-parse/actions?query=workflow%3A%22Test+Suite%22)
[](https://uci-parse.readthedocs.io/en/stable/)
[](https://coveralls.io/github/pronovic/uci-parse?branch=master)
[](https://python-poetry.org/)
Python 3 library and command line tools to parse, diff, and normalize OpenWRT
[UCI](https://openwrt.org/docs/guide-user/base-system/uci) configuration files.
These tools were written to ease OpenWRT upgrades, making it easier to see the
differences between two config files. As of this writing (mid-2020), OpenWRT
upgrades often don't normalize upgraded config files in the same way from
version to version. For instance, the new version from `opkg upgrade` (saved
off with a `-opkg` filename) might use single quotes on all lines, while the
original version on disk might not use quotes at all. This makes it very
difficult understand the often-minimal differences between an upgraded file and
the original file.
## Installing the Package
Installing this package on your OpenWRT router is not as simple as it could be.
A lot of routers do not have enough space available to install a full version
of Python including `pip` or `setuptools`. If yours does have lots of space,
it's as simple as this:
```
$ opkg update
$ opkg install python3-pip
$ pip3 install uciparse
```
If not, it gets a little ugly. First, install `wget` with support for HTTPS:
```
$ opkg update
$ opkg install wget ca-bundle ca-certificates
```
Then, go to [PyPI](https://pypi.org/project/uciparse/#files) and copy the
URL for the source package `.tar.gz` file. Retrieve the source package
with `wget` and then manually extract it:
```
$ wget https://files.pythonhosted.org/.../uciparse-0.1.2.tar.gz
$ tar zxvf uciparse-0.1.2.tar.gz
$ cd uciparse-0.1.2
```
Finally, run the custom install script provided with the source package:
```
$ sh ./scripts/install
```
This installs the OpenWRT `python3-light` package, then copies the Python
packages into the right `site-packages` directory and the `uciparse` and
`ucidiff` scripts to `/usr/bin`.
## Using the Tools
Once you have installed the package as described above, the `uciparse` and
`ucidiff` tools will be available in your path.
### ucidiff
The `ucidiff` tool is probably the tool you'll use most often when updating
your router. It reads two UCI configuration files from disk, normalizes both in
memory (without making changes on disk), and then compares them. The result is
a unified diff, like `diff -Naur`. This gives you a way to understand the real
differences between two files without ever having to change anything on disk.
```
$ ucidiff --help
usage: ucidiff [-h] a b
Diff two UCI configuration files.
positional arguments:
a Path to the first UCI file to compare
b Path to the second UCI file to compare
optional arguments:
-h, --help show this help message and exit
The comparison is equivalent to a 'diff -Naur' between the normalized versions
of the files. If either file can't be parsed, then an error will be returned
and no diff will be shown.
```
### uciparse
If you would prefer to clean up and normalize your configuration files on disk,
then you can use the `uciparse` tool. It reads a UCI config file from disk or
from `stdin`, parses it, and prints normalized output to `stdout`.
```
$ uciparse --help
usage: uciparse [-h] uci
Parse and normalize a UCI configuration file.
positional arguments:
uci Path to the UCI file to normalize, or '-' for stdin
optional arguments:
-h, --help show this help message and exit
Results will be printed to stdout. If the file can't be parsed then an error
will be returned and no output will be generated.
```
Before using ``uciparse``, you should make a backup of any config file that you
are going to normalized.
Raw data
{
"_id": null,
"home_page": "https://pypi.org/project/uciparse/",
"name": "uciparse",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.10",
"maintainer_email": null,
"keywords": null,
"author": "Kenneth J. Pronovici",
"author_email": "pronovic@ieee.org",
"download_url": "https://files.pythonhosted.org/packages/fb/89/d45e5da5a189d4432fb4ebc643879d0415c28a24d8052023620091cf49e9/uciparse-0.1.24.tar.gz",
"platform": null,
"description": "# UCI Parse Library\n\n[](https://pypi.org/project/uciparse/)\n[](https://github.com/pronovic/uci-parse/blob/master/LICENSE)\n[](https://pypi.org/project/uciparse/)\n[](https://pypi.org/project/uciparse/)\n[](https://github.com/pronovic/uci-parse/actions?query=workflow%3A%22Test+Suite%22)\n[](https://uci-parse.readthedocs.io/en/stable/)\n[](https://coveralls.io/github/pronovic/uci-parse?branch=master)\n[](https://python-poetry.org/)\n\nPython 3 library and command line tools to parse, diff, and normalize OpenWRT\n[UCI](https://openwrt.org/docs/guide-user/base-system/uci) configuration files.\n\nThese tools were written to ease OpenWRT upgrades, making it easier to see the\ndifferences between two config files. As of this writing (mid-2020), OpenWRT\nupgrades often don't normalize upgraded config files in the same way from\nversion to version. For instance, the new version from `opkg upgrade` (saved\noff with a `-opkg` filename) might use single quotes on all lines, while the\noriginal version on disk might not use quotes at all. This makes it very\ndifficult understand the often-minimal differences between an upgraded file and\nthe original file.\n\n## Installing the Package\n\nInstalling this package on your OpenWRT router is not as simple as it could be.\nA lot of routers do not have enough space available to install a full version\nof Python including `pip` or `setuptools`. If yours does have lots of space,\nit's as simple as this:\n\n```\n$ opkg update\n$ opkg install python3-pip\n$ pip3 install uciparse\n```\n\nIf not, it gets a little ugly. First, install `wget` with support for HTTPS:\n\n```\n$ opkg update\n$ opkg install wget ca-bundle ca-certificates\n```\n\nThen, go to [PyPI](https://pypi.org/project/uciparse/#files) and copy the\nURL for the source package `.tar.gz` file. Retrieve the source package \nwith `wget` and then manually extract it:\n\n```\n$ wget https://files.pythonhosted.org/.../uciparse-0.1.2.tar.gz\n$ tar zxvf uciparse-0.1.2.tar.gz\n$ cd uciparse-0.1.2\n```\n\nFinally, run the custom install script provided with the source package:\n\n```\n$ sh ./scripts/install\n```\n\nThis installs the OpenWRT `python3-light` package, then copies the Python\npackages into the right `site-packages` directory and the `uciparse` and\n`ucidiff` scripts to `/usr/bin`.\n\n## Using the Tools\n\nOnce you have installed the package as described above, the `uciparse` and\n`ucidiff` tools will be available in your path. \n\n### ucidiff\n\nThe `ucidiff` tool is probably the tool you'll use most often when updating\nyour router. It reads two UCI configuration files from disk, normalizes both in\nmemory (without making changes on disk), and then compares them. The result is\na unified diff, like `diff -Naur`. This gives you a way to understand the real\ndifferences between two files without ever having to change anything on disk.\n\n```\n$ ucidiff --help\nusage: ucidiff [-h] a b\n\nDiff two UCI configuration files.\n\npositional arguments:\n a Path to the first UCI file to compare\n b Path to the second UCI file to compare\n\noptional arguments:\n -h, --help show this help message and exit\n\nThe comparison is equivalent to a 'diff -Naur' between the normalized versions\nof the files. If either file can't be parsed, then an error will be returned\nand no diff will be shown.\n```\n\n### uciparse\n\nIf you would prefer to clean up and normalize your configuration files on disk,\nthen you can use the `uciparse` tool. It reads a UCI config file from disk or\nfrom `stdin`, parses it, and prints normalized output to `stdout`. \n\n```\n$ uciparse --help\nusage: uciparse [-h] uci\n\nParse and normalize a UCI configuration file.\n\npositional arguments:\n uci Path to the UCI file to normalize, or '-' for stdin\n\noptional arguments:\n -h, --help show this help message and exit\n\nResults will be printed to stdout. If the file can't be parsed then an error\nwill be returned and no output will be generated.\n```\n\nBefore using ``uciparse``, you should make a backup of any config file that you\nare going to normalized.\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Parse and emit OpenWRT uci-format files",
"version": "0.1.24",
"project_urls": {
"Homepage": "https://pypi.org/project/uciparse/",
"Repository": "https://github.com/pronovic/uci-parse"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "96e99f419cf2ce4c1aa086bb94cfaa1c224e1dbda222ddce03b269f5847a1fc7",
"md5": "84adcbd64ef3bfddb3b9ebebd6309147",
"sha256": "81295ead3c749aab0513e58180ffb9d0d57766dee605283f18b04d8025f4ed75"
},
"downloads": -1,
"filename": "uciparse-0.1.24-py3-none-any.whl",
"has_sig": false,
"md5_digest": "84adcbd64ef3bfddb3b9ebebd6309147",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.10",
"size": 14411,
"upload_time": "2024-10-15T16:35:20",
"upload_time_iso_8601": "2024-10-15T16:35:20.211259Z",
"url": "https://files.pythonhosted.org/packages/96/e9/9f419cf2ce4c1aa086bb94cfaa1c224e1dbda222ddce03b269f5847a1fc7/uciparse-0.1.24-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fb89d45e5da5a189d4432fb4ebc643879d0415c28a24d8052023620091cf49e9",
"md5": "eef7b780a7c1b4c5d36419e7c50978f2",
"sha256": "9cde2b9640bebd9b05c93e4dfb97bf083101af15b63874977e4b5c02e1c37638"
},
"downloads": -1,
"filename": "uciparse-0.1.24.tar.gz",
"has_sig": false,
"md5_digest": "eef7b780a7c1b4c5d36419e7c50978f2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.10",
"size": 38191,
"upload_time": "2024-10-15T16:35:21",
"upload_time_iso_8601": "2024-10-15T16:35:21.495423Z",
"url": "https://files.pythonhosted.org/packages/fb/89/d45e5da5a189d4432fb4ebc643879d0415c28a24d8052023620091cf49e9/uciparse-0.1.24.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-15 16:35:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pronovic",
"github_project": "uci-parse",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "uciparse"
}
JSON
