Fixed #32559 -- Added 'step_size’ to numeric form fields.

Co-authored-by: Jacob Rief <jacob.rief@uibk.ac.at>

3 files changed, 67 insertions, 16 deletions

diff --git a/docs/ref/forms/fields.txt b/docs/ref/forms/fields.txt
index fc92f8998f..4d0205b4d3 100644
--- a/docs/ref/forms/fields.txt
+++ b/docs/ref/forms/fields.txt
@@ -492,18 +492,20 @@ For each field, we describe the default widget used if you don't specify
     * Normalizes to: A Python ``decimal``.
     * Validates that the given value is a decimal. Uses
       :class:`~django.core.validators.MaxValueValidator` and
-      :class:`~django.core.validators.MinValueValidator` if  ``max_value`` and
-      ``min_value`` are provided. Leading and trailing whitespace is ignored.
+      :class:`~django.core.validators.MinValueValidator` if ``max_value`` and
+      ``min_value`` are provided. Uses
+      :class:`~django.core.validators.StepValueValidator` if ``step_size`` is
+      provided. Leading and trailing whitespace is ignored.
     * Error message keys: ``required``, ``invalid``, ``max_value``,
       ``min_value``, ``max_digits``, ``max_decimal_places``,
-      ``max_whole_digits``
+      ``max_whole_digits``, ``step_size``.
 
     The ``max_value`` and ``min_value`` error messages may contain
     ``%(limit_value)s``, which will be substituted by the appropriate limit.
     Similarly, the ``max_digits``, ``max_decimal_places`` and
     ``max_whole_digits`` error messages may contain ``%(max)s``.
 
-    Takes four optional arguments:
+    Takes five optional arguments:
 
     .. attribute:: max_value
     .. attribute:: min_value
@@ -521,6 +523,14 @@ For each field, we describe the default widget used if you don't specify
 
         The maximum number of decimal places permitted.
 
+    .. attribute:: step_size
+
+        Limit valid inputs to an integral multiple of ``step_size``.
+
+    .. versionchanged:: 4.1
+
+        The ``step_size`` argument was added.
+
 ``DurationField``
 -----------------
 
@@ -636,13 +646,25 @@ For each field, we describe the default widget used if you don't specify
     * Validates that the given value is a float. Uses
       :class:`~django.core.validators.MaxValueValidator` and
       :class:`~django.core.validators.MinValueValidator` if ``max_value`` and
-      ``min_value`` are provided. Leading and trailing whitespace is allowed,
-      as in Python's ``float()`` function.
+      ``min_value`` are provided. Uses
+      :class:`~django.core.validators.StepValueValidator` if ``step_size`` is
+      provided. Leading and trailing whitespace is allowed, as in Python's
+      ``float()`` function.
     * Error message keys: ``required``, ``invalid``, ``max_value``,
-      ``min_value``
+      ``min_value``, ``step_size``.
+
+    Takes three optional arguments:
+
+    .. attribute:: max_value
+    .. attribute:: min_value
 
-    Takes two optional arguments for validation, ``max_value`` and ``min_value``.
-    These control the range of values permitted in the field.
+        These control the range of values permitted in the field.
+
+    .. attribute:: step_size
+
+        .. versionadded:: 4.1
+
+        Limit valid inputs to an integral multiple of ``step_size``.
 
 ``GenericIPAddressField``
 -------------------------
@@ -755,21 +777,30 @@ For each field, we describe the default widget used if you don't specify
     * Validates that the given value is an integer. Uses
       :class:`~django.core.validators.MaxValueValidator` and
       :class:`~django.core.validators.MinValueValidator` if ``max_value`` and
-      ``min_value`` are provided. Leading and trailing whitespace is allowed,
-      as in Python's ``int()`` function.
+      ``min_value`` are provided. Uses
+      :class:`~django.core.validators.StepValueValidator` if ``step_size`` is
+      provided. Leading and trailing whitespace is allowed, as in Python's
+      ``int()`` function.
     * Error message keys: ``required``, ``invalid``, ``max_value``,
-      ``min_value``
+      ``min_value``, ``step_size``
 
-    The ``max_value`` and ``min_value`` error messages may contain
-    ``%(limit_value)s``, which will be substituted by the appropriate limit.
+    The ``max_value``, ``min_value`` and ``step_size`` error messages may
+    contain ``%(limit_value)s``, which will be substituted by the appropriate
+    limit.
 
-    Takes two optional arguments for validation:
+    Takes three optional arguments for validation:
 
     .. attribute:: max_value
     .. attribute:: min_value
 
         These control the range of values permitted in the field.
 
+    .. attribute:: step_size
+
+        .. versionadded:: 4.1
+
+        Limit valid inputs to an integral multiple of ``step_size``.
+
 ``JSONField``
 -------------
 
diff --git a/docs/ref/validators.txt b/docs/ref/validators.txt
index 5fe1384bd8..2a7b85e614 100644
--- a/docs/ref/validators.txt
+++ b/docs/ref/validators.txt
@@ -333,3 +333,15 @@ to, or in lieu of custom ``field.clean()`` methods.
 
         The error code used by :exc:`~django.core.exceptions.ValidationError`
         if validation fails. Defaults to ``"null_characters_not_allowed"``.
+
+``StepValueValidator``
+----------------------
+
+.. versionadded:: 4.1
+
+.. class:: StepValueValidator(limit_value, message=None)
+
+    Raises a :exc:`~django.core.exceptions.ValidationError` with a code of
+    ``'step_size'`` if ``value`` is not an integral multiple of
+    ``limit_value``, which can be a float, integer or decimal value or a
+    callable.
diff --git a/docs/releases/4.1.txt b/docs/releases/4.1.txt
index 84eca03563..677e8c0345 100644
--- a/docs/releases/4.1.txt
+++ b/docs/releases/4.1.txt
@@ -297,6 +297,11 @@ Forms
   error messages for invalid number of forms by passing ``'too_few_forms'``
   and ``'too_many_forms'`` keys.
 
+* :class:`~django.forms.IntegerField`, :class:`~django.forms.FloatField`, and
+  :class:`~django.forms.DecimalField` now optionally accept a ``step_size``
+  argument. This is used to set the ``step`` HTML attribute, and is validated
+  on form submission.
+
 Generic Views
 ~~~~~~~~~~~~~
 
@@ -444,7 +449,10 @@ Utilities
 Validators
 ~~~~~~~~~~
 
-* ...
+* The new :class:`~django.core.validators.StepValueValidator` checks if a value
+  is an integral multiple of a given step size. This new validator is used for
+  the new ``step_size`` argument added to form fields representing numeric
+  values.
 
 .. _backwards-incompatible-4.1: