Merge pull request #99 from binary-butterfly/decimal-rounding-mode

DecimalValidator: Add parameter to specify rounding mode (#88)

Author: binaryDiv

docs/03-basic-validators.md

@@ -474,15 +474,23 @@ The `DecimalValidator` accepts decimal numbers **as strings** (e.g. `"1.234"`) a
 Only allows finite numbers in regular decimal notation (e.g. `"1.234"`, `"-42"`, `".00"`, ...), but no other values that
 are accepted by `decimal.Decimal` (e.g. no `Infinity` or `NaN` and no scientific notation).
 
-Optionally a number range (minimum/maximum value either as `Decimal`, integer or decimal string), minimum/maximum number
-of decimal places and a fixed number of decimal places in the output value can be specified.
+Optionally a number range (minimum/maximum value as `Decimal`, integer or decimal string) can be specified using the
+parameters `min_value` and `max_value`, as well as a minimum/maximum number of decimal places in the input using
+`min_places` and `max_places`.
 
-A fixed number of output places will result in rounding according to the current decimal context (see `decimal.getcontext()`),
-by default this means that `"1.49"` will be rounded to `1` and `"1.50"` to `2`.
+You can also specify how many decimal places the output value should have using `output_places`. If this parameter
+is set, the output value will always have the specified amount of decimal places. If rounding is necessary, a
+rounding mode as defined by the `decimal` module (https://docs.python.org/3/library/decimal.html#rounding-modes) is
+used, which can be specified with the `rounding` parameter.
+
+The rounding mode defaults to `decimal.ROUND_HALF_UP`, which basically means that digits 0 to 4 are rounded down and
+digits 5 to 9 are rounded up (e.g. with `output_places=1`, "1.149" would be rounded to "1.1" and "1.150" would be
+rounded to "1.2"). Alternatively, set `rounding=None` to use the rounding mode set by the current decimal context.
 
 **Examples:**
 
 ```python
+import decimal
 from decimal import Decimal
 
 from validataclass.validators import DecimalValidator
@@ -515,6 +523,13 @@ validator.validate("1.23")       # will return Decimal('1.230')
 validator.validate("0.1234")     # will return Decimal('0.123')
 validator.validate("0.1235")     # will return Decimal('0.124')
 validator.validate("100000.00")  # will return Decimal('100000.000')
+
+# Use a different rounding mode to always round numbers up (i.e. away from zero)
+validator = DecimalValidator(output_places=2, rounding=decimal.ROUND_UP)
+validator.validate("1.0")     # will return Decimal('1.00')
+validator.validate("1.001")   # will return Decimal('1.01')
+validator.validate("1.009")   # will return Decimal('1.01')
+validator.validate("-1.001")  # will return Decimal('-1.01')
 ```
 
 
@@ -533,8 +548,8 @@ If you want to accept all three numeric input types (integers, floats and decima
 basically is just a `FloatToDecimalValidator` with those two options always enabled.
 
 Like the `DecimalValidator` it supports the optional parameters `min_value` and `max_value` (specified as `Decimal`,
-decimal strings, floats or integers), as well as `output_places`. However, it **does not** support the `min_places` and
-max_places` parameters (those are technically not possible with floats)!
+decimal strings, floats or integers), as well as `output_places` and `rounding`. However, it **does not** support the
+`min_places` and max_places` parameters (those are technically not possible with floats)!
 
 **Note:** Due to the way that floats work, the resulting decimals can have inaccuracies! It is recommended to use
 `DecimalValidator` with decimal strings instead of floats as input whenever possible. This validator mainly exists for
@@ -582,7 +597,7 @@ always enabled, and is intended as a shortcut.
 
 Like the `FloatToDecimalValidator`, the `NumericValidator` supports the optional parameters `min_value` and `max_value`
 to specify the allowed value range, as well as `output_places` to set a fixed number of decimal places in the output
-value.
+value and `rounding` to set the rounding mode.
 
 **Examples:**
 

src/validataclass/validators/decimal_validator.py

@@ -4,6 +4,7 @@
 Use of this source code is governed by an MIT-style license that can be found in the LICENSE file.
 """
 
+import decimal
 import re
 from decimal import Decimal, InvalidOperation
 from typing import Any, Optional, Union
@@ -23,10 +24,18 @@ class DecimalValidator(StringValidator):
     Only allows finite numbers in regular decimal notation (e.g. '1.234', '-42', '.00', ...), but no other values that
     are accepted by `decimal.Decimal` (e.g. no 'Infinity' or 'NaN' and no scientific notation).
 
-    Optionally a number range (minimum/maximum value as `Decimal`, integer or decimal string), minimum/maximum number of
-    decimal places and a fixed number of decimal places in the output value can be specified. A fixed number of output
-    places will result in rounding according to the current decimal context (see `decimal.getcontext()`), by default
-    this means that "1.49" will be rounded to "1" and "1.50" to "2".
+    Optionally a number range (minimum/maximum value as `Decimal`, integer or decimal string) can be specified using the
+    parameters `min_value` and `max_value`, as well as a minimum/maximum number of decimal places in the input using
+    `min_places` and `max_places`.
+
+    You can also specify how many decimal places the output value should have using `output_places`. If this parameter
+    is set, the output value will always have the specified amount of decimal places. If rounding is necessary, a
+    rounding mode as defined by the `decimal` module (https://docs.python.org/3/library/decimal.html#rounding-modes) is
+    used, which can be specified with the `rounding` parameter.
+
+    The rounding mode defaults to `decimal.ROUND_HALF_UP`, which basically means that digits 0 to 4 are rounded down and
+    digits 5 to 9 are rounded up (e.g. with `output_places=1`, "1.149" would be rounded to "1.1" and "1.150" would be
+    rounded to "1.2"). Alternatively, set `rounding=None` to use the rounding mode set by the current decimal context.
 
     Examples:
 
@@ -48,6 +57,9 @@ class DecimalValidator(StringValidator):
 
     # As above, but only allow 2 or less decimal places in input (e.g. '1' -> '1.00', '1.23' -> '1.23' but '1.234' raises an exception)
     DecimalValidator(max_places=2, output_places=2)
+
+    # Two output places, but always round up (e.g. '1.001' -> '1.01')
+    DecimalValidator(output_places=2, rounding=decimal.ROUND_UP)
     ```
 
     Valid input: `str` in decimal notation
@@ -65,6 +77,9 @@ class DecimalValidator(StringValidator):
     # Quantum used in `.quantize()` to set a fixed number of decimal places (from constructor argument output_places)
     output_quantum: Optional[Decimal] = None
 
+    # Rounding mode (constant from decimal module)
+    rounding: Optional[str] = None
+
     # Precompiled regular expression for decimal values
     decimal_regex: re.Pattern = re.compile(r'[+-]?([0-9]+\.[0-9]*|\.?[0-9]+)')
 
@@ -75,17 +90,19 @@ def __init__(
         min_places: Optional[int] = None,
         max_places: Optional[int] = None,
         output_places: Optional[int] = None,
+        rounding: Optional[str] = decimal.ROUND_HALF_UP,
     ):
         """
-        Create a DecimalValidator with optional value range, optional minimum/maximum number of decimal places and optional number
-        of decimal places in output value.
+        Create a DecimalValidator with optional value range, optional minimum/maximum number of decimal places and
+        optional number of decimal places in output value.
 
         Parameters:
             min_value: Decimal, integer or string, specifies lowest allowed value (default: None, no minimum value)
             max_value: Decimal, integer or string, specifies highest allowed value (default: None, no maximum value)
             min_places: Integer, minimum number of decimal places an input value must have (default: None, no minimum places)
             max_places: Integer, maximum number of decimal places an input value must have (default: None, no maximum places)
             output_places: Integer, number of decimal places the output Decimal object shall have (default: None, output equals input)
+            rounding: Rounding mode for numbers that need to be rounded (default: decimal.ROUND_HALF_UP)
         """
         # Restrict string length
         super().__init__(max_length=40)
@@ -112,6 +129,7 @@ def __init__(
         self.max_value = max_value
         self.min_places = min_places
         self.max_places = max_places
+        self.rounding = rounding
 
         # Set output "quantum" (the output decimal will have the same number of decimal places as this value)
         if output_places is not None:
@@ -151,6 +169,6 @@ def validate(self, input_data: Any, **kwargs) -> Decimal:
 
         # Set fixed number of decimal places (if wanted)
         if self.output_quantum is not None:
-            return decimal_out.quantize(self.output_quantum)
+            return decimal_out.quantize(self.output_quantum, rounding=self.rounding)
         else:
             return decimal_out

src/validataclass/validators/float_to_decimal_validator.py

@@ -4,6 +4,7 @@
 Use of this source code is governed by an MIT-style license that can be found in the LICENSE file.
 """
 
+import decimal
 import math
 from decimal import Decimal
 from typing import Any, Optional, Union, List
@@ -20,9 +21,9 @@ class FloatToDecimalValidator(DecimalValidator):
     """
     Validator that converts float values (IEEE 754) to `decimal.Decimal` objects. Sub class of `DecimalValidator`.
 
-    Optionally a number range can be specified using the parameters 'min_value' and 'max_value' (specified as `Decimal`,
-    decimal strings, floats or integers), as well as a fixed number of decimal places in the output value using
-    'output_places'. These parameters will be passed to the underlying `DecimalValidator`.
+    Optionally the parameters `min_value` and `max_value` (allowed number range), `output_places` (fixed number of
+    decimal places in the output value) and `rounding` (rounding mode as defined in the `decimal` module) can be
+    specified, which will be passed to the underlying `DecimalValidator`.
 
     By default, only floats are allowed as input type. Set `allow_integers=True` to also accept integers as input (e.g.
     `1` results in a `Decimal('1')`). Furthermore, with `allow_strings=True` the validator will also accept decimal
@@ -71,21 +72,23 @@ def __init__(
         min_value: Optional[Union[Decimal, str, float, int]] = None,
         max_value: Optional[Union[Decimal, str, float, int]] = None,
         output_places: Optional[int] = None,
+        rounding: Optional[str] = decimal.ROUND_HALF_UP,
         allow_integers: bool = False,
         allow_strings: bool = False,
     ):
         """
         Create a FloatToDecimalValidator with optional value range and optional number of decimal places in output value.
 
-        The parameters 'min_value', 'max_value' and 'output_places' are passed to the underlying DecimalValidator.
+        The parameters `min_value`, `max_value`, `output_places` and `rounding` are passed to the underlying DecimalValidator.
 
-        The parameters 'allow_integers' and 'allow_strings' can be used to extend the allowed input types. Strings, if
+        The parameters `allow_integers` and `allow_strings` can be used to extend the allowed input types. Strings, if
         accepted, will be simply passed to the DecimalValidator.
 
         Parameters:
             min_value: Decimal, str, float or int, specifies lowest value an input float may have (default: None, no minimum value)
             max_value: Decimal, str, float or int, specifies highest value an input float may have (default: None, no maximum value)
             output_places: Integer, number of decimal places the output Decimal object shall have (default: None, output equals input)
+            rounding: Rounding mode for numbers that need to be rounded (default: decimal.ROUND_HALF_UP)
             allow_integers: Boolean, if True, integers are accepted as input (default: False)
             allow_strings: Boolean, if True, decimal strings are accepted and will be parsed by a DecimalValidator (default: False)
         """
@@ -94,6 +97,7 @@ def __init__(
             min_value=str(min_value) if type(min_value) in [float, int] else min_value,
             max_value=str(max_value) if type(max_value) in [float, int] else max_value,
             output_places=output_places,
+            rounding=rounding,
         )
 
         # Save parameters

src/validataclass/validators/numeric_validator.py

@@ -4,6 +4,7 @@
 Use of this source code is governed by an MIT-style license that can be found in the LICENSE file.
 """
 
+import decimal
 from decimal import Decimal
 from typing import Optional, Union
 
@@ -22,8 +23,8 @@ class NumericValidator(FloatToDecimalValidator):
     This validator is based on the `FloatToDecimalValidator`. In fact, the validator is basically just a shortcut for
     `FloatToDecimalValidator(allow_integers=True, allow_strings=True)`.
 
-    The validator supports the optional parameters 'min_value', 'max_value' and 'output_places' which will be passed
-    to the `FloatToDecimalValidator`.
+    The validator supports the optional parameters `min_value`, `max_value`, `output_places` and `rounding` which will
+    be passed to the `FloatToDecimalValidator`.
 
     NOTE: Due to the way that floats work, the resulting decimals for float input values can have inaccuracies! It is
     recommended to use `DecimalValidator` with decimal strings as input data instead of using float input (e.g. strings
@@ -61,22 +62,25 @@ def __init__(
         min_value: Optional[Union[Decimal, str, float, int]] = None,
         max_value: Optional[Union[Decimal, str, float, int]] = None,
         output_places: Optional[int] = None,
+        rounding: Optional[str] = decimal.ROUND_HALF_UP,
     ):
         """
         Create a `NumericValidator` with optional value range and optional number of decimal places in output value.
 
-        The parameters 'min_value', 'max_value' and 'output_places' are passed to the underlying `FloatToDecimalValidator`.
+        The parameters `min_value`, `max_value`, `output_places` and `rounding` are passed to the underlying DecimalValidator.
 
         Parameters:
             min_value: Decimal, str, float or int, specifies lowest value an input float may have (default: None, no minimum value)
             max_value: Decimal, str, float or int, specifies highest value an input float may have (default: None, no maximum value)
             output_places: Integer, number of decimal places the output Decimal object shall have (default: None, output equals input)
+            rounding: Rounding mode for numbers that need to be rounded (default: decimal.ROUND_HALF_UP)
         """
         # Initialize base FloatToDecimalValidator with allow_integers and allow_strings always being enabled
         super().__init__(
             min_value=min_value,
             max_value=max_value,
             output_places=output_places,
+            rounding=rounding,
             allow_integers=True,
             allow_strings=True,
         )

tests/test_utils.py

@@ -4,7 +4,8 @@
 Use of this source code is governed by an MIT-style license that can be found in the LICENSE file.
 """
 
-from typing import Any, List
+from decimal import Decimal
+from typing import Any, List, Union
 
 from validataclass.validators import Validator
 
@@ -73,6 +74,14 @@ def unpack_params(*args) -> List[tuple]:
 UNSET_PARAMETER = object()
 
 
+def assert_decimal(actual: Decimal, expected: Union[Decimal, str]) -> None:
+    """
+    Assert that `actual` is of type `Decimal` and has the same decimal value (string comparison) as `expected`.
+    """
+    assert type(actual) is Decimal
+    assert str(actual) == str(expected)
+
+
 # Test validator that parses context arguments
 class UnitTestContextValidator(Validator):
     """