graceful.resources package¶
graceful.resources.base module¶
-
class
graceful.resources.base.
BaseResource
¶ Base resouce class with core param and response functionality.
This base class handles resource responses, parameter deserialization, and validation of request included representations if serializer is defined.
All custom resource classes based on
BaseResource
accept additionalwith_context
keyword argument:class MyResource(BaseResource, with_context=True): ...
The
with_context
argument tells if resource modification methods (metods injected with mixins - list/create/update/etc.) should accept thecontext
argument in their signatures. For more details see Dealing with falcon context objects section of documentation. The default value forwith_context
class keyword argument isFalse
.Changed in version 0.3.0: Added the
with_context
keyword argument.-
static
__new__
(*args, **kwargs)¶ Do some sanity checks before resource instance initialization.
-
allowed_methods
()¶ Return list of allowed HTTP methods on this resource.
This is only for purpose of making resource description.
Returns: list – list of allowed HTTP method names (uppercase)
-
describe
(req=None, resp=None, **kwargs)¶ Describe API resource using resource introspection.
Additional description on derrived resource class can be added using keyword arguments and calling
super().decribe()
method call like following:class SomeResource(BaseResource): def describe(req, resp, **kwargs): return super().describe( req, resp, type='list', **kwargs )
Parameters: - req (falcon.Request) – request object
- resp (falcon.Response) – response object
- kwargs (dict) – dictionary of values created from resource url template
Returns: dict – dictionary with resource descritpion information
Changed in version 0.2.0: The req and resp parameters became optional to ease the implementation of application-level documentation generators.
-
make_body
(resp, params, meta, content)¶ Construct response body in
resp
object using JSON serialization.Parameters: - resp (falcon.Response) – response object where to include serialized body
- params (dict) – dictionary of parsed parameters
- meta (dict) – dictionary of metadata to be included in ‘meta’ section of response
- content (dict) – dictionary of response content (resource representation) to be included in ‘content’ section of response
Returns: None
-
on_options
(req, resp, **kwargs)¶ Respond with JSON formatted resource description on OPTIONS request.
Parameters: - req (falcon.Request) – Optional request object. Defaults to None.
- resp (falcon.Response) – Optional response object. Defaults to None.
- kwargs (dict) – Dictionary of values created by falcon from resource uri template.
Returns: None
Changed in version 0.2.0: Default
OPTIONS
responses includeAllow
header with list of allowed HTTP methods.
-
params
¶ Return dictionary of parameter definition objects.
-
require_meta_and_content
(content_handler, params, **kwargs)¶ Require ‘meta’ and ‘content’ dictionaries using proper hander.
Parameters: - content_handler (callable) – function that accepts
params, meta, **kwargs
argument and returns dictionary forcontent
response section - params (dict) – dictionary of parsed resource parameters
- kwargs (dict) – dictionary of values created from resource url template
Returns: tuple (meta, content) –
- two-tuple with dictionaries of
meta
and content
response sections
- content_handler (callable) – function that accepts
-
require_params
(req)¶ Require all defined parameters from request query string.
Raises
falcon.errors.HTTPMissingParam
exception if any of required parameters is missing andfalcon.errors.HTTPInvalidParam
if any of parameters could not be understood (wrong format).Parameters: req (falcon.Request) – request object
-
require_representation
(req)¶ Require raw representation dictionary from falcon request object.
This does not perform any field parsing or validation but only uses allowed content-encoding handler to decode content body.
Note
Currently only JSON is allowed as content type.
Parameters: req (falcon.Request) – request object Returns: dict – raw dictionary of representation supplied in request body
-
require_validated
(req, partial=False, bulk=False)¶ Require fully validated internal object dictionary.
Internal object dictionary creation is based on content-decoded representation retrieved from request body. Internal object validation is performed using resource serializer.
Parameters: - req (falcon.Request) – request object
- partial (bool) – set to True if partially complete representation is accepted (e.g. for patching instead of full update). Missing fields in representation will be skiped.
- bulk (bool) – set to True if request payload represents multiple resources instead of single one.
Returns: dict –
- dictionary of fields and values representing internal object.
Each value is a result of
field.from_representation
call.
-
serializer
= None¶
-
static
-
class
graceful.resources.base.
MetaResource
(name, bases, namespace, **kwargs)¶ Metaclass for handling parametrization with parameter objects.
-
static
__new__
(mcs, name, bases, namespace, **kwargs)¶ Create new class object instance and alter its namespace.
-
classmethod
__prepare__
(mcs, name, bases, **kwargs)¶ Prepare class namespace in a way that ensures order of attributes.
This needs to be an
OrderedDict
instance so_get_params()
method can construct params storage that preserves the same order of parameters as defined in code.Parameters: - bases – all base classes of created resource class
- namespace (dict) – namespace as dictionary of attributes
-
static
graceful.resources.generic module¶
-
class
graceful.resources.generic.
ListAPI
¶ Generic List API with resource serialization.
Generic resource that uses serializer for resource description, serialization and validation.
Allowed methods:
- GET: list multiple resource instances representations (handled
with
.list()
method handler)
-
describe
(req=None, resp=None, **kwargs)¶ Extend default endpoint description with serializer description.
-
on_get
(req, resp, **kwargs)¶ Respond on GET requests using
self.list()
handler.
- GET: list multiple resource instances representations (handled
with
-
class
graceful.resources.generic.
ListCreateAPI
¶ Generic List/Create API with resource serialization.
Generic resource that uses serializer for resource description, serialization and validation.
Allowed methods:
- GET: list multiple resource instances representations (handled
with
.list()
method handler) - POST: create new resource from representation provided in request body
(handled with
.create()
method handler) - PATCH: create multiple resources from list of representations provided
in request body (handled with
.create_bulk()
method handler.
-
create_bulk
(params, meta, **kwargs)¶ Create items in bulk by reusing existing
.create()
handler.Note
This is default create_bulk implementation that may not be safe to use in production environment depending on your implementation of
.create()
method handler.
-
on_patch
(req, resp, **kwargs)¶ Respond on PATCH requests using
self.create_bulk()
handler.
-
on_post
(req, resp, **kwargs)¶ Respond on POST requests using
self.create()
handler.
- GET: list multiple resource instances representations (handled
with
-
class
graceful.resources.generic.
ListResource
¶ Basic retrieval of resource instance lists without serialization.
This resource class is intended for endpoints that do not require automatic representation serialization and extensive field descriptions but still gives support for defining parameters as resource class attributes.
Example usage:
-
class
graceful.resources.generic.
PaginatedListAPI
¶ Generic List API with resource serialization and pagination.
Generic resource that uses serializer for resource description, serialization and validation.
Adds simple pagination to list of resources.
Allowed methods:
- GET: list multiple resource instances representations (handled
with
.list()
method handler)
- GET: list multiple resource instances representations (handled
with
-
class
graceful.resources.generic.
PaginatedListCreateAPI
¶ Generic List/Create API with resource serialization and pagination.
Generic resource that uses serializer for resource description, serialization and validation.
Adds simple pagination to list of resources.
Allowed methods:
- GET: list multiple resource instances representations (handled
with
.list()
method handler) - POST: create new resource from representation provided in request body
(handled with
.create()
method handler)
- GET: list multiple resource instances representations (handled
with
-
class
graceful.resources.generic.
Resource
¶ Basic retrieval of resource instance lists without serialization.
This resource class is intended for endpoints that do not require automatic representation serialization and extensive field descriptions but still gives support for defining parameters as resource class attributes.
Example usage:
-
class
graceful.resources.generic.
RetrieveAPI
¶ Generic Retrieve API with resource serialization.
Generic resource that uses serializer for resource description, serialization and validation.
Allowed methods:
- GET: retrieve resource representation (handled with
.retrieve()
method handler)
-
describe
(req=None, resp=None, **kwargs)¶ Extend default endpoint description with serializer description.
-
on_get
(req, resp, **kwargs)¶ Respond on GET requests using
self.retrieve()
handler.
-
serializer
= None¶
- GET: retrieve resource representation (handled with
-
class
graceful.resources.generic.
RetrieveUpdateAPI
¶ Generic Retrieve/Update API with resource serialization.
Generic resource that uses serializer for resource description, serialization and validation.
Allowed methods:
- GET: retrieve resource representation handled with
.retrieve()
method handler - PUT: update resource with representation provided in request body
(handled with
.update()
method handler)
-
on_put
(req, resp, **kwargs)¶ Respond on PUT requests using
self.update()
handler.
- GET: retrieve resource representation handled with
-
class
graceful.resources.generic.
RetrieveUpdateDeleteAPI
¶ Generic Retrieve/Update/Delete API with resource serialization.
Generic resource that uses serializer for resource description, serialization and validation.
Allowed methods:
- GET: retrieve resource representation (handled with
.retrieve()
method handler) - PUT: update resource with representation provided in request body
(handled with
.update()
method handler) - DELETE: delete resource (handled with
.delete()
method handler)
- GET: retrieve resource representation (handled with
graceful.resources.mixins module¶
-
class
graceful.resources.mixins.
BaseMixin
¶ Base mixin class.
-
handle
(handler, req, resp, **kwargs)¶ Handle given resource manipulation flow in consistent manner.
This mixin is intended to be used only as a base class in new flow mixin classes. It ensures that regardless of resource manunipulation semantics (retrieve, get, delete etc.) the flow is always the same:
- Decode and validate all request parameters from the query string
using
self.require_params()
method. - Use
self.require_meta_and_content()
method to constructmeta
andcontent
dictionaries that will be later used to create serialized response body. - Construct serialized response body using
self.body()
method.
Parameters: - handler (method) – resource manipulation method handler.
- req (falcon.Request) – request object instance.
- resp (falcon.Response) – response object instance to be modified.
- **kwargs – additional keyword arguments retrieved from url template.
Returns: Content dictionary (preferably resource representation).
- Decode and validate all request parameters from the query string
using
-
-
class
graceful.resources.mixins.
CreateBulkMixin
¶ Add default “bulk creation flow on PATCH” to any resource class.
-
create_bulk
(params, meta, **kwargs)¶ Create multiple resource instances and return their representation.
This is default multiple resource instances creation method. Value returned is the representation of multiple resource instances. It will be included in the ‘content’ section of response body.
Parameters: - params (dict) – dictionary of parsed parameters accordingly to definitions provided as resource class atributes.
- meta (dict) – dictionary of meta parameters anything added to this dict will will be later included in response ‘meta’ section. This can already prepopulated by method that calls this handler.
- kwargs (dict) – dictionary of values retrieved from the route url template by falcon. This is suggested way for providing resource identifiers.
Returns: value to be included in response ‘content’ section
-
on_patch
(req, resp, handler=None, **kwargs)¶ Respond on POST HTTP request assuming resource creation flow.
This request handler assumes that POST requests are associated with resource creation. Thus default flow for such requests is:
- Create new resource instances and prepare their representation by calling its bulk creation method handler.
- Set response status code to
201 Created
.
Note: this handler does not set
Location
header by default as it would be valid only for single resource creation.Parameters: - req (falcon.Request) – request object instance.
- resp (falcon.Response) – response object instance to be modified
- handler (method) – creation method handler to be called. Defaults
to
self.create
. - **kwargs – additional keyword arguments retrieved from url template.
-
-
class
graceful.resources.mixins.
CreateMixin
¶ Add default “creation flow on POST” to any resource class.
-
create
(params, meta, **kwargs)¶ Create new resource instance and return its representation.
This is default resource instance creation method. Value returned is the representation of single resource instance. It will be included in the ‘content’ section of response body.
Parameters: - params (dict) – dictionary of parsed parameters accordingly to definitions provided as resource class atributes.
- meta (dict) – dictionary of meta parameters anything added to this dict will will be later included in response ‘meta’ section. This can already prepopulated by method that calls this handler.
- kwargs (dict) – dictionary of values retrieved from route url template by falcon. This is suggested way for providing resource identifiers.
Returns: value to be included in response ‘content’ section
-
get_object_location
(obj)¶ Return location URI associated with given resource representation.
This handler is optional. Returned URI will be included as the value of
Location
header on POST responses.
-
on_post
(req, resp, handler=None, **kwargs)¶ Respond on POST HTTP request assuming resource creation flow.
This request handler assumes that POST requests are associated with resource creation. Thus default flow for such requests is:
- Create new resource instance and prepare its representation by calling its creation method handler.
- Try to retrieve URI of newly created object using
self.get_object_location()
. If it succeeds use that URI as the value ofLocation
header in response object instance. - Set response status code to
201 Created
.
Parameters: - req (falcon.Request) – request object instance.
- resp (falcon.Response) – response object instance to be modified
- handler (method) – creation method handler to be called. Defaults
to
self.create
. - **kwargs – additional keyword arguments retrieved from url template.
-
-
class
graceful.resources.mixins.
DeleteMixin
¶ Add default “delete flow on DELETE” to any resource class.
-
delete
(params, meta, **kwargs)¶ Delete existing resource instance.
Parameters: - params (dict) – dictionary of parsed parameters accordingly to definitions provided as resource class atributes.
- meta (dict) – dictionary of meta parameters anything added to this dict will will be later included in response ‘meta’ section. This can already prepopulated by method that calls this handler.
- **kwargs – dictionary of values retrieved from route url template by falcon. This is suggested way for providing resource identifiers.
Returns: value to be included in response ‘content’ section
-
on_delete
(req, resp, handler=None, **kwargs)¶ Respond on DELETE HTTP request assuming resource deletion flow.
This request handler assumes that DELETE requests are associated with resource deletion. Thus default flow for such requests is:
- Delete existing resource instance.
- Set response status code to
202 Accepted
.
Parameters: - req (falcon.Request) – request object instance.
- resp (falcon.Response) – response object instance to be modified
- handler (method) – deletion method handler to be called. Defaults
to
self.delete
. - **kwargs – additional keyword arguments retrieved from url template.
-
-
class
graceful.resources.mixins.
ListMixin
¶ Add default “list flow on GET” to any resource class.
-
list
(params, meta, **kwargs)¶ List existing resource instances and return their representations.
Value returned by this handler will be included in response ‘content’ section.
Parameters: - params (dict) – dictionary of parsed parameters accordingly to definitions provided as resource class atributes.
- meta (dict) – dictionary of meta parameters anything added to this dict will will be later included in response ‘meta’ section. This can already prepopulated by method that calls this handler.
- **kwargs – dictionary of values retrieved from route url template by falcon. This is suggested way for providing resource identifiers.
Returns: value to be included in response ‘content’ section
-
on_get
(req, resp, handler=None, **kwargs)¶ Respond on GET HTTP request assuming resource list retrieval flow.
This request handler assumes that GET requests are associated with resource list retrieval. Thus default flow for such requests is:
- Retrieve list of existing resource instances and prepare their representations by calling list retrieval method handler.
Parameters: - req (falcon.Request) – request object instance.
- resp (falcon.Response) – response object instance to be modified
- handler (method) – list method handler to be called. Defaults
to
self.list
. - **kwargs – additional keyword arguments retrieved from url template.
-
-
class
graceful.resources.mixins.
PaginatedMixin
¶ Add simple pagination capabilities to resource.
This class provides two additional parameters with some default descriptions and
add_pagination_meta
method that can update meta with more useful pagination information.Example usage:
from graceful.resources.mixins import PaginatedMixin from graceful.resources.generic import ListResource class SomeResource(PaginatedMixin, ListResource): def list(self, params, meta): # params has now 'page' and 'page_size' params that # can be used for offset&limit-like operations self.add_pagination_meta(params, meta) # ...
-
add_pagination_meta
(params, meta)¶ Extend default meta dictionary value with pagination hints.
Note
This method handler attaches values to
meta
dictionary without changing it’s reference. This means that you should never replacemeta
dictionary with any other dict instance but simply modify its content.Parameters: - params (dict) – dictionary of decoded parameter values
- meta (dict) – dictionary of meta values attached to response
-
-
class
graceful.resources.mixins.
RetrieveMixin
¶ Add default “retrieve flow on GET” to any resource class.
-
on_get
(req, resp, handler=None, **kwargs)¶ Respond on GET HTTP request assuming resource retrieval flow.
This request handler assumes that GET requests are associated with single resource instance retrieval. Thus default flow for such requests is:
- Retrieve single resource instance of prepare its representation by calling retrieve method handler.
Parameters: - req (falcon.Request) – request object instance.
- resp (falcon.Response) – response object instance to be modified
- handler (method) – list method handler to be called. Defaults
to
self.list
. - **kwargs – additional keyword arguments retrieved from url template.
-
retrieve
(params, meta, **kwargs)¶ Retrieve existing resource instance and return its representation.
Value returned by this handler will be included in response ‘content’ section.
Parameters: - params (dict) – dictionary of parsed parameters accordingly to definitions provided as resource class atributes.
- meta (dict) – dictionary of meta parameters anything added to this dict will will be later included in response ‘meta’ section. This can already prepopulated by method that calls this handler.
- **kwargs – dictionary of values retrieved from route url template by falcon. This is suggested way for providing resource identifiers.
Returns: value to be included in response ‘content’ section
-
-
class
graceful.resources.mixins.
UpdateMixin
¶ Add default “update flow on PUT” to any resource class.
-
on_put
(req, resp, handler=None, **kwargs)¶ Respond on PUT HTTP request assuming resource update flow.
This request handler assumes that PUT requests are associated with resource update/modification. Thus default flow for such requests is:
- Modify existing resource instance and prepare its representation by calling its update method handler.
- Set response status code to
202 Accepted
.
Parameters: - req (falcon.Request) – request object instance.
- resp (falcon.Response) – response object instance to be modified
- handler (method) – update method handler to be called. Defaults
to
self.update
. - **kwargs – additional keyword arguments retrieved from url template.
-
update
(params, meta, **kwargs)¶ Update existing resource instance and return its representation.
Value returned by this handler will be included in response ‘content’ section.
Parameters: - params (dict) – dictionary of parsed parameters accordingly to definitions provided as resource class atributes.
- meta (dict) – dictionary of meta parameters anything added to this dict will will be later included in response ‘meta’ section. This can already prepopulated by method that calls this handler.
- **kwargs – dictionary of values retrieved from route url template by falcon. This is suggested way for providing resource identifiers.
Returns: value to be included in response ‘content’ section
-