-
Notifications
You must be signed in to change notification settings - Fork 2
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Updated README.md with generic information about the project and some new badges. Extended the example section. Breaking changes: - Changed json_fingerprint() `data` parameter to `input`
- Loading branch information
Showing
4 changed files
with
48 additions
and
22 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,27 +1,48 @@ | ||
![](https://img.shields.io/github/license/cobaltine/json-fingerprint) ![](https://img.shields.io/pypi/pyversions/json-fingerprint) ![](https://img.shields.io/pypi/v/json-fingerprint) [![Coverage Status](https://coveralls.io/repos/github/cobaltine/json-fingerprint/badge.svg?branch=main)](https://coveralls.io/github/cobaltine/json-fingerprint?branch=main) | ||
# json-fingerprint | ||
|
||
The **json-fingerprint** package provides easy checksum creation ("fingerprinting") from unordered JSON data. | ||
![](https://img.shields.io/github/license/cobaltine/json-fingerprint) ![](https://img.shields.io/pypi/pyversions/json-fingerprint) ![](https://img.shields.io/github/workflow/status/cobaltine/json-fingerprint/Test%20runner/main) ![](https://img.shields.io/github/workflow/status/cobaltine/json-fingerprint/Release%20Python%20package/main?label=pypi%20release) [![](https://img.shields.io/pypi/v/json-fingerprint)](https://pypi.org/project/json-fingerprint/) [![Coverage Status](https://coveralls.io/repos/github/cobaltine/json-fingerprint/badge.svg?branch=main)](https://coveralls.io/github/cobaltine/json-fingerprint?branch=main) | ||
|
||
## Installation and use | ||
|
||
To install the package, run `pip install json-fingerprint`. | ||
Create consistent and comparable fingerprints (checksums/hashes) from unordered JSON data. | ||
|
||
Below is a sample for creating simple fingerprints: | ||
A json fingerprint consists of three parts: the version of the underlying algorithm, the hash function used and a hex digest of the hash function output. A complete example could look like this: `jfpv1$sha256$5815eb0ce6f4e5ab0a771cce2a8c5432f64222f8fd84b4cc2d38e4621fae86af`. | ||
|
||
The first part indicates the algorithm version, `jfpv1`, which would translate to **j**son **f**inger**p**rint **v**ersion **1**. The second part, `sha256`, indicates that SHA256 is the hash function that was used. The last part, `5815eb0ce6f4e5ab0a771cce2a8c5432f64222f8fd84b4cc2d38e4621fae86af`, is a standard hex digest of the hash function output. | ||
|
||
|
||
## Installation | ||
|
||
To install the json-fingerprint package, run `pip install json-fingerprint`. | ||
|
||
|
||
## Examples | ||
|
||
The example below shows how to create and compare json fingerprints. | ||
|
||
```python | ||
import json | ||
import json_fingerprint as jfp | ||
|
||
obj_1_str = json.dumps([3, 2, 1, {"foo": "bar"}]) | ||
obj_2_str = json.dumps([2, {"foo": "bar"}, 1, 3]) | ||
fp_1 = jfp.json_fingerprint(obj_1_str, hash_function='sha256', version=1) | ||
fp_2 = jfp.json_fingerprint(obj_2_str, hash_function='sha256', version=1) | ||
print(f'fp_1: {fp_1}') | ||
print(f'fp_2: {fp_2}') | ||
obj_1_str = json.dumps([3, 2, 1, {'foo': 'bar'}]) | ||
obj_2_str = json.dumps([2, {'foo': 'bar'}, 1, 3]) # Same data in different order | ||
fp_1 = jfp.json_fingerprint(input=obj_1_str, hash_function='sha256', version=1) | ||
fp_2 = jfp.json_fingerprint(input=obj_2_str, hash_function='sha256', version=1) | ||
print(f'Fingerprint 1: {fp_1}') | ||
print(f'Fingerprint 2: {fp_2}') | ||
``` | ||
This will output two identical fingerprints regardless of the different ordering of the json elements: | ||
This will output two identical fingerprints regardless of the different order of the json elements: | ||
|
||
``` | ||
fp_1: jfpv1$sha256$5815eb0ce6f4e5ab0a771cce2a8c5432f64222f8fd84b4cc2d38e4621fae86af | ||
fp_2: jfpv1$sha256$5815eb0ce6f4e5ab0a771cce2a8c5432f64222f8fd84b4cc2d38e4621fae86af | ||
Fingerprint 1: jfpv1$sha256$5815eb0ce6f4e5ab0a771cce2a8c5432f64222f8fd84b4cc2d38e4621fae86af | ||
Fingerprint 2: jfpv1$sha256$5815eb0ce6f4e5ab0a771cce2a8c5432f64222f8fd84b4cc2d38e4621fae86af | ||
``` | ||
If the previous example was extended a bit, the objects could be easily compared: | ||
```python | ||
if fp_1 == fp_2: | ||
# Do something if fingerprints match | ||
print('Fingerprints match') | ||
else: | ||
# Do nothing or something else | ||
print('Fingerprints not matching') | ||
``` | ||
Since json objects with identical data content and structure will always produce identical fingerprints, the fingerprints can be used effectively for various purposes. These include finding duplicate json data from a larger dataset, json data cache validation/invalidation and data integrity checking. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters