Skip to content
Browse files

Improve docs around deconstruction/serialisation (refs #22337)

  • Loading branch information...
1 parent f9d7e18 commit 827d5dc189fba33ec69d8916be310ff1e76361b1 @andrewgodwin andrewgodwin committed
Showing with 44 additions and 0 deletions.
  1. +7 −0 docs/howto/custom-file-storage.txt
  2. +21 −0 docs/releases/1.7.txt
  3. +16 −0 docs/topics/migrations.txt
7 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 <custom-deconstruct-method>`
+ 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 <migration-serializing>`, 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:
21 docs/releases/1.7.txt
@@ -128,6 +128,11 @@ built-in Django fields (``django/db/models/fields/``) 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 <migration-serializing>`.
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 <custom-field-deconstruct-method>`.
+The requirement for all field arguments to be
+:ref:`serializable <migration-serializing>` 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 <custom-deconstruct-method>`, though Django provides a handy
+class decorator that will work for most applications.
App-loading changes
16 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

0 comments on commit 827d5dc

Please sign in to comment.
Something went wrong with that request. Please try again.