This is a pre-production deployment of Warehouse, however changes made here WILL affect the production instance of PyPI.
Latest Version Dependencies status unknown Test status unknown Test coverage unknown
Project Description

Kinto is a service that allows users to store and synchronize arbitrary data, attached to a user account. Its primary interface is HTTP.

kinto-http 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-http

Usage

Note

Operations are always performed directly on the server, and no synchronisation features have been implemented yet.

  • The first version of this API doesn’t cache any access nor provides 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_http 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):
    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_http 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)

Getting server information

You can use the server_info method to get the server information:

from kinto_http import Client

client = Client(server_url='http://localhost:8888/v1')
info = client.server_info()
assert 'schema' in info['capabilities'], "Server doesn't support schema validation."

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_http 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={})

# Or delete a bucket and everything under.
client.delete_bucket('payment')

# Or even every writable buckets.
client.delete_buckets()

Groups

A group associates a name to a list of principals. It is useful in order to handle permissions.

client.create_group('receipts', bucket='payments', data={'members': ['blah', 'foo']})

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

# To delete an existing group.
client.delete_group('receipts', bucket='payments')

# Or all groups in a bucket.
client.delete_groups(bucket='payments')

Collections

A collection is where records are stored.

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

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

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

# Or every collections in a bucket.
client.delete_collections(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.
records = client.get_records(collection='todos', bucket='default')

# Retrieve records timestamp.
records_timestamp = client.get_records_timestamp(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 a record.
client.delete_record(id='89881454-e4e9-4ef0-99a9-404d95900352',
                     collection='todos')

# Or every records of a collection.
client.delete_records(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')

Note

Every creation or modification operation on a distant object can be given a permissions parameter.

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, group 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)

Delete

In some cases, you might want to delete a bucket, collection, group or record only if it exists already. To do so, you can pass the if_exists=True to the delete_* methods:

client.delete_bucket('bucket', if_exists=True)

Overwriting existing objects

Most of the methods take a safe argument, which defaults to True. If set to True and a if_match 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)

Generating endpoint paths

You may want to generate some endpoint paths, you can use the get_endpoint utility to do so:

client = Client(server_url='http://localhost:8888/v1',
                auth=('token', 'your-token'),
                bucket="payments",
                collection="receipts")
print(client.get_endpoint("record",
                          id="c6894b2c-1856-11e6-9415-3c970ede22b0"))

# '/buckets/payments/collections/receipts/records/c6894b2c-1856-11e6-9415-3c970ede22b0'

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_http 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
Release History

Release History

7.0.0

This version

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

6.2.1

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

6.1.0

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

6.0.0

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

Download Files

Download Files

TODO: Brief introduction on what you do with files - including link to relevant help section.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
kinto_http-7.0.0-py2.py3-none-any.whl (34.4 kB) Copy SHA256 Checksum SHA256 py2.py3 Wheel Sep 30, 2016
kinto-http-7.0.0.tar.gz (28.3 kB) Copy SHA256 Checksum SHA256 Source Sep 30, 2016

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS HPE HPE Development Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting