https://github.com/k3a/struct_diff
Structural diff for JSON, YAML and other similar structures
https://github.com/k3a/struct_diff
comparison diff json library object python yaml
Last synced: about 2 months ago
JSON representation
Structural diff for JSON, YAML and other similar structures
- Host: GitHub
- URL: https://github.com/k3a/struct_diff
- Owner: k3a
- License: mit
- Created: 2022-09-10T19:11:03.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2022-10-26T19:43:51.000Z (over 3 years ago)
- Last Synced: 2025-10-19T01:02:55.396Z (8 months ago)
- Topics: comparison, diff, json, library, object, python, yaml
- Language: Python
- Homepage:
- Size: 29.3 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# struct_diff
Copares two objects and produces a dictionary describing changes.
Ideal for comparing two JSON or YAML objects and generating a structural human-readable diff.
This is a Python port of [json-diff](https://github.com/andreyvit/json-diff) JavaScript library.
## Purpose
It produces diff like this:
```json
{
"type__deleted": "donut",
"name": {
"__old": "Cake",
"__new": "Donut"
},
"arr": [
[
" "
],
[
"-",
2
],
[
"+",
{
"obj": "ok",
"secondkey": 123
}
],
[
" "
],
[
"+",
4
]
],
... shortened ...
}
```
and from that it can generate a human-readable structural JSON diff:
```diff
{
- type: "donut"
- name: "Cake"
+ name: "Donut"
arr: [
...
- 2
+ {
+ obj: "ok"
+ secondkey: 123
+ }
...
+ 4
]
image: {
caption: {
- width: 123
+ width: 321
- height: 321
+ height: {
+ value: 642
+ units: "mm"
+ }
}
}
thumbnail: {
+ extra: {
+ price: 111
+ sizes: [
+ "L"
+ "XL"
+ ]
+ }
- width: 32
+ width: 64
}
}
```
or structural YAML diff:
```diff
- type: "donut"
- name: "Cake"
+ name: "Donut"
arr:
...
- - 2
+ - obj: "ok"
+ secondkey: 123
...
+ - 4
image:
caption:
- width: 123
+ width: 321
- height: 321
+ height:
+ value: 642
+ units: "mm"
thumbnail:
+ extra:
+ price: 111
+ sizes:
+ - "L"
+ - "XL"
- width: 32
+ width: 64
```
## CLI Usage
Simple:
```python3 -m struct_diff a.json b.json```
Detailed:
```txt
% python3 -m struct_diff -h
usage: struct_diff [-h] [-C] [--no-color] [-j] [-Y] [-f] [--max-elisions MAX_ELISIONS] [-o KEY [KEY ...]] [-n] [-s] [-c] [-k] [-K] [-p DECIMALS] [-w INDENT_WIDTH] old new
positional arguments:
old original file
new new file
optional arguments:
-h, --help show this help message and exit
-C force colorize the output
--no-color do not colorize the output
-j, --raw-json display raw JSON encoding of the diff
-Y, --yaml output diff as YAML
-f, --full include the equal sections of the document, not just the deltas
--max-elisions MAX_ELISIONS
max number of ...'s to show in a row in "deltas" mode (before collapsing them) #var(maxElisions)
-o KEY [KEY ...], --output-keys KEY [KEY ...]
always print this comma separated keys, with their value, if they are part of an object with any diff
-n, --output-new-only
output only the updated and new key/value pairs (without marking them as such). If you need only the diffs from the old file, just exchange the first and second json
-s, --sort sort primitive values in arrays before comparing
-c, --object-context if a scalar value of an object key is changed, also include other (unchanged) values of that object
-k, --keys-only compare only the keys, ignore the differences in values
-K, --keep-unchanged-values
instead of omitting values that are equal, output them as they are
-p DECIMALS, --precision DECIMALS
round all floating point numbers to this number of decimal places prior to comparison
-w INDENT_WIDTH, --indent-width INDENT_WIDTH
number of spaces for indendation
```
## Library Usage
```py
>>> from struct_diff import Comparator, YAMLFormatter
>>> d = diff({'a':'first'}, {'b': 'second'})
>>> f = YAMLFormatter(d, {'max_elisions': 1})
>>> print(f)
- a: first
+ b: second
```
## Things to do
- add unit tests
## Contributing
It is currently good enough for me so I don't intend to spend much more time on it.
You are welcome to implement stuff from `Things to do` or more and submit pull requests.
## Change Log
- 0.9.0-4,5,6,7 PyPI releases with bugfixes
- 0.9.0-3 Added object-context option to include unchanged values in an object with a changed scalar value
- 0.9.0-2 Multi-line unified diff for strings in YAML mode
- 0.9.0-1 Implements mixed sorting (numerical sort first, alphanumerical string sort next)
- 0.9.0 The first complete port of json-diff JS library with all the functionality
## Credits
- [json-diff](https://github.com/andreyvit/json-diff) - the original javascript implementation
Released under the MIT license.