django/docs/ref/contrib/postgres/forms.txt

245 lines
8.0 KiB
Plaintext
Raw Normal View History

===========================================
Added array field support for PostgreSQL. The first part of django.contrib.postgres, including model and two form fields for arrays of other data types. This commit is formed of the following work: Add shell of postgres app and test handling. First draft of array fields. Use recursive deconstruction. Stop creating classes at lookup time. Add validation and size parameter. Add contained_by lookup. Add SimpleArrayField for forms. Add SplitArrayField (mainly for admin). Fix prepare_value for SimpleArrayField. Stop using MultiValueField and MultiWidget. They don't play nice with flexible sizes. Add basics of admin integration. Missing: - Tests - Fully working js Add reference document for django.contrib.postgres.fields.ArrayField. Various performance and style tweaks. Fix internal docs link, formalise code snippets. Remove the admin code for now. It needs a better way of handing JS widgets in the admin as a whole before it is easy to write. In particular there are serious issues involving DateTimePicker when used in an array. Add a test for nested array fields with different delimiters. This will be a documented pattern so having a test for it is useful. Add docs for SimpleArrayField. Add docs for SplitArrayField. Remove admin related code for now. definition -> description Fix typo. Py3 errors. Avoid using regexes where they're not needed. Allow passing tuples by the programmer. Add some more tests for multidimensional arrays. Also fix slicing as much as it can be fixed. Simplify SplitArrayWidget's data loading. If we aren't including the variable size one, we don't need to search like this.
2014-03-27 00:44:21 +08:00
PostgreSQL specific form fields and widgets
===========================================
All of these fields and widgets are available from the
``django.contrib.postgres.forms`` module.
.. currentmodule:: django.contrib.postgres.forms
Fields
======
``SimpleArrayField``
--------------------
Added array field support for PostgreSQL. The first part of django.contrib.postgres, including model and two form fields for arrays of other data types. This commit is formed of the following work: Add shell of postgres app and test handling. First draft of array fields. Use recursive deconstruction. Stop creating classes at lookup time. Add validation and size parameter. Add contained_by lookup. Add SimpleArrayField for forms. Add SplitArrayField (mainly for admin). Fix prepare_value for SimpleArrayField. Stop using MultiValueField and MultiWidget. They don't play nice with flexible sizes. Add basics of admin integration. Missing: - Tests - Fully working js Add reference document for django.contrib.postgres.fields.ArrayField. Various performance and style tweaks. Fix internal docs link, formalise code snippets. Remove the admin code for now. It needs a better way of handing JS widgets in the admin as a whole before it is easy to write. In particular there are serious issues involving DateTimePicker when used in an array. Add a test for nested array fields with different delimiters. This will be a documented pattern so having a test for it is useful. Add docs for SimpleArrayField. Add docs for SplitArrayField. Remove admin related code for now. definition -> description Fix typo. Py3 errors. Avoid using regexes where they're not needed. Allow passing tuples by the programmer. Add some more tests for multidimensional arrays. Also fix slicing as much as it can be fixed. Simplify SplitArrayWidget's data loading. If we aren't including the variable size one, we don't need to search like this.
2014-03-27 00:44:21 +08:00
.. class:: SimpleArrayField(base_field, delimiter=',', max_length=None, min_length=None)
A simple field which maps to an array. It is represented by an HTML
``<input>``.
.. attribute:: base_field
This is a required argument.
It specifies the underlying form field for the array. This is not used
to render any HTML, but it is used to process the submitted data and
validate it. For example::
>>> from django.contrib.postgres.forms import SimpleArrayField
>>> from django import forms
>>> class NumberListForm(forms.Form):
... numbers = SimpleArrayField(forms.IntegerField())
>>> form = NumberListForm({'numbers': '1,2,3'})
>>> form.is_valid()
True
>>> form.cleaned_data
{'numbers': [1, 2, 3]}
>>> form = NumberListForm({'numbers': '1,2,a'})
>>> form.is_valid()
False
.. attribute:: delimiter
This is an optional argument which defaults to a comma: ``,``. This
value is used to split the submitted data. It allows you to chain
``SimpleArrayField`` for multidimensional data::
>>> from django.contrib.postgres.forms import SimpleArrayField
>>> from django import forms
>>> class GridForm(forms.Form):
... places = SimpleArrayField(SimpleArrayField(IntegerField()), delimiter='|')
>>> form = GridForm({'places': '1,2|2,1|4,3'})
>>> form.is_valid()
True
>>> form.cleaned_data
{'places': [[1, 2], [2, 1], [4, 3]]}
.. note::
The field does not support escaping of the delimiter, so be careful
in cases where the delimiter is a valid character in the underlying
field. The delimiter does not need to be only one character.
.. attribute:: max_length
This is an optional argument which validates that the array does not
exceed the stated length.
.. attribute:: min_length
This is an optional argument which validates that the array reaches at
least the stated length.
.. admonition:: User friendly forms
``SimpleArrayField`` is not particularly user friendly in most cases,
however it is a useful way to format data from a client-side widget for
submission to the server.
``SplitArrayField``
-------------------
Added array field support for PostgreSQL. The first part of django.contrib.postgres, including model and two form fields for arrays of other data types. This commit is formed of the following work: Add shell of postgres app and test handling. First draft of array fields. Use recursive deconstruction. Stop creating classes at lookup time. Add validation and size parameter. Add contained_by lookup. Add SimpleArrayField for forms. Add SplitArrayField (mainly for admin). Fix prepare_value for SimpleArrayField. Stop using MultiValueField and MultiWidget. They don't play nice with flexible sizes. Add basics of admin integration. Missing: - Tests - Fully working js Add reference document for django.contrib.postgres.fields.ArrayField. Various performance and style tweaks. Fix internal docs link, formalise code snippets. Remove the admin code for now. It needs a better way of handing JS widgets in the admin as a whole before it is easy to write. In particular there are serious issues involving DateTimePicker when used in an array. Add a test for nested array fields with different delimiters. This will be a documented pattern so having a test for it is useful. Add docs for SimpleArrayField. Add docs for SplitArrayField. Remove admin related code for now. definition -> description Fix typo. Py3 errors. Avoid using regexes where they're not needed. Allow passing tuples by the programmer. Add some more tests for multidimensional arrays. Also fix slicing as much as it can be fixed. Simplify SplitArrayWidget's data loading. If we aren't including the variable size one, we don't need to search like this.
2014-03-27 00:44:21 +08:00
.. class:: SplitArrayField(base_field, size, remove_trailing_nulls=False)
This field handles arrays by reproducing the underlying field a fixed
number of times.
.. attribute:: base_field
This is a required argument. It specifies the form field to be
repeated.
.. attribute:: size
This is the fixed number of times the underlying field will be used.
.. attribute:: remove_trailing_nulls
By default, this is set to ``False``. When ``False``, each value from
the repeated fields is stored. When set to ``True``, any trailing
values which are blank will be stripped from the result. If the
underlying field has ``required=True``, but ``remove_trailing_nulls``
is ``True``, then null values are only allowed at the end, and will be
stripped.
Some examples::
SplitArrayField(IntegerField(required=True), size=3, remove_trailing_nulls=False)
['1', '2', '3'] # -> [1, 2, 3]
['1', '2', ''] # -> ValidationError - third entry required.
['1', '', '3'] # -> ValidationError - second entry required.
['', '2', ''] # -> ValidationError - first and third entries required.
SplitArrayField(IntegerField(required=False), size=3, remove_trailing_nulls=False)
['1', '2', '3'] # -> [1, 2, 3]
['1', '2', ''] # -> [1, 2, None]
['1', '', '3'] # -> [1, None, 3]
['', '2', ''] # -> [None, 2, None]
SplitArrayField(IntegerField(required=True), size=3, remove_trailing_nulls=True)
['1', '2', '3'] # -> [1, 2, 3]
['1', '2', ''] # -> [1, 2]
['1', '', '3'] # -> ValidationError - second entry required.
['', '2', ''] # -> ValidationError - first entry required.
SplitArrayField(IntegerField(required=False), size=3, remove_trailing_nulls=True)
['1', '2', '3'] # -> [1, 2, 3]
['1', '2', ''] # -> [1, 2]
['1', '', '3'] # -> [1, None, 3]
['', '2', ''] # -> [None, 2]
``HStoreField``
---------------
.. class:: HStoreField
A field which accepts JSON encoded data for an
:class:`~django.contrib.postgres.fields.HStoreField`. It casts all values
(except nulls) to strings. It is represented by an HTML ``<textarea>``.
.. admonition:: User friendly forms
``HStoreField`` is not particularly user friendly in most cases,
however it is a useful way to format data from a client-side widget for
submission to the server.
.. note::
2014-11-18 07:42:54 +08:00
On occasions it may be useful to require or restrict the keys which are
valid for a given field. This can be done using the
:class:`~django.contrib.postgres.validators.KeysValidator`.
``JSONField``
-------------
.. class:: JSONField
A field which accepts JSON encoded data for a
:class:`~django.contrib.postgres.fields.JSONField`. It is represented by an
HTML ``<textarea>``.
.. admonition:: User friendly forms
``JSONField`` is not particularly user friendly in most cases, however
it is a useful way to format data from a client-side widget for
submission to the server.
Range Fields
------------
This group of fields all share similar functionality for accepting range data.
They are based on :class:`~django.forms.MultiValueField`. They treat one
omitted value as an unbounded range. They also validate that the lower bound is
not greater than the upper bound. All of these fields use
:class:`~django.contrib.postgres.forms.RangeWidget`.
``IntegerRangeField``
~~~~~~~~~~~~~~~~~~~~~
.. class:: IntegerRangeField
Based on :class:`~django.forms.IntegerField` and translates its input into
:class:`~psycopg2:psycopg2.extras.NumericRange`. Default for
:class:`~django.contrib.postgres.fields.IntegerRangeField` and
:class:`~django.contrib.postgres.fields.BigIntegerRangeField`.
``FloatRangeField``
~~~~~~~~~~~~~~~~~~~
.. class:: FloatRangeField
Based on :class:`~django.forms.FloatField` and translates its input into
:class:`~psycopg2:psycopg2.extras.NumericRange`. Default for
:class:`~django.contrib.postgres.fields.FloatRangeField`.
``DateTimeRangeField``
~~~~~~~~~~~~~~~~~~~~~~
.. class:: DateTimeRangeField
Based on :class:`~django.forms.DateTimeField` and translates its input into
:class:`~psycopg2:psycopg2.extras.DateTimeTZRange`. Default for
:class:`~django.contrib.postgres.fields.DateTimeRangeField`.
``DateRangeField``
~~~~~~~~~~~~~~~~~~
.. class:: DateRangeField
Based on :class:`~django.forms.DateField` and translates its input into
:class:`~psycopg2:psycopg2.extras.DateRange`. Default for
:class:`~django.contrib.postgres.fields.DateRangeField`.
Widgets
=======
``RangeWidget``
---------------
.. class:: RangeWidget(base_widget, attrs=None)
Widget used by all of the range fields.
Based on :class:`~django.forms.MultiWidget`.
:class:`~RangeWidget` has one required argument:
.. attribute:: base_widget
A :class:`~RangeWidget` comprises a 2-tuple of ``base_widget``.
.. method:: decompress(value)
Takes a single "compressed" value of a field, for example a
:class:`~django.contrib.postgres.fields.DateRangeField`,
and returns a tuple representing and lower and upper bound.