mirror of
https://github.com/django/django.git
synced 2024-12-27 11:35:53 +00:00
604162604b
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.
136 lines
4.7 KiB
Plaintext
136 lines
4.7 KiB
Plaintext
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
|
|
|
|
SimpleArrayField
|
|
----------------
|
|
|
|
.. 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
|
|
---------------
|
|
|
|
.. 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]
|