From 610746f6cb89c13b364c27fc41ecc9592cbe1605 Mon Sep 17 00:00:00 2001 From: Aymeric Augustin Date: Mon, 20 Aug 2012 21:21:00 +0200 Subject: [PATCH] Fixed #18023 -- Documented simplejson issues. Thanks Luke Plant for reporting the issue and Alex Ogier for thoroughly investigating it. --- docs/releases/1.5.txt | 62 ++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 59 insertions(+), 3 deletions(-) diff --git a/docs/releases/1.5.txt b/docs/releases/1.5.txt index 4f25919d79..6042569cea 100644 --- a/docs/releases/1.5.txt +++ b/docs/releases/1.5.txt @@ -172,6 +172,54 @@ If you were using the ``data`` parameter in a PUT request without a ``content_type``, you must encode your data before passing it to the test client and set the ``content_type`` argument. +.. _simplejson-incompatibilities: + +System version of :mod:`simplejson` no longer used +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:ref:`As explained below `, Django 1.5 deprecates +:mod:`django.utils.simplejson` in favor of Python 2.6's built-in :mod:`json` +module. In theory, this change is harmless. Unfortunately, because of +incompatibilities between versions of :mod:`simplejson`, it may trigger errors +in some circumstances. + +JSON-related features in Django 1.4 always used :mod:`django.utils.simplejson`. +This module was actually: + +- A system version of :mod:`simplejson`, if one was available (ie. ``import + simplejson`` works), if it was more recent than Django's built-in copy or it + had the C speedups, or +- The :mod:`json` module from the standard library, if it was available (ie. + Python 2.6 or greater), or +- A built-in copy of version 2.0.7 of :mod:`simplejson`. + +In Django 1.5, those features use Python's :mod:`json` module, which is based +on version 2.0.9 of :mod:`simplejson`. + +There are no known incompatibilities between Django's copy of version 2.0.7 and +Python's copy of version 2.0.9. However, there are some incompatibilities +between other versions of :mod:`simplejson`: + +- While the :mod:`simplejson` API is documented as always returning unicode + strings, the optional C implementation can return a byte string. This was + fixed in Python 2.7. +- :class:`simplejson.JSONEncoder` gained a ``namedtuple_as_object`` keyword + argument in version 2.2. + +More information on these incompatibilities is available in `ticket #18023`_. + +The net result is that, if you have installed :mod:`simplejson` and your code +uses Django's serialization internals directly -- for instance +:class:`django.core.serializers.json.DjangoJSONEncoder`, the switch from +:mod:`simplejson` to :mod:`json` could break your code. (In general, changes to +internals aren't documented; we're making an exception here.) + +At this point, the maintainers of Django believe that using :mod:`json` from +the standard library offers the strongest guarantee of backwards-compatibility. +They recommend to use it from now on. + +.. _ticket #18023: https://code.djangoproject.com/ticket/18023#comment:10 + String types of hasher method parameters ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -282,13 +330,21 @@ Miscellaneous Features deprecated in 1.5 ========================== +.. _simplejson-deprecation: + ``django.utils.simplejson`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Since Django 1.5 drops support for Python 2.5, we can now rely on the -:mod:`json` module being in Python's standard library -- so we've removed -our own copy of ``simplejson``. You can safely change any use of -:mod:`django.utils.simplejson` to :mod:`json`. +:mod:`json` module being available in Python's standard library, so we've +removed our own copy of :mod:`simplejson`. You should now import :mod:`json` +instead :mod:`django.utils.simplejson`. + +Unfortunately, this change might have unwanted side-effects, because of +incompatibilities between versions of :mod:`simplejson` -- see the +:ref:`backwards-incompatible changes ` section. +If you rely on features added to :mod:`simplejson` after it became Python's +:mod:`json`, you should import :mod:`simplejson` explicitly. ``itercompat.product`` ~~~~~~~~~~~~~~~~~~~~~~