Getting started¶

Installation¶

$ pip install kinto

You can use Kinto-Core by doing import kinto.core in your application.

More details about installation and storage backend is provided in a dedicated section.

Start a Pyramid project¶

As detailed in Pyramid documentation, create a minimal application, or use its scaffolding tool:

$ pcreate -s starter MyProject

Include Kinto-Core¶

In the application main file (e.g. MyProject/myproject/__init__.py), just add some extra initialization code:

import pkg_resources

import kinto.core
from pyramid.config import Configurator

# Module version, as defined in PEP-0396.
__version__ = pkg_resources.get_distribution(__package__).version


def main(global_config, **settings):
    config = Configurator(settings=settings)

    kinto.core.initialize(config, __version__, 'myproject')
    return config.make_wsgi_app()

By doing that, basic features like authentication, monitoring, error formatting, deprecation indicators are now available, and rely on configuration present in development.ini.

Run!¶

With some backends, like PostgreSQL, some tables and indices have to be created. A generic command is provided to accomplish this:

$ kinto migrate --ini development.ini

Like any Pyramid application, it can be served locally with:

$ pserve development.ini --reload

A hello view is now available at http://localhost:6543/v0/ (As well as basic endpoints like the utilities).

The next steps will consist in building a custom application using Cornice or the Pyramid ecosystem.

But most likely, it will consist in defining REST resources using Kinto-Core‘s Python API !

Authentication¶

Currently, if no authentication is set in settings, Kinto-Core relies on Basic Auth. It will associate a unique user id for every user/password combination.

Using HTTPie, it is as easy as:

$ http -v http://localhost:6543/v0/ --auth user:pass

Note

In the case of Basic Auth, there is no need of registering a user/password. Pick any combination, and include them in each request.

Define resources¶

In order to define a resource, inherit from kinto.core.resource.Resource, in a subclass, in myproject/views.py for example:

from kinto.core import resource

@resource.register()
class Mushroom(resource.Resource):
    # No schema yet.
    pass

In application initialization, make Pyramid aware of it:

def main(global_config, **settings):
    config = Configurator(settings=settings)

    kinto.core.initialize(config, __version__, 'myproject')
    config.scan("myproject.views")
    return config.make_wsgi_app()

In order to bypass the installation and configuration of Redis or PostgreSQL, specify the «in-memory» backends in development.ini:

# development.ini
myproject.cache_backend = kinto.core.cache.memory
myproject.storage_backend = kinto.core.storage.memory
myproject.permission_backend = kinto.core.permission.memory

A Mushroom resource API is now available at the /mushrooms/ URL.

It will accept a bunch of REST operations (GET, POST, …).

The next step consists in attaching a schema to the resource, to control what fields are accepted and stored.

Schema validation¶

It is possible to validate records against a predefined schema, associated to the resource.

Currently, only Colander is supported, and it looks like this:

import colander
from kinto.core import resource


class MushroomSchema(resource.ResourceSchema):
    name = colander.SchemaNode(colander.String())

    class Options:
        preserve_unknown = False  # Fails if field is unknown!


@resource.register()
class Mushroom(resource.Resource):
    schema = MushroomSchema

Enable middleware¶

In order to enable WSGI middleware, wrap the application in the project main function:

def main(global_config, **settings):
    config = Configurator(settings=settings)

    kinto.core.initialize(config, __version__, 'myproject')
    config.scan("myproject.views")
    app = config.make_wsgi_app()
    return kinto.core.install_middlewares(app, settings)

What’s next ?¶

Resource customization¶

See the resource documentation to specify custom URLs, schemaless resources, read-only fields, record pre-processing…

Advanced initialization¶

kinto.core.initialize(config, version=None, settings_prefix='', default_settings=None)¶

Initialize kinto.core with the given configuration, version and project name.

This will basically include kinto.core in Pyramid and set route prefix based on the specified version.

Parameters

config (Configurator) – Pyramid configuration
version (str) – Current project version (e.g. ‘0.0.1’) if not defined in application settings.
settings_prefix (str) – Project name if not defined in application settings.
default_settings (dict) – Override kinto.core default settings values.

Beyond Kinto-Core¶

Kinto-Core is just a component! The application can still be built and extended using the full Pyramid ecosystem.