Creating a client

The passed auth parameter is a requests authentication policy, allowing authenticating using whatever scheme fits you best.

By default, Kinto supports Firefox Accounts and Basic authentication policies.

from kinto_client import Client
credentials = ('alexis', 'p4ssw0rd')

client = Client(server_url='http://localhost:8888/v1',
                auth=credentials)

It is also possible to pass the bucket and the collection to the client at creation time, so that this value will be used by default.

client = Client(bucket="payments", collection="receipts", auth=auth)

Handling buckets

All operations are rooted in a bucket. It makes little sense for one application to handle multiple buckets at once (but it is possible). If no specific bucket name is provided, the “default” bucket is used.

from kinto_client import Client
credentials = ('alexis', 'p4ssw0rd')

client = Client(server_url='http://localhost:8888/v1',
                auth=credentials)
client.create_bucket('payments')
client.get_bucket('payments')

# It is also possible to manipulate bucket permissions (see later)
client.update_bucket('payments', permissions={})

Collections

A collection is where records are stored.

client.create_collection('receipts', bucket='payments')

# Or get an existing one.
client.get_collection('receipts', bucket='payments')

# To delete an existing collection.
client.delete_collection('receipts', bucket='payments')

Records

Records can be retrieved from and saved to collections.

A record is a dict with the “permissions” and “data” keys.

# You can pass a python dictionary to create the record
# bucket='default' can be omitted since it's the default value

client.create_record(data={'id': 1234, status: 'done', title: 'Todo #1'},
                     collection='todos', bucket='default')

# Retrieve all records.
record = client.get_records(collection='todos', bucket='default')

# Retrieve a specific record and update it.
record = client.get_record('89881454-e4e9-4ef0-99a9-404d95900352',
                           collection='todos', bucket='default')
client.update_record(record, collection='todos', bucket='default')

# Update multiple records at once.
client.update_records(records, collection='todos')

# It is also possible to delete records.
client.delete_record(id='89881454-e4e9-4ef0-99a9-404d95900352',
                     collection='todos')

Permissions

By default, authors will get read and write access to the manipulated objects. It is possible to change this behavior by passing a dict to the permissions parameter.

client.create_record(
    data={'foo': 'bar'},
    permissions={'read': ['group:groupid']},
    collection='todos')

Buckets, collections and records have permissions which can be edited. For instance to give access to “leplatrem” to a specific record, you would do:

record = client.get_record(1234, collection='todos', bucket='alexis')
record['permissions']['write'].append('leplatrem')
client.update_record(record)

# During creation, it is possible to pass the permissions dict.
client.create_record(data={'foo': 'bar'}, permissions={})

Overwriting existing objects

Most of the methods take a safe argument, which defaults to True. If set to True and a last_modified field is present in the passed data, then a check will be added to the requests to ensure the record wasn’t modified on the server side in the meantime.