renames diffsync.DiffSync to diffsync.Adapter

Author: Leo Kirchner

diffsync/__init__.py

@@ -91,7 +91,7 @@ class DiffSyncModel(BaseModel):
     Can be set as a class attribute or an instance attribute as needed.
     """
 
-    diffsync: Optional["DiffSync"] = None
+    diffsync: Optional["Adapter"] = None
     """Optional: the DiffSync instance that owns this model instance."""
 
     _status: DiffSyncStatus = PrivateAttr(DiffSyncStatus.SUCCESS)
@@ -183,7 +183,7 @@ def set_status(self, status: DiffSyncStatus, message: StrType = "") -> None:
         self._status_message = message
 
     @classmethod
-    def create_base(cls, diffsync: "DiffSync", ids: Dict, attrs: Dict) -> Optional[Self]:
+    def create_base(cls, diffsync: "Adapter", ids: Dict, attrs: Dict) -> Optional[Self]:
         """Instantiate this class, along with any platform-specific data creation.
 
         This method is not meant to be subclassed, users should redefine create() instead.
@@ -201,7 +201,7 @@ def create_base(cls, diffsync: "DiffSync", ids: Dict, attrs: Dict) -> Optional[S
         return model
 
     @classmethod
-    def create(cls, diffsync: "DiffSync", ids: Dict, attrs: Dict) -> Optional[Self]:
+    def create(cls, diffsync: "Adapter", ids: Dict, attrs: Dict) -> Optional[Self]:
         """Instantiate this class, along with any platform-specific data creation.
 
         Subclasses must call `super().create()` or `self.create_base()`; they may wish to then override the default status information
@@ -402,7 +402,7 @@ def remove_child(self, child: "DiffSyncModel") -> None:
         childs.remove(child.get_unique_id())
 
 
-class DiffSync:  # pylint: disable=too-many-public-methods
+class Adapter:  # pylint: disable=too-many-public-methods
     """Class for storing a group of DiffSyncModel instances and diffing/synchronizing to another DiffSync instance."""
 
     # In any subclass, you would add mapping of names to specific model classes here:
@@ -535,7 +535,7 @@ def load_from_dict(self, data: Dict) -> None:
 
     def sync_from(  # pylint: disable=too-many-arguments
         self,
-        source: "DiffSync",
+        source: "Adapter",
         diff_class: Type[Diff] = Diff,
         flags: DiffSyncFlags = DiffSyncFlags.NONE,
         callback: Optional[Callable[[StrType, int, int], None]] = None,
@@ -573,7 +573,7 @@ def sync_from(  # pylint: disable=too-many-arguments
 
     def sync_to(  # pylint: disable=too-many-arguments
         self,
-        target: "DiffSync",
+        target: "Adapter",
         diff_class: Type[Diff] = Diff,
         flags: DiffSyncFlags = DiffSyncFlags.NONE,
         callback: Optional[Callable[[StrType, int, int], None]] = None,
@@ -597,7 +597,7 @@ def sync_to(  # pylint: disable=too-many-arguments
 
     def sync_complete(
         self,
-        source: "DiffSync",
+        source: "Adapter",
         diff: Diff,
         flags: DiffSyncFlags = DiffSyncFlags.NONE,
         logger: Optional[structlog.BoundLogger] = None,
@@ -623,7 +623,7 @@ def sync_complete(
 
     def diff_from(
         self,
-        source: "DiffSync",
+        source: "Adapter",
         diff_class: Type[Diff] = Diff,
         flags: DiffSyncFlags = DiffSyncFlags.NONE,
         callback: Optional[Callable[[StrType, int, int], None]] = None,
@@ -644,7 +644,7 @@ def diff_from(
 
     def diff_to(
         self,
-        target: "DiffSync",
+        target: "Adapter",
         diff_class: Type[Diff] = Diff,
         flags: DiffSyncFlags = DiffSyncFlags.NONE,
         callback: Optional[Callable[[StrType, int, int], None]] = None,
@@ -854,5 +854,8 @@ def count(self, model: Union[StrType, "DiffSyncModel", Type["DiffSyncModel"], No
         return self.store.count(model=model)
 
 
+# For backwards-compatibility, keep around the old name
+DiffSync = Adapter
+
 # DiffSyncModel references DiffSync and DiffSync references DiffSyncModel. Break the typing loop:
 DiffSyncModel.update_forward_refs()

diffsync/helpers.py

@@ -26,7 +26,7 @@
 
 if TYPE_CHECKING:  # pragma: no cover
     # For type annotation purposes, we have a circular import loop between __init__.py and this file.
-    from . import DiffSync, DiffSyncModel  # pylint: disable=cyclic-import
+    from . import Adapter, DiffSyncModel  # pylint: disable=cyclic-import
 
 
 class DiffSyncDiffer:  # pylint: disable=too-many-instance-attributes
@@ -37,8 +37,8 @@ class DiffSyncDiffer:  # pylint: disable=too-many-instance-attributes
 
     def __init__(  # pylint: disable=too-many-arguments
         self,
-        src_diffsync: "DiffSync",
-        dst_diffsync: "DiffSync",
+        src_diffsync: "Adapter",
+        dst_diffsync: "Adapter",
         flags: DiffSyncFlags,
         diff_class: Type[Diff] = Diff,
         callback: Optional[Callable[[str, int, int], None]] = None,
@@ -288,8 +288,8 @@ class DiffSyncSyncer:  # pylint: disable=too-many-instance-attributes
     def __init__(  # pylint: disable=too-many-arguments
         self,
         diff: Diff,
-        src_diffsync: "DiffSync",
-        dst_diffsync: "DiffSync",
+        src_diffsync: "Adapter",
+        dst_diffsync: "Adapter",
         flags: DiffSyncFlags,
         callback: Optional[Callable[[str, int, int], None]] = None,
     ):

diffsync/store/__init__.py

@@ -6,7 +6,7 @@
 
 if TYPE_CHECKING:
     from diffsync import DiffSyncModel
-    from diffsync import DiffSync
+    from diffsync import Adapter
 
 
 class BaseStore:
@@ -15,7 +15,7 @@ class BaseStore:
     def __init__(
         self,  # pylint: disable=unused-argument
         *args: Any,  # pylint: disable=unused-argument
-        diffsync: Optional["DiffSync"] = None,
+        diffsync: Optional["Adapter"] = None,
         name: str = "",
         **kwargs: Any,  # pylint: disable=unused-argument
     ) -> None:

docs/source/core_engine/01-flags.md

@@ -34,12 +34,12 @@ diff = nautobot.diff_from(local, flags=flags)
 Model flags are stored in the attribute `model_flags` of each model and are usually set when the data is being loaded into the adapter.
 
 ```python
-from diffsync import DiffSync
+from diffsync import Adapter
 from diffsync.enum import DiffSyncModelFlags
 from model import MyDeviceModel
 
-class MyAdapter(DiffSync):
 
+class MyAdapter(Adapter):
     device = MyDeviceModel
 
     def load(self, data):

docs/source/core_engine/03-store.md

@@ -9,10 +9,12 @@ The `store` is a class attribute in the `DiffSync` class, but all the store oper
 When you initialize the `Diffsync` Adapter class, there is an optional keyed-argument, `internal_storage_engine`, defaulting to the `LocalStore` class.
 
 ```python
->>> from diffsync import DiffSync
->>> adapter = DiffSync()
->>> type(adapter.store)
-<class 'diffsync.store.local.LocalStore'>
+>> > from diffsync import Adapter
+>> > adapter = Adapter()
+>> > type(adapter.store)
+<
+
+class 'diffsync.store.local.LocalStore'>
 ```
 
 ## Use the `RedisStore` Backend
@@ -22,12 +24,14 @@ To get it, you have to install diffsync package with the "redis" extra option: `
 The `RedisStore` backend, as the name suggests, connects to an external Redis service, to store data loaded by the `DiffSync` tasks. The biggest change is that it requires to initialize the Redis store class, before using it in the `DiffSync` adapter class.
 
 ```python
->>> from diffsync import DiffSync
->>> from diffsync.store.redis import RedisStore
->>> store = RedisStore(host="redis host")
->>> adapter = DiffSync(internal_storage_engine=store)
->>> type(adapter.store)
-<class 'diffsync.store.local.RedisStore'>
+>> > from diffsync import Adapter
+>> > from diffsync.store.redis import RedisStore
+>> > store = RedisStore(host="redis host")
+>> > adapter = Adapter(internal_storage_engine=store)
+>> > type(adapter.store)
+<
+
+class 'diffsync.store.local.RedisStore'>
 ```
 
 Notice that the `RedisStore` will validate, when initialized, that there is a reachability to the Redis host, and if not, will raise an exception:

docs/source/getting_started/01-getting-started.md

@@ -44,10 +44,10 @@ Currently the relationships between models are very loose by design. Instead of
 A `DiffSync` "adapter" subclass must reference each model available at the top of the object by its modelname and must have a `top_level` attribute defined to indicate how the diff and the synchronization should be done. In the example below, `"site"` is the only top level object so the synchronization engine will only check all known `Site` instances and all children of each Site. In this case, as shown in the code above, `Device`s are children of `Site`s, so this is exactly the intended logic.
 
 ```python
-from diffsync import DiffSync
+from diffsync import Adapter
 
-class BackendA(DiffSync):
 
+class BackendA(Adapter):
     site = Site
     device = Device
 

examples/01-multiple-data-sources/backend_a.py

@@ -16,7 +16,7 @@
 """
 
 # pylint: disable=wrong-import-order
-from diffsync import DiffSync
+from diffsync import Adapter
 from models import Site, Device, Interface  # pylint: disable=no-name-in-module
 
 DATA = {
@@ -31,7 +31,7 @@
 }
 
 
-class BackendA(DiffSync):
+class BackendA(Adapter):
     """Example of a DiffSync adapter implementation."""
 
     site = Site

examples/01-multiple-data-sources/backend_b.py

@@ -16,7 +16,7 @@
 """
 
 # pylint: disable=wrong-import-order
-from diffsync import DiffSync
+from diffsync import Adapter
 from models import Site, Device, Interface  # pylint: disable=no-name-in-module
 
 DATA = {
@@ -35,7 +35,7 @@
 }
 
 
-class BackendB(DiffSync):
+class BackendB(Adapter):
     """Example of a DiffSync adapter implementation."""
 
     site = Site

examples/01-multiple-data-sources/backend_c.py

@@ -16,7 +16,7 @@
 """
 
 # pylint: disable=wrong-import-order
-from diffsync import DiffSync
+from diffsync import Adapter
 from models import Site, Device, Interface  # pylint: disable=no-name-in-module
 
 DATA = {
@@ -31,7 +31,7 @@
 }
 
 
-class BackendC(DiffSync):
+class BackendC(Adapter):
     """Example of a DiffSync adapter implementation."""
 
     site = Site

examples/02-callback-function/main.py

@@ -17,7 +17,7 @@
 """
 import random
 
-from diffsync import DiffSync, DiffSyncModel
+from diffsync import Adapter, DiffSyncModel
 from diffsync.logging import enable_console_logging
 
 
@@ -30,7 +30,7 @@ class Number(DiffSyncModel):
     number: int
 
 
-class DiffSync1(DiffSync):
+class Adapter1(Adapter):
     """DiffSync adapter that contains a number of Numbers constructed in order."""
 
     number = Number
@@ -43,7 +43,7 @@ def load(self, count):  # pylint: disable=arguments-differ
             self.add(Number(number=(i + 1)))
 
 
-class DiffSync2(DiffSync):
+class Adapter2(Adapter):
     """DiffSync adapter that contains a number of Numbers spread randomly across a range."""
 
     number = Number
@@ -69,11 +69,11 @@ def main():
     enable_console_logging(verbosity=0)  # Show WARNING and ERROR logs only
 
     # Create a DiffSync1 instance and load it with records numbered 1-100
-    ds1 = DiffSync1()
+    ds1 = Adapter1()
     ds1.load(count=100)
 
     # Create a DiffSync2 instance and load it with 100 random records in the range 1-200
-    ds2 = DiffSync2()
+    ds2 = Adapter2()
     ds2.load(count=100)
 
     # Identify and attempt to resolve the differences between the two,