diffsync 2.1.0__tar.gz → 2.2.0__tar.gz

{diffsync-2.1.0 → diffsync-2.2.0}/LICENSE

@@ -1,12 +1,12 @@
-Copyright 2020-2023 Network to Code <info@networktocode.com>
-Network to Code, LLC
+Apache Software License 2.0
+
+Copyright (c) 2025, Network to Code, LLC
 
 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
+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,

{diffsync-2.1.0 → diffsync-2.2.0}/PKG-INFO

@@ -1,15 +1,16 @@
 Metadata-Version: 2.3
 Name: diffsync
-Version: 2.1.0
+Version: 2.2.0
 Summary: Library to easily sync/diff/update 2 different data sources
 License: Apache-2.0
 Keywords: source-of-truth,synchronization
 Author: Network to Code, LLC
 Author-email: info@networktocode.com
-Requires-Python: >=3.9,<4.0
+Requires-Python: >=3.10,<3.14
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
@@ -31,7 +32,7 @@ DiffSync is a utility library that can be used to compare and synchronize differ
 
 For example, it can be used to compare a list of devices from 2 inventory systems and, if required, synchronize them in either direction.
 
-# Primary Use Cases
+## Primary Use Cases
 
 DiffSync is at its most useful when you have multiple sources or sets of data to compare and/or synchronize, and especially if any of the following are true:
 
@@ -40,7 +41,7 @@ DiffSync is at its most useful when you have multiple sources or sets of data to
 - If various types of data in your data set naturally form a tree-like or parent-child relationship with other data.
 - If the different data sets have some attributes in common and other attributes that are exclusive to one or the other.
 
-# Overview of DiffSync
+## Overview of DiffSync
 
 DiffSync acts as an intermediate translation layer between all of the data sets you are diffing and/or syncing. In practical terms, this means that to use DiffSync, you will define a set of data models as well as the “adapters” needed to translate between each base data source and the data model. In Python terms, the adapters will be subclasses of the `Adapter` class, and each data model class will be a subclass of the `DiffSyncModel` class.
 
