From 2ef0ee0eaeff323c0b9309d8c0d6f0b6829e67eb Mon Sep 17 00:00:00 2001 From: itdependsnetworks Date: Fri, 2 Sep 2022 19:45:03 -0400 Subject: [PATCH 1/3] Update readme to start with use cases --- README.md | 25 +++++++++++++++++++++---- 1 file changed, 21 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 3832935..d3e73a0 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,14 @@ # jdiff -`jdiff` is a lightweight Python library allowing you to examine structured data. `jdiff` provides an interface to intelligently compare JSON data objects and test for the presence (or absence) of keys. You can also examine and compare corresponding key-values. +`jdiff` is a lightweight Python library allowing you to examine structured data. `jdiff` provides an interface to intelligently compare JSON data objects in a intelligently way. -The library heavily relies on [JMESPath](https://jmespath.org/) for traversing the JSON object and finding the values to be evaluated. More on that [here](#customized-jmespath). +Our primary use case is the examination of structured data returned from networking devices, such as: + +* Compare the operational state of network devices pre and post change +* Compare operational state of a device vs a "known healthy" state +* Compare state of similar devices, such as a pair of leafs or a pair of backbone routers + +However, the library fits other use cases where structured data needs to be operated on. ## Installation @@ -12,9 +18,20 @@ Install from PyPI: pip install jdiff ``` -## Use cases +## Intelligent Comparison + +The library provides the ability to ask more intelligent questions of a given data structure. Comparisons of data such as "Is my pre change state the same as my post change state", is not that interesting of a comparison. The library intends to ask intelligent questions _like_: + +* Is the route table within 10% of routes before and after a change? +* Is all of the interfaces that were up before the change, still up? +* Is there at least 10k sessions of traffic on my firewall? +* Is there there at least 2 interfaces up within lldp neighbors? + +## Technical Overview + +The library heavily relies on [JMESPath](https://jmespath.org/) for traversing the JSON object and finding the values to be evaluated. More on that [here](#customized-jmespath). -`jdiff` has been developed around diffing and testing structured data returned from APIs and other Python modules and libraries (such as TextFSM). Our primary use case is the examination of structured data returned from networking devices. However, we found the library fits other use cases where structured data needs to be operated on, and is especially useful when working or dealing with data returned from APIs. +`jdiff` has been developed around diffing and testing structured data returned from APIs and other Python modules and libraries (such as TextFSM) but is equally useful when working or dealing with data returned from APIs. ## Documentation From 2d6428ad01f7fc5619202d571d72592e3dc4bb59 Mon Sep 17 00:00:00 2001 From: Ken Celenza Date: Tue, 6 Sep 2022 11:24:07 -0400 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Patryk Szulczewski Co-authored-by: Stephen Corry --- README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index d3e73a0..e2afdd9 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,7 @@ Our primary use case is the examination of structured data returned from network * Compare the operational state of network devices pre and post change * Compare operational state of a device vs a "known healthy" state * Compare state of similar devices, such as a pair of leafs or a pair of backbone routers +* Compare operational state of a component (interface, vrf, bgp peering, etc.) migrated from one device to another However, the library fits other use cases where structured data needs to be operated on. @@ -24,14 +25,14 @@ The library provides the ability to ask more intelligent questions of a given da * Is the route table within 10% of routes before and after a change? * Is all of the interfaces that were up before the change, still up? -* Is there at least 10k sessions of traffic on my firewall? +* Are there at least 10k sessions of traffic on my firewall? * Is there there at least 2 interfaces up within lldp neighbors? ## Technical Overview The library heavily relies on [JMESPath](https://jmespath.org/) for traversing the JSON object and finding the values to be evaluated. More on that [here](#customized-jmespath). -`jdiff` has been developed around diffing and testing structured data returned from APIs and other Python modules and libraries (such as TextFSM) but is equally useful when working or dealing with data returned from APIs. +`jdiff` has been developed around diffing and testing structured data returned from Network APIs and libraries (such as TextFSM) but is equally useful when working or dealing with data returned from APIs. ## Documentation From 273d47f5b2467c4c627dc4c0898ec0722d562dd9 Mon Sep 17 00:00:00 2001 From: Ken Celenza Date: Tue, 6 Sep 2022 15:21:08 -0400 Subject: [PATCH 3/3] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index e2afdd9..2165fe7 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # jdiff -`jdiff` is a lightweight Python library allowing you to examine structured data. `jdiff` provides an interface to intelligently compare JSON data objects in a intelligently way. +`jdiff` is a lightweight Python library allowing you to examine structured data. jdiff` provides an interface to intelligently compare--via key presense/absense and value comparison--JSON data objects Our primary use case is the examination of structured data returned from networking devices, such as: