$ pip install cliquet
More details about installation and storage backend is provided in a dedicated section <installation>
.
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 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
.
Note
Shortcut!
In order to bypass the installation and configuration of Redis required by the default storage, permission manager and cache, use the «in-memory» backend in development.ini
:
# development.ini
cliquet.cache_backend = cliquet.cache.memory
cliquet.storage_backend = cliquet.storage.memory
cliquet.permission_backend = cliquet.permission.memory
Now is a good time to install the Cliquet project locally:
$ pip install -e .
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
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 Cliquet python API !
Currently, if no authentication is set in settings <configuration-authentication>
, 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.
In order to define a resource, inherit from cliquet.resource.BaseResource
, in a subclass, in myproject/views.py
for example:
from cliquet import resource
@resource.register()
class Mushroom(resource.BaseResource):
# 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()
By doing that, a Mushroom resource API is now available at the /mushrooms/
endpoint.
It will accept a bunch of REST operations, as defined in the API section
<api-endpoints>
.
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 cliquet import resource
class MushroomSchema(resource.ResourceSchema):
name = colander.SchemaNode(colander.String())
@resource.register()
class Mushroom(resource.BaseResource):
mapping = MushroomSchema()
See configuration
to customize the application settings, such as authentication, storage or cache backends.
See the resource documentation <resource>
to specify custom URLs, schemaless resources, read-only fields, unicity constraints, record pre-processing...
cliquet.initialize
Cliquet is just a component! The application can still be built and extended using the full Pyramid ecosystem.
See the dedicated section <ecosystem>
for examples of Cliquet extensions.