diffsync 2.0.1__tar.gz → 2.2.0__tar.gz

{diffsync-2.0.1 → 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.0.1 → diffsync-2.2.0}/PKG-INFO

@@ -1,29 +1,28 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.3
 Name: diffsync
-Version: 2.0.1
+Version: 2.2.0
 Summary: Library to easily sync/diff/update 2 different data sources
-Home-page: https://diffsync.readthedocs.io
 License: Apache-2.0
 Keywords: source-of-truth,synchronization
 Author: Network to Code, LLC
 Author-email: info@networktocode.com
-Requires-Python: >=3.8,<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.8
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Provides-Extra: redis
-Requires-Dist: colorama (>=0.4.3,<0.5.0)
-Requires-Dist: packaging (>=21.3,<24.0)
+Requires-Dist: packaging (>=21.3)
 Requires-Dist: pydantic (>=2.0.0,<3.0.0)
 Requires-Dist: redis (>=4.3,<5.0) ; extra == "redis"
 Requires-Dist: structlog (>=20.1.0)
 Requires-Dist: typing-extensions (>=4.0.1) ; python_version < "3.11"
 Project-URL: Documentation, https://diffsync.readthedocs.io
+Project-URL: Homepage, https://diffsync.readthedocs.io
 Project-URL: Repository, https://github.com/networktocode/diffsync
 Description-Content-Type: text/markdown
 
@@ -33,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:
 
@@ -42,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.
 
@@ -57,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()
@@ -79,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.0.1 → 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.0.1 → diffsync-2.2.0}/diffsync/__init__.py

@@ -14,32 +14,34 @@ 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 sys
+from copy import deepcopy
 from inspect import isclass
 from typing import (
+    Any,
     Callable,
     ClassVar,
     Dict,
     List,
     Optional,
+    Set,
     Tuple,
     Type,
     Union,
-    Any,
-    Set,
 )
-from typing_extensions import deprecated
 
-from pydantic import ConfigDict, BaseModel, PrivateAttr
 import structlog  # type: ignore
+from pydantic import BaseModel, ConfigDict, PrivateAttr
+from typing_extensions import deprecated
 
 from diffsync.diff import Diff
-from diffsync.enum import DiffSyncModelFlags, DiffSyncFlags, DiffSyncStatus
+from diffsync.enum import DiffSyncFlags, DiffSyncModelFlags, DiffSyncStatus
 from diffsync.exceptions import (
     DiffClassMismatch,
     ObjectAlreadyExists,
-    ObjectStoreWrongType,
     ObjectNotFound,
+    ObjectStoreWrongType,
 )
 from diffsync.helpers import DiffSyncDiffer, DiffSyncSyncer
 from diffsync.store import BaseStore
@@ -59,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.
 
@@ -69,7 +71,7 @@ class DiffSyncModel(BaseModel):
     be included in **at most** one of these three tuples.
     """
 
-    _modelname: ClassVar[str] = "diffsyncmodel"
+    _modelname: ClassVar[str] = "diffsyncmodel"  # pylint: disable=used-before-assignment
     """Name of this model, used by DiffSync to store and look up instances of this model or its equivalents.
 
     Lowercase by convention; typically corresponds to the class name, but that is not enforced.
@@ -133,16 +135,16 @@ class DiffSyncModel(BaseModel):
         """
         # Make sure that any field referenced by name actually exists on the model
         for attr in cls._identifiers:
-            if attr not in cls.model_fields and not hasattr(cls, attr):
+            if attr not in cls.model_fields and not hasattr(cls, attr):  # pylint: disable=unsupported-membership-test
                 raise AttributeError(f"_identifiers {cls._identifiers} references missing or un-annotated attr {attr}")
         for attr in cls._shortname:
-            if attr not in cls.model_fields:
+            if attr not in cls.model_fields:  # pylint: disable=unsupported-membership-test
                 raise AttributeError(f"_shortname {cls._shortname} references missing or un-annotated attr {attr}")
         for attr in cls._attributes:
-            if attr not in cls.model_fields:
+            if attr not in cls.model_fields:  # pylint: disable=unsupported-membership-test
                 raise AttributeError(f"_attributes {cls._attributes} references missing or un-annotated attr {attr}")
         for attr in cls._children.values():
-            if attr not in cls.model_fields:
+            if attr not in cls.model_fields:  # pylint: disable=unsupported-membership-test
                 raise AttributeError(f"_children {cls._children} references missing or un-annotated attr {attr}")
 
         # Any given field can only be in one of (_identifiers, _attributes, _children)
@@ -157,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:
@@ -304,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
@@ -431,7 +435,7 @@ class Adapter:  # pylint: disable=too-many-public-methods
     # modelname1 = MyModelClass1
     # modelname2 = MyModelClass2
 
-    type: Optional[str] = None
+    type: Optional[str] = None  # pylint: disable=used-before-assignment
     """Type of the object, will default to the name of the class if not provided."""
 
     top_level: ClassVar[List[str]] = []
@@ -446,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
@@ -479,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:
@@ -486,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:
@@ -557,7 +568,7 @@ class Adapter:  # pylint: disable=too-many-public-methods
     # Synchronization between DiffSync instances
     # ------------------------------------------------------------------------------
 
-    def sync_from(  # pylint: disable=too-many-arguments
+    def sync_from(  # pylint: disable=too-many-arguments, too-many-positional-arguments
         self,
         source: "Adapter",
         diff_class: Type[Diff] = Diff,
@@ -574,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:
@@ -601,7 +613,7 @@ class Adapter:  # pylint: disable=too-many-public-methods
 
         return diff
 
-    def sync_to(  # pylint: disable=too-many-arguments
+    def sync_to(  # pylint: disable=too-many-arguments, too-many-positional-arguments
         self,
         target: "Adapter",
         diff_class: Type[Diff] = Diff,
@@ -618,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:
@@ -728,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.0.1 → diffsync-2.2.0}/diffsync/diff.py

@@ -16,11 +16,11 @@ limitations under the License.
 """
 
 from functools import total_ordering
