From 1d1cfd0bd8016358719a1e73117c811f02ca8c02 Mon Sep 17 00:00:00 2001 From: Andrew Godwin Date: Fri, 9 Aug 2013 14:31:24 +0100 Subject: [PATCH] Document new field API in release notes --- docs/releases/1.7.txt | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/docs/releases/1.7.txt b/docs/releases/1.7.txt index 23e4e3e64af..5d187967da6 100644 --- a/docs/releases/1.7.txt +++ b/docs/releases/1.7.txt @@ -57,6 +57,33 @@ but a few of the key features are: will still work, but that method name is deprecated and you should change it as soon as possible (nothing more than renaming is required). +New method on Field subclasses +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To help power both schema migrations and composite keys, the Field API now +has a new required method: ``deconstruct()``. + +This method takes no arguments, and returns a tuple of four items: + +* ``name``: The field's attribute name on its parent model, or None if it is not part of a model +* ``path``: A dotted, Python path to the class of this field, including the class name. +* ``args``: Positional arguments, as a list +* ``kwargs``: Keyword arguments, as a dict + +These four values allow any field to be serialized into a file, as well as +allowing the field to be copied safely, both essential parts of these new features. + +This change should not affect you unless you write custom Field subclasses; +if you do, you may need to reimplement the ``deconstruct()`` method if your +subclass changes the method signature of ``__init__`` in any way. If your +field just inherits from a built-in Django field and doesn't override ``__init__``, +no changes are necessary. + +If you do need to override ``deconstruct()``, a good place to start is the +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. + Calling custom ``QuerySet`` methods from the ``Manager`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~