From be20e7b97b0846e82e36c1f939ca193b56e1bdf0 Mon Sep 17 00:00:00 2001 From: Leo Kirchner Date: Thu, 1 Feb 2024 16:01:56 +0100 Subject: [PATCH 1/9] fixes docs build --- .readthedocs.yml | 6 ++- docs/requirements.txt | 6 +-- poetry.lock | 100 +++++++++++++++++++++++++++++++----------- pyproject.toml | 2 +- 4 files changed, 84 insertions(+), 30 deletions(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index 5455df55..28f9b3e4 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -6,8 +6,12 @@ sphinx: configuration: "docs/source/conf.py" fail_on_warning: false +build: + os: "ubuntu-22.04" + tools: + python: "3.11" + python: - version: "3.7" install: - requirements: "docs/requirements.txt" - method: "pip" diff --git a/docs/requirements.txt b/docs/requirements.txt index 5f7db800..9a67117f 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,5 +1,5 @@ -m2r2==0.2.7 +m2r2==0.3.3.post2 mistune==0.8.4 -sphinx==4.5.0 +sphinx==6.2.1 toml==0.10.2 -sphinx-rtd-theme==1.0.0 \ No newline at end of file +sphinx-rtd-theme==2.0.0 diff --git a/poetry.lock b/poetry.lock index 29720188..fc27a185 100644 --- a/poetry.lock +++ b/poetry.lock @@ -581,6 +581,25 @@ files = [ {file = "imagesize-1.4.1.tar.gz", hash = "sha256:69150444affb9cb0d5cc5a92b3676f0b2fb7cd9ae39e947a5e11a36b4497cd4a"}, ] +[[package]] +name = "importlib-metadata" +version = "7.0.1" +description = "Read metadata from Python packages" +optional = false +python-versions = ">=3.8" +files = [ + {file = "importlib_metadata-7.0.1-py3-none-any.whl", hash = "sha256:4805911c3a4ec7c3966410053e9ec6a1fecd629117df5adee56dfc9432a1081e"}, + {file = "importlib_metadata-7.0.1.tar.gz", hash = "sha256:f238736bb06590ae52ac1fab06a3a9ef1d8dce2b7a35b5ab329371d6c8f5d2cc"}, +] + +[package.dependencies] +zipp = ">=0.5" + +[package.extras] +docs = ["furo", "jaraco.packaging (>=9.3)", "jaraco.tidelift (>=1.4)", "rst.linker (>=1.9)", "sphinx (<7.2.5)", "sphinx (>=3.5)", "sphinx-lint"] +perf = ["ipython"] +testing = ["flufl.flake8", "importlib-resources (>=1.3)", "packaging", "pyfakefs", "pytest (>=6)", "pytest-black (>=0.3.7)", "pytest-checkdocs (>=2.4)", "pytest-cov", "pytest-enabler (>=2.2)", "pytest-mypy (>=0.9.1)", "pytest-perf (>=0.9.2)", "pytest-ruff"] + [[package]] name = "iniconfig" version = "2.0.0" @@ -1388,55 +1407,57 @@ files = [ [[package]] name = "sphinx" -version = "3.5.3" +version = "6.2.1" description = "Python documentation generator" optional = false -python-versions = ">=3.5" +python-versions = ">=3.8" files = [ - {file = "Sphinx-3.5.3-py3-none-any.whl", hash = "sha256:3f01732296465648da43dec8fb40dc451ba79eb3e2cc5c6d79005fd98197107d"}, - {file = "Sphinx-3.5.3.tar.gz", hash = "sha256:ce9c228456131bab09a3d7d10ae58474de562a6f79abb3dc811ae401cf8c1abc"}, + {file = "Sphinx-6.2.1.tar.gz", hash = "sha256:6d56a34697bb749ffa0152feafc4b19836c755d90a7c59b72bc7dfd371b9cc6b"}, + {file = "sphinx-6.2.1-py3-none-any.whl", hash = "sha256:97787ff1fa3256a3eef9eda523a63dbf299f7b47e053cfcf684a1c2a8380c912"}, ] [package.dependencies] alabaster = ">=0.7,<0.8" -babel = ">=1.3" -colorama = {version = ">=0.3.5", markers = "sys_platform == \"win32\""} -docutils = ">=0.12" -imagesize = "*" -Jinja2 = ">=2.3" -packaging = "*" -Pygments = ">=2.0" -requests = ">=2.5.0" -setuptools = "*" -snowballstemmer = ">=1.1" +babel = ">=2.9" +colorama = {version = ">=0.4.5", markers = "sys_platform == \"win32\""} +docutils = ">=0.18.1,<0.20" +imagesize = ">=1.3" +importlib-metadata = {version = ">=4.8", markers = "python_version < \"3.10\""} +Jinja2 = ">=3.0" +packaging = ">=21.0" +Pygments = ">=2.13" +requests = ">=2.25.0" +snowballstemmer = ">=2.0" sphinxcontrib-applehelp = "*" sphinxcontrib-devhelp = "*" -sphinxcontrib-htmlhelp = "*" +sphinxcontrib-htmlhelp = ">=2.0.0" sphinxcontrib-jsmath = "*" sphinxcontrib-qthelp = "*" -sphinxcontrib-serializinghtml = "*" +sphinxcontrib-serializinghtml = ">=1.1.5" [package.extras] docs = ["sphinxcontrib-websupport"] -lint = ["docutils-stubs", "flake8 (>=3.5.0)", "isort", "mypy (>=0.800)"] -test = ["cython", "html5lib", "pytest", "pytest-cov", "typed-ast"] +lint = ["docutils-stubs", "flake8 (>=3.5.0)", "flake8-simplify", "isort", "mypy (>=0.990)", "ruff", "sphinx-lint", "types-requests"] +test = ["cython", "filelock", "html5lib", "pytest (>=4.6)"] [[package]] name = "sphinx-rtd-theme" -version = "0.5.1" +version = "2.0.0" description = "Read the Docs theme for Sphinx" optional = false -python-versions = "*" +python-versions = ">=3.6" files = [ - {file = "sphinx_rtd_theme-0.5.1-py2.py3-none-any.whl", hash = "sha256:fa6bebd5ab9a73da8e102509a86f3fcc36dec04a0b52ea80e5a033b2aba00113"}, - {file = "sphinx_rtd_theme-0.5.1.tar.gz", hash = "sha256:eda689eda0c7301a80cf122dad28b1861e5605cbf455558f3775e1e8200e83a5"}, + {file = "sphinx_rtd_theme-2.0.0-py2.py3-none-any.whl", hash = "sha256:ec93d0856dc280cf3aee9a4c9807c60e027c7f7b461b77aeffed682e68f0e586"}, + {file = "sphinx_rtd_theme-2.0.0.tar.gz", hash = "sha256:bd5d7b80622406762073a04ef8fadc5f9151261563d47027de09910ce03afe6b"}, ] [package.dependencies] -sphinx = "*" +docutils = "<0.21" +sphinx = ">=5,<8" +sphinxcontrib-jquery = ">=4,<5" [package.extras] -dev = ["bump2version", "sphinxcontrib-httpdomain", "transifex-client"] +dev = ["bump2version", "sphinxcontrib-httpdomain", "transifex-client", "wheel"] [[package]] name = "sphinxcontrib-applehelp" @@ -1483,6 +1504,20 @@ files = [ lint = ["docutils-stubs", "flake8", "mypy"] test = ["html5lib", "pytest"] +[[package]] +name = "sphinxcontrib-jquery" +version = "4.1" +description = "Extension to include jQuery on newer Sphinx releases" +optional = false +python-versions = ">=2.7" +files = [ + {file = "sphinxcontrib-jquery-4.1.tar.gz", hash = "sha256:1620739f04e36a2c779f1a131a2dfd49b2fd07351bf1968ced074365933abc7a"}, + {file = "sphinxcontrib_jquery-4.1-py2.py3-none-any.whl", hash = "sha256:f936030d7d0147dd026a4f2b5a57343d233f1fc7b363f68b3d4f1cb0993878ae"}, +] + +[package.dependencies] +Sphinx = ">=1.8" + [[package]] name = "sphinxcontrib-jsmath" version = "1.0.1" @@ -1783,10 +1818,25 @@ pathspec = ">=0.5.3" pyyaml = "*" setuptools = "*" +[[package]] +name = "zipp" +version = "3.17.0" +description = "Backport of pathlib-compatible object wrapper for zip files" +optional = false +python-versions = ">=3.8" +files = [ + {file = "zipp-3.17.0-py3-none-any.whl", hash = "sha256:0e923e726174922dce09c53c59ad483ff7bbb8e572e00c7f7c46b88556409f31"}, + {file = "zipp-3.17.0.tar.gz", hash = "sha256:84e64a1c28cf7e91ed2078bb8cc8c259cb19b76942096c8d7b84947690cabaf0"}, +] + +[package.extras] +docs = ["furo", "jaraco.packaging (>=9.3)", "jaraco.tidelift (>=1.4)", "rst.linker (>=1.9)", "sphinx (<7.2.5)", "sphinx (>=3.5)", "sphinx-lint"] +testing = ["big-O", "jaraco.functools", "jaraco.itertools", "more-itertools", "pytest (>=6)", "pytest-black (>=0.3.7)", "pytest-checkdocs (>=2.4)", "pytest-cov", "pytest-enabler (>=2.2)", "pytest-ignore-flaky", "pytest-mypy (>=0.9.1)", "pytest-ruff"] + [extras] redis = ["redis"] [metadata] lock-version = "2.0" python-versions = ">=3.8,<4.0" -content-hash = "4e607b247cbc76d2f676733677c182e154883d78d16a227081b4f1036d4690fa" +content-hash = "c94995e97cbb7d053c55eceff623439f1a88c480a4bfece682701b1692f108b2" diff --git a/pyproject.toml b/pyproject.toml index 2f48372c..9bff7760 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -42,7 +42,7 @@ mypy = "*" pytest-cov = "*" pytest-structlog = "*" coverage = {extras = ["toml"], version = "*"} -Sphinx = "*" +Sphinx = "^6.0.0" m2r2 = "*" sphinx-rtd-theme = "*" toml = "*" From d2766637327f5504a653d67e3a802377492b364e Mon Sep 17 00:00:00 2001 From: Leo Kirchner Date: Thu, 15 Feb 2024 11:22:03 +0100 Subject: [PATCH 2/9] fixes wording for a couple of docstrings --- diffsync/__init__.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/diffsync/__init__.py b/diffsync/__init__.py index acaf732d..e6867cb7 100644 --- a/diffsync/__init__.py +++ b/diffsync/__init__.py @@ -425,7 +425,7 @@ def remove_child(self, child: "DiffSyncModel") -> None: class Adapter: # pylint: disable=too-many-public-methods - """Class for storing a group of DiffSyncModel instances and diffing/synchronizing to another DiffSync instance.""" + """Class for storing a group of DiffSyncModel instances and diffing/synchronizing to another Adapter instance.""" # In any subclass, you would add mapping of names to specific model classes here: # modelname1 = MyModelClass1 @@ -835,7 +835,7 @@ def remove(self, obj: DiffSyncModel, remove_children: bool = False) -> None: def get_or_instantiate( self, model: Type[DiffSyncModel], ids: Dict, attrs: Optional[Dict] = None ) -> Tuple[DiffSyncModel, bool]: - """Attempt to get the object with provided identifiers or instantiate it with provided identifiers and attrs. + """Attempt to get the object with provided identifiers or instantiate and add it with provided identifiers and attrs. Args: model: The DiffSyncModel to get or create. @@ -848,7 +848,7 @@ def get_or_instantiate( return self.store.get_or_instantiate(model=model, ids=ids, attrs=attrs) def get_or_add_model_instance(self, obj: DiffSyncModel) -> Tuple[DiffSyncModel, bool]: - """Attempt to get the object with provided obj identifiers or instantiate obj. + """Attempt to get the object with provided obj identifiers or add obj. Args: obj: An obj of the DiffSyncModel to get or add. From a57ad36d37b7373fe3cfb9da4b8d8bd9c4f3fd8d Mon Sep 17 00:00:00 2001 From: corubba Date: Mon, 24 Jun 2024 15:06:16 +0200 Subject: [PATCH 3/9] Replace mentions of deprecated DiffSync class At least the ones I found, there are probably some more. --- diffsync/__init__.py | 4 ++-- docs/source/core_engine/01-flags.md | 8 ++++---- docs/source/core_engine/03-store.md | 2 +- docs/source/getting_started/01-getting-started.md | 14 +++++++------- 4 files changed, 14 insertions(+), 14 deletions(-) diff --git a/diffsync/__init__.py b/diffsync/__init__.py index e6867cb7..788b8e64 100644 --- a/diffsync/__init__.py +++ b/diffsync/__init__.py @@ -480,7 +480,7 @@ def __init_subclass__(cls) -> None: raise AttributeError(f'top_level references attribute "{name}" but it is not a DiffSyncModel subclass!') def __str__(self) -> StrType: - """String representation of a DiffSync.""" + """String representation of an Adapter.""" if self.type != self.name: return f'{self.type} "{self.name}"' return self.type @@ -526,7 +526,7 @@ def dict(self, exclude_defaults: bool = True, **kwargs: Any) -> Dict[str, Dict[s return data def str(self, indent: int = 0) -> StrType: - """Build a detailed string representation of this DiffSync.""" + """Build a detailed string representation of this Adapter.""" margin = " " * indent output = "" for modelname in self.top_level: diff --git a/docs/source/core_engine/01-flags.md b/docs/source/core_engine/01-flags.md index 12f4ca9b..bae958fd 100644 --- a/docs/source/core_engine/01-flags.md +++ b/docs/source/core_engine/01-flags.md @@ -24,8 +24,8 @@ diff = nautobot.diff_from(local, flags=flags) | Name | Description | Binary Value | |---|---|---| | CONTINUE_ON_FAILURE | Continue synchronizing even if failures are encountered when syncing individual models. | 0b1 | -| SKIP_UNMATCHED_SRC | Ignore objects that only exist in the source/"from" DiffSync when determining diffs and syncing. If this flag is set, no new objects will be created in the target/"to" DiffSync. | 0b10 | -| SKIP_UNMATCHED_DST | Ignore objects that only exist in the target/"to" DiffSync when determining diffs and syncing. If this flag is set, no objects will be deleted from the target/"to" DiffSync. | 0b100 | +| SKIP_UNMATCHED_SRC | Ignore objects that only exist in the source/"from" adapter when determining diffs and syncing. If this flag is set, no new objects will be created in the target/"to" adapter. | 0b10 | +| SKIP_UNMATCHED_DST | Ignore objects that only exist in the target/"to" adapter when determining diffs and syncing. If this flag is set, no objects will be deleted from the target/"to" adapter. | 0b100 | | SKIP_UNMATCHED_BOTH | Convenience value combining both SKIP_UNMATCHED_SRC and SKIP_UNMATCHED_DST into a single flag | 0b110 | | LOG_UNCHANGED_RECORDS | If this flag is set, a log message will be generated during synchronization for each model, even unchanged ones. | 0b1000 | @@ -57,8 +57,8 @@ class MyAdapter(Adapter): |---|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---| | IGNORE | Do not render diffs containing this model; do not make any changes to this model when synchronizing. Can be used to indicate a model instance that exists but should not be changed by DiffSync. | 0b1 | | SKIP_CHILDREN_ON_DELETE | When deleting this model, do not recursively delete its children. Can be used for the case where deletion of a model results in the automatic deletion of all its children. | 0b10 | -| SKIP_UNMATCHED_SRC | Ignore the model if it only exists in the source/"from" DiffSync when determining diffs and syncing. If this flag is set, no new model will be created in the target/"to" DiffSync. | 0b100 | -| SKIP_UNMATCHED_DST | Ignore the model if it only exists in the target/"to" DiffSync when determining diffs and syncing. If this flag is set, the model will not be deleted from the target/"to" DiffSync. | 0b1000 | +| SKIP_UNMATCHED_SRC | Ignore the model if it only exists in the source/"from" adapter when determining diffs and syncing. If this flag is set, no new model will be created in the target/"to" adapter. | 0b100 | +| SKIP_UNMATCHED_DST | Ignore the model if it only exists in the target/"to" adapter when determining diffs and syncing. If this flag is set, the model will not be deleted from the target/"to" adapter. | 0b1000 | | SKIP_UNMATCHED_BOTH | Convenience value combining both SKIP_UNMATCHED_SRC and SKIP_UNMATCHED_DST into a single flag | 0b1100 | | NATURAL_DELETION_ORDER | When deleting, delete children before instances of this model. | 0b10000 | diff --git a/docs/source/core_engine/03-store.md b/docs/source/core_engine/03-store.md index a3cb6905..2afe963a 100644 --- a/docs/source/core_engine/03-store.md +++ b/docs/source/core_engine/03-store.md @@ -6,7 +6,7 @@ The `store` is a class attribute in the `Adapter` class, but all the store opera ## Use the `LocalStore` Backend -When you initialize the `Diffsync` Adapter class, there is an optional keyed-argument, `internal_storage_engine`, defaulting to the `LocalStore` class. +When you initialize the `Adapter` class, there is an optional keyed-argument, `internal_storage_engine`, defaulting to the `LocalStore` class. ```python >> > from diffsync import Adapter diff --git a/docs/source/getting_started/01-getting-started.md b/docs/source/getting_started/01-getting-started.md index 3696dd73..d6bc2b5f 100644 --- a/docs/source/getting_started/01-getting-started.md +++ b/docs/source/getting_started/01-getting-started.md @@ -97,7 +97,7 @@ class Cable(DiffSyncModel): [...] -class Nautobot(DiffSync): +class Nautobot(Adapter): site = Site device = Device interface = Interface @@ -121,7 +121,7 @@ Would result in processing in the following order for each element until there i - ip_address - cable -> Note: This applies to the actual diff sync (`Diffsync.sync_from/Diffsync.sync_to`), and not the loading of the data (`Diffsync.load`), which is up to the developer to determine the order. +> Note: This applies to the actual diff sync (`Adapter.sync_from` and `Adapter.sync_to`), and not the loading of the data (`Adapter.load`), which is up to the developer to determine the order. This can be visualized here in the included diagram. @@ -129,7 +129,7 @@ This can be visualized here in the included diagram. ### Mapping Tree Traversal with `get_tree_traversal` method -For your convenience, there is a helper method that will provide a mapping of the order. The `DiffSync.get_tree_traversal()` class method will return a tree-like string, or optionally a dictionary when passing the `as_dict=True` parameter. +For your convenience, there is a helper method that will provide a mapping of the order. The `Adapter.get_tree_traversal()` class method will return a tree-like string, or optionally a dictionary when passing the `as_dict=True` parameter. ```python >>> from nautobot_device_onboarding.network_importer.adapters.network_device.adapter import NetworkImporterAdapter @@ -150,7 +150,7 @@ NetworkImporterAdapter To add a site to the local cache/store, you need to pass a valid `DiffSyncModel` object to the `add()` function. ```python -class BackendA(DiffSync): +class BackendA(Adapter): [...] def load(self): @@ -203,14 +203,14 @@ class Device(DiffSyncModel): If you prefer to update the entire remote system with the final state after performing all individual create/update/delete operations (as might be the case if your "remote system" is a single YAML or JSON file), the easiest place to implement this logic is in the `sync_complete()` callback method that is automatically invoked by DiffSync upon completion of a sync operation. ```python -class BackendA(DiffSync): +class BackendA(Adapter): [...] - def sync_complete(self, source: DiffSync, diff: Diff, flags: DiffSyncFlags, logger: structlog.BoundLogger): + def sync_complete(self, source: Adapter, diff: Diff, flags: DiffSyncFlags, logger: structlog.BoundLogger): ## TODO add your own logic to update the remote system now. # The various parameters passed to this method are for your convenience in implementing more complex logic, and # can be ignored if you do not need them. # - # The default DiffSync.sync_complete() method does nothing, but it's always a good habit to call super(): + # The default Adapter.sync_complete() method does nothing, but it's always a good habit to call super(): super().sync_complete(source, diff, flags, logger) ``` From 81f174d73d03df06ef7e69455410fba872f3b49d Mon Sep 17 00:00:00 2001 From: corubba Date: Mon, 24 Jun 2024 15:08:08 +0200 Subject: [PATCH 4/9] Fix miss-capitalization It is stylized using Pascal case: DiffSync --- README.md | 6 +++--- docs/source/core_engine/03-store.md | 2 +- docs/source/upgrading/01-upgrading-to-2.0.md | 4 ++-- examples/03-remote-system/README.md | 2 +- examples/05-nautobot-peeringdb/adapter_nautobot.py | 2 +- examples/05-nautobot-peeringdb/adapter_peeringdb.py | 2 +- 6 files changed, 9 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 61eec471..62a3c987 100644 --- a/README.md +++ b/README.md @@ -17,16 +17,16 @@ DiffSync is at its most useful when you have multiple sources or sets of data to 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. -![Diffsync Components](https://raw.githubusercontent.com/networktocode/diffsync/develop/docs/images/diffsync_components.png "Diffsync Components") +![DiffSync Components](https://raw.githubusercontent.com/networktocode/diffsync/develop/docs/images/diffsync_components.png "DiffSync Components") Once you have used each adapter to load each data source into a collection of data model records, you can then ask DiffSync to “diff” the two data sets, and it will produce a structured representation of the difference between them. In Python, this is accomplished by calling the `diff_to()` or `diff_from()` method on one adapter and passing the other adapter as a parameter. -![Diffsync Diff Creation](https://raw.githubusercontent.com/networktocode/diffsync/develop/docs/images/diffsync_diff_creation.png "Diffsync Diff Creation") +![DiffSync Diff Creation](https://raw.githubusercontent.com/networktocode/diffsync/develop/docs/images/diffsync_diff_creation.png "DiffSync Diff Creation") You can also ask DiffSync to “sync” one data set onto the other, and it will instruct your adapter as to the steps it needs to take to make sure that its data set accurately reflects the other. In Python, this is accomplished by calling the `sync_to()` or `sync_from()` method on one adapter and passing the other adapter as a parameter. -![Diffsync Sync](https://raw.githubusercontent.com/networktocode/diffsync/develop/docs/images/diffsync_sync.png "Diffsync Sync") +![DiffSync Sync](https://raw.githubusercontent.com/networktocode/diffsync/develop/docs/images/diffsync_sync.png "DiffSync Sync") # Simple Example diff --git a/docs/source/core_engine/03-store.md b/docs/source/core_engine/03-store.md index 2afe963a..31e0d476 100644 --- a/docs/source/core_engine/03-store.md +++ b/docs/source/core_engine/03-store.md @@ -1,6 +1,6 @@ # Store backends -By default, `Diffsync` supports a local memory storage. All the loaded models from the adapters will be stored in memory, and become available for the diff calculation and sync process. This default behavior works well when executing all the steps in the same process, having access to the same memory space. However, if you want to scale out the execution of the tasks, running it in different processes or in totally different workers, a more distributed memory support is necessary. +By default, DiffSync supports a local memory storage. All the loaded models from the adapters will be stored in memory, and become available for the diff calculation and sync process. This default behavior works well when executing all the steps in the same process, having access to the same memory space. However, if you want to scale out the execution of the tasks, running it in different processes or in totally different workers, a more distributed memory support is necessary. The `store` is a class attribute in the `Adapter` class, but all the store operations in that class are abstracted in the following methods: `get_all_model_names`, `get`, `get_by_uids`, `add`, `update`, `remove`, `get_or_instantiate`, `update_or_instantiate` and `count`. diff --git a/docs/source/upgrading/01-upgrading-to-2.0.md b/docs/source/upgrading/01-upgrading-to-2.0.md index 34c7bfef..f2bc7efe 100644 --- a/docs/source/upgrading/01-upgrading-to-2.0.md +++ b/docs/source/upgrading/01-upgrading-to-2.0.md @@ -2,9 +2,9 @@ With diffsync 2.0, there a couple of breaking changes. What they are and how to deal with them is described in this document. -## Rename of the `diffsync.Diffsync` class to `diffsync.Adapter` +## Rename of the `diffsync.DiffSync` class to `diffsync.Adapter` -The main diffsync class `diffsync.Diffsync` has been renamed to `diffsync.Adapter` as we have found that this is the verbiage that is most often used by users and explains the intent of the class clearer. The old name will still be around until 2.1, but is considered deprecated at this point. +The main diffsync class `diffsync.DiffSync` has been renamed to `diffsync.Adapter` as we have found that this is the verbiage that is most often used by users and explains the intent of the class clearer. The old name will still be around until 2.1, but is considered deprecated at this point. As a consequence, a lot of fields have been renamed all across diffsync. To the end user, this will most prominently appear in the signature of the `create` method, where you will have to rename the `diffsync` parameter to `adapter`. diff --git a/examples/03-remote-system/README.md b/examples/03-remote-system/README.md index 102b00e9..eaff7141 100644 --- a/examples/03-remote-system/README.md +++ b/examples/03-remote-system/README.md @@ -34,7 +34,7 @@ export NAUTOBOT_TOKEN = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" The first time you run this example, a lot of changes should be reported between Nautobot and the local data because by default the demo instance doesn't have the subregion defined. After the first sync, on subsequent runs, the diff should show no changes. -At this point, `Diffsync` will be able to identify and fix all changes in Nautobot. You can try to add/update or delete any country in Nautobot and DiffSync will automatically catch it and it will fix it with running in sync mode. +At this point, DiffSync will be able to identify and fix all changes in Nautobot. You can try to add/update or delete any country in Nautobot and DiffSync will automatically catch it and it will fix it with running in sync mode. ``` ### DIFF Compare the data between Nautobot and the local JSON file. diff --git a/examples/05-nautobot-peeringdb/adapter_nautobot.py b/examples/05-nautobot-peeringdb/adapter_nautobot.py index 51b6f8af..13bcb574 100644 --- a/examples/05-nautobot-peeringdb/adapter_nautobot.py +++ b/examples/05-nautobot-peeringdb/adapter_nautobot.py @@ -1,4 +1,4 @@ -"""Diffsync adapter class for Nautobot.""" +"""DiffSync adapter class for Nautobot.""" # pylint: disable=import-error,no-name-in-module import pynautobot from models import RegionModel, SiteModel diff --git a/examples/05-nautobot-peeringdb/adapter_peeringdb.py b/examples/05-nautobot-peeringdb/adapter_peeringdb.py index 91cdf6ae..6c3a1b22 100644 --- a/examples/05-nautobot-peeringdb/adapter_peeringdb.py +++ b/examples/05-nautobot-peeringdb/adapter_peeringdb.py @@ -1,4 +1,4 @@ -"""Diffsync adapter class for PeeringDB.""" +"""DiffSync adapter class for PeeringDB.""" # pylint: disable=import-error,no-name-in-module import os import requests From 4bae7b8c68a56e3e5cd741a640ed4ce5a573d366 Mon Sep 17 00:00:00 2001 From: Marek Zbroch Date: Wed, 26 Jun 2024 13:16:10 +0200 Subject: [PATCH 5/9] Documentation fix. --- docs/source/getting_started/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/getting_started/index.rst b/docs/source/getting_started/index.rst index 9f461ee2..8a07331b 100644 --- a/docs/source/getting_started/index.rst +++ b/docs/source/getting_started/index.rst @@ -1,5 +1,5 @@ ######### -Upgrading +Getting started ######### .. mdinclude:: 01-getting-started.md From abbf4a065233e04c37f6d3d035c910f042440544 Mon Sep 17 00:00:00 2001 From: James Harr Date: Wed, 17 Jul 2024 13:57:26 -0500 Subject: [PATCH 6/9] chore: Un-pin structlog so we can use 23.2.0, which gets rid of deprected utcnow() call --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index 9bff7760..d7158cc7 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -18,7 +18,7 @@ include = [ [tool.poetry.dependencies] python = ">=3.8,<4.0" pydantic = "^2.0.0" -structlog = ">= 20.1.0, < 23.0.0" +structlog = ">= 20.1.0" packaging = ">= 21.3, < 24.0" colorama = {version = "^0.4.3", optional = true} redis = {version = "^4.3", optional = true} From d4c159d28e70dd35650be63d2e6d9fe08627bfd5 Mon Sep 17 00:00:00 2001 From: James Harr Date: Wed, 17 Jul 2024 13:57:41 -0500 Subject: [PATCH 7/9] chore: poetry update structlog --- poetry.lock | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/poetry.lock b/poetry.lock index fc27a185..b50f5d3e 100644 --- a/poetry.lock +++ b/poetry.lock @@ -1,4 +1,4 @@ -# This file is automatically @generated by Poetry 1.7.1 and should not be changed by hand. +# This file is automatically @generated by Poetry 1.8.3 and should not be changed by hand. [[package]] name = "alabaster" @@ -1578,20 +1578,20 @@ pbr = ">=2.0.0,<2.1.0 || >2.1.0" [[package]] name = "structlog" -version = "22.3.0" +version = "24.4.0" description = "Structured Logging for Python" optional = false -python-versions = ">=3.7" +python-versions = ">=3.8" files = [ - {file = "structlog-22.3.0-py3-none-any.whl", hash = "sha256:b403f344f902b220648fa9f286a23c0cc5439a5844d271fec40562dbadbc70ad"}, - {file = "structlog-22.3.0.tar.gz", hash = "sha256:e7509391f215e4afb88b1b80fa3ea074be57a5a17d794bd436a5c949da023333"}, + {file = "structlog-24.4.0-py3-none-any.whl", hash = "sha256:597f61e80a91cc0749a9fd2a098ed76715a1c8a01f73e336b746504d1aad7610"}, + {file = "structlog-24.4.0.tar.gz", hash = "sha256:b27bfecede327a6d2da5fbc96bd859f114ecc398a6389d664f62085ee7ae6fc4"}, ] [package.extras] -dev = ["structlog[docs,tests,typing]"] -docs = ["furo", "myst-parser", "sphinx", "sphinx-notfound-page", "sphinxcontrib-mermaid", "twisted"] -tests = ["coverage[toml]", "freezegun (>=0.2.8)", "pretend", "pytest (>=6.0)", "pytest-asyncio (>=0.17)", "simplejson"] -typing = ["mypy", "rich", "twisted"] +dev = ["freezegun (>=0.2.8)", "mypy (>=1.4)", "pretend", "pytest (>=6.0)", "pytest-asyncio (>=0.17)", "rich", "simplejson", "twisted"] +docs = ["cogapp", "furo", "myst-parser", "sphinx", "sphinx-notfound-page", "sphinxcontrib-mermaid", "sphinxext-opengraph", "twisted"] +tests = ["freezegun (>=0.2.8)", "pretend", "pytest (>=6.0)", "pytest-asyncio (>=0.17)", "simplejson"] +typing = ["mypy (>=1.4)", "rich", "twisted"] [[package]] name = "toml" @@ -1839,4 +1839,4 @@ redis = ["redis"] [metadata] lock-version = "2.0" python-versions = ">=3.8,<4.0" -content-hash = "c94995e97cbb7d053c55eceff623439f1a88c480a4bfece682701b1692f108b2" +content-hash = "65e48f3039ab67da7e6325e2dcfee33b79537330d501f83b125d6ec1eb77279c" From 75c2d8f54a110434f6daf231f51d10a8ee5da275 Mon Sep 17 00:00:00 2001 From: Andrew Bates Date: Thu, 26 Sep 2024 12:15:21 -0700 Subject: [PATCH 8/9] DiffSync deprecation fix (#281) * DiffSync deprecation fix * Formatting --- diffsync/__init__.py | 11 +++-------- tests/unit/test_deprecation.py | 30 ++++++++++++++++++++++++++++++ 2 files changed, 33 insertions(+), 8 deletions(-) create mode 100644 tests/unit/test_deprecation.py diff --git a/diffsync/__init__.py b/diffsync/__init__.py index 788b8e64..db404eaa 100644 --- a/diffsync/__init__.py +++ b/diffsync/__init__.py @@ -28,7 +28,7 @@ Any, Set, ) -import warnings +from typing_extensions import deprecated from pydantic import ConfigDict, BaseModel, PrivateAttr import structlog # type: ignore @@ -894,15 +894,10 @@ def count(self, model: Union[StrType, "DiffSyncModel", Type["DiffSyncModel"], No return self.store.count(model=model) -def DiffSync(*args: Any, **kwargs: Any) -> Adapter: # noqa pylint: disable=invalid-name +@deprecated("'diffsync.DiffSync' is deprecated and will be removed with 2.1, use 'diffsync.Adapter' instead.") +class DiffSync(Adapter): """For backwards-compatibility, keep around the old name.""" - warnings.warn( - "'diffsync.DiffSync' is deprecated and will be removed with 2.1, use 'diffsync.Adapter' instead.", - DeprecationWarning, - ) - return Adapter(*args, **kwargs) - # DiffSyncModel references Adapter and Adapter references DiffSyncModel. Break the typing loop: DiffSyncModel.model_rebuild() diff --git a/tests/unit/test_deprecation.py b/tests/unit/test_deprecation.py new file mode 100644 index 00000000..c85345b3 --- /dev/null +++ b/tests/unit/test_deprecation.py @@ -0,0 +1,30 @@ +"""Unit tests for the DiffSync deprecation warning. + +Copyright (c) 2020-2024 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 + +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 pytest + +from diffsync import DiffSync + + +def test_diffsync_deprecation_warning(): + """Test that `DiffSync` causes a deprecation warning.""" + with pytest.deprecated_call(): + + class TestAdapter(DiffSync): # pylint:disable=missing-class-docstring + pass + + TestAdapter() From d82d5b0dec94c9aa4d4df229c52df5a2a823965a Mon Sep 17 00:00:00 2001 From: Leo Kirchner Date: Tue, 22 Oct 2024 07:21:49 +0200 Subject: [PATCH 9/9] prepares release 2.0.1 --- CHANGELOG.md | 15 +++++++++++++++ pyproject.toml | 2 +- 2 files changed, 16 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 84336999..1cc72176 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,21 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). +## [2.0.1] + +### Changed + +- #276 - Removed upper version boud for `structlog` dependency + +### Fixed + +- #281 - Properly deprecated `DiffSync` class name +- #273 - Properly capitalized `DiffSync` in documentation +- #273 - Removed more mentions of `DiffSync` in favor of `Adapter` +- #274 - Fixed doc section title for getting started +- #269 - Fixed wording for a couple of docstrings +- #265 - Fixed readthedocs build + ## [2.0.0] ### Changed diff --git a/pyproject.toml b/pyproject.toml index d7158cc7..5e10b44a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [tool.poetry] name = "diffsync" -version = "2.0.0" +version = "2.0.1" description = "Library to easily sync/diff/update 2 different data sources" authors = ["Network to Code, LLC "] license = "Apache-2.0"