Operations

Merge Update

Traditional dictionary updates are destructive to sub dictionaries, merge update on the other hand will add the two sub dictionaries together.

Merge

box_1 = Box(val={'important_key': 1}) 
box_2 = Box(val={'less_important_key': 2})

box_1.merge_update(box_2)

print(box_1)
# {'val': {'important_key': 1, 'less_important_key': 2}}

Traditional Update

box_1 = Box(val={'important_key': 1}) 
box_2 = Box(val={'less_important_key': 2})

box_1.update(box_2)

print(box_1)
# {'val': {'less_important_key': 2}}

Addition and Union

In Python 3.9 they will add the ability to update two dictionaries using the union operator |, but boxes can already do that!

Union

box_1 = Box(cast={'Scooby-Doo': True, 'Velma': True, 'Shaggy': True}, 
            props={'Mystery Machine': True})
box_2 = Box(props={}, set='Desert')

box_1 | box_2
# <Box: {'cast': {'Scooby-Doo': True, 'Velma': True, 'Shaggy': True}, 
#        'props': {}, 'set': 'Desert'}>

Box also supports in place union using |=

Addition

Addition uses the internal merge_update instead of the dictionary update

box_1 = Box(cast={'Scooby-Doo': True, 'Velma': True, 'Shaggy': True}, 
            props={'Mystery Machine': True})
box_2 = Box(props={}, set='Desert')

box_1 + box_2
# <Box: {'cast': {'Scooby-Doo': True, 'Velma': True, 'Shaggy': True}, 
#        'props': {'Mystery Machine': True}, 'set': 'Desert'}>

Box also supports in place addition using +=

Subtraction

box_1 = Box(cast={'Scooby-Doo': True, 'Velma': True, 'Shaggy': True}, 
            props={'Mystery Machine': True})
box_2 = Box(props={}, set='Desert')

box_1 - box_2
# <Box: {'cast': {'Scooby-Doo': True, 'Velma': True, 'Shaggy': True}, 
#        'props': {'Mystery Machine': True}}>

Notice that box doesn't delete the entire sub dictionary when a key matches, but like merge_update will do a recursive subtraction. So if something with the same key name exists lower, it them will be removed.

box_1 = Box(cast={'Scooby-Doo': True, 'Velma': True, 'Shaggy': True}, 
            props={'Mystery Machine': True})
box_2 = Box(props={'Mystery Machine': 'Fully Loaded'}, set='Desert')

box_1 - box_2
# <Box: {'cast': {'Scooby-Doo': True, 'Velma': True, 'Shaggy': True}}>