@@ -55,7 +56,7 @@ You can also ask DiffSync to “sync” one data set onto the other, and it will
 
 ![DiffSync Sync](https://raw.githubusercontent.com/networktocode/diffsync/develop/docs/images/diffsync_sync.png "DiffSync Sync")
 
-# Simple Example
+## Simple Example
 
 ```python
 A = DiffSyncSystemA()
@@ -77,34 +78,51 @@ A.sync_to(B)
 
 > You may wish to peruse the `diffsync` [GitHub topic](https://github.com/topics/diffsync) for examples of projects using this library.
 
-# Documentation
+## Documentation
 
-The documentation is available [on Read The Docs](https://diffsync.readthedocs.io/en/latest/index.html).
+Full documentation for this library can be found over on the [Diffsync Docs](https://diffsync.readthedocs.io/) website:
 
-# Installation
+- [User Guide](https://diffsync.readthedocs.io/user/app_overview/) - Overview, Using the Library, Getting Started.
+- [Administrator Guide](https://diffsync.readthedocs.io/admin/install/) - How to Install, Configure, Upgrade, or Uninstall the Library.
+- [Developer Guide](https://diffsync.readthedocs.io/dev/contributing/) - Extending the Library, Code Reference, Contribution Guide.
+- [Release Notes / Changelog](https://diffsync.readthedocs.io/admin/release_notes/).
+- [Frequently Asked Questions](https://diffsync.readthedocs.io/user/faq/).
 
-### Option 1: Install from PyPI.
+## Installation
 
-```
-$ pip install diffsync
+### Option 1: Install from PyPI
+
+```shell
+pip install diffsync
 ```
 
 ### Option 2: Install from a GitHub branch, such as main as shown below.
+
+```shell
+pip install git+https://github.com/networktocode/diffsync.git@main
 ```
-$ pip install git+https://github.com/networktocode/diffsync.git@main
-```
 
-# Contributing
+## Contributing
+
 Pull requests are welcomed and automatically built and tested against multiple versions of Python through GitHub Actions.
 
-The project is following Network to Code software development guidelines and are leveraging the following:
+The project is following Network to Code software development guidelines and is leveraging the following:
 
-- Black, Pylint, Bandit, flake8, and pydocstyle, mypy for Python linting, formatting and type hint checking.
+- Ruff, mypy for Python linting, formatting and type hint checking.
 - pytest, coverage, and unittest for unit tests.
 
 You can ensure your contribution adheres to these checks by running `invoke tests` from the CLI.
 The command `invoke build` builds a docker container with all the necessary dependencies (including the redis backend) locally to facilitate the execution of these tests.
 
-# Questions
-Please see the [documentation](https://diffsync.readthedocs.io/en/latest/index.html) for detailed documentation on how to use `diffsync`. For any additional questions or comments, feel free to swing by the [Network to Code slack channel](https://networktocode.slack.com/) (channel #networktocode). Sign up [here](http://slack.networktocode.com/)
+## Contributing to the Documentation
+
+You can find all the Markdown source for the App documentation under the [`docs`](https://github.com/networktocode/diffsync/tree/develop/docs) folder in this repository. For simple edits, a Markdown capable editor is sufficient: clone the repository and edit away.
+
+If you need to view the fully-generated documentation site, you can build it with [MkDocs](https://www.mkdocs.org/). A container hosting the documentation can be started using the `invoke` commands (details in the [Development Environment Guide](https://diffsync/dev/dev_environment/#docker-development-environment)) on [http://localhost:8001](http://localhost:8001). Using this container, as your changes to the documentation are saved, they will be automatically rebuilt and any pages currently being viewed will be reloaded in your browser.
+
+Any PRs with fixes or improvements are very welcome!
+
+## Questions
+
+For any questions or comments, please check the [FAQ](https://diffsync.readthedocs.io/en/latest/user/faq/) first. Feel free to also swing by the [Network to Code Slack](https://networktocode.slack.com/) (channel `#networktocode`), sign up [here](http://slack.networktocode.com/) if you don't have an account.
 

{diffsync-2.1.0 → diffsync-2.2.0}/README.md

@@ -4,7 +4,7 @@ DiffSync is a utility library that can be used to compare and synchronize differ
 
 For example, it can be used to compare a list of devices from 2 inventory systems and, if required, synchronize them in either direction.
 
-# Primary Use Cases
+## Primary Use Cases
 
 DiffSync is at its most useful when you have multiple sources or sets of data to compare and/or synchronize, and especially if any of the following are true:
 
@@ -13,7 +13,7 @@ DiffSync is at its most useful when you have multiple sources or sets of data to
 - If various types of data in your data set naturally form a tree-like or parent-child relationship with other data.
 - If the different data sets have some attributes in common and other attributes that are exclusive to one or the other.
 
-# Overview of DiffSync
+## Overview of DiffSync
 
 DiffSync acts as an intermediate translation layer between all of the data sets you are diffing and/or syncing. In practical terms, this means that to use DiffSync, you will define a set of data models as well as the “adapters” needed to translate between each base data source and the data model. In Python terms, the adapters will be subclasses of the `Adapter` class, and each data model class will be a subclass of the `DiffSyncModel` class.
 
@@ -28,7 +28,7 @@ You can also ask DiffSync to “sync” one data set onto the other, and it will
 
 ![DiffSync Sync](https://raw.githubusercontent.com/networktocode/diffsync/develop/docs/images/diffsync_sync.png "DiffSync Sync")
 
-# Simple Example
+## Simple Example
 
 ```python
 A = DiffSyncSystemA()
@@ -50,33 +50,50 @@ A.sync_to(B)
 
 > You may wish to peruse the `diffsync` [GitHub topic](https://github.com/topics/diffsync) for examples of projects using this library.
 
-# Documentation
+## Documentation
 
-The documentation is available [on Read The Docs](https://diffsync.readthedocs.io/en/latest/index.html).
+Full documentation for this library can be found over on the [Diffsync Docs](https://diffsync.readthedocs.io/) website:
 
-# Installation
+- [User Guide](https://diffsync.readthedocs.io/user/app_overview/) - Overview, Using the Library, Getting Started.
+- [Administrator Guide](https://diffsync.readthedocs.io/admin/install/) - How to Install, Configure, Upgrade, or Uninstall the Library.
+- [Developer Guide](https://diffsync.readthedocs.io/dev/contributing/) - Extending the Library, Code Reference, Contribution Guide.
+- [Release Notes / Changelog](https://diffsync.readthedocs.io/admin/release_notes/).
+- [Frequently Asked Questions](https://diffsync.readthedocs.io/user/faq/).
 
-### Option 1: Install from PyPI.
+## Installation
 
-```
-$ pip install diffsync
+### Option 1: Install from PyPI
+
+```shell
+pip install diffsync
 ```
 
 ### Option 2: Install from a GitHub branch, such as main as shown below.
+
+```shell
+pip install git+https://github.com/networktocode/diffsync.git@main
 ```
-$ pip install git+https://github.com/networktocode/diffsync.git@main
-```
 
-# Contributing
+## Contributing
+
 Pull requests are welcomed and automatically built and tested against multiple versions of Python through GitHub Actions.
 
-The project is following Network to Code software development guidelines and are leveraging the following:
+The project is following Network to Code software development guidelines and is leveraging the following:
 
-- Black, Pylint, Bandit, flake8, and pydocstyle, mypy for Python linting, formatting and type hint checking.
+- Ruff, mypy for Python linting, formatting and type hint checking.
 - pytest, coverage, and unittest for unit tests.
 
 You can ensure your contribution adheres to these checks by running `invoke tests` from the CLI.
 The command `invoke build` builds a docker container with all the necessary dependencies (including the redis backend) locally to facilitate the execution of these tests.
 
-# Questions
-Please see the [documentation](https://diffsync.readthedocs.io/en/latest/index.html) for detailed documentation on how to use `diffsync`. For any additional questions or comments, feel free to swing by the [Network to Code slack channel](https://networktocode.slack.com/) (channel #networktocode). Sign up [here](http://slack.networktocode.com/)
+## Contributing to the Documentation
+
+You can find all the Markdown source for the App documentation under the [`docs`](https://github.com/networktocode/diffsync/tree/develop/docs) folder in this repository. For simple edits, a Markdown capable editor is sufficient: clone the repository and edit away.
+
+If you need to view the fully-generated documentation site, you can build it with [MkDocs](https://www.mkdocs.org/). A container hosting the documentation can be started using the `invoke` commands (details in the [Development Environment Guide](https://diffsync/dev/dev_environment/#docker-development-environment)) on [http://localhost:8001](http://localhost:8001). Using this container, as your changes to the documentation are saved, they will be automatically rebuilt and any pages currently being viewed will be reloaded in your browser.
+
+Any PRs with fixes or improvements are very welcome!
+
+## Questions
+
+For any questions or comments, please check the [FAQ](https://diffsync.readthedocs.io/en/latest/user/faq/) first. Feel free to also swing by the [Network to Code Slack](https://networktocode.slack.com/) (channel `#networktocode`), sign up [here](http://slack.networktocode.com/) if you don't have an account.

{diffsync-2.1.0 → diffsync-2.2.0}/diffsync/__init__.py

@@ -16,6 +16,7 @@ limitations under the License.
 """
 
 import sys
+from copy import deepcopy
 from inspect import isclass
 from typing import (
     Any,
@@ -60,7 +61,7 @@ StrType = str
 class DiffSyncModel(BaseModel):
     """Base class for all DiffSync object models.
 
-    Note that read-only APIs of this class are implemented as `get_*()` functions rather than as properties;
+    Note that read-only APIs of this class are implemented as `get_*()` methods rather than as properties;
     this is intentional as specific model classes may want to use these names (`type`, `keys`, `attrs`, etc.)
     as model attributes and we want to avoid any ambiguity or collisions.
 
@@ -158,9 +159,11 @@ class DiffSyncModel(BaseModel):
             raise AttributeError(f"Fields {attr_child_overlap} are included in both _attributes and _children.")
 
     def __repr__(self) -> str:
+        """Return a string representation of this DiffSyncModel."""
         return f'{self.get_type()} "{self.get_unique_id()}"'
 
     def __str__(self) -> str:
+        """Return a string representation of this DiffSyncModel."""
         return self.get_unique_id()
 
     def dict(self, **kwargs: Any) -> Dict:
@@ -305,7 +308,7 @@ class DiffSyncModel(BaseModel):
 
     @classmethod
     def get_type(cls) -> StrType:
-        """Return the type AKA modelname of the object or the class
+        """Return the type AKA modelname of the object or the class.
 
         Returns:
             str: modelname of the class, used in to store all objects
@@ -447,7 +450,6 @@ class Adapter:  # pylint: disable=too-many-public-methods
 
         Subclasses should be careful to call super().__init__() if they override this method.
         """
-
         if isinstance(internal_storage_engine, BaseStore):
             self.store = internal_storage_engine
             self.store.adapter = self
@@ -480,6 +482,13 @@ class Adapter:  # pylint: disable=too-many-public-methods
             if not isclass(value) or not issubclass(value, DiffSyncModel):
                 raise AttributeError(f'top_level references attribute "{name}" but it is not a DiffSyncModel subclass!')
 
+    def __new__(cls, **kwargs):  # type: ignore[no-untyped-def]
+        """Document keyword arguments that were used to initialize Adapter."""
+        meta_kwargs = deepcopy(kwargs)
+        instance = super().__new__(cls)
+        instance._meta_kwargs = meta_kwargs
+        return instance
+
     def __str__(self) -> StrType:
         """String representation of an Adapter."""
         if self.type != self.name:
@@ -487,6 +496,7 @@ class Adapter:  # pylint: disable=too-many-public-methods
         return self.type
 
     def __repr__(self) -> StrType:
+        """Representation of an Adapter."""
         return f"<{str(self)}>"
 
     def __len__(self) -> int:
@@ -575,6 +585,7 @@ class Adapter:  # pylint: disable=too-many-public-methods
             callback: Function with parameters (stage, current, total), to be called at intervals as the calculation of
                 the diff and subsequent sync proceed.
             diff: An existing diff to be used rather than generating a completely new diff.
+
         Returns:
             Diff between origin object and source
         Raises:
@@ -619,6 +630,7 @@ class Adapter:  # pylint: disable=too-many-public-methods
             callback: Function with parameters (stage, current, total), to be called at intervals as the calculation of
                 the diff and subsequent sync proceed.
             diff: An existing diff that will be used when determining what needs to be synced.
+
         Returns:
             Diff between origin object and target
         Raises:
@@ -729,7 +741,7 @@ class Adapter:  # pylint: disable=too-many-public-methods
         obj: Union[StrType, DiffSyncModel, Type[DiffSyncModel]],
         identifier: Union[StrType, Dict],
     ) -> Optional[DiffSyncModel]:
-        """Get one object from the data store based on its unique id or get a None
+        """Get one object from the data store based on its unique id or get a None.
 
         Args:
             obj: DiffSyncModel class or instance, or modelname string, that defines the type of the object to retrieve

{diffsync-2.1.0 → diffsync-2.2.0}/diffsync/exceptions.py

@@ -15,7 +15,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 """
 
-from typing import TYPE_CHECKING, Union, Any
+from typing import TYPE_CHECKING, Any, Union
 
 if TYPE_CHECKING:
     from diffsync import DiffSyncModel

diffsync-2.2.0/diffsync/log.py

@@ -0,0 +1,74 @@
+"""
+Logging utilities for diffsync.
+
+This module contains helpers and wrappers for making logging more consistent across applications.
+
+How to use me:
+
+    >>> from diffsync.log import initialize_logging
+    >>> log = initialize_logging(level="debug")
+"""
+
+import logging.config
+
+APP = "diffsync"
+
+
+def initialize_logging(config=None, level="INFO", filename=None):
+    """Initialize logging using sensible defaults.
+
+    Args:
+        config (dict): User provided configuration dictionary.
+        level (str): The level of logging for STDOUT logging.
+        filename (str): Where to output debug logging to file.
+
+    """
+    if not config:
+        config = {
+            "version": 1,
+            "disable_existing_loggers": False,
+            "formatters": {
+                "standard": {
+                    "format": "%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+                    "datefmt": "%Y-%m-%dT%H:%M:%S%z",
+                },
+                "debug": {
+                    "format": "%(asctime)s [%(levelname)s] [%(module)s] [%(funcName)s] %(name)s: %(message)s",
+                    "datefmt": "%Y-%m-%dT%H:%M:%S%z",
+                },
+            },
+            "handlers": {
+                "standard": {
+                    "class": "logging.StreamHandler",
+                    "formatter": "standard",
+                    "level": level.upper(),
+                },
+            },
+            "loggers": {
+                "": {
+                    "handlers": ["standard"],
+                    "level": "DEBUG",
+                }
+            },
+        }
+
+        # If a filename is passed in, let's add a FileHandler
+        if filename:
+            config["handlers"].update(
+                {
+                    "file_output": {
+                        "class": "logging.FileHandler",
+                        "formatter": "debug",
+                        "level": "DEBUG",
+                        "filename": filename,
+                    }
+                }
+            )
+            config["loggers"][""]["handlers"].append("file_output")
+
+    # Configure the logging
+    logging.config.dictConfig(config)
+
+    # Initialize root logger and advise logging has been initialized
+    log = logging.getLogger(APP)
+    log.debug("Logging initialized.")