Resource¶
Kinto-Core provides a basic component to build resource oriented APIs. In most cases, the main customization consists in defining the schema of the records for this resource.
Full example¶
import colander
from kinto.core import resource
from kinto.core import utils
class BookmarkSchema(resource.ResourceSchema):
url = colander.SchemaNode(colander.String(), validator=colander.url)
title = colander.SchemaNode(colander.String())
favorite = colander.SchemaNode(colander.Boolean(), missing=False)
device = colander.SchemaNode(colander.String(), missing='')
class Options:
readonly_fields = ('device',)
@resource.register()
class Bookmark(resource.Resource):
schema = BookmarkSchema
def process_object(self, new, old=None):
new = super().process_object(new, old)
if new['device'] != old['device']:
new['device'] = self.request.headers.get('User-Agent')
return new
See the ReadingList and Kinto projects source code for real use cases.
URLs¶
By default, a resource defines two URLs:
/{classname}s
for the list of records/{classname}s/{id}
for single records
Since adding an s
suffix for the plural form might not always be relevant,
URLs can be specified during registration:
@resource.register(plural_path='/user/bookmarks',
object_path='/user/bookmarks/{{id}}')
class Bookmark(resource.Resource):
schema = BookmarkSchema
Note
The same resource can be registered with different URLs.
Schema¶
Override the base schema to add extra fields using the Colander API.
class Movie(resource.ResourceSchema):
director = colander.SchemaNode(colander.String())
year = colander.SchemaNode(colander.Int(),
validator=colander.Range(min=1850))
genre = colander.SchemaNode(colander.String(),
validator=colander.OneOf(['Sci-Fi', 'Comedy']))
See the resource schema options to define schema-less resources or specify rules like readonly fields.
HTTP methods and options¶
In order to specify which HTTP verbs (GET
, PUT
, PATCH
, …)
are allowed on the resource, as well as specific custom Pyramid (or Cornice)
view arguments, refer to the viewset section.
Events¶
When a record is created/deleted in a resource, an event is sent. See the dedicated section about notifications to plug events in your Pyramid/Kinto-Core application or plugin.
Model¶
Plug custom model¶
In order to customize the interaction of a HTTP resource with its storage, a custom model can be plugged-in:
from kinto.core import resource
class TrackedModel(resource.Model):
def create_record(self, record, parent_id=None):
record = super().create_record(record, parent_id)
trackid = index.track(record)
record['trackid'] = trackid
return record
class Payment(resource.Resource):
default_model = TrackedModel
Relationships¶
With the default model and storage backend, Kinto-Core does not support complex relations.
However, it is possible to plug a custom model class, that will take care of saving and retrieving records with relations.
Note
This part deserves more love, please come and discuss!
In Pyramid views¶
In Pyramid views, a request
object is available and allows to use the storage
configured in the application:
from kinto.core import resource
def view(request):
registry = request.registry
flowers = resource.Model(storage=registry.storage,
resource_name='app:flowers')
flowers.create_object({'name': 'Jonquille', 'size': 30})
flowers.create_object({'name': 'Amapola', 'size': 18})
min_size = resource.Filter('size', 20, resource.COMPARISON.MIN)
objects = flowers.get_objects(filters=[min_size])
flowers.delete_object(records[0])
Outside views¶
Outside views, an application context has to be built from scratch.
As an example, let’s build a code that will copy a collection into another:
from kinto.core import resource, DEFAULT_SETTINGS
from pyramid import Configurator
config = Configurator(settings=DEFAULT_SETTINGS)
config.add_settings({
'kinto.storage_backend': 'kinto.core.storage.postgresql'
'kinto.storage_url': 'postgresql://user:pass@db.server.lan:5432/dbname'
})
kinto.core.initialize(config, '0.0.1')
local = resource.Model(storage=config.registry.storage,
parent_id='browsing',
resource_name='history')
remote = resource.Model(storage=config_remote.registry.storage,
parent_id='',
resource_name='history')
records, total = in remote.get_records():
for record in records:
local.create_record(record)
Custom record ids¶
By default, records ids are UUID4.
A custom record ID generator can be set globally in Configuration, or at the resource level:
from kinto.core import resource
from kinto.core import utils
from kinto.core.storage import generators
class MsecId(generators.Generator):
def __call__(self):
return '%s' % utils.msec_time()
@resource.register()
class Mushroom(resource.Resource):
def __init__(request):
super().__init__(request)
self.model.id_generator = MsecId()
Python API¶
- kinto.core.resource.register(depth=1, **kwargs)¶
Ressource class decorator.
Register the decorated class in the cornice registry. Pass all its keyword arguments to the register_resource function.
Resource¶
- class kinto.core.resource.Resource(request, context=None)¶
Resource class providing every HTTP endpoint.
A resource provides all the necessary mechanism for: - storage and retrieval of objects according to HTTP verbs - permission checking and tracking - concurrency control - synchronization - OpenAPI metadata
Permissions are verified in
kinto.core.authorization.AuthorizationPolicy
based on the verb and context (eg. a put can create or update). The resulting context is passed in the context constructor parameter.- default_viewset¶
Default
kinto.core.resource.viewset.ViewSet
class to use when the resource is registered.alias of
ViewSet
- default_model¶
Default
kinto.core.resource.model.Model
class to use for interacting thekinto.core.storage
andkinto.core.permission
backends.alias of
Model
- schema¶
Schema to validate objects.
alias of
ResourceSchema
- permissions = ('read', 'write')¶
List of allowed permissions names.
- timestamp¶
Return the current resource timestamp.
- Return type
int
- object_id¶
Return the object id for this request. It’s either in the match dict or in the posted body.
- get_parent_id(request)¶
Return the parent_id of the resource with regards to the current request.
The resource will isolate the objects from one parent id to another. For example, in Kinto, the
group``s and ``collection``s are isolated by ``bucket
.In order to obtain a resource where users can only see their own objects, just return the user id as the parent id:
def get_parent_id(self, request): return request.prefixed_userid
- Parameters
request – The request used to access the resource.
- Return type
str
- is_known_field(field)¶
Return
True
if field is defined in the resource schema. If the resource schema allows unknown fields, this will always returnTrue
.- Parameters
field (str) – Field name
- Return type
bool
- plural_head()¶
Model
HEAD
endpoint: empty reponse with aTotal-Objects
header.- Raises
HTTPNotModified
ifIf-None-Match
header is provided and collection not modified in the interim.- Raises
HTTPPreconditionFailed
ifIf-Match
header is provided and collection modified in the iterim.- Raises
HTTPBadRequest
if filters or sorting are invalid.
- plural_get()¶
Model
GET
endpoint: retrieve multiple objects.- Raises
HTTPNotModified
ifIf-None-Match
header is provided and the objects not modified in the interim.- Raises
HTTPPreconditionFailed
ifIf-Match
header is provided and the objects modified in the iterim.- Raises
HTTPBadRequest
if filters or sorting are invalid.
- plural_post()¶
Model
POST
endpoint: create an object.If the new object id conflicts against an existing one, the posted object is ignored, and the existing object is returned, with a
200
status.- Raises
HTTPPreconditionFailed
ifIf-Match
header is provided and the objects modified in the iterim.
See also
Add custom behaviour by overriding
kinto.core.resource.Resource.process_object()
- plural_delete()¶
Model
DELETE
endpoint: delete multiple objects.- Raises
HTTPPreconditionFailed
ifIf-Match
header is provided and the objects modified in the iterim.- Raises
HTTPBadRequest
if filters are invalid.
- get()¶
Object
GET
endpoint: retrieve an object.- Raises
HTTPNotFound
if the object is not found.- Raises
HTTPNotModified
ifIf-None-Match
header is provided and object not modified in the interim.- Raises
HTTPPreconditionFailed
ifIf-Match
header is provided and object modified in the iterim.
- put()¶
Object
PUT
endpoint: create or replace the provided object and return it.- Raises
HTTPPreconditionFailed
ifIf-Match
header is provided and object modified in the iterim.
Note
If
If-None-Match: *
request header is provided, thePUT
will succeed only if no object exists with this id.See also
Add custom behaviour by overriding
kinto.core.resource.Resource.process_object()
.
- patch()¶
Object
PATCH
endpoint: modify an object and return its new version.If a request header
Response-Behavior
is set tolight
, only the fields whose value was changed are returned. If set todiff
, only the fields whose value became different than the one provided are returned.- Raises
HTTPNotFound
if the object is not found.- Raises
HTTPPreconditionFailed
ifIf-Match
header is provided and object modified in the iterim.
See also
Add custom behaviour by overriding
kinto.core.resource.Resource.apply_changes()
orkinto.core.resource.Resource.process_object()
.
- delete()¶
Object
DELETE
endpoint: delete an object and return it.- Raises
HTTPNotFound
if the object is not found.- Raises
HTTPPreconditionFailed
ifIf-Match
header is provided and object modified in the iterim.
- process_object(new, old=None)¶
Hook for processing objects before they reach storage, to introduce specific logics on fields for example.
def process_object(self, new, old=None): new = super().process_object(new, old) version = old['version'] if old else 0 new['version'] = version + 1 return new
Or add extra validation based on request:
from kinto.core.errors import raise_invalid def process_object(self, new, old=None): new = super().process_object(new, old) if new['browser'] not in request.headers['User-Agent']: raise_invalid(self.request, name='browser', error='Wrong') return new
- Parameters
new (dict) – the validated object to be created or updated.
old (dict) – the old object to be updated,
None
for creation endpoints.
- Returns
the processed object.
- Return type
dict
- apply_changes(obj, requested_changes)¶
Merge changes into object fields.
Note
This is used in the context of PATCH only.
Override this to control field changes at object level, for example:
def apply_changes(self, obj, requested_changes): # Ignore value change if inferior if object['position'] > changes.get('position', -1): changes.pop('position', None) return super().apply_changes(obj, requested_changes)
- Raises
HTTPBadRequest
if result does not comply with resource schema.- Returns
the new object with changes applied.
- Return type
tuple
Schema¶
- class kinto.core.resource.schema.TimeStamp(*args, **kw)¶
This schema is deprecated, you shoud use kinto.core.schema.TimeStamp instead.
- class kinto.core.resource.schema.URL(*args, **kw)¶
This schema is deprecated, you shoud use kinto.core.schema.URL instead.
- class kinto.core.resource.schema.ResourceSchema(*args, **kw)¶
Base resource schema, with Cliquet specific built-in options.
- class Options¶
Resource schema options.
This is meant to be overriden for changing values:
class Product(ResourceSchema): reference = colander.SchemaNode(colander.String()) class Options: readonly_fields = ('reference',)
- readonly_fields = ()¶
Fields that cannot be updated. Values for fields will have to be provided either during object creation, through default values using
missing
attribute or implementing a custom logic inkinto.core.resource.Resource.process_object()
.
- preserve_unknown = True¶
Define if unknown fields should be preserved or not.
The resource is schema-less by default. In other words, any field name will be accepted on objects. Set this to
False
in order to limit the accepted fields to the ones defined in the schema.
- classmethod is_readonly(field)¶
Return True if specified field name is read-only.
- Parameters
field (str) – the field name in the schema
- Returns
True
if the specified field is read-only,False
otherwise.- Return type
bool
- schema_type()¶
A type which represents a mapping of names to nodes.
The subnodes of the
colander.SchemaNode
that wraps this type imply the named keys and values in the mapping.The constructor of this type accepts one extra optional keyword argument that other types do not:
unknown
. An attribute of the same name can be set on a type instance to control the behavior after construction.- unknown
unknown
controls the behavior of this type when an unknown key is encountered in the cstruct passed to thedeserialize
method of this instance. All the potential values ofunknown
are strings. They are:ignore
means that keys that are not present in the schema associated with this type will be ignored during deserialization.raise
will cause acolander.Invalid
exception to be raised when unknown keys are present in the cstruct during deserialization.preserve
will preserve the ‘raw’ unknown keys and values in the appstruct returned by deserialization.
Default:
ignore
.
Special behavior is exhibited when a subvalue of a mapping is present in the schema but is missing from the mapping passed to either the
serialize
ordeserialize
method of this class. In this case, thecolander.null
value will be passed to theserialize
ordeserialize
method of the schema node representing the subvalue of the mapping respectively. During serialization, this will result in the behavior described in Serializing The Null Value for the subnode. During deserialization, this will result in the behavior described in Deserializing The Null Value for the subnode.If the
colander.null
value is passed to the serialize method of this class, a dictionary will be returned, where each of the values in the returned dictionary is the serialized representation of the null value for its type.
- class kinto.core.resource.schema.PermissionsSchema(*args, **kw)¶
A permission mapping defines ACEs.
It has permission names as keys and principals as values.
{ "write": ["fxa:af3e077eb9f5444a949ad65aa86e82ff"], "groups:create": ["fxa:70a9335eecfe440fa445ba752a750f3d"] }
- deserialize(cstruct=<colander.null>)¶
Deserialize the cstruct into an appstruct based on the schema, run this appstruct through the preparer, if one is present, then validate the prepared appstruct. The
cstruct
value is deserialized into anappstruct
unconditionally.If
appstruct
returned by type deserialization and preparation is the valuecolander.null
, do something special before attempting validation:If the
missing
attribute of this node has been set explicitly, return its value. No validation of this value is performed; it is simply returned.If the
missing
attribute of this node has not been set explicitly, raise acolander.Invalid
exception error.
If the appstruct is not
colander.null
and cannot be validated , acolander.Invalid
exception will be raised.If a
cstruct
argument is not explicitly provided, it defaults tocolander.null
.
- class kinto.core.resource.schema.HeaderSchema(*args, **kw)¶
Base schema used for validating and deserializing request headers.
- static schema_type()¶
A type which represents a mapping of names to nodes.
The subnodes of the
colander.SchemaNode
that wraps this type imply the named keys and values in the mapping.The constructor of this type accepts one extra optional keyword argument that other types do not:
unknown
. An attribute of the same name can be set on a type instance to control the behavior after construction.- unknown
unknown
controls the behavior of this type when an unknown key is encountered in the cstruct passed to thedeserialize
method of this instance. All the potential values ofunknown
are strings. They are:ignore
means that keys that are not present in the schema associated with this type will be ignored during deserialization.raise
will cause acolander.Invalid
exception to be raised when unknown keys are present in the cstruct during deserialization.preserve
will preserve the ‘raw’ unknown keys and values in the appstruct returned by deserialization.
Default:
ignore
.
Special behavior is exhibited when a subvalue of a mapping is present in the schema but is missing from the mapping passed to either the
serialize
ordeserialize
method of this class. In this case, thecolander.null
value will be passed to theserialize
ordeserialize
method of the schema node representing the subvalue of the mapping respectively. During serialization, this will result in the behavior described in Serializing The Null Value for the subnode. During deserialization, this will result in the behavior described in Deserializing The Null Value for the subnode.If the
colander.null
value is passed to the serialize method of this class, a dictionary will be returned, where each of the values in the returned dictionary is the serialized representation of the null value for its type.
- class kinto.core.resource.schema.PatchHeaderSchema(*args, **kw)¶
Header schema used with PATCH requests.
- class kinto.core.resource.schema.QuerySchema(*args, **kw)¶
Schema used for validating and deserializing querystrings. It will include and try to guess the type of unknown fields (field filters) on deserialization.
- static schema_type()¶
A type which represents a mapping of names to nodes.
The subnodes of the
colander.SchemaNode
that wraps this type imply the named keys and values in the mapping.The constructor of this type accepts one extra optional keyword argument that other types do not:
unknown
. An attribute of the same name can be set on a type instance to control the behavior after construction.- unknown
unknown
controls the behavior of this type when an unknown key is encountered in the cstruct passed to thedeserialize
method of this instance. All the potential values ofunknown
are strings. They are:ignore
means that keys that are not present in the schema associated with this type will be ignored during deserialization.raise
will cause acolander.Invalid
exception to be raised when unknown keys are present in the cstruct during deserialization.preserve
will preserve the ‘raw’ unknown keys and values in the appstruct returned by deserialization.
Default:
ignore
.
Special behavior is exhibited when a subvalue of a mapping is present in the schema but is missing from the mapping passed to either the
serialize
ordeserialize
method of this class. In this case, thecolander.null
value will be passed to theserialize
ordeserialize
method of the schema node representing the subvalue of the mapping respectively. During serialization, this will result in the behavior described in Serializing The Null Value for the subnode. During deserialization, this will result in the behavior described in Deserializing The Null Value for the subnode.If the
colander.null
value is passed to the serialize method of this class, a dictionary will be returned, where each of the values in the returned dictionary is the serialized representation of the null value for its type.
- deserialize(cstruct=<colander.null>)¶
Deserialize and validate the QuerySchema fields and try to deserialize and get the native value of additional filds (field filters) that may be present on the cstruct.
e.g:: ?exclude_id=a,b&deleted=true -> {‘exclude_id’: [‘a’, ‘b’], deleted: True}
- class kinto.core.resource.schema.PluralQuerySchema(*args, **kw)¶
Querystring schema used with plural endpoints.
- class kinto.core.resource.schema.ObjectGetQuerySchema(*args, **kw)¶
Querystring schema for GET object requests.
- class kinto.core.resource.schema.PluralGetQuerySchema(*args, **kw)¶
Querystring schema for GET plural endpoints requests.
- class kinto.core.resource.schema.ObjectSchema(*args, **kw)¶
- static schema_type()¶
A type which represents a mapping of names to nodes.
The subnodes of the
colander.SchemaNode
that wraps this type imply the named keys and values in the mapping.The constructor of this type accepts one extra optional keyword argument that other types do not:
unknown
. An attribute of the same name can be set on a type instance to control the behavior after construction.- unknown
unknown
controls the behavior of this type when an unknown key is encountered in the cstruct passed to thedeserialize
method of this instance. All the potential values ofunknown
are strings. They are:ignore
means that keys that are not present in the schema associated with this type will be ignored during deserialization.raise
will cause acolander.Invalid
exception to be raised when unknown keys are present in the cstruct during deserialization.preserve
will preserve the ‘raw’ unknown keys and values in the appstruct returned by deserialization.
Default:
ignore
.
Special behavior is exhibited when a subvalue of a mapping is present in the schema but is missing from the mapping passed to either the
serialize
ordeserialize
method of this class. In this case, thecolander.null
value will be passed to theserialize
ordeserialize
method of the schema node representing the subvalue of the mapping respectively. During serialization, this will result in the behavior described in Serializing The Null Value for the subnode. During deserialization, this will result in the behavior described in Deserializing The Null Value for the subnode.If the
colander.null
value is passed to the serialize method of this class, a dictionary will be returned, where each of the values in the returned dictionary is the serialized representation of the null value for its type.
- class kinto.core.resource.schema.JsonPatchOperationSchema(*args, **kw)¶
Single JSON Patch Operation.
- static schema_type()¶
A type which represents a mapping of names to nodes.
The subnodes of the
colander.SchemaNode
that wraps this type imply the named keys and values in the mapping.The constructor of this type accepts one extra optional keyword argument that other types do not:
unknown
. An attribute of the same name can be set on a type instance to control the behavior after construction.- unknown
unknown
controls the behavior of this type when an unknown key is encountered in the cstruct passed to thedeserialize
method of this instance. All the potential values ofunknown
are strings. They are:ignore
means that keys that are not present in the schema associated with this type will be ignored during deserialization.raise
will cause acolander.Invalid
exception to be raised when unknown keys are present in the cstruct during deserialization.preserve
will preserve the ‘raw’ unknown keys and values in the appstruct returned by deserialization.
Default:
ignore
.
Special behavior is exhibited when a subvalue of a mapping is present in the schema but is missing from the mapping passed to either the
serialize
ordeserialize
method of this class. In this case, thecolander.null
value will be passed to theserialize
ordeserialize
method of the schema node representing the subvalue of the mapping respectively. During serialization, this will result in the behavior described in Serializing The Null Value for the subnode. During deserialization, this will result in the behavior described in Deserializing The Null Value for the subnode.If the
colander.null
value is passed to the serialize method of this class, a dictionary will be returned, where each of the values in the returned dictionary is the serialized representation of the null value for its type.
- class kinto.core.resource.schema.JsonPatchBodySchema(*args, **kw)¶
Body used with JSON Patch (application/json-patch+json) as in RFC 6902.
- class kinto.core.resource.schema.RequestSchema(*args, **kw)¶
Base schema for kinto requests.
- class kinto.core.resource.schema.PayloadRequestSchema(*args, **kw)¶
Base schema for methods that use a JSON request body.
- class kinto.core.resource.schema.JsonPatchRequestSchema(*args, **kw)¶
JSON Patch (application/json-patch+json) request schema.
- class kinto.core.resource.schema.ResponseHeaderSchema(*args, **kw)¶
Kinto API custom response headers.
- class kinto.core.resource.schema.ErrorResponseSchema(*args, **kw)¶
Response schema used on 4xx and 5xx errors.
- class kinto.core.resource.schema.NotModifiedResponseSchema(*args, **kw)¶
Response schema used on 304 Not Modified responses.
- class kinto.core.resource.schema.ObjectResponseSchema(*args, **kw)¶
Response schema used with sigle resource endpoints.
- class kinto.core.resource.schema.PluralResponseSchema(*args, **kw)¶
Response schema used with plural endpoints.
Model¶
- class kinto.core.resource.model.Model(storage, permission, id_generator=None, resource_name='', parent_id='', current_principal=None, prefixed_principals=None, explicit_perm=True)¶
A resource stores and manipulate objects in its attached storage.
It is not aware of HTTP environment nor HTTP API.
Objects are isolated according to the provided name and parent_id.
Those notions have no particular semantic and can represent anything. For example, the resource name can be the type of objects stored, and parent_id can be the current user id or a group where the resource belongs. If left empty, the resource objects are not isolated.
- id_field = 'id'¶
Name of id field in objects
- modified_field = 'last_modified'¶
Name of last modified field in objects
- deleted_field = 'deleted'¶
Name of deleted field in deleted objects
- timestamp(parent_id=None)¶
Fetch the resource current timestamp.
- Parameters
parent_id (str) – optional filter for parent id
- Return type
int
- get_objects(filters=None, sorting=None, pagination_rules=None, limit=None, include_deleted=False, parent_id=None)¶
Fetch the resource objects.
Override to post-process objects after feching them from storage.
- Parameters
filters (list of
kinto.core.storage.Filter
) – Optionally filter the objects by their attribute. Each filter in this list is a tuple of a field, a value and a comparison (see kinto.core.utils.COMPARISON). All filters are combined using AND.sorting (list of
kinto.core.storage.Sort
) – Optionally sort the objects by attribute. Each sort instruction in this list refers to a field and a direction (negative means descending). All sort instructions are cumulative.pagination_rules (list of list of
kinto.core.storage.Filter
) – Optionally paginate the list of objects. This list of rules aims to reduce the set of objects to the current page. A rule is a list of filters (see filters parameter), and all rules are combined using OR.limit (int) – Optionally limit the number of objects to be retrieved.
include_deleted (bool) – Optionally include the deleted objects that match the filters.
parent_id (str) – optional filter for parent id
- Returns
A list of objects in the current page.
- Return type
list
- count_objects(filters=None, parent_id=None)¶
Fetch the total count of resource objects
Override to post-process objects after feching them from storage.
- Parameters
filters (list of
kinto.core.storage.Filter
) – Optionally filter the objects by their attribute. Each filter in this list is a tuple of a field, a value and a comparison (see kinto.core.utils.COMPARISON). All filters are combined using AND.parent_id (str) – optional filter for parent id
- Returns
An integer of the total number of objects in the result set.
- Return type
int
- delete_objects(filters=None, sorting=None, pagination_rules=None, limit=None, parent_id=None)¶
Delete multiple resource objects.
Override to post-process objects after their deletion from storage.
- Parameters
filters (list of
kinto.core.storage.Filter
) – Optionally filter the objects by their attribute. Each filter in this list is a tuple of a field, a value and a comparison (see kinto.core.utils.COMPARISON). All filters are combined using AND.sorting (list of
kinto.core.storage.Sort
) – Optionnally sort the objects by attribute. Each sort instruction in this list refers to a field and a direction (negative means descending). All sort instructions are cumulative.pagination_rules (list of list of
kinto.core.storage.Filter
) – Optionnally paginate the deletion of objects. This list of rules aims to reduce the set of objects to the current page. A rule is a list of filters (see filters parameter), and all rules are combined using OR.limit (int) – Optionnally limit the number of objects to be deleted.
parent_id (str) – optional filter for parent id
- Returns
The list of deleted objects from storage.
- get_object(object_id, parent_id=None)¶
Fetch current view related object, and raise 404 if missing.
- Parameters
object_id (str) – object identifier
parent_id (str) – optional filter for parent id
- Returns
the object from storage
- Return type
dict
- create_object(obj, parent_id=None)¶
Create an object in the resource.
The current principal is added to the owner (
write
permission).Override to perform actions or post-process objects after their creation in storage.
def create_object(self, obj): obj = super().create_object(obj) idx = index.store(obj) object['index'] = idx return object
- Parameters
obj (dict) – object to store
parent_id (str) – optional filter for parent id
- Returns
the newly created object.
- Return type
dict
- update_object(obj, parent_id=None)¶
Update object and the specified permissions.
If no permissions is specified, the current permissions are not modified.
The current principal is added to the owner (
write
permission).Override to perform actions or post-process objects after their modification in storage.
def update_object(self, obj, parent_id=None): obj = super().update_object(obj, parent_id) subject = f'Object {record[self.id_field]} was changed' send_email(subject) return object
- Parameters
obj (dict) – object to store
parent_id (str) – optional filter for parent id
- Returns
the updated object.
- Return type
dict
- delete_object(obj, parent_id=None, last_modified=None)¶
Delete an object and its associated permissions.
Override to perform actions or post-process objects after deletion from storage for example:
def delete_object(self, obj): deleted = super().delete_object(obj) erase_media(obj) deleted['media'] = 0 return deleted
- Parameters
obj (dict) – the object to delete
parent_id (str) – optional filter for parent id
- Returns
the deleted object.
- Return type
dict
Generators¶
- class kinto.core.storage.generators.Generator(config=None)¶
Base generator for objects ids.
Id generators are used by storage backend during object creation, and at resource level to validate object id in requests paths.
- regexp = '^[a-zA-Z0-9][a-zA-Z0-9_-]*$'¶
Default object id pattern. Can be changed to comply with custom ids.
- match(object_id)¶
Validate that object ids match the generator. This is used mainly when an object id is picked arbitrarily (e.g with
PUT
requests).- Returns
True if the specified object id matches expected format.
- Return type
bool
- class kinto.core.storage.generators.UUID4(config=None)¶
UUID4 object id generator.
UUID block are separated with
-
. (example:'472be9ec-26fe-461b-8282-9c4e4b207ab3'
)UUIDs are very safe in term of unicity. If 1 billion of UUIDs are generated every second for the next 100 years, the probability of creating just one duplicate would be about 50% (source).
- regexp = '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'¶
UUID4 accurate pattern.