$ 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 <install>
.
As detailed in Pyramid documentation, create a minimal application, or use its scaffolding tool:
$ pcreate -s starter MyProject
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
.
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 <api-utilities>
).
The next steps will consist in building a custom application using Cornice <cornice>
or the Pyramid ecosystem.
But most likely, it will consist in defining REST resources using Kinto-Core's Python API !
Currently, if no authentication is set in settings <configuration-authentication>
, 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.
In order to define a resource, inherit from kinto.core.resource.UserResource
, in a subclass, in myproject/views.py
for example:
from kinto.core import resource
@resource.register()
class Mushroom(resource.UserResource):
# 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.
It is possible to validate records against a predefined schema, associated to the resource.
Currently, only Colander <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.UserResource):
schema = MushroomSchema
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.install_middlewares(app, settings)
See the resource documentation <resource>
to specify custom URLs, schemaless resources, read-only fields, record pre-processing...
kinto.core.initialize
Kinto-Core is just a component! The application can still be built and extended using the full Pyramid ecosystem.