-from typing import Any, Iterator, Optional, Type, List, Dict, Iterable
+from typing import Any, Dict, Iterable, Iterator, List, Optional, Type
 
-from .exceptions import ObjectAlreadyExists
-from .utils import intersection, OrderedDefaultDict
 from .enum import DiffSyncActions
+from .exceptions import ObjectAlreadyExists
+from .utils import OrderedDefaultDict, intersection
 
 # This workaround is used because we are defining a method called `str` in our class definition, which therefore renders
 # the builtin `str` type unusable.
@@ -105,8 +105,7 @@ class Diff:
 
         Since children is already an OrderedDefaultDict, this method is not doing anything special.
         """
-        for child in children.values():
-            yield child
+        yield from children.values()
 
     def summary(self) -> Dict[StrType, int]:
         """Build a dict summary of this Diff and its child DiffElements."""
@@ -161,7 +160,7 @@ class Diff:
 class DiffElement:  # pylint: disable=too-many-instance-attributes
     """DiffElement object, designed to represent a single item/object that may or may not have any diffs."""
 
-    def __init__(
+    def __init__(  # pylint: disable=too-many-positional-arguments
         self,
         obj_type: StrType,
         name: StrType,

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

@@ -14,7 +14,8 @@ 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.
 """
-from typing import TYPE_CHECKING, Union, Any
+
+from typing import TYPE_CHECKING, Any, Union
 
 if TYPE_CHECKING:
     from diffsync import DiffSyncModel

{diffsync-2.0.1 → diffsync-2.2.0}/diffsync/helpers.py

@@ -14,14 +14,16 @@ 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.
 """
-from collections.abc import Iterable as ABCIterable, Mapping as ABCMapping
-from typing import Callable, List, Optional, Tuple, Type, TYPE_CHECKING, Dict, Iterable
+
+from collections.abc import Iterable as ABCIterable
+from collections.abc import Mapping as ABCMapping
+from typing import TYPE_CHECKING, Callable, Dict, Iterable, List, Optional, Tuple, Type
 
 import structlog  # type: ignore
 
 from .diff import Diff, DiffElement
-from .enum import DiffSyncModelFlags, DiffSyncFlags, DiffSyncStatus, DiffSyncActions
-from .exceptions import ObjectNotFound, ObjectNotCreated, ObjectNotUpdated, ObjectNotDeleted, ObjectCrudException
+from .enum import DiffSyncActions, DiffSyncFlags, DiffSyncModelFlags, DiffSyncStatus
+from .exceptions import ObjectCrudException, ObjectNotCreated, ObjectNotDeleted, ObjectNotFound, ObjectNotUpdated
 from .utils import intersection, symmetric_difference
 
 if TYPE_CHECKING:  # pragma: no cover
@@ -35,7 +37,7 @@ class DiffSyncDiffer:  # pylint: disable=too-many-instance-attributes
     Independent from Diff and DiffElement as those classes are purely data objects, while this stores some state.
     """
 
-    def __init__(  # pylint: disable=too-many-arguments
+    def __init__(  # pylint: disable=too-many-arguments, too-many-positional-arguments
         self,
         src_diffsync: "Adapter",
         dst_diffsync: "Adapter",
@@ -114,9 +116,9 @@ class DiffSyncDiffer:  # pylint: disable=too-many-instance-attributes
 
             combined_dict = {}
             for uid in dict_src:
-                combined_dict[uid] = (dict_src.get(uid), dict_dst.get(uid))
+                combined_dict[uid] = (dict_src.get(uid), dict_dst.get(uid))  # type: ignore
             for uid in dict_dst:
-                combined_dict[uid] = (dict_src.get(uid), dict_dst.get(uid))
+                combined_dict[uid] = (dict_src.get(uid), dict_dst.get(uid))  # type: ignore
         else:
             # In the future we might support set, etc...
             raise TypeError(f"Type combination {type(src)}/{type(dst)} is not supported... for now")
@@ -137,7 +139,7 @@ class DiffSyncDiffer:  # pylint: disable=too-many-instance-attributes
 
     @staticmethod
     def validate_objects_for_diff(
-        object_pairs: Iterable[Tuple[Optional["DiffSyncModel"], Optional["DiffSyncModel"]]]
+        object_pairs: Iterable[Tuple[Optional["DiffSyncModel"], Optional["DiffSyncModel"]]],
     ) -> None:
         """Check whether all DiffSyncModels in the given dictionary are valid for comparison to one another.
 
@@ -285,7 +287,7 @@ class DiffSyncSyncer:  # pylint: disable=too-many-instance-attributes
     Independent from DiffSync and DiffSyncModel as those classes are purely data objects, while this stores some state.
     """
 
-    def __init__(  # pylint: disable=too-many-arguments
+    def __init__(  # pylint: disable=too-many-arguments, too-many-positional-arguments
         self,
         diff: Diff,
         src_diffsync: "Adapter",

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.")