Add add_or_update to DiffSync class.

[FragmentedPacket]

Fixes #50

• Adds add_or_update to DiffSync class that requires a DiffSyncModel to be passed in and will attempt to add or update an existing object
• Convert one of the examples over to use the new method
• Add test to validate proper functionality

[glennmatthews]

Thanks for the PR!

While this looks like an interesting feature I'm not sure it fully addresses #50. I think I'd like to see functionality for all of the following to be able to consider #50 as "done":

• Allow add()ing the same identical object repeatedly without it being considered an error condition. (No update() as part of this call, and in fact if the new object differs in any attrs from the previously added object, this should still raise ObjectAlreadyExists)
• get_or_create functionality, similar to Django's, that either retrieves a previously stored item (whose ids and attrs match the provided values) or instantiates and add()s a new item, then returns it. Probably would be useful to follow Django's example and have this function return a tuple (record, bool_created)
• update_or_create functionality to either find an existing object by ids and update with the provided attrs, or create a new object with the given ids and attrs, and in either case return the object. (Again, returning (record, bool_created) would be a good plan)

I'm also uncertain whether it's correct/desirable to call obj.update() as a part of any of the above APIs, versus directly just updating its attrs without making such a call - recall that obj.update() implies a change to be propagated/written to the underlying system or database, which should normally only happen as a result of a DiffSync.sync() call.

[FragmentedPacket]

@glennmatthews Do you mind reviewing my latest commits to make sure I'm on the right path?

[glennmatthews]

Great stuff!

[FragmentedPacket]

@dgarros Not sure if you want to review it before it gets merged in.

[dgarros]

LGTM, great work @FragmentedPacket and thanks helping with this one

One last change for me before merging
please. can you add a README.md in the new example directory (04-XX) and add a link to this readme file in the documentation > diffsync/docs/source/examples/index.rst

[FragmentedPacket]

@dgarros I completely forgot to even write any docs for this so thanks for catching that.

[FragmentedPacket]

Does this also address #73? Just want to make sure once this is merged, we can close it.

[dgarros]

Looks great, thanks @FragmentedPacket

[dgarros]

Does this also address #73? Just want to make sure once this is merged, we can close it.

I think it does

[dgarros]

I'll merge since Glenn already approved it