Document decimal_quantization usage.

babel/numbers.py

@@ -341,9 +341,20 @@ def format_decimal(
     >>> format_decimal(12345.5, locale='en_US')
     u'12,345.5'
 
+    By default the locale is allowed to truncate and round a high-precision
+    number by forcing its format pattern onto the decimal part. You can bypass
+    this behavior with the `decimal_quantization` parameter:
+
+    >>> format_decimal(1.2346, locale='en_US')
+    u'1.235'
+    >>> format_decimal(1.2346, locale='en_US', decimal_quantization=False)
+    u'1.2346'
+
     :param number: the number to format
     :param format:
     :param locale: the `Locale` object or locale identifier
+    :param decimal_quantization: Truncate and round high-precision numbers to
+                                 the format pattern. Defaults to `True`.
     """
     locale = Locale.parse(locale)
     if not format:
@@ -409,12 +420,23 @@ def format_currency(
         ...
     UnknownCurrencyFormatError: "'unknown' is not a known currency format type"
 
+    By default the locale is allowed to truncate and round a high-precision
+    number by forcing its format pattern onto the decimal part. You can bypass
+    this behavior with the `decimal_quantization` parameter:
+
+    >>> format_currency(1099.9876, 'USD', locale='en_US')
+    u'$1,099.99'
+    >>> format_currency(1099.9876, 'USD', locale='en_US', decimal_quantization=False)
+    u'$1,099.9876'
+
     :param number: the number to format
     :param currency: the currency code
     :param format: the format string to use
     :param locale: the `Locale` object or locale identifier
     :param currency_digits: use the currency's natural number of decimal digits
     :param format_type: the currency format type to use
+    :param decimal_quantization: Truncate and round high-precision numbers to
+                                 the format pattern. Defaults to `True`.
     """
     locale = Locale.parse(locale)
     if format:
@@ -447,9 +469,20 @@ def format_percent(
     >>> format_percent(25.1234, u'#,##0\u2030', locale='en_US')
     u'25,123\u2030'
 
+    By default the locale is allowed to truncate and round a high-precision
+    number by forcing its format pattern onto the decimal part. You can bypass
+    this behavior with the `decimal_quantization` parameter:
+
+    >>> format_percent(23.9876, locale='en_US')
+    u'2,399%'
+    >>> format_percent(23.9876, locale='en_US', decimal_quantization=False)
+    u'2,398.76%'
+
     :param number: the percent number to format
     :param format:
     :param locale: the `Locale` object or locale identifier
+    :param decimal_quantization: Truncate and round high-precision numbers to
+                                 the format pattern. Defaults to `True`.
     """
     locale = Locale.parse(locale)
     if not format:
@@ -471,9 +504,20 @@ def format_scientific(
     >>> format_scientific(1234567, u'##0E00', locale='en_US')
     u'1E06'
 
+    By default the locale is allowed to truncate and round a high-precision
+    number by forcing its format pattern onto the decimal part. You can bypass
+    this behavior with the `decimal_quantization` parameter:
+
+    >>> format_scientific(1234.9876, locale='en_US')
+    u'1E3'
+    >>> format_scientific(1234.9876, locale='en_US', decimal_quantization=False)
+    u'1.2349876E3'
+
     :param number: the number to format
     :param format:
     :param locale: the `Locale` object or locale identifier
+    :param decimal_quantization: Truncate and round high-precision numbers to
+                                 the format pattern. Defaults to `True`.
     """
     locale = Locale.parse(locale)
     if not format: