API¶
Resolvers¶
-
class
flask.ext.pushrod.
Pushrod
(app=None, renderers=('json', 'jinja2'), default_renderer='html')[source]¶ The main resolver class for Pushrod.
Parameters: renderers – A tuple of renderers that are registered immediately (can also be strings, which are currently expanded to flask.ext.pushrod.renderers.%s_renderer) -
app
= None¶ The current app, only set from the constructor, not if using
init_app()
.
-
format_arg_name
= 'format'¶ The query string argument checked for an explicit renderer (to override header-based content type negotiation).
Note
This is set on the class level, not the instance level.
-
get_renderers_for_request
(request=None)[source]¶ Inspects a Flask
Request
for hints regarding what renderer to use.This is found out by first looking in the query string argument named after
format_arg_name
(format
by default), and then matching the contents of the Accept:-header. If nothing is found anyway, thendefault_renderer
is used.Note
If the query string argument is specified but doesn’t exist (or fails), then the request fails immediately, without trying the other methods.
Parameters: request – The request to be inspected (defaults to flask.request
)Returns: List of matching renderers, in order of user preference
-
init_app
(app)[source]¶ Registers the Pushrod resolver with the Flask app (can also be done by passing the app to the constructor).
-
logger
¶ Gets the logger to use, mainly for internal use.
The current resolution order looks as follows:
-
mime_type_renderers
= None¶ The renderers keyed by MIME type.
-
named_renderers
= None¶ The renderers keyed by output format name (such as html).
-
normalize
(obj)[source]¶ Runs an object through the normalizer mechanism, with the goal of producing a value consisting only of “native types” (
unicode
,int
,long
,float
,dict
,list
, etc).The resolution order looks like this:
- Loop through
self.normalizer_overrides[type(obj)]
(taking parent classes into account), should be a callable taking (obj, pushrod), falls through onNotImplemented
self.normalizers[type(obj)]
(taking parent classes into account), should be a callable taking (obj, pushrod), falls through onNotImplemented
See Bundled Normalizers for all default normalizers.
Parameters: obj – The object to normalize. - Loop through
-
normalizer_overrides
= None¶ Hooks for overriding a class’ normalizer, even if they explicitly define one.
All items should be lists of callables. All values default to an empty list.
-
normalizers
= None¶ Hooks for providing a class with a fallback normalizer, which is called only if it doesn’t define one. All items should be callables.
-
register_renderer
(renderer, default=False)[source]¶ Registers a renderer with the Pushrod resolver (can also be done by passing the renderer to the constructor).
-
render_response
(response, renderer=None, renderer_kwargs=None)[source]¶ Renders an unrendered response (a bare value, a (response, status, headers)-
tuple
, or anUnrenderedResponse
object).Throws RendererNotFound: If a usable renderer could not be found (explicit renderer argument points to an invalid render, or no acceptable mime types can be used as targets and there is no default renderer)
Parameters: - response – The response to render
- renderer – The renderer(s) to use (defaults to using
get_renderer_for_request()
) - renderer_kwargs – Any extra arguments to pass to the renderer
Note
For convenience, a bare string (
unicode
,str
, or any otherbasestring
derivative), or a derivative ofwerkzeug.wrappers.BaseResponse
(such asflask.Response
) is passed through unchanged.Note
A renderer may mark itself as unable to render a specific response by returning
None
, in which case the next possible renderer is attempted.
-
Views¶
-
flask.ext.pushrod.
pushrod_view
(**renderer_kwargs)[source]¶ Decorator that wraps view functions and renders their responses through
flask.ext.pushrod.Pushrod.render_response()
.Note
Views should only return
dicts
or a type thatnormalizes
down todicts
.Parameters: renderer_kwargs – Any extra arguments to pass to the renderer
Renderers¶
-
flask.ext.pushrod.renderers.
renderer
(name=None, mime_type=None, normalize=True)[source]¶ Flags a function as a Pushrod renderer.
Note
Before it is recognized by
flask.ext.pushrod.Pushrod.get_renderers_for_request()
(and, by extension,render_response()
) it must be registered to the app’sPushrod
instance (usingregister_renderer()
, or passed as part of therenderers
argument to thePushrod
constructor).Parameters: - name – A
basestring
or a tuple of basestrings to match against when explicitly requested in the query string - mime_type – A
basestring
or a tuple of basestrings to match against against when using HTTP content negotiation - normalize – If True then the unrendered response will be passed through
flask.ext.pushrod.Pushrod.normalize()
- name – A
-
class
flask.ext.pushrod.renderers.
UnrenderedResponse
(response=None, status=None, headers=None)[source]¶ Holds basic response data from the view function until it is processed by the renderer.
-
rendered
(rendered_response, mime_type)[source]¶ Constructs a
rendered_class
(flask.Response
by default) based on the response parameters.
-
rendered_class
¶ The class to construct with the rendered response, defaults to
flask.Response
.alias of
Response
-
Bundled Renderers¶
-
flask.ext.pushrod.renderers.
json_renderer
(unrendered, **kwargs)[source]¶ Renders a response using
json.dumps()
.Renderer MIME type triggers: - application/json
Renderer name triggers: - json
-
flask.ext.pushrod.renderers.
jinja2_renderer
(unrendered, jinja_template=None, **kwargs)[source]¶ Renders a response using
flask.render_template()
.Renderer MIME type triggers: - text/html
Renderer name triggers: - html
Bundled Normalizers¶
Flask-Pushrod ships with a few normalizers by default. For more info, see normalize()
.
Flask-Pushrod’s built-in normalizers are generally named with the scheme normalize_type
.
Note
Normalizers also apply to subclasses, unless the subclass defines another normalizer.
-
flask.ext.pushrod.normalizers.
normalize_dict
(x, pushrod)[source]¶ Takes: dict
Returns: dict
with all keys converted tounicode
and thennormalized
and all valuesnormalized
-
flask.ext.pushrod.normalizers.
normalize_iterable
(x, pushrod)[source]¶ Takes: Returns: list
with all valuesnormalized
-
flask.ext.pushrod.normalizers.
normalize_object
(x, pushrod)[source]¶ Delegates normalization to the object itself, looking for the following attributes/methods (in this order):
- __pushrod_normalize__ - Essentially treated as if a normalizer was explicitly registered
- __pushrod_fields__ - A list of names fields, which is essentially treated like
{k: getattr(x, k) for k in x.__pushrod_fields__}
- __pushrod_field__ - A name of a single field, x is then substituted for what is (simplified)
getattr(x, x.__pushrod_field)
Note
__pushrod_fields__ and __pushrod_field__ can be either a callable or an attribute, while __pushrod_normalize__ must be a callable.
Takes: object
-
flask.ext.pushrod.normalizers.
normalize_basestring
(x, pushrod)[source] Takes: Returns:
-
flask.ext.pushrod.normalizers.
normalize_iterable
(x, pushrod)[source] Takes: Returns: list
with all valuesnormalized
-
flask.ext.pushrod.normalizers.
normalize_dict
(x, pushrod)[source] Takes: dict
Returns: dict
with all keys converted tounicode
and thennormalized
and all valuesnormalized
-
flask.ext.pushrod.normalizers.
normalize_object
(x, pushrod)[source] Delegates normalization to the object itself, looking for the following attributes/methods (in this order):
- __pushrod_normalize__ - Essentially treated as if a normalizer was explicitly registered
- __pushrod_fields__ - A list of names fields, which is essentially treated like
{k: getattr(x, k) for k in x.__pushrod_fields__}
- __pushrod_field__ - A name of a single field, x is then substituted for what is (simplified)
getattr(x, x.__pushrod_field)
Note
__pushrod_fields__ and __pushrod_field__ can be either a callable or an attribute, while __pushrod_normalize__ must be a callable.
Takes: object
Exceptions¶
-
exception
flask.ext.pushrod.renderers.
RendererNotFound
[source]¶ Thrown when no acceptable renderer can be found, see
flask.ext.pushrod.Pushrod.get_renderers_for_request()
.Note
This class inherits from
werkzeug.exceptions.NotAcceptable
, so it’s automatically converted to406 Not Acceptable
by Werkzeug if not explicitly handled (which is usually the intended behaviour).