Simperium client library for Python (python3 port)
Add contributing guidelines
Update upstream repository url and publish to pypi
Remove pipenv support and update readme



You can also use your local clone with git send-email.


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 https://github.com/Simperium/simperium-python.

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 setup.py


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



Please send your comments, bug reports, feature requests, and patches to this public mailing list: ~swalladge/public-inbox@lists.sr.ht (archives).

#Getting Started

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

To get started, first log into https://simperium.com 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+https://github.com/Simperium/simperium-python.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('joe@example.com', '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
>>> api.todo.post(todo1_id,
                  {'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:

>>> api.todo.post(uuid.uuid4().hex,
                  {'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:

>>> api.todo.post(todo1_id, {'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.