python-jsonstore 1.3.0

Basics

# by default JsonStore commits on every change unless in a transaction
store = JsonStore('config.json')
store.a_string = "something"
store.a_list = [1, 2, 3]
store.a_dictionary = {
  'dict-list': [{}],
  'ln(2)': 0.69314718056,
  'for-you': u"💐",
}

# you can use […] to set/get/delete string keys
store['some_key'] = "a value"
# the key is split on '.'s and works on dictionaries
del store['a_dictionary.dict-list']
store['a_dictionary.new_value'] = "old value"
#  you can also use the syntactic sugar for tuple keys (explicit lists work too)
assert store['a_dictionary', 'new_value'] == "old value"
# you can traverse lists too
assert store['a_list', -1] == 3
# you can use slices in lists
assert len(store['a_list', 1:]) == 2
del store['a_list', :2]
assert store.a_list == [3]

# deep copies are made when assigning values
my_list = ['fun']
store.a_list = my_list
assert store.a_list is not my_list
assert 'a_list' in store

# deep copies are also returned to avoid unsanitary changes being made
store.a_dictionary['new_value'] = "new value"  # won't update the store!
assert store.a_dictionary['new_value'] == "old value"
assert store.a_dictionary is not store.a_dictionary

# Appending to, extending a list
>>> store.list = [1, 2, 3]

# Because of the fact that .append won't modify the list in the actual file,
# but only a copy...
>>> store.list.append(4)
>>> store.list
[1, 2, 3]

# ... we need to rather use the += operator to append to a list.
>>> store.list += [4]
>>> store.list
[1, 2, 3, 4]

# Similarly, we can extend the list
>>> store.list += [5, 6]
>>> store.list
[1, 2, 3, 4, 5, 6]

Transactions

JsonStore objects can be used as context managers to provide transactions which are rolled back in the event of an exception. The transaction model is primitive; you can only nest transactions.

While a store is put into a transaction, it will not save changes to file until all of the transactions have been closed.

from jsonstore import JsonStore

# even with auto_commit=True, the file won't be saved until the last contexts has been closed
with JsonStore('config.json', indent=None, auto_commit=False) as store:
  self.value = 1

# the context manager will roll back changes made if an exception is raised
store = JsonStore('config.json', indent=None)
try:
  with store:
    store.value = "new"
    raise Exception
except Exception:
  pass
# here we see the value that was saved previously
assert store.value == 1