From 9fd90c4088833855b1ae973e4a66cab09a26f3e6 Mon Sep 17 00:00:00 2001 From: David Beitey Date: Mon, 11 Mar 2019 03:14:01 +0000 Subject: [PATCH] Clarified deconstruct() in Custom Model Field docs. --- docs/howto/custom-model-fields.txt | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/docs/howto/custom-model-fields.txt b/docs/howto/custom-model-fields.txt index 0a9aab4706..4bb81611cd 100644 --- a/docs/howto/custom-model-fields.txt +++ b/docs/howto/custom-model-fields.txt @@ -231,9 +231,10 @@ Field deconstruction -------------------- The counterpoint to writing your ``__init__()`` method is writing the -``deconstruct()`` method. This method tells Django how to take an instance -of your new field and reduce it to a serialized form - in particular, what -arguments to pass to ``__init__()`` to re-create it. +:meth:`~.Field.deconstruct` method. It's used during :doc:`model migrations +` to tell Django how to take an instance of your new field +and reduce it to a serialized form - in particular, what arguments to pass to +``__init__()`` to re-create it. If you haven't added any extra options on top of the field you inherited from, then there's no need to write a new ``deconstruct()`` method. If, however, @@ -269,8 +270,10 @@ we can drop it from the keyword arguments for readability:: del kwargs["max_length"] return name, path, args, kwargs -If you add a new keyword argument, you need to write code to put its value -into ``kwargs`` yourself:: +If you add a new keyword argument, you need to write code in ``deconstruct()`` +that puts its value into ``kwargs`` yourself. You should also omit the value +from ``kwargs`` when it isn't necessary to reconstruct the state of the field, +such as when the default value is being used:: from django.db import models