Getting started¶
Installation¶
$ 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
Include Cliquet¶
In the application main file (e.g. MyProject/myproject/__init__.py
),
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
in myproject.ini
.
Run!¶
With some backends, like PostgreSQL, some tables and indices have to be created. A generic command is provided to accomplish this:
$ cliquet --ini myproject.ini migrate
Like any Pyramid application, it can be served locally with:
$ pserve myproject.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 Cliquet python API !
Authentication¶
Currently, if no authentication is set in settings, Cliquet 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 cliquet.resource.UserResource
,
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 myproject.ini
:
# myproject.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 /mushrooms/
URL.
It will accept a bunch of REST operations, as defined in the API section.
Warning
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.
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 cliquet import resource
class MushroomSchema(resource.ResourceSchema):
name = colander.SchemaNode(colander.String())
@resource.register()
class Mushroom(resource.UserResource):
mapping = MushroomSchema()
What’s next ?¶
Configuration¶
See Configuration to customize the application settings, such as authentication, storage or cache backends.
Resource customization¶
See the resource documentation to specify custom URLs, schemaless resources, read-only fields, unicity constraints, record pre-processing...
Advanced initialization¶
-
cliquet.
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.
Parameters: - 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.
Beyond Cliquet¶
Cliquet is just a component! The application can still be built and extended using the full Pyramid ecosystem.
See the dedicated section for examples of Cliquet extensions.