thcrdt 0.9.2

TangledHub Thcrdt Library

THCRDT

Overview

TangledHub library that handles Conflict-free Replicated Data types.

Licencing

thcrdt is licensed under the BSD license. Check the LICENSE for details.

---

Installation

pip install thcrdt

Testing

docker-compose build thcrdt-test ; docker-compose run --rm thcrdt-test

Building

docker-compose build thcrdt-builning ; docker-compose run --rm thcrdt-builning

Publish

docker-compose build thcrdt-publish ; docker-compose run --rm thcrdt-publish

---

CRDT supported in this library

CRDT_Dict

doc: dict = crdt.from_({'cards': [{'x': 0, 'y': 10, 'z': 20}]}).unwrap()

CRDT_List

doc: dict = crdt.from_({'cards': [[1, 2, 3]]}).unwrap()

CRDT_Counter

doc: dict = crdt.from_({'cards': [Counter(1)]}).unwrap()

increment(int)

Increase counter value

doc['cards'][0].increment(2)

decrement(int)

Decrease counter value

doc['cards'][0].decrement(1)

API

thcrdt api is using the thresult library, so all api functions are returning result wrapped in Ok or Err object.
Therefore, in order to reach into the result object, you should use .unwrap() as in examples.

crdt = CRDT()

crdt.from_(self, o: Any)

Creates a new CRDT object and populates it with the contents of the passed object

Example:

Create document with initial state

doc_s0: dict = crdt.from_({'cards': [{'x': 0}]}).unwrap()

crdt.clone(self, Any)

Creates a new copy of the CRDT instance

Example:

doc_clone = crdt.clone(doc_s0)

crdt.change(self, doc: Any, fn: Callable)

Modify an CRDT object, returning an updated copy

Example:

# CLIENT A
# changes on client A
def doc_ca(doc: dict):
    doc['cards'][0]['x'] = 5
    doc['cards'][0]['y'] = 10
    doc['cards'][0]['z'] = 20
    
# The doc_a0 object is treated as immutable, you must never change it directly, create doc_a0 clone using crdt.clone().
# In order to update doc_a0 you should use crdt.change() instead.
doc_a1: dict = crdt.change(crdt.clone(doc_s0).unwrap(), doc_ca).unwrap()

crdt.merge(self, a: Any, b: Any)

Example:

Merges the two CRDT instances

# CLIENT B
# Create initial document on client B
doc_b0: dict = crdt.from_({'cards': [{}]}).unwrap()

# Now merge this two documents
doc_b1: dict = crdt.merge(doc_b0, doc_a1).unwrap()

# changes on client B
def doc_cb(doc: dict):
    doc['cards'][0]['x'] = -5
    doc['cards'][0]['y'] = -10
    doc['cards'][0]['z'] = -20

doc_b2: dict = crdt.change(crdt.clone(doc_s0).unwrap(), doc_cb).unwrap()

# Now merge the changes from client B back into client A. You can also
# do the merge the other way round, and you'll get the same result.
final_doc: dict = crdt.merge(doc_b2, doc_a1).unwrap()

crdt.get_changes(self, root: Any, doc: Any)

Returns a list of all the changes that were made in the document

Example:

# Create document with initial state
doc1s: dict = crdt.from_({'cards': [{}]}).unwrap()

# CLIENT A
# changes on client A
def doc_ca(doc: dict):
    doc['cards'][0]['x'] = 5
    doc['cards'][0]['y'] = 10
    doc['cards'][0]['z'] = 20

# In order to update doc1s you should use crdt.change().
doc_a1: dict = crdt.change(crdt.clone(doc1s).unwrap(), doc_ca).unwrap()

# Get changes made on client A. These changes are encoded as byte arrays (Uint8Array)
doc_a1_changes: list = crdt.get_changes(doc1s, doc_a1).unwrap()

crdt.apply_changes

Applies the list of changes to the given document, and returns a new document with those changes applied

Example:

# CLIENT B
# Now apply changes on client B
doc_b1, patch = crdt.apply_changes(doc1s, doc_a1_changes).unwrap()