$ pip install cliquet
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
In the application main file (e.g.
just add some extra initialization code:
import pkg_resources import cliquet 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) cliquet.initialize(config, __version__) 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
With some backends, like PostgreSQL, some tables and indices have to be created. A generic command is provided to accomplish this:
$ cliquet --ini development.ini migrate
Like any Pyramid application, it can be served locally with:
$ pserve development.ini --reload
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 Cliquet python API !
Using HTTPie, it is as easy as:
$ http -v http://localhost:6543/v0/ --auth user:pass
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
in a subclass, in
myproject/views.py for example:
from cliquet 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) cliquet.initialize(config, __version__) 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 cliquet.cache_backend = cliquet.cache.memory cliquet.storage_backend = cliquet.storage.memory cliquet.permission_backend = cliquet.permission.memory
A Mushroom resource API is now available at the
It will accept a bunch of REST operations, as defined in the API section.
Without schema, a resource will not store any field at all!
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 is supported, and it looks like this:
import colander from cliquet import resource class MushroomSchema(resource.ResourceSchema): name = colander.SchemaNode(colander.String()) @resource.register() class Mushroom(resource.UserResource): mapping = MushroomSchema()
What’s next ?¶
See Configuration to customize the application settings, such as authentication, storage or cache backends.
See the resource documentation to specify custom URLs, schemaless resources, read-only fields, unicity constraints, record pre-processing...
initialize(config, version=None, project_name='', default_settings=None)¶
Initialize Cliquet with the given configuration, version and project name.
This will basically include cliquet in Pyramid and set route prefix based on the specified version.
- config (Configurator) – Pyramid configuration
- version (str) – Current project version (e.g. ‘0.0.1’) if not defined in application settings.
- project_name (str) – Project name if not defined in application settings.
- default_settings (dict) – Override cliquet default settings values.