diffsync.diff

Diff and DiffElement classes for DiffSync.

Copyright (c) 2020-2021 Network To Code, LLC info@networktocode.com

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

diffsync.diff.Diff

Diff Object, designed to store multiple DiffElement object and organize them in a group.

children = OrderedDefaultDict[StrType, Dict[StrType, DiffElement]](dict) instance-attribute

DefaultDict for storing DiffElement objects.

self.children[group][unique_id] == DiffElement(...)

__init__()

Initialize a new, empty Diff object.

__len__()

Total number of DiffElements stored herein.

add(element)

Add a new DiffElement to the changeset of this Diff.

Raises:

Type	Description
ObjectAlreadyExists	if an element of the same type and same name is already stored.

complete()

Method to call when this Diff has been fully populated with data and is "complete".

The default implementation does nothing, but a subclass could use this, for example, to save the completed Diff to a file or database record.

dict()

Build a dictionary representation of this Diff.

get_children()

Iterate over all child elements in all groups in self.children.

For each group of children, check if an order method is defined, Otherwise use the default method.

groups()

Get the list of all group keys in self.children.

has_diffs()

Indicate if at least one of the child elements contains some diff.

Returns:

Type	Description
bool	True if at least one child element contains some diff

order_children_default(children) classmethod

Default method to an Iterator for children.

Since children is already an OrderedDefaultDict, this method is not doing anything special.

str(indent=0)

Build a detailed string representation of this Diff and its child DiffElements.

summary()

Build a dict summary of this Diff and its child DiffElements.

diffsync.diff.DiffElement

DiffElement object, designed to represent a single item/object that may or may not have any diffs.

action property

Action, if any, that should be taken to remediate the diffs described by this element.

Returns:

Type	Description
Optional[StrType]	"create", "update", "delete", or None)

__eq__(other)

Logical equality of DiffElements.

Other comparison methods (gt, le, ge, etc.) are created by our use of the @total_ordering decorator.

__init__(obj_type, name, keys, source_name='source', dest_name='dest', diff_class=Diff)

Instantiate a DiffElement.

Parameters:

Name	Type	Description	Default
obj_type	StrType	Name of the object type being described, as in DiffSyncModel.get_type().	required
name	StrType	Human-readable name of the object being described, as in DiffSyncModel.get_shortname(). This name must be unique within the context of the Diff that is the direct parent of this DiffElement.	required
keys	Dict	Primary keys and values uniquely describing this object, as in DiffSyncModel.get_identifiers().	required
source_name	StrType	Name of the source DiffSync object	'source'
dest_name	StrType	Name of the destination DiffSync object	'dest'
diff_class	Type[Diff]	Diff or subclass thereof to use to calculate the diffs to use for synchronization	Diff

__len__()

Total number of DiffElements in this one, including itself.

__lt__(other)

Logical ordering of DiffElements.

Other comparison methods (gt, le, ge, etc.) are created by our use of the @total_ordering decorator.

__str__()

Basic string representation of a DiffElement.

add_attrs(source=None, dest=None)

Set additional attributes of a source and/or destination item that may result in diffs.

add_child(element)

Attach a child object of type DiffElement.

Childs are saved in a Diff object and are organized by type and name.

dict()

Build a dictionary representation of this DiffElement and its children.

get_attrs_diffs()

Get the dict of actual attribute diffs between source_attrs and dest_attrs.

Returns:

Type	Description
Dict[StrType, Dict[StrType, Any]]	Dictionary of the form {"-": {key1: <value>, key2: ...}, "+": {key1: <value>, key2: ...}},
Dict[StrType, Dict[StrType, Any]]	where the "-" or "+" dicts may be absent.

get_attrs_keys()

Get the list of shared attrs between source and dest, or the attrs of source or dest if only one is present.

• If source_attrs is not set, return the keys of dest_attrs
• If dest_attrs is not set, return the keys of source_attrs
• If both are defined, return the intersection of both keys

get_children()

Iterate over all child DiffElements of this one.

has_diffs(include_children=True)

Check whether this element (or optionally any of its children) has some diffs.

Parameters:

Name	Type	Description	Default
include_children	bool	If True, recursively check children for diffs as well.	True

str(indent=0)

Build a detailed string representation of this DiffElement and its children.

summary()

Build a summary of this DiffElement and its children.