Skip to main content

Library for Persistent key-value containers, compatible with Python dict.

Project description


Build Status Codecov Python 3.6

Base library for persistent key-value stores, 100% compatible with Python dict.

Stones image

The idea behind this project is to have a common interface for a multitude of persistent key-value stores, easy to use and extend, with some extra built-in features as bonus. Inspired from Datastore and MemDown.

It plays nice with Object Querying libraries like: JMESPath, or JSONPath RW, or ObjectPath.

Features and Limitations

  • the same API that you already know from Python dict
  • thread safe updates
  • excellent test coverage (>90%)
  • 1st limitation: the keys can only be bytes. They are converted from str to bytes for compatibility.
  • 2nd limitation: the values are actually also bytes, but a serializer (default is Pickle) converts the data structure into bytes
  • there are several serializers available: Pickle, JSON and optional: cbor2, msgpack. You can easily add your own serializer, please check the documentation below.
  • 3rd limitation: after the data was serialized, you have to continue using the same serializer. If for some reason, you want to switch the serializer, you can create a new Store with your new serializer and copy all the data from the old Store.
  • the Memory Store and LMDB are available by default. Other key-value Stores used to be implemented (DBM, LevelDB, Redis), but are not included anymore.


This project uses Python 3.6+ and pip. A virtual environment is strongly encouraged.

$ pip install stones


from stones import stone, LmdbStore

# Create a new persistent dictionary, backed by LMDB
stor = stone('my-db', LmdbStore, serialize='pickle')

# You can use it just like a normal Python dict,
# with the limitation that keys are bytes,
# and the values must be serializable
stor[b's'] = b'whatever'
stor[b'li'] = [True, False, None, -1]
stor[b'tu'] = ('Yes', 'No', 3)

b's' in stor
# True
# 3
# [b'li', b's', b'tu']
# [[True, False, None, -1], b'whatever', ('Yes', 'No', 3)]

# The data is decoded in place
-1 in stor[b'li']
# True
3 in stor[b'tu']
# True

del stor[b'li']
stor.get(b'li', False)
# False

# The data is persisted
del stor
# Re-create the store, using the same encoder
stor = stone('my-db', LmdbStore, serialize='pickle')

# 2
# [b's', b'tu']

More or less similar projects



  • MemDown - abstract LevelDown store for Node.js and browsers
  • AppStorage - LocalStorage for Node.js, auto syncing objects with JSON files
  • NeDB - embedded database for Node.js, nw.js, Electron and browsers
  • FortuneJS - database abstraction layer with a common interface for databases
  • PouchDB - pocket-sized database


MIT © Cristi Constantin.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

stones-0.1.4.tar.gz (10.1 kB view hashes)

Uploaded source

Built Distribution

stones-0.1.4-py3-none-any.whl (10.2 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page