Add example 2

Author: glennmatthews

examples/example1/README.md

@@ -1,12 +1,12 @@
+# Example 1
 
-
-This is a simple example to show how diffsync can be used to compare and synchronize multiple data sources.
+This is a simple example to show how DiffSync can be used to compare and synchronize multiple data sources.
 
 For this example, we have a shared model for Device and Interface defined in `models.py`
 And we have 3 instances of DiffSync based on the same model but with different values (BackendA, BackendB & BackendC).
 
+First create and populate all 3 objects:
 
-First create and populate all 3 objects
 ```python
 from backend_a import BackendA
 from backend_b import BackendB
@@ -27,33 +27,38 @@ c.load()
 print(c.str())
 ```
 
-Configure verbosity of DiffSync's structured logging to console; the default is full verbosity (all logs including debugging)
+Configure verbosity of DiffSync's structured logging to console; the default is full verbosity (all logs including debugging):
+
 ```python
 from diffsync.logging import enable_console_logging
 enable_console_logging(verbosity=0)  # Show WARNING and ERROR logs only
 # enable_console_logging(verbosity=1)  # Also include INFO logs
 # enable_console_logging(verbosity=2)  # Also include DEBUG logs
 ```
 
-Show the differences between A and B
+Show the differences between A and B:
+
 ```python
 diff_a_b = a.diff_to(b)
 print(diff_a_b.str())
 ```
 
-Show the differences between B and C
+Show the differences between B and C:
+
 ```python
 diff_b_c = c.diff_from(b)
 print(diff_b_c.str())
 ```
 
-Synchronize A and B (update B with the contents of A)
+Synchronize A and B (update B with the contents of A):
+
 ```python
 a.sync_to(b)
 print(a.diff_to(b).str())
 ```
 
-Now A and B will show no differences
+Now A and B will show no differences:
+
 ```python
 diff_a_b = a.diff_to(b)
 print(diff_a_b.str())

examples/example2/README.md

@@ -0,0 +1,44 @@
+# Example 2 - Callback Function
+
+This example shows how you can set up DiffSync to invoke a callback function to update its status as a sync proceeds. This could be used to, for example, update a status bar (such as with the [tqdm](https://github.com/tqdm/tqdm) library), although here for simplicity we'll just have the callback print directly to the console.
+
+```python
+from diffsync.logging import enable_console_logging
+from example2 import DiffSync1, DiffSync2, print_callback
+
+enable_console_logging(verbosity=0)  # Show WARNING and ERROR logs only
+
+# Create a DiffSync1 instance and populate it with records numbered 1-100
+ds1 = DiffSync1()
+ds1.populate(count=100)
+
+# Create a DiffSync2 instance and populate it with 100 random records in the range 1-200
+ds2 = DiffSync2()
+ds2.populate(count=100)
+
+# Identify and attempt to resolve the differences between the two,
+# periodically invoking print_callback() as DiffSync progresses
+ds1.sync_to(ds2, callback=print_callback)
+```
+
+You should see output similar to the following:
+
+```
+diff: Processed     1/  200 records.
+diff: Processed     3/  200 records.
+...
+diff: Processed   199/  200 records.
+diff: Processed   200/  200 records.
+sync: Processed     1/  134 records.
+sync: Processed     2/  134 records.
+...
+sync: Processed   134/  134 records.
+```
+
+A few points to note:
+
+- For each record in `ds1` and `ds2`, either it exists in both, exists only in `ds1`, or exists only in `ds2`.
+- The total number of records reported during the `"diff"` stage is the sum of the number of records in both `ds1` and `ds2`.
+- For this very simple set of models, the progress counter during the `"diff"` stage will increase at each step by 2 (if a corresponding pair of models is identified between`ds1` and `ds2`) or by 1 (if a model exists only in `ds1` or only in `ds2`).
+- The total number of records reported during the `"sync"` stage is the number of distinct records existing across `ds1` and `ds2` combined, so it will be less than the total reported during the `"diff"` stage.
+- By design for this example, `ds2` is populated semi-randomly with records, so the exact number reported during the `"sync"` stage may differ for you.

examples/example2/example2.py

@@ -0,0 +1,85 @@
+#!/usr/bin/env python
+"""Example 2 - simple pair of DiffSync adapters and a callback function to report progress.
+
+Copyright (c) 2021 Network To Code, LLC <info@networktocode.com>
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+import random
+
+from diffsync import DiffSync, DiffSyncModel
+from diffsync.logging import enable_console_logging
+
+
+class Number(DiffSyncModel):
+    """Simple model that consists only of a number."""
+
+    _modelname = "number"
+    _identifiers = ("number",)
+
+    number: int
+
+
+class DiffSync1(DiffSync):
+    """DiffSync adapter that contains a number of Numbers constructed in order."""
+
+    number = Number
+
+    top_level = ["number"]
+
+    def populate(self, count):
+        """Construct Numbers from 1 to count."""
+        for i in range(count):
+            self.add(Number(number=(i + 1)))
+
+
+class DiffSync2(DiffSync):
+    """DiffSync adapter that contains a number of Numbers spread randomly across a range."""
+
+    number = Number
+
+    top_level = ["number"]
+
+    def populate(self, count):
+        """Construct count numbers in the range (1 - 2*count)."""
+        prev = 0
+        for i in range(count):  # pylint: disable=unused-variable
+            num = prev + random.randint(1, 2)  # nosec
+            self.add(Number(number=num))
+            prev = num
+
+
+def print_callback(stage, current, total):
+    """Callback for DiffSync; stage is "diff"/"sync", current is records processed to date, total is self-evident."""
+    print(f"{stage}: Processed {current:>5}/{total:>5} records.")
+
+
+def main():
+    """Create instances of DiffSync1 and DiffSync2 and sync them with a progress-reporting callback function."""
+    enable_console_logging(verbosity=0)  # Show WARNING and ERROR logs only
+
+    # Create a DiffSync1 instance and populate it with records numbered 1-100
+    ds1 = DiffSync1()
+    ds1.populate(count=100)
+
+    # Create a DiffSync2 instance and populate it with 100 random records in the range 1-200
+    ds2 = DiffSync2()
+    ds2.populate(count=100)
+
+    # Identify and attempt to resolve the differences between the two,
+    # periodically invoking print_callback() as DiffSync progresses
+    ds1.sync_to(ds2, callback=print_callback)
+
+
+if __name__ == "__main__":
+    main()

tests/unit/test_examples.py

@@ -27,3 +27,11 @@ def test_example_1():
     example1_main = join(example1_dir, "main.py")
     # Run it and make sure it doesn't raise an exception or otherwise exit with a non-zero code.
     subprocess.run(example1_main, cwd=example1_dir, check=True)
+
+
+def test_example_2():
+    """Test that the "example2" script runs successfully."""
+    example2_dir = join(EXAMPLES, "example2")
+    example2_main = join(example2_dir, "example2.py")
+    # Run it and make sure it doesn't raise an exception or otherwise exit with a non-zero code.
+    subprocess.run(example2_main, cwd=example2_dir, check=True)