From 1ed876ee5bd71092faf07559a25091bc27f96489 Mon Sep 17 00:00:00 2001 From: Andrew Godwin Date: Tue, 6 May 2014 23:06:41 -0700 Subject: [PATCH] [1.7.x] Improve docs around deconstruction/serialisation (refs #22337) --- docs/howto/custom-file-storage.txt | 7 +++++++ docs/releases/1.7.txt | 21 +++++++++++++++++++++ docs/topics/migrations.txt | 16 ++++++++++++++++ 3 files changed, 44 insertions(+) diff --git a/docs/howto/custom-file-storage.txt b/docs/howto/custom-file-storage.txt index 090cc089cb..5109986d45 100644 --- a/docs/howto/custom-file-storage.txt +++ b/docs/howto/custom-file-storage.txt @@ -34,6 +34,13 @@ You'll need to follow these steps: In addition, if your class provides local file storage, it must override the ``path()`` method. +#. Your storage class must be :ref:`deconstructible ` + so it can be serialized when it's used on a field in a migration. As long + as your field has arguments that are themselves + :ref:`serializable `, you can use the + ``django.utils.deconstruct.deconstructible`` class decorator for this + (that's what Django uses on FileSystemStorage). + Your custom storage system may override any of the storage methods explained in :doc:`/ref/files/storage`, but you **must** implement the following methods: diff --git a/docs/releases/1.7.txt b/docs/releases/1.7.txt index 86ad76a1db..0709cea1a5 100644 --- a/docs/releases/1.7.txt +++ b/docs/releases/1.7.txt @@ -128,6 +128,11 @@ built-in Django fields (``django/db/models/fields/__init__.py``) as several fields, including ``DecimalField`` and ``DateField``, override it and show how to call the method on the superclass and simply add or remove extra arguments. +This also means that all arguments to fields must themselves be serializable; +to see what we consider serializable, and to find out how to make your own +classes serializable, read the +:ref:`migration serialization documentation `. + Calling custom ``QuerySet`` methods from the ``Manager`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -876,6 +881,22 @@ Instead, you are encouraged to load initial data in migrations if you need it this has the added advantage that your initial data will not need updating every time you change the schema. +deconstruct() and serializability +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Django now requires all Field classes and all of their constructor arguments +to be serializable. If you modify the constructor signature in your custom +Field in any way, you'll need to implement a deconstruct() method; +we've expanded the custom field documentation with :ref:`instructions +on implementing this method `. + +The requirement for all field arguments to be +:ref:`serializable ` means that any custom class +instances being passed into Field constructors - things like custom Storage +subclasses, for instance - need to have a :ref:`deconstruct method defined on +them as well `, though Django provides a handy +class decorator that will work for most applications. + App-loading changes ~~~~~~~~~~~~~~~~~~~ diff --git a/docs/topics/migrations.txt b/docs/topics/migrations.txt index a53444f568..4f75fcff56 100644 --- a/docs/topics/migrations.txt +++ b/docs/topics/migrations.txt @@ -520,6 +520,22 @@ available at the top level of a module it is not serializable. Django will write out the value as an instantiation of your class with the given arguments, similar to the way it writes out references to Django fields. +As long as all of the arguments to your class' constructor are themselves +serializable, you can just use the ``@deconstructible`` class decorator +from ``django.utils.deconstruct`` to add the method:: + + from django.utils.deconstruct import deconstructible + + @deconstructible + class MyCustomClass(object): + + def __init__(self, foo=1): + ... + +The decorator adds logic to capture and preserve the arguments on their +way into your constructor, and then returns those arguments exactly when +deconstruct() is called. + Upgrading from South --------------------