Merge pull request #68 from networktocode-llc/docs-review

OSRB documentation review

Author: scetron

README.md

@@ -0,0 +1,126 @@
+# Library Architecture
+
+| ![jdiff HLD](./images/hld-architecture.png) |
+|:---:|
+| **`jdiff` architecture** |
+
+We use the `CheckType` factory class method `create` along with the specified check type to instantiate a concrete object of the specified `CheckType` class.
+
+```python
+from jdiff import CheckType, extract_data_from_json
+check = CheckType.create("exact_match")
+>>> <jdiff.check_types.ExactMatchType at 0x10a618e80>
+```
+
+- `exact_match`
+- `tolerance`
+- `parameter_match`
+- `regex`
+- `operator`
+
+
+Next, load a JSON object as reference data. as well as a JMESPath expression to extract the values wanted and pass them to `extract_data_from_json` method. Be aware! `jdiff` works with a customized version of JMESPath. More on that [below](#customized-jmespath).
+
+> We'll use data from the tests folder. We assume the current working directory is the root of the repo if you've cloned it.
+
+```python
+>>> bgp_reference_state = json.load(open("tests/mock/napalm_get_bgp_neighbors/pre.json"))
+>>> bgp_jmspath_exp =  "global.$peers$.*.*.ipv4.[accepted_prefixes,received_prefixes,sent_prefixes]"
+>>> bgp_reference_value = extract_data_from_json(bgp_reference_state, bgp_jmspath_exp)
+```
+
+Once the pre-change values are extracted, we would need to evaluate them against our post-change value. In the case of check-type `exact_match`, our post value would be another JSON object:
+
+```python
+>>> bgp_comparison_state = json.load(open("tests/mock/napalm_get_bgp_neighbors/post.json"))
+>>> bgp_comparison_value = extract_data_from_json(bgp_comparison_state, bgp_jmspath_exp)
+```
+
+Each check type expects different types of arguments based on how and what they are checking. For example: check type `tolerance` needs a `tolerance` argument, whereas `parameter_match` expects a dictionary.
+
+Now that we have pre and post data, we use the `evaluate` method to compare them, which will return our evaluation result.
+
+```python
+>>> check = CheckType.create(check_type="exact_match")
+>>> results = check.evaluate(bgp_reference_value, bgp_comparison_value)
+>>> results
+({'10.1.0.0': {'accepted_prefixes': {'new_value': 900, 'old_value': 1000},
+   'received_prefixes': {'new_value': 999, 'old_value': 1000},
+   'sent_prefixes': {'new_value': 1011, 'old_value': 1000}}},
+ False)
+```
+
+
+## Arguments
+
+Generally, for all of the `CheckTypes`, the arguments will be in the order `intended state`, `actual state`, `options`. For instance, the reference state would be the first argument and comparison state the second argument in the `exact_match` check type. 
+
+For regex or parameter matching, your provided regex or dictionary would be the first argument and the collected data would be the second argument.
+
+# Customized JMESPath
+
+Since `jdiff` works with JSON objects as data inputs, JMESPath was the obvious choice for traversing the data and extracting the value(s) to compare. However, JMESPath has a limitation where context is lost for the values it collects, in other words, for each given value that JMESPath returns, we cannot be sure what key it was part of.
+
+Below is the output of `show bgp`.
+
+```python
+>>> data = {
+  "result": [
+    {
+      "vrfs": {
+        "default": {
+          "peerList": [
+            {
+              "linkType": "external",
+              "localAsn": "65130.1100",
+              "prefixesSent": 50,
+              "receivedUpdates": 0,
+              "peerAddress": "7.7.7.7",
+              "state": "Idle",
+              "updownTime": 1394,
+              "asn": "1.2354",
+              "routerId": "0.0.0.0"
+            },
+            {
+              "linkType": "external",
+              "localAsn": "65130.1100",
+              "receivedUpdates": 0,
+              "peerAddress": "10.1.0.0",
+              "state": "Connected",
+              "updownTime": 1394,
+              "asn": "1.2354",
+              "routerId": "0.0.0.0"
+            }
+          ]
+        }
+      }
+    }
+  ]
+}
+```
+A JMESPath expression to extract `state` is shown below.
+
+```python
+>>> path = result[0].vrfs.default.peerList[*].state
+```
+
+...which will return
+
+```python
+>>> extract_data_from_json(data, path)
+["Idle", "Connected"]
+```
+
+How can we understand that `Idle` is relative to peer 7.7.7.7 and `Connected` to peer `10.1.0.0`? 
+We could index the output, but that would require some post-processing of the data. For that reason, `jdiff` uses a customized version of JMESPath where it is possible to define a reference key for the value(s) wanted. The reference key must be within `$` sign anchors and defined in a list, together with the value(s):
+
+```python
+>>> path = "result[0].vrfs.default.peerList[*].[$peerAddress$,state]"
+```
+
+That  would give us...
+
+```python
+>>> extract_data_from_json(pre,path)
+[{'7.7.7.7': {'state': 'Idle'}}, {'10.1.0.0': {'state': 'Connected'}}]
+```

docs/architecture.md

@@ -0,0 +1,19 @@
+/* Images */
+img {
+    display: block;
+    margin-left: auto;
+    margin-right: auto;
+}
+
+/* Tables */
+table {
+    margin-bottom: 24px;
+    width: 100%;
+}
+th {
+    background-color: #f0f0f0;
+    padding: 6px;
+}
+td {
+    padding: 6px;
+}

docs/development.md

@@ -0,0 +1,78 @@
+# 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.
+
+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](architecture.md#customized-jmespath).
+
+## Getting Started
+
+
+First, you import the `CheckType` class.
+
+```python
+from jdiff import CheckType
+```
+
+Get (or fabricate) some data. (This data may also be loaded from a file or from a string, more examples later.)
+
+```python
+a = {"foo": "bar"}
+b = {"foo": "bar baz"}
+```
+
+Call the `create` method of the `CheckType` class to get an instance of the check type you want to perform.
+
+```python
+match = CheckType.create("exact_match")
+```
+
+Evaluate the check type and the diff.
+```python
+match.evaluate(a, b)
+>>> ({'foo': {'new_value': 'bar baz', 'old_value': 'bar'}}, False)
+```
+
+This results in a tuple:
+- The first value is the diff between the two data structures.
+- The second value is a boolean with the result of the check.
+
+This diff can also show whether any keys were added or deleted. 
+The second value returned will be the boolean result of the check. In this case, the two data structures were not an exact match.
+
+
+## Checking Data Structures
+
+As shown in the example, the check evaluation both performs a diff and tests the objects. All of the concrete `CheckTypes` both perform the diff and their specified check.
+
+More on the **check** part: The check provides a way to test some keys or values in our collected data. The check portion is focused on providing a boolean result of the test. There are a few different ways to check our data. 
+
+Below are the names of checks provided by the library. These both describe the type of check performed against the data and are used as an argument to instantiate that type of check with the `create` method, e.g. `CheckType.create("check_type")`.
+
+- `exact_match`: the keys and values must match exactly between the two objects
+- `tolerance`: the keys must match and the values can differ according to the 'tolerance' value provided
+- `parameter_match`: a reference key and value is provided and its presence (or absence) is checked in the provided object
+- `regex`: a reference regex pattern is provided and is used to find a match in the provided object
+- `operator`: similar to parameter match, but the reference includes several different possible operators: 'in', 'bool', 'string', and numerical comparison with 'int' and 'float' to check against
+
+`CheckTypes` are explained in more detail in the [architecture](architecture.md).
+
+
+## Workflow
+
+| ![jdiff Workflow](./images/jdiff-workflow.png) |
+|:---:|
+| **`jdiff` Workflow** |
+
+
+1. The reference state object is retrieved or assembled. The structured data may be from:
+
+    - an API
+    - another Python module/library
+    - retrieved from a saved file
+    - constructed programmatically
+
+2. Some time passes where some change to the data may occur; then the comparison state is retrieved or assembled, often using a similar process used to get the reference state.
+3. The reference state is then compared to the current state via the jdiff library using one of the `CheckTypes`.
+4. The evaluate method is called on the `check` object, and the result is returned.
+
+Please see [usage](usage.md) for commands and more information.