Debian Codegraph @

docs/ref/contrib/postgres/forms.txt

raw
1 ===========================================
2 PostgreSQL specific form fields and widgets
3 ===========================================
4
5 All of these fields and widgets are available from the
6 ``django.contrib.postgres.forms`` module.
7
8 .. currentmodule:: django.contrib.postgres.forms
9
10 Fields
11 ======
12
13 ``SimpleArrayField``
14 --------------------
15
16 .. class:: SimpleArrayField(base_field, delimiter=',', max_length=None, min_length=None)
17
18 A field which maps to an array. It is represented by an HTML ``<input>``.
19
20 .. attribute:: base_field
21
22 This is a required argument.
23
24 It specifies the underlying form field for the array. This is not used
25 to render any HTML, but it is used to process the submitted data and
26 validate it. For example:
27
28 .. code-block:: pycon
29
30 >>> from django import forms
31 >>> from django.contrib.postgres.forms import SimpleArrayField
32
33 >>> class NumberListForm(forms.Form):
34 ... numbers = SimpleArrayField(forms.IntegerField())
35 ...
36
37 >>> form = NumberListForm({"numbers": "1,2,3"})
38 >>> form.is_valid()
39 True
40 >>> form.cleaned_data
41 {'numbers': [1, 2, 3]}
42
43 >>> form = NumberListForm({"numbers": "1,2,a"})
44 >>> form.is_valid()
45 False
46
47 .. attribute:: delimiter
48
49 This is an optional argument which defaults to a comma: ``,``. This
50 value is used to split the submitted data. It allows you to chain
51 ``SimpleArrayField`` for multidimensional data:
52
53 .. code-block:: pycon
54
55 >>> from django import forms
56 >>> from django.contrib.postgres.forms import SimpleArrayField
57
58 >>> class GridForm(forms.Form):
59 ... places = SimpleArrayField(SimpleArrayField(IntegerField()), delimiter="|")
60 ...
61
62 >>> form = GridForm({"places": "1,2|2,1|4,3"})
63 >>> form.is_valid()
64 True
65 >>> form.cleaned_data
66 {'places': [[1, 2], [2, 1], [4, 3]]}
67
68 .. note::
69
70 The field does not support escaping of the delimiter, so be careful
71 in cases where the delimiter is a valid character in the underlying
72 field. The delimiter does not need to be only one character.
73
74 .. attribute:: max_length
75
76 This is an optional argument which validates that the array does not
77 exceed the stated length.
78
79 .. attribute:: min_length
80
81 This is an optional argument which validates that the array reaches at
82 least the stated length.
83
84 .. admonition:: User friendly forms
85
86 ``SimpleArrayField`` is not particularly user friendly in most cases,
87 however it is a useful way to format data from a client-side widget for
88 submission to the server.
89
90 ``SplitArrayField``
91 -------------------
92
93 .. class:: SplitArrayField(base_field, size, remove_trailing_nulls=False)
94
95 This field handles arrays by reproducing the underlying field a fixed
96 number of times.
97
98 .. attribute:: base_field
99
100 This is a required argument. It specifies the form field to be
101 repeated.
102
103 .. attribute:: size
104
105 This is the fixed number of times the underlying field will be used.
106
107 .. attribute:: remove_trailing_nulls
108
109 By default, this is set to ``False``. When ``False``, each value from
110 the repeated fields is stored. When set to ``True``, any trailing
111 values which are blank will be stripped from the result. If the
112 underlying field has ``required=True``, but ``remove_trailing_nulls``
113 is ``True``, then null values are only allowed at the end, and will be
114 stripped.
115
116 Some examples::
117
118 SplitArrayField(IntegerField(required=True), size=3, remove_trailing_nulls=False)
119
120 ["1", "2", "3"] # -> [1, 2, 3]
121 ["1", "2", ""] # -> ValidationError - third entry required.
122 ["1", "", "3"] # -> ValidationError - second entry required.
123 ["", "2", ""] # -> ValidationError - first and third entries required.
124
125 SplitArrayField(IntegerField(required=False), size=3, remove_trailing_nulls=False)
126
127 ["1", "2", "3"] # -> [1, 2, 3]
128 ["1", "2", ""] # -> [1, 2, None]
129 ["1", "", "3"] # -> [1, None, 3]
130 ["", "2", ""] # -> [None, 2, None]
131
132 SplitArrayField(IntegerField(required=True), size=3, remove_trailing_nulls=True)
133
134 ["1", "2", "3"] # -> [1, 2, 3]
135 ["1", "2", ""] # -> [1, 2]
136 ["1", "", "3"] # -> ValidationError - second entry required.
137 ["", "2", ""] # -> ValidationError - first entry required.
138
139 SplitArrayField(IntegerField(required=False), size=3, remove_trailing_nulls=True)
140
141 ["1", "2", "3"] # -> [1, 2, 3]
142 ["1", "2", ""] # -> [1, 2]
143 ["1", "", "3"] # -> [1, None, 3]
144 ["", "2", ""] # -> [None, 2]
145
146 ``HStoreField``
147 ---------------
148
149 .. class:: HStoreField
150
151 A field which accepts JSON encoded data for an
152 :class:`~django.contrib.postgres.fields.HStoreField`. It casts all values
153 (except nulls) to strings. It is represented by an HTML ``<textarea>``.
154
155 .. admonition:: User friendly forms
156
157 ``HStoreField`` is not particularly user friendly in most cases,
158 however it is a useful way to format data from a client-side widget for
159 submission to the server.
160
161 .. note::
162
163 On occasions it may be useful to require or restrict the keys which are
164 valid for a given field. This can be done using the
165 :class:`~django.contrib.postgres.validators.KeysValidator`.
166
167 Range Fields
168 ------------
169
170 This group of fields all share similar functionality for accepting range data.
171 They are based on :class:`~django.forms.MultiValueField`. They treat one
172 omitted value as an unbounded range. They also validate that the lower bound is
173 not greater than the upper bound. All of these fields use
174 :class:`~django.contrib.postgres.forms.RangeWidget`.
175
176 ``IntegerRangeField``
177 ~~~~~~~~~~~~~~~~~~~~~
178
179 .. class:: IntegerRangeField
180
181 Based on :class:`~django.forms.IntegerField` and translates its input into
182 ``django.db.backends.postgresql.psycopg_any.NumericRange``. Default for
183 :class:`~django.contrib.postgres.fields.IntegerRangeField` and
184 :class:`~django.contrib.postgres.fields.BigIntegerRangeField`.
185
186 ``DecimalRangeField``
187 ~~~~~~~~~~~~~~~~~~~~~
188
189 .. class:: DecimalRangeField
190
191 Based on :class:`~django.forms.DecimalField` and translates its input into
192 ``django.db.backends.postgresql.psycopg_any.NumericRange``. Default for
193 :class:`~django.contrib.postgres.fields.DecimalRangeField`.
194
195 ``DateTimeRangeField``
196 ~~~~~~~~~~~~~~~~~~~~~~
197
198 .. class:: DateTimeRangeField
199
200 Based on :class:`~django.forms.DateTimeField` and translates its input into
201 ``django.db.backends.postgresql.psycopg_any.DateTimeTZRange``. Default for
202 :class:`~django.contrib.postgres.fields.DateTimeRangeField`.
203
204 ``DateRangeField``
205 ~~~~~~~~~~~~~~~~~~
206
207 .. class:: DateRangeField
208
209 Based on :class:`~django.forms.DateField` and translates its input into
210 ``django.db.backends.postgresql.psycopg_any.DateRange``. Default for
211 :class:`~django.contrib.postgres.fields.DateRangeField`.
212
213 Widgets
214 =======
215
216 ``RangeWidget``
217 ---------------
218
219 .. class:: RangeWidget(base_widget, attrs=None)
220
221 Widget used by all of the range fields.
222 Based on :class:`~django.forms.MultiWidget`.
223
224 :class:`~RangeWidget` has one required argument:
225
226 .. attribute:: base_widget
227
228 A :class:`~RangeWidget` comprises a 2-tuple of ``base_widget``.
229
230 .. method:: decompress(value)
231
232 Takes a single "compressed" value of a field, for example a
233 :class:`~django.contrib.postgres.fields.DateRangeField`,
234 and returns a tuple representing a lower and upper bound.