Skip to main content

Python 3 client for the Simperium synchronization platform

Project description


Simperium is a simple way for developers to move data as it changes, instantly and automatically. This is the Python library. You can browse the documentation.

You can sign up for a hosted version of Simperium. There are Simperium libraries for other languages too.

This is not yet a full Simperium library for parsing diffs and changes. It's a wrapper for our HTTP API intended for scripting and basic backend development.

About this fork

This is a Python 3 fork of

Ported and maintained by Samuel Walladge.

The following changes were done from the original python 2 version:

  • 2to3
  • use requests instead of urllib
  • don't catch any http errors; clients can handle that
  • add type hints
  • update


pip install Simperium3


Set up an environment and install the requirements:

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
pip install -r requirements-dev.txt

Check for code quality issues (formatting and type checking):

make lint

Run integration tests. Put the following in .env (with your actual client credentials; the api key must allow creating users):

export SIMPERIUM_CLIENT_TEST_APIKEY="<app api key>"


make test

Format all the code consistently:

make fmt


A bunch of examples are included in the examples/ directory. Run them like so:

python examples/simpletodo list app-name-123 myusertoken


Getting Started

Note: these instructions have not been updated for the python3 fork.

To get started, first log into and create a new application. Copy down the new app's name, api key and admin key.

Next install the python client:

$ sudo pip install git+

Start python and import the lib:

$ python
>>> from simperium.core import Auth, Api

We'll need to create a user to be able to store data:

>>> auth = Auth(yourappname, yourapikey)
>>> token = auth.create('', 'secret')
>>> token

We can now store and retrieve data from simperium. Data is stored in buckets. For example, we could store a list of todo items in a todo bucket. When you store items, you need to give them a unique identifier. Uuids are usually a good choice.

>>> import uuid
>>> api = Api(yourappname, token)
>>> todo1_id = uuid.uuid4().hex
                  {'text': 'Read general theory of love', 'done': False})

We can retrieve this item:

>>> api.todo.get(todo1_id)
{'text': 'Read general theory of love', 'done': False}

Store another todo:

                  {'text': 'Watch battle royale', 'done': False})

You can retrieve an index of all of a buckets items:

>>> api.todo.index()
    'count': 2,
    'index': [
        {'id': 'f6b680f8504c4e31a0e54a95401ffca0', 'v': 1},
        {'id': 'c0d07bb7c46e48e693653425eca93af9', 'v': 1}],
    'current': '4f8507b8faf44720dfc432b1',}

Retrieve all the docuemnts in the index:

>>> [api.todo.get(x['id']) for x in api.todo.index()['index']]
    {'text': 'Read general theory of love', 'done': False},
    {'text': 'Watch battle royale', 'done': False}]

It's also possible to get the data for each document in the index with data=True:

>>> api.todo.index(data=True)
    'count': 2,
    'index': [
        {'id': 'f6b680f8504c4e31a0e54a95401ffca0', 'v': 1,
            'd': {'text': 'Read general theory of love', 'done': False},},
        {'id': 'c0d07bb7c46e48e693653425eca93af9', 'v': 1,
            'd': {'text': 'Watch battle royale', 'done': False},}],
    'current': '4f8507b8faf44720dfc432b1'}

To update fields in an item, post the updated fields. They'll be merged with the current document:

>>>, {'done': True})
>>> api.todo.get(todo1_id)
{'text': 'Read general theory of love', 'done': True}

Simperium items are versioned. It's possible to go back in time and retrieve previous versions of documents:

>>> api.todo.get(todo1_id, version=1)
{'text': 'Read general theory of love', 'done': False}

Of course, you can delete items:

>>> api.todo.delete(todo1_id)
>>> api.todo.get(todo1_id) == None
>>> api.todo.index()['count']


The Simperium Python library is available for free and commercial use under the MIT license.

Project details

Download files

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

Files for Simperium3, version 0.1.5
Filename, size File type Python version Upload date Hashes
Filename, size Simperium3-0.1.5.tar.gz (11.4 kB) File type Source Python version None Upload date Hashes View
Filename, size Simperium3-0.1.5-py3-none-any.whl (12.0 kB) File type Wheel Python version py3 Upload date Hashes View

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