Kinto client
Project description
Kinto is a service that allows to store and synchronize arbitrary data, attached to a user account. Its primary interface is HTTP.
kinto-client is a Python library that eases the interactions with a Kinto server instance. A project with related goals is also available for JavaScript.
Installation
Use pip:
$ pip install kinto-client
Usage
The first version of this API doesn’t cache any access nor provide any refresh mechanism. If you want to be sure you have the latest data available, issue another call.
Here is an overview of what the API provides:
from kinto_client import Client
client = Client(server_url="http://localhost:8888/v1",
auth=('alexis', 'p4ssw0rd'))
records = client.get_records(bucket='default', collection='todos')
for i, record in enumerate(records['data']):
record['title'] = 'Todo #%d' %i
for record in records:
client.update_record(record)
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={})
Get or create
In some cases, you might want to create a bucket, collection or record only if it doesn’t exist already. To do so, you can pass the if_not_exists=True to the create_* methods:
client.create_bucket('bucket', if_not_exists=True)
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.
Batching operations
Rather than issuing a request for each and every operation, it is possible to batch the requests. The client will then issue as little requests as possible.
Currently, batching operations only supports write operations, so it is not possible to do the retrieval of information inside a batch.
It is possible to do batch requests using a Python context manager (with):
with client.batch() as batch:
for idx in range(0,100):
batch.update_record(data={'id': idx})
A batch object shares the same methods as another client.
Retry on error
When the server is throttled (under heavy load or maintenance) it can return error responses.
The client can hence retry to send the same request until it succeeds. To enable this, specify the number of retries on the client:
client = Client(server_url='http://localhost:8888/v1',
auth=credentials,
retry=10)
The Kinto protocol lets the server define the duration in seconds between retries. It is possible (but not recommended) to force this value in the clients:
client = Client(server_url='http://localhost:8888/v1',
auth=credentials,
retry=10,
retry_after=5)
Command-line scripts
In order to have common arguments and options for scripts, some utilities are provided to ease configuration and initialization of client from command-line arguments.
import argparse
import logging
from kinto_client import cli_utils
logger = logging.getLogger(__name__)
if __name__ == "__main__":
parser = argparse.ArgumentParser(description="Download records")
cli_utils.set_parser_server_options(parser)
args = parser.parse_args()
cli_utils.setup_logger(logger, args)
logger.debug("Instantiate Kinto client.")
client = cli_utils.create_client_from_args(args)
logger.info("Fetch records.")
records = client.get_records()
logger.warn("%s records." % len(records))
The script now accepts basic options:
$ python example.py --help usage: example.py [-h] [-s SERVER] [-a AUTH] [-b BUCKET] [-c COLLECTION] [-v] [-q] [-D] Download records optional arguments: -h, --help show this help message and exit -s SERVER, --server SERVER The location of the remote server (with prefix) -a AUTH, --auth AUTH BasicAuth token:my-secret -b BUCKET, --bucket BUCKET Bucket name. -c COLLECTION, --collection COLLECTION Collection name. -v, --verbose Show all messages. -q, --quiet Show only critical errors. -D, --debug Show all messages, including debug messages.
Run tests
In one terminal, run a Kinto server:
$ make runkinto
In another, run the tests against it:
$ make tests
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for kinto_client-4.0.0-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 50baa1c29da0fc6955a0948eaec2e3f4723fd31a0c611a91914603de7ac1ae8f |
|
MD5 | 83d05c0be2cd4575f7e2db77196f2781 |
|
BLAKE2b-256 | c3ff1920353f1b3976ab3603439599e93db1b7e72f199b2f29112275ee064743 |