From d81ea33ac67ac750053acbfd12616db0130de3c8 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Tue, 10 Jan 2012 22:52:24 -0600 Subject: intermediate commit --- docs/api/renderers.rst | 2 ++ docs/narr/renderers.rst | 10 ++++++---- 2 files changed, 8 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/api/renderers.rst b/docs/api/renderers.rst index 312aa0b31..ea000ad02 100644 --- a/docs/api/renderers.rst +++ b/docs/api/renderers.rst @@ -11,6 +11,8 @@ .. autofunction:: render_to_response +.. autoclass:: JSON + .. autoclass:: JSONP .. attribute:: null_renderer diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst index 76035cbdf..47182c09e 100644 --- a/docs/narr/renderers.rst +++ b/docs/narr/renderers.rst @@ -177,8 +177,8 @@ using the API of the ``request.response`` attribute. See .. index:: pair: renderer; JSON -``json``: JSON Renderer -~~~~~~~~~~~~~~~~~~~~~~~ +JSON Renderer +~~~~~~~~~~~~~ The ``json`` renderer renders view callable results to :term:`JSON`. It passes the return value through the ``json.dumps`` standard library function, @@ -207,7 +207,10 @@ representing the JSON serialization of the return value: '{"content": "Hello!"}' The return value needn't be a dictionary, but the return value must contain -values serializable by :func:`json.dumps`. +values serializable by :func:`json.dumps`. Extra arguments can be passed +to :func:`json.dumps` by overriding the default renderer. See +:class:`pyramid.renderers.JSON` and +:ref:`_adding_and_overriding_renderers` for more information. You can configure a view to use the JSON renderer by naming ``json`` as the ``renderer`` argument of a view configuration, e.g. by using @@ -221,7 +224,6 @@ You can configure a view to use the JSON renderer by naming ``json`` as the context='myproject.resources.Hello', renderer='json') - Views which use the JSON renderer can vary non-body response attributes by using the api of the ``request.response`` attribute. See :ref:`request_response_attr`. -- cgit v1.2.3 From ba60524b56a639ecad42f85b63af2120d9d96cdc Mon Sep 17 00:00:00 2001 From: Wayne Witzel III Date: Wed, 28 Mar 2012 12:03:52 -0400 Subject: JSON-API rework and Object.__json__ support --- docs/api/renderers.rst | 2 ++ docs/narr/renderers.rst | 7 +++++++ 2 files changed, 9 insertions(+) (limited to 'docs') diff --git a/docs/api/renderers.rst b/docs/api/renderers.rst index ea000ad02..ab182365e 100644 --- a/docs/api/renderers.rst +++ b/docs/api/renderers.rst @@ -15,6 +15,8 @@ .. autoclass:: JSONP +.. autoclass:: ObjectJSONEncoder + .. attribute:: null_renderer An object that can be used in advanced integration cases as input to the diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst index 47182c09e..52e97d091 100644 --- a/docs/narr/renderers.rst +++ b/docs/narr/renderers.rst @@ -212,6 +212,13 @@ to :func:`json.dumps` by overriding the default renderer. See :class:`pyramid.renderers.JSON` and :ref:`_adding_and_overriding_renderers` for more information. +Custom objects can be easily serialized by defining a :func:`__json__` method +on the object. This method should return values serializable by +:func:`json_dumps`. By defining this method and using a :term:`JSON` +renderer the :class:`pyramid.renderers.ObjectJSONEncoder` class will be used +for encoding your object. If you later define your own custom encoder it will +override :class:`pyramid.renderers.ObjectJSONEncoder`. + You can configure a view to use the JSON renderer by naming ``json`` as the ``renderer`` argument of a view configuration, e.g. by using :meth:`~pyramid.config.Configurator.add_view`: -- cgit v1.2.3 From de797c4cefb03f16cfe3505c85d94c0af24eb066 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 29 Mar 2012 04:21:30 -0400 Subject: - Coverage and docs updates for custom JSON class. - Fork point: master now represents a future 1.4 release. --- docs/narr/renderers.rst | 68 ++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 56 insertions(+), 12 deletions(-) (limited to 'docs') diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst index 52e97d091..34bee3c7f 100644 --- a/docs/narr/renderers.rst +++ b/docs/narr/renderers.rst @@ -207,17 +207,13 @@ representing the JSON serialization of the return value: '{"content": "Hello!"}' The return value needn't be a dictionary, but the return value must contain -values serializable by :func:`json.dumps`. Extra arguments can be passed -to :func:`json.dumps` by overriding the default renderer. See -:class:`pyramid.renderers.JSON` and -:ref:`_adding_and_overriding_renderers` for more information. - -Custom objects can be easily serialized by defining a :func:`__json__` method -on the object. This method should return values serializable by -:func:`json_dumps`. By defining this method and using a :term:`JSON` -renderer the :class:`pyramid.renderers.ObjectJSONEncoder` class will be used -for encoding your object. If you later define your own custom encoder it will -override :class:`pyramid.renderers.ObjectJSONEncoder`. +values serializable by ``json.dumps``. + +.. note:: + + Extra arguments can be passed to ``json.dumps`` by overriding the default + ``json`` renderer. See :class:`pyramid.renderers.JSON` and + :ref:`adding_and_overriding_renderers` for more information. You can configure a view to use the JSON renderer by naming ``json`` as the ``renderer`` argument of a view configuration, e.g. by using @@ -235,13 +231,57 @@ Views which use the JSON renderer can vary non-body response attributes by using the api of the ``request.response`` attribute. See :ref:`request_response_attr`. +.. _json_serializing_custom_objects: + +Serializing Custom Objects +++++++++++++++++++++++++++ + +Custom objects can be made easily JSON-serializable in Pyramid by defining a +``__json__`` method on the object's class. This method should return values +natively serializable by ``json.dumps`` (such as ints, lists, dictionaries, +strings, and so forth). + +.. code-block:: python + :linenos: + + from pyramid.view import view_config + + class MyObject(object): + def __init__(self, x): + self.x = x + + def __json__(self): + return {'x':self.x} + + @view_config(renderer='json') + def objects(request): + return [MyObject(1), MyObject(2)] + + # the JSON value returned by ``objects`` will be: + # [{"x": 1}, {"x": 2}] + +.. note:: + + Honoring the ``__json__`` method of custom objects is a feature new in + Pyramid 1.4. + +.. warning:: + + The machinery which performs the ``__json__`` method-calling magic is in + the :class:`pyramid.renderers.ObjectJSONEncoder` class. This class will + be used for encoding any non-basic Python object when you use the default + ```json`` or ``jsonp`` renderers. But if you later define your own custom + JSON renderer and pass it a "cls" argument signifying a different encoder, + the encoder you pass will override Pyramid's use of + :class:`pyramid.renderers.ObjectJSONEncoder`. + .. index:: pair: renderer; JSONP .. _jsonp_renderer: JSONP Renderer --------------- +~~~~~~~~~~~~~~ .. note:: This feature is new in Pyramid 1.1. @@ -306,6 +346,10 @@ The string ``callback=?`` above in the the ``url`` param to the JQuery a JSONP request; the ``callback`` parameter will be automatically filled in for you and used. +The same custom-object serialization scheme defined used for a "normal" JSON +renderer in :ref:`json_serializing_custom_objects` can be used when passing +values to a JSONP renderer too. + .. index:: pair: renderer; chameleon -- cgit v1.2.3