Debian Codegraph @

docs/fields.rst

raw
1 Fields
2 ======
3
4 .. _StatusField:
5
6 StatusField
7 -----------
8
9 A simple convenience for giving a model a set of "states."
10 ``StatusField`` is a ``CharField`` subclass that expects to find a
11 class attribute called ``STATUS`` on its model or you can pass
12 ``choices_name`` to use a different attribute name, and uses that as
13 its ``choices``. Also sets a default ``max_length`` of 100, and sets
14 its default value to the first item in the ``STATUS`` choices:
15
16 .. code-block:: python
17
18 from model_utils.fields import StatusField
19 from model_utils import Choices
20
21 class Article(models.Model):
22 STATUS = Choices('draft', 'published')
23 # ...
24 status = StatusField()
25
26 (The ``STATUS`` class attribute does not have to be a :ref:`Choices`
27 instance, it can be an ordinary list of two-tuples).
28
29 Using a different name for the model's choices class attribute
30
31 .. code-block:: python
32
33 from model_utils.fields import StatusField
34 from model_utils import Choices
35
36 class Article(models.Model):
37 ANOTHER_CHOICES = Choices('draft', 'published')
38 # ...
39 another_field = StatusField(choices_name='ANOTHER_CHOICES')
40
41 ``StatusField`` does not set ``db_index=True`` automatically; if you
42 expect to frequently filter on your status field (and it will have
43 enough selectivity to make an index worthwhile) you may want to add this
44 yourself.
45
46
47 .. _MonitorField:
48
49 MonitorField
50 ------------
51
52 A ``DateTimeField`` subclass that monitors another field on the model,
53 and updates itself to the current date-time whenever the monitored
54 field changes:
55
56 .. code-block:: python
57
58 from model_utils.fields import MonitorField, StatusField
59
60 class Article(models.Model):
61 STATUS = Choices('draft', 'published')
62
63 status = StatusField()
64 status_changed = MonitorField(monitor='status')
65
66 (A ``MonitorField`` can monitor any type of field for changes, not only a
67 ``StatusField``.)
68
69 If a list is passed to the ``when`` parameter, the field will only
70 update when it matches one of the specified values:
71
72 .. code-block:: python
73
74 from model_utils.fields import MonitorField, StatusField
75
76 class Article(models.Model):
77 STATUS = Choices('draft', 'published')
78
79 status = StatusField()
80 published_at = MonitorField(monitor='status', when=['published'])
81
82
83 SplitField
84 ----------
85
86 A ``TextField`` subclass that automatically pulls an excerpt out of
87 its content (based on a "split here" marker or a default number of
88 initial paragraphs) and stores both its content and excerpt values in
89 the database.
90
91 A ``SplitField`` is easy to add to any model definition:
92
93 .. code-block:: python
94
95 from django.db import models
96 from model_utils.fields import SplitField
97
98 class Article(models.Model):
99 title = models.CharField(max_length=100)
100 body = SplitField()
101
102 ``SplitField`` automatically creates an extra non-editable field
103 ``_body_excerpt`` to store the excerpt. This field doesn't need to be
104 accessed directly; see below.
105
106
107 Accessing a SplitField on a model
108 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
109
110 When accessing an attribute of a model that was declared as a
111 ``SplitField``, a ``SplitText`` object is returned. The ``SplitText``
112 object has three attributes:
113
114 ``content``:
115 The full field contents.
116 ``excerpt``:
117 The excerpt of ``content`` (read-only).
118 ``has_more``:
119 True if the excerpt and content are different, False otherwise.
120
121 This object also has a ``__unicode__`` method that returns the full
122 content, allowing ``SplitField`` attributes to appear in templates
123 without having to access ``content`` directly.
124
125 Assuming the ``Article`` model above:
126
127 .. code-block:: pycon
128
129 >>> a = Article.objects.all()[0]
130 >>> a.body.content
131 u'some text\n\n<!-- split -->\n\nmore text'
132 >>> a.body.excerpt
133 u'some text\n'
134 >>> unicode(a.body)
135 u'some text\n\n<!-- split -->\n\nmore text'
136
137 Assignment to ``a.body`` is equivalent to assignment to
138 ``a.body.content``.
139
140 .. note::
141
142 a.body.excerpt is only updated when a.save() is called
143
144
145 Customized excerpting
146 ~~~~~~~~~~~~~~~~~~~~~
147
148 By default, ``SplitField`` looks for the marker ``<!-- split -->``
149 alone on a line and takes everything before that marker as the
150 excerpt. This marker can be customized by setting the ``SPLIT_MARKER``
151 setting.
152
153 If no marker is found in the content, the first two paragraphs (where
154 paragraphs are blocks of text separated by a blank line) are taken to
155 be the excerpt. This number can be customized by setting the
156 ``SPLIT_DEFAULT_PARAGRAPHS`` setting.
157
158
159 UUIDField
160 ----------
161
162 A ``UUIDField`` subclass that provides an UUID field. You can
163 add this field to any model definition.
164
165 With the param ``primary_key`` you can set if this field is the
166 primary key for the model, default is True.
167
168 Param ``version`` is an integer that set default UUID version.
169 Versions 1,3,4 and 5 are supported, default is 4.
170
171 If ``editable`` is set to false the field will not be displayed in the admin
172 or any other ModelForm, default is False.
173
174
175 .. code-block:: python
176
177 from django.db import models
178 from model_utils.fields import UUIDField
179
180 class MyAppModel(models.Model):
181 uuid = UUIDField(primary_key=True, version=4, editable=False)
182
183
184 UrlsafeTokenField
185 -----------------
186
187 A ``CharField`` subclass that provides random token generating using
188 python's ``secrets.token_urlsafe`` as default value.
189
190 If ``editable`` is set to false the field will not be displayed in the admin
191 or any other ModelForm, default is False.
192
193 ``max_length`` specifies the maximum length of the token. The default value is 128.
194
195
196 .. code-block:: python
197
198 from django.db import models
199 from model_utils.fields import UrlsafeTokenField
200
201
202 class MyAppModel(models.Model):
203 uuid = UrlsafeTokenField(editable=False, max_length=128)
204
205
206 You can provide your custom token generator using the ``factory`` argument.
207 ``factory`` should be callable. It will raise ``TypeError`` if it is not callable.
208 ``factory`` is called with ``max_length`` argument to generate the token, and should
209 return a string of specified maximum length.
210
211
212 .. code-block:: python
213
214 import uuid
215
216 from django.db import models
217 from model_utils.fields import UrlsafeTokenField
218
219
220 def _token_factory(max_length):
221 return uuid.uuid4().hex
222
223
224 class MyAppModel(models.Model):
225 uuid = UrlsafeTokenField(max_length=32, factory=_token_factory)