Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/babel/numbers.py: 9%
Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1"""
2 babel.numbers
3 ~~~~~~~~~~~~~
5 Locale dependent formatting and parsing of numeric data.
7 The default locale for the functions in this module is determined by the
8 following environment variables, in that order:
10 * ``LC_NUMERIC``,
11 * ``LC_ALL``, and
12 * ``LANG``
14 :copyright: (c) 2013-2024 by the Babel Team.
15 :license: BSD, see LICENSE for more details.
16"""
17# TODO:
18# Padding and rounding increments in pattern:
19# - https://www.unicode.org/reports/tr35/ (Appendix G.6)
20from __future__ import annotations
22import datetime
23import decimal
24import re
25import warnings
26from typing import TYPE_CHECKING, Any, cast, overload
28from babel.core import Locale, default_locale, get_global
29from babel.localedata import LocaleDataDict
31if TYPE_CHECKING:
32 from typing_extensions import Literal
34LC_NUMERIC = default_locale('LC_NUMERIC')
37class UnknownCurrencyError(Exception):
38 """Exception thrown when a currency is requested for which no data is available.
39 """
41 def __init__(self, identifier: str) -> None:
42 """Create the exception.
43 :param identifier: the identifier string of the unsupported currency
44 """
45 Exception.__init__(self, f"Unknown currency {identifier!r}.")
47 #: The identifier of the locale that could not be found.
48 self.identifier = identifier
51def list_currencies(locale: Locale | str | None = None) -> set[str]:
52 """ Return a `set` of normalized currency codes.
54 .. versionadded:: 2.5.0
56 :param locale: filters returned currency codes by the provided locale.
57 Expected to be a locale instance or code. If no locale is
58 provided, returns the list of all currencies from all
59 locales.
60 """
61 # Get locale-scoped currencies.
62 if locale:
63 return set(Locale.parse(locale).currencies)
64 return set(get_global('all_currencies'))
67def validate_currency(currency: str, locale: Locale | str | None = None) -> None:
68 """ Check the currency code is recognized by Babel.
70 Accepts a ``locale`` parameter for fined-grained validation, working as
71 the one defined above in ``list_currencies()`` method.
73 Raises a `UnknownCurrencyError` exception if the currency is unknown to Babel.
74 """
75 if currency not in list_currencies(locale):
76 raise UnknownCurrencyError(currency)
79def is_currency(currency: str, locale: Locale | str | None = None) -> bool:
80 """ Returns `True` only if a currency is recognized by Babel.
82 This method always return a Boolean and never raise.
83 """
84 if not currency or not isinstance(currency, str):
85 return False
86 try:
87 validate_currency(currency, locale)
88 except UnknownCurrencyError:
89 return False
90 return True
93def normalize_currency(currency: str, locale: Locale | str | None = None) -> str | None:
94 """Returns the normalized identifier of any currency code.
96 Accepts a ``locale`` parameter for fined-grained validation, working as
97 the one defined above in ``list_currencies()`` method.
99 Returns None if the currency is unknown to Babel.
100 """
101 if isinstance(currency, str):
102 currency = currency.upper()
103 if not is_currency(currency, locale):
104 return None
105 return currency
108def get_currency_name(
109 currency: str,
110 count: float | decimal.Decimal | None = None,
111 locale: Locale | str | None = LC_NUMERIC,
112) -> str:
113 """Return the name used by the locale for the specified currency.
115 >>> get_currency_name('USD', locale='en_US')
116 u'US Dollar'
118 .. versionadded:: 0.9.4
120 :param currency: the currency code.
121 :param count: the optional count. If provided the currency name
122 will be pluralized to that number if possible.
123 :param locale: the `Locale` object or locale identifier.
124 """
125 loc = Locale.parse(locale)
126 if count is not None:
127 try:
128 plural_form = loc.plural_form(count)
129 except (OverflowError, ValueError):
130 plural_form = 'other'
131 plural_names = loc._data['currency_names_plural']
132 if currency in plural_names:
133 currency_plural_names = plural_names[currency]
134 if plural_form in currency_plural_names:
135 return currency_plural_names[plural_form]
136 if 'other' in currency_plural_names:
137 return currency_plural_names['other']
138 return loc.currencies.get(currency, currency)
141def get_currency_symbol(currency: str, locale: Locale | str | None = LC_NUMERIC) -> str:
142 """Return the symbol used by the locale for the specified currency.
144 >>> get_currency_symbol('USD', locale='en_US')
145 u'$'
147 :param currency: the currency code.
148 :param locale: the `Locale` object or locale identifier.
149 """
150 return Locale.parse(locale).currency_symbols.get(currency, currency)
153def get_currency_precision(currency: str) -> int:
154 """Return currency's precision.
156 Precision is the number of decimals found after the decimal point in the
157 currency's format pattern.
159 .. versionadded:: 2.5.0
161 :param currency: the currency code.
162 """
163 precisions = get_global('currency_fractions')
164 return precisions.get(currency, precisions['DEFAULT'])[0]
167def get_currency_unit_pattern(
168 currency: str,
169 count: float | decimal.Decimal | None = None,
170 locale: Locale | str | None = LC_NUMERIC,
171) -> str:
172 """
173 Return the unit pattern used for long display of a currency value
174 for a given locale.
175 This is a string containing ``{0}`` where the numeric part
176 should be substituted and ``{1}`` where the currency long display
177 name should be substituted.
179 >>> get_currency_unit_pattern('USD', locale='en_US', count=10)
180 u'{0} {1}'
182 .. versionadded:: 2.7.0
184 :param currency: the currency code.
185 :param count: the optional count. If provided the unit
186 pattern for that number will be returned.
187 :param locale: the `Locale` object or locale identifier.
188 """
189 loc = Locale.parse(locale)
190 if count is not None:
191 plural_form = loc.plural_form(count)
192 try:
193 return loc._data['currency_unit_patterns'][plural_form]
194 except LookupError:
195 # Fall back to 'other'
196 pass
198 return loc._data['currency_unit_patterns']['other']
201@overload
202def get_territory_currencies(
203 territory: str,
204 start_date: datetime.date | None = ...,
205 end_date: datetime.date | None = ...,
206 tender: bool = ...,
207 non_tender: bool = ...,
208 include_details: Literal[False] = ...,
209) -> list[str]:
210 ... # pragma: no cover
213@overload
214def get_territory_currencies(
215 territory: str,
216 start_date: datetime.date | None = ...,
217 end_date: datetime.date | None = ...,
218 tender: bool = ...,
219 non_tender: bool = ...,
220 include_details: Literal[True] = ...,
221) -> list[dict[str, Any]]:
222 ... # pragma: no cover
225def get_territory_currencies(
226 territory: str,
227 start_date: datetime.date | None = None,
228 end_date: datetime.date | None = None,
229 tender: bool = True,
230 non_tender: bool = False,
231 include_details: bool = False,
232) -> list[str] | list[dict[str, Any]]:
233 """Returns the list of currencies for the given territory that are valid for
234 the given date range. In addition to that the currency database
235 distinguishes between tender and non-tender currencies. By default only
236 tender currencies are returned.
238 The return value is a list of all currencies roughly ordered by the time
239 of when the currency became active. The longer the currency is being in
240 use the more to the left of the list it will be.
242 The start date defaults to today. If no end date is given it will be the
243 same as the start date. Otherwise a range can be defined. For instance
244 this can be used to find the currencies in use in Austria between 1995 and
245 2011:
247 >>> from datetime import date
248 >>> get_territory_currencies('AT', date(1995, 1, 1), date(2011, 1, 1))
249 ['ATS', 'EUR']
251 Likewise it's also possible to find all the currencies in use on a
252 single date:
254 >>> get_territory_currencies('AT', date(1995, 1, 1))
255 ['ATS']
256 >>> get_territory_currencies('AT', date(2011, 1, 1))
257 ['EUR']
259 By default the return value only includes tender currencies. This
260 however can be changed:
262 >>> get_territory_currencies('US')
263 ['USD']
264 >>> get_territory_currencies('US', tender=False, non_tender=True,
265 ... start_date=date(2014, 1, 1))
266 ['USN', 'USS']
268 .. versionadded:: 2.0
270 :param territory: the name of the territory to find the currency for.
271 :param start_date: the start date. If not given today is assumed.
272 :param end_date: the end date. If not given the start date is assumed.
273 :param tender: controls whether tender currencies should be included.
274 :param non_tender: controls whether non-tender currencies should be
275 included.
276 :param include_details: if set to `True`, instead of returning currency
277 codes the return value will be dictionaries
278 with detail information. In that case each
279 dictionary will have the keys ``'currency'``,
280 ``'from'``, ``'to'``, and ``'tender'``.
281 """
282 currencies = get_global('territory_currencies')
283 if start_date is None:
284 start_date = datetime.date.today()
285 elif isinstance(start_date, datetime.datetime):
286 start_date = start_date.date()
287 if end_date is None:
288 end_date = start_date
289 elif isinstance(end_date, datetime.datetime):
290 end_date = end_date.date()
292 curs = currencies.get(territory.upper(), ())
293 # TODO: validate that the territory exists
295 def _is_active(start, end):
296 return (start is None or start <= end_date) and \
297 (end is None or end >= start_date)
299 result = []
300 for currency_code, start, end, is_tender in curs:
301 if start:
302 start = datetime.date(*start)
303 if end:
304 end = datetime.date(*end)
305 if ((is_tender and tender) or
306 (not is_tender and non_tender)) and _is_active(start, end):
307 if include_details:
308 result.append({
309 'currency': currency_code,
310 'from': start,
311 'to': end,
312 'tender': is_tender,
313 })
314 else:
315 result.append(currency_code)
317 return result
320def _get_numbering_system(locale: Locale, numbering_system: Literal["default"] | str = "latn") -> str:
321 if numbering_system == "default":
322 return locale.default_numbering_system
323 else:
324 return numbering_system
327def _get_number_symbols(
328 locale: Locale | str | None,
329 *,
330 numbering_system: Literal["default"] | str = "latn",
331) -> LocaleDataDict:
332 parsed_locale = Locale.parse(locale)
333 numbering_system = _get_numbering_system(parsed_locale, numbering_system)
334 try:
335 return parsed_locale.number_symbols[numbering_system]
336 except KeyError as error:
337 raise UnsupportedNumberingSystemError(f"Unknown numbering system {numbering_system} for Locale {parsed_locale}.") from error
340class UnsupportedNumberingSystemError(Exception):
341 """Exception thrown when an unsupported numbering system is requested for the given Locale."""
342 pass
345def get_decimal_symbol(
346 locale: Locale | str | None = LC_NUMERIC,
347 *,
348 numbering_system: Literal["default"] | str = "latn",
349) -> str:
350 """Return the symbol used by the locale to separate decimal fractions.
352 >>> get_decimal_symbol('en_US')
353 u'.'
354 >>> get_decimal_symbol('ar_EG', numbering_system='default')
355 u'٫'
356 >>> get_decimal_symbol('ar_EG', numbering_system='latn')
357 u'.'
359 :param locale: the `Locale` object or locale identifier
360 :param numbering_system: The numbering system used for fetching the symbol. Defaults to "latn".
361 The special value "default" will use the default numbering system of the locale.
362 :raise `UnsupportedNumberingSystemError`: If the numbering system is not supported by the locale.
363 """
364 return _get_number_symbols(locale, numbering_system=numbering_system).get('decimal', '.')
367def get_plus_sign_symbol(
368 locale: Locale | str | None = LC_NUMERIC,
369 *,
370 numbering_system: Literal["default"] | str = "latn",
371) -> str:
372 """Return the plus sign symbol used by the current locale.
374 >>> get_plus_sign_symbol('en_US')
375 u'+'
376 >>> get_plus_sign_symbol('ar_EG', numbering_system='default')
377 u'\u061c+'
378 >>> get_plus_sign_symbol('ar_EG', numbering_system='latn')
379 u'\u200e+'
381 :param locale: the `Locale` object or locale identifier
382 :param numbering_system: The numbering system used for fetching the symbol. Defaults to "latn".
383 The special value "default" will use the default numbering system of the locale.
384 :raise `UnsupportedNumberingSystemError`: if the numbering system is not supported by the locale.
385 """
386 return _get_number_symbols(locale, numbering_system=numbering_system).get('plusSign', '+')
389def get_minus_sign_symbol(
390 locale: Locale | str | None = LC_NUMERIC,
391 *,
392 numbering_system: Literal["default"] | str = "latn",
393) -> str:
394 """Return the plus sign symbol used by the current locale.
396 >>> get_minus_sign_symbol('en_US')
397 u'-'
398 >>> get_minus_sign_symbol('ar_EG', numbering_system='default')
399 u'\u061c-'
400 >>> get_minus_sign_symbol('ar_EG', numbering_system='latn')
401 u'\u200e-'
403 :param locale: the `Locale` object or locale identifier
404 :param numbering_system: The numbering system used for fetching the symbol. Defaults to "latn".
405 The special value "default" will use the default numbering system of the locale.
406 :raise `UnsupportedNumberingSystemError`: if the numbering system is not supported by the locale.
407 """
408 return _get_number_symbols(locale, numbering_system=numbering_system).get('minusSign', '-')
411def get_exponential_symbol(
412 locale: Locale | str | None = LC_NUMERIC,
413 *,
414 numbering_system: Literal["default"] | str = "latn",
415) -> str:
416 """Return the symbol used by the locale to separate mantissa and exponent.
418 >>> get_exponential_symbol('en_US')
419 u'E'
420 >>> get_exponential_symbol('ar_EG', numbering_system='default')
421 u'أس'
422 >>> get_exponential_symbol('ar_EG', numbering_system='latn')
423 u'E'
425 :param locale: the `Locale` object or locale identifier
426 :param numbering_system: The numbering system used for fetching the symbol. Defaults to "latn".
427 The special value "default" will use the default numbering system of the locale.
428 :raise `UnsupportedNumberingSystemError`: if the numbering system is not supported by the locale.
429 """
430 return _get_number_symbols(locale, numbering_system=numbering_system).get('exponential', 'E')
433def get_group_symbol(
434 locale: Locale | str | None = LC_NUMERIC,
435 *,
436 numbering_system: Literal["default"] | str = "latn",
437) -> str:
438 """Return the symbol used by the locale to separate groups of thousands.
440 >>> get_group_symbol('en_US')
441 u','
442 >>> get_group_symbol('ar_EG', numbering_system='default')
443 u'٬'
444 >>> get_group_symbol('ar_EG', numbering_system='latn')
445 u','
447 :param locale: the `Locale` object or locale identifier
448 :param numbering_system: The numbering system used for fetching the symbol. Defaults to "latn".
449 The special value "default" will use the default numbering system of the locale.
450 :raise `UnsupportedNumberingSystemError`: if the numbering system is not supported by the locale.
451 """
452 return _get_number_symbols(locale, numbering_system=numbering_system).get('group', ',')
455def get_infinity_symbol(
456 locale: Locale | str | None = LC_NUMERIC,
457 *,
458 numbering_system: Literal["default"] | str = "latn",
459) -> str:
460 """Return the symbol used by the locale to represent infinity.
462 >>> get_infinity_symbol('en_US')
463 u'∞'
464 >>> get_infinity_symbol('ar_EG', numbering_system='default')
465 u'∞'
466 >>> get_infinity_symbol('ar_EG', numbering_system='latn')
467 u'∞'
469 :param locale: the `Locale` object or locale identifier
470 :param numbering_system: The numbering system used for fetching the symbol. Defaults to "latn".
471 The special value "default" will use the default numbering system of the locale.
472 :raise `UnsupportedNumberingSystemError`: if the numbering system is not supported by the locale.
473 """
474 return _get_number_symbols(locale, numbering_system=numbering_system).get('infinity', '∞')
477def format_number(number: float | decimal.Decimal | str, locale: Locale | str | None = LC_NUMERIC) -> str:
478 """Return the given number formatted for a specific locale.
480 >>> format_number(1099, locale='en_US') # doctest: +SKIP
481 u'1,099'
482 >>> format_number(1099, locale='de_DE') # doctest: +SKIP
483 u'1.099'
485 .. deprecated:: 2.6.0
487 Use babel.numbers.format_decimal() instead.
489 :param number: the number to format
490 :param locale: the `Locale` object or locale identifier
493 """
494 warnings.warn('Use babel.numbers.format_decimal() instead.', DeprecationWarning, stacklevel=2)
495 return format_decimal(number, locale=locale)
498def get_decimal_precision(number: decimal.Decimal) -> int:
499 """Return maximum precision of a decimal instance's fractional part.
501 Precision is extracted from the fractional part only.
502 """
503 # Copied from: https://github.com/mahmoud/boltons/pull/59
504 assert isinstance(number, decimal.Decimal)
505 decimal_tuple = number.normalize().as_tuple()
506 # Note: DecimalTuple.exponent can be 'n' (qNaN), 'N' (sNaN), or 'F' (Infinity)
507 if not isinstance(decimal_tuple.exponent, int) or decimal_tuple.exponent >= 0:
508 return 0
509 return abs(decimal_tuple.exponent)
512def get_decimal_quantum(precision: int | decimal.Decimal) -> decimal.Decimal:
513 """Return minimal quantum of a number, as defined by precision."""
514 assert isinstance(precision, (int, decimal.Decimal))
515 return decimal.Decimal(10) ** (-precision)
518def format_decimal(
519 number: float | decimal.Decimal | str,
520 format: str | NumberPattern | None = None,
521 locale: Locale | str | None = LC_NUMERIC,
522 decimal_quantization: bool = True,
523 group_separator: bool = True,
524 *,
525 numbering_system: Literal["default"] | str = "latn",
526) -> str:
527 """Return the given decimal number formatted for a specific locale.
529 >>> format_decimal(1.2345, locale='en_US')
530 u'1.234'
531 >>> format_decimal(1.2346, locale='en_US')
532 u'1.235'
533 >>> format_decimal(-1.2346, locale='en_US')
534 u'-1.235'
535 >>> format_decimal(1.2345, locale='sv_SE')
536 u'1,234'
537 >>> format_decimal(1.2345, locale='de')
538 u'1,234'
539 >>> format_decimal(1.2345, locale='ar_EG', numbering_system='default')
540 u'1٫234'
541 >>> format_decimal(1.2345, locale='ar_EG', numbering_system='latn')
542 u'1.234'
544 The appropriate thousands grouping and the decimal separator are used for
545 each locale:
547 >>> format_decimal(12345.5, locale='en_US')
548 u'12,345.5'
550 By default the locale is allowed to truncate and round a high-precision
551 number by forcing its format pattern onto the decimal part. You can bypass
552 this behavior with the `decimal_quantization` parameter:
554 >>> format_decimal(1.2346, locale='en_US')
555 u'1.235'
556 >>> format_decimal(1.2346, locale='en_US', decimal_quantization=False)
557 u'1.2346'
558 >>> format_decimal(12345.67, locale='fr_CA', group_separator=False)
559 u'12345,67'
560 >>> format_decimal(12345.67, locale='en_US', group_separator=True)
561 u'12,345.67'
563 :param number: the number to format
564 :param format:
565 :param locale: the `Locale` object or locale identifier
566 :param decimal_quantization: Truncate and round high-precision numbers to
567 the format pattern. Defaults to `True`.
568 :param group_separator: Boolean to switch group separator on/off in a locale's
569 number format.
570 :param numbering_system: The numbering system used for formatting number symbols. Defaults to "latn".
571 The special value "default" will use the default numbering system of the locale.
572 :raise `UnsupportedNumberingSystemError`: If the numbering system is not supported by the locale.
573 """
574 locale = Locale.parse(locale)
575 if format is None:
576 format = locale.decimal_formats[format]
577 pattern = parse_pattern(format)
578 return pattern.apply(
579 number, locale, decimal_quantization=decimal_quantization, group_separator=group_separator, numbering_system=numbering_system)
582def format_compact_decimal(
583 number: float | decimal.Decimal | str,
584 *,
585 format_type: Literal["short", "long"] = "short",
586 locale: Locale | str | None = LC_NUMERIC,
587 fraction_digits: int = 0,
588 numbering_system: Literal["default"] | str = "latn",
589) -> str:
590 """Return the given decimal number formatted for a specific locale in compact form.
592 >>> format_compact_decimal(12345, format_type="short", locale='en_US')
593 u'12K'
594 >>> format_compact_decimal(12345, format_type="long", locale='en_US')
595 u'12 thousand'
596 >>> format_compact_decimal(12345, format_type="short", locale='en_US', fraction_digits=2)
597 u'12.34K'
598 >>> format_compact_decimal(1234567, format_type="short", locale="ja_JP")
599 u'123万'
600 >>> format_compact_decimal(2345678, format_type="long", locale="mk")
601 u'2 милиони'
602 >>> format_compact_decimal(21000000, format_type="long", locale="mk")
603 u'21 милион'
604 >>> format_compact_decimal(12345, format_type="short", locale='ar_EG', fraction_digits=2, numbering_system='default')
605 u'12٫34\xa0ألف'
607 :param number: the number to format
608 :param format_type: Compact format to use ("short" or "long")
609 :param locale: the `Locale` object or locale identifier
610 :param fraction_digits: Number of digits after the decimal point to use. Defaults to `0`.
611 :param numbering_system: The numbering system used for formatting number symbols. Defaults to "latn".
612 The special value "default" will use the default numbering system of the locale.
613 :raise `UnsupportedNumberingSystemError`: If the numbering system is not supported by the locale.
614 """
615 locale = Locale.parse(locale)
616 compact_format = locale.compact_decimal_formats[format_type]
617 number, format = _get_compact_format(number, compact_format, locale, fraction_digits)
618 # Did not find a format, fall back.
619 if format is None:
620 format = locale.decimal_formats[None]
621 pattern = parse_pattern(format)
622 return pattern.apply(number, locale, decimal_quantization=False, numbering_system=numbering_system)
625def _get_compact_format(
626 number: float | decimal.Decimal | str,
627 compact_format: LocaleDataDict,
628 locale: Locale,
629 fraction_digits: int,
630) -> tuple[decimal.Decimal, NumberPattern | None]:
631 """Returns the number after dividing by the unit and the format pattern to use.
632 The algorithm is described here:
633 https://www.unicode.org/reports/tr35/tr35-45/tr35-numbers.html#Compact_Number_Formats.
634 """
635 if not isinstance(number, decimal.Decimal):
636 number = decimal.Decimal(str(number))
637 if number.is_nan() or number.is_infinite():
638 return number, None
639 format = None
640 for magnitude in sorted([int(m) for m in compact_format["other"]], reverse=True):
641 if abs(number) >= magnitude:
642 # check the pattern using "other" as the amount
643 format = compact_format["other"][str(magnitude)]
644 pattern = parse_pattern(format).pattern
645 # if the pattern is "0", we do not divide the number
646 if pattern == "0":
647 break
648 # otherwise, we need to divide the number by the magnitude but remove zeros
649 # equal to the number of 0's in the pattern minus 1
650 number = cast(decimal.Decimal, number / (magnitude // (10 ** (pattern.count("0") - 1))))
651 # round to the number of fraction digits requested
652 rounded = round(number, fraction_digits)
653 # if the remaining number is singular, use the singular format
654 plural_form = locale.plural_form(abs(number))
655 if plural_form not in compact_format:
656 plural_form = "other"
657 if number == 1 and "1" in compact_format:
658 plural_form = "1"
659 format = compact_format[plural_form][str(magnitude)]
660 number = rounded
661 break
662 return number, format
665class UnknownCurrencyFormatError(KeyError):
666 """Exception raised when an unknown currency format is requested."""
669def format_currency(
670 number: float | decimal.Decimal | str,
671 currency: str,
672 format: str | NumberPattern | None = None,
673 locale: Locale | str | None = LC_NUMERIC,
674 currency_digits: bool = True,
675 format_type: Literal["name", "standard", "accounting"] = "standard",
676 decimal_quantization: bool = True,
677 group_separator: bool = True,
678 *,
679 numbering_system: Literal["default"] | str = "latn",
680) -> str:
681 """Return formatted currency value.
683 >>> format_currency(1099.98, 'USD', locale='en_US')
684 '$1,099.98'
685 >>> format_currency(1099.98, 'USD', locale='es_CO')
686 u'US$1.099,98'
687 >>> format_currency(1099.98, 'EUR', locale='de_DE')
688 u'1.099,98\\xa0\\u20ac'
689 >>> format_currency(1099.98, 'EGP', locale='ar_EG', numbering_system='default')
690 u'\u200f1٬099٫98\xa0ج.م.\u200f'
692 The format can also be specified explicitly. The currency is
693 placed with the '¤' sign. As the sign gets repeated the format
694 expands (¤ being the symbol, ¤¤ is the currency abbreviation and
695 ¤¤¤ is the full name of the currency):
697 >>> format_currency(1099.98, 'EUR', u'\xa4\xa4 #,##0.00', locale='en_US')
698 u'EUR 1,099.98'
699 >>> format_currency(1099.98, 'EUR', u'#,##0.00 \xa4\xa4\xa4', locale='en_US')
700 u'1,099.98 euros'
702 Currencies usually have a specific number of decimal digits. This function
703 favours that information over the given format:
705 >>> format_currency(1099.98, 'JPY', locale='en_US')
706 u'\\xa51,100'
707 >>> format_currency(1099.98, 'COP', u'#,##0.00', locale='es_ES')
708 u'1.099,98'
710 However, the number of decimal digits can be overridden from the currency
711 information, by setting the last parameter to ``False``:
713 >>> format_currency(1099.98, 'JPY', locale='en_US', currency_digits=False)
714 u'\\xa51,099.98'
715 >>> format_currency(1099.98, 'COP', u'#,##0.00', locale='es_ES', currency_digits=False)
716 u'1.099,98'
718 If a format is not specified the type of currency format to use
719 from the locale can be specified:
721 >>> format_currency(1099.98, 'EUR', locale='en_US', format_type='standard')
722 u'\\u20ac1,099.98'
724 When the given currency format type is not available, an exception is
725 raised:
727 >>> format_currency('1099.98', 'EUR', locale='root', format_type='unknown')
728 Traceback (most recent call last):
729 ...
730 UnknownCurrencyFormatError: "'unknown' is not a known currency format type"
732 >>> format_currency(101299.98, 'USD', locale='en_US', group_separator=False)
733 u'$101299.98'
735 >>> format_currency(101299.98, 'USD', locale='en_US', group_separator=True)
736 u'$101,299.98'
738 You can also pass format_type='name' to use long display names. The order of
739 the number and currency name, along with the correct localized plural form
740 of the currency name, is chosen according to locale:
742 >>> format_currency(1, 'USD', locale='en_US', format_type='name')
743 u'1.00 US dollar'
744 >>> format_currency(1099.98, 'USD', locale='en_US', format_type='name')
745 u'1,099.98 US dollars'
746 >>> format_currency(1099.98, 'USD', locale='ee', format_type='name')
747 u'us ga dollar 1,099.98'
749 By default the locale is allowed to truncate and round a high-precision
750 number by forcing its format pattern onto the decimal part. You can bypass
751 this behavior with the `decimal_quantization` parameter:
753 >>> format_currency(1099.9876, 'USD', locale='en_US')
754 u'$1,099.99'
755 >>> format_currency(1099.9876, 'USD', locale='en_US', decimal_quantization=False)
756 u'$1,099.9876'
758 :param number: the number to format
759 :param currency: the currency code
760 :param format: the format string to use
761 :param locale: the `Locale` object or locale identifier
762 :param currency_digits: use the currency's natural number of decimal digits
763 :param format_type: the currency format type to use
764 :param decimal_quantization: Truncate and round high-precision numbers to
765 the format pattern. Defaults to `True`.
766 :param group_separator: Boolean to switch group separator on/off in a locale's
767 number format.
768 :param numbering_system: The numbering system used for formatting number symbols. Defaults to "latn".
769 The special value "default" will use the default numbering system of the locale.
770 :raise `UnsupportedNumberingSystemError`: If the numbering system is not supported by the locale.
771 """
772 if format_type == 'name':
773 return _format_currency_long_name(number, currency, format=format,
774 locale=locale, currency_digits=currency_digits,
775 decimal_quantization=decimal_quantization, group_separator=group_separator,
776 numbering_system=numbering_system)
777 locale = Locale.parse(locale)
778 if format:
779 pattern = parse_pattern(format)
780 else:
781 try:
782 pattern = locale.currency_formats[format_type]
783 except KeyError:
784 raise UnknownCurrencyFormatError(f"{format_type!r} is not a known currency format type") from None
786 return pattern.apply(
787 number, locale, currency=currency, currency_digits=currency_digits,
788 decimal_quantization=decimal_quantization, group_separator=group_separator, numbering_system=numbering_system)
791def _format_currency_long_name(
792 number: float | decimal.Decimal | str,
793 currency: str,
794 format: str | NumberPattern | None = None,
795 locale: Locale | str | None = LC_NUMERIC,
796 currency_digits: bool = True,
797 format_type: Literal["name", "standard", "accounting"] = "standard",
798 decimal_quantization: bool = True,
799 group_separator: bool = True,
800 *,
801 numbering_system: Literal["default"] | str = "latn",
802) -> str:
803 # Algorithm described here:
804 # https://www.unicode.org/reports/tr35/tr35-numbers.html#Currencies
805 locale = Locale.parse(locale)
806 # Step 1.
807 # There are no examples of items with explicit count (0 or 1) in current
808 # locale data. So there is no point implementing that.
809 # Step 2.
811 # Correct number to numeric type, important for looking up plural rules:
812 number_n = float(number) if isinstance(number, str) else number
814 # Step 3.
815 unit_pattern = get_currency_unit_pattern(currency, count=number_n, locale=locale)
817 # Step 4.
818 display_name = get_currency_name(currency, count=number_n, locale=locale)
820 # Step 5.
821 if not format:
822 format = locale.decimal_formats[None]
824 pattern = parse_pattern(format)
826 number_part = pattern.apply(
827 number, locale, currency=currency, currency_digits=currency_digits,
828 decimal_quantization=decimal_quantization, group_separator=group_separator, numbering_system=numbering_system)
830 return unit_pattern.format(number_part, display_name)
833def format_compact_currency(
834 number: float | decimal.Decimal | str,
835 currency: str,
836 *,
837 format_type: Literal["short"] = "short",
838 locale: Locale | str | None = LC_NUMERIC,
839 fraction_digits: int = 0,
840 numbering_system: Literal["default"] | str = "latn",
841) -> str:
842 """Format a number as a currency value in compact form.
844 >>> format_compact_currency(12345, 'USD', locale='en_US')
845 u'$12K'
846 >>> format_compact_currency(123456789, 'USD', locale='en_US', fraction_digits=2)
847 u'$123.46M'
848 >>> format_compact_currency(123456789, 'EUR', locale='de_DE', fraction_digits=1)
849 '123,5\xa0Mio.\xa0€'
851 :param number: the number to format
852 :param currency: the currency code
853 :param format_type: the compact format type to use. Defaults to "short".
854 :param locale: the `Locale` object or locale identifier
855 :param fraction_digits: Number of digits after the decimal point to use. Defaults to `0`.
856 :param numbering_system: The numbering system used for formatting number symbols. Defaults to "latn".
857 The special value "default" will use the default numbering system of the locale.
858 :raise `UnsupportedNumberingSystemError`: If the numbering system is not supported by the locale.
859 """
860 locale = Locale.parse(locale)
861 try:
862 compact_format = locale.compact_currency_formats[format_type]
863 except KeyError as error:
864 raise UnknownCurrencyFormatError(f"{format_type!r} is not a known compact currency format type") from error
865 number, format = _get_compact_format(number, compact_format, locale, fraction_digits)
866 # Did not find a format, fall back.
867 if format is None or "¤" not in str(format):
868 # find first format that has a currency symbol
869 for magnitude in compact_format['other']:
870 format = compact_format['other'][magnitude].pattern
871 if '¤' not in format:
872 continue
873 # remove characters that are not the currency symbol, 0's or spaces
874 format = re.sub(r'[^0\s\¤]', '', format)
875 # compress adjacent spaces into one
876 format = re.sub(r'(\s)\s+', r'\1', format).strip()
877 break
878 if format is None:
879 raise ValueError('No compact currency format found for the given number and locale.')
880 pattern = parse_pattern(format)
881 return pattern.apply(number, locale, currency=currency, currency_digits=False, decimal_quantization=False,
882 numbering_system=numbering_system)
885def format_percent(
886 number: float | decimal.Decimal | str,
887 format: str | NumberPattern | None = None,
888 locale: Locale | str | None = LC_NUMERIC,
889 decimal_quantization: bool = True,
890 group_separator: bool = True,
891 *,
892 numbering_system: Literal["default"] | str = "latn",
893) -> str:
894 """Return formatted percent value for a specific locale.
896 >>> format_percent(0.34, locale='en_US')
897 u'34%'
898 >>> format_percent(25.1234, locale='en_US')
899 u'2,512%'
900 >>> format_percent(25.1234, locale='sv_SE')
901 u'2\\xa0512\\xa0%'
902 >>> format_percent(25.1234, locale='ar_EG', numbering_system='default')
903 u'2٬512%'
905 The format pattern can also be specified explicitly:
907 >>> format_percent(25.1234, u'#,##0\u2030', locale='en_US')
908 u'25,123\u2030'
910 By default the locale is allowed to truncate and round a high-precision
911 number by forcing its format pattern onto the decimal part. You can bypass
912 this behavior with the `decimal_quantization` parameter:
914 >>> format_percent(23.9876, locale='en_US')
915 u'2,399%'
916 >>> format_percent(23.9876, locale='en_US', decimal_quantization=False)
917 u'2,398.76%'
919 >>> format_percent(229291.1234, locale='pt_BR', group_separator=False)
920 u'22929112%'
922 >>> format_percent(229291.1234, locale='pt_BR', group_separator=True)
923 u'22.929.112%'
925 :param number: the percent number to format
926 :param format:
927 :param locale: the `Locale` object or locale identifier
928 :param decimal_quantization: Truncate and round high-precision numbers to
929 the format pattern. Defaults to `True`.
930 :param group_separator: Boolean to switch group separator on/off in a locale's
931 number format.
932 :param numbering_system: The numbering system used for formatting number symbols. Defaults to "latn".
933 The special value "default" will use the default numbering system of the locale.
934 :raise `UnsupportedNumberingSystemError`: If the numbering system is not supported by the locale.
935 """
936 locale = Locale.parse(locale)
937 if not format:
938 format = locale.percent_formats[None]
939 pattern = parse_pattern(format)
940 return pattern.apply(
941 number, locale, decimal_quantization=decimal_quantization, group_separator=group_separator,
942 numbering_system=numbering_system,
943 )
946def format_scientific(
947 number: float | decimal.Decimal | str,
948 format: str | NumberPattern | None = None,
949 locale: Locale | str | None = LC_NUMERIC,
950 decimal_quantization: bool = True,
951 *,
952 numbering_system: Literal["default"] | str = "latn",
953) -> str:
954 """Return value formatted in scientific notation for a specific locale.
956 >>> format_scientific(10000, locale='en_US')
957 u'1E4'
958 >>> format_scientific(10000, locale='ar_EG', numbering_system='default')
959 u'1أس4'
961 The format pattern can also be specified explicitly:
963 >>> format_scientific(1234567, u'##0.##E00', locale='en_US')
964 u'1.23E06'
966 By default the locale is allowed to truncate and round a high-precision
967 number by forcing its format pattern onto the decimal part. You can bypass
968 this behavior with the `decimal_quantization` parameter:
970 >>> format_scientific(1234.9876, u'#.##E0', locale='en_US')
971 u'1.23E3'
972 >>> format_scientific(1234.9876, u'#.##E0', locale='en_US', decimal_quantization=False)
973 u'1.2349876E3'
975 :param number: the number to format
976 :param format:
977 :param locale: the `Locale` object or locale identifier
978 :param decimal_quantization: Truncate and round high-precision numbers to
979 the format pattern. Defaults to `True`.
980 :param numbering_system: The numbering system used for formatting number symbols. Defaults to "latn".
981 The special value "default" will use the default numbering system of the locale.
982 :raise `UnsupportedNumberingSystemError`: If the numbering system is not supported by the locale.
983 """
984 locale = Locale.parse(locale)
985 if not format:
986 format = locale.scientific_formats[None]
987 pattern = parse_pattern(format)
988 return pattern.apply(
989 number, locale, decimal_quantization=decimal_quantization, numbering_system=numbering_system)
992class NumberFormatError(ValueError):
993 """Exception raised when a string cannot be parsed into a number."""
995 def __init__(self, message: str, suggestions: list[str] | None = None) -> None:
996 super().__init__(message)
997 #: a list of properly formatted numbers derived from the invalid input
998 self.suggestions = suggestions
1001SPACE_CHARS = {
1002 ' ', # space
1003 '\xa0', # no-break space
1004 '\u202f', # narrow no-break space
1005}
1007SPACE_CHARS_RE = re.compile('|'.join(SPACE_CHARS))
1010def parse_number(
1011 string: str,
1012 locale: Locale | str | None = LC_NUMERIC,
1013 *,
1014 numbering_system: Literal["default"] | str = "latn",
1015) -> int:
1016 """Parse localized number string into an integer.
1018 >>> parse_number('1,099', locale='en_US')
1019 1099
1020 >>> parse_number('1.099', locale='de_DE')
1021 1099
1023 When the given string cannot be parsed, an exception is raised:
1025 >>> parse_number('1.099,98', locale='de')
1026 Traceback (most recent call last):
1027 ...
1028 NumberFormatError: '1.099,98' is not a valid number
1030 :param string: the string to parse
1031 :param locale: the `Locale` object or locale identifier
1032 :param numbering_system: The numbering system used for formatting number symbols. Defaults to "latn".
1033 The special value "default" will use the default numbering system of the locale.
1034 :return: the parsed number
1035 :raise `NumberFormatError`: if the string can not be converted to a number
1036 :raise `UnsupportedNumberingSystemError`: if the numbering system is not supported by the locale.
1037 """
1038 group_symbol = get_group_symbol(locale, numbering_system=numbering_system)
1040 if (
1041 group_symbol in SPACE_CHARS and # if the grouping symbol is a kind of space,
1042 group_symbol not in string and # and the string to be parsed does not contain it,
1043 SPACE_CHARS_RE.search(string) # but it does contain any other kind of space instead,
1044 ):
1045 # ... it's reasonable to assume it is taking the place of the grouping symbol.
1046 string = SPACE_CHARS_RE.sub(group_symbol, string)
1048 try:
1049 return int(string.replace(group_symbol, ''))
1050 except ValueError as ve:
1051 raise NumberFormatError(f"{string!r} is not a valid number") from ve
1054def parse_decimal(
1055 string: str,
1056 locale: Locale | str | None = LC_NUMERIC,
1057 strict: bool = False,
1058 *,
1059 numbering_system: Literal["default"] | str = "latn",
1060) -> decimal.Decimal:
1061 """Parse localized decimal string into a decimal.
1063 >>> parse_decimal('1,099.98', locale='en_US')
1064 Decimal('1099.98')
1065 >>> parse_decimal('1.099,98', locale='de')
1066 Decimal('1099.98')
1067 >>> parse_decimal('12 345,123', locale='ru')
1068 Decimal('12345.123')
1069 >>> parse_decimal('1٬099٫98', locale='ar_EG', numbering_system='default')
1070 Decimal('1099.98')
1072 When the given string cannot be parsed, an exception is raised:
1074 >>> parse_decimal('2,109,998', locale='de')
1075 Traceback (most recent call last):
1076 ...
1077 NumberFormatError: '2,109,998' is not a valid decimal number
1079 If `strict` is set to `True` and the given string contains a number
1080 formatted in an irregular way, an exception is raised:
1082 >>> parse_decimal('30.00', locale='de', strict=True)
1083 Traceback (most recent call last):
1084 ...
1085 NumberFormatError: '30.00' is not a properly formatted decimal number. Did you mean '3.000'? Or maybe '30,00'?
1087 >>> parse_decimal('0.00', locale='de', strict=True)
1088 Traceback (most recent call last):
1089 ...
1090 NumberFormatError: '0.00' is not a properly formatted decimal number. Did you mean '0'?
1092 :param string: the string to parse
1093 :param locale: the `Locale` object or locale identifier
1094 :param strict: controls whether numbers formatted in a weird way are
1095 accepted or rejected
1096 :param numbering_system: The numbering system used for formatting number symbols. Defaults to "latn".
1097 The special value "default" will use the default numbering system of the locale.
1098 :raise NumberFormatError: if the string can not be converted to a
1099 decimal number
1100 :raise UnsupportedNumberingSystemError: if the numbering system is not supported by the locale.
1101 """
1102 locale = Locale.parse(locale)
1103 group_symbol = get_group_symbol(locale, numbering_system=numbering_system)
1104 decimal_symbol = get_decimal_symbol(locale, numbering_system=numbering_system)
1106 if not strict and (
1107 group_symbol in SPACE_CHARS and # if the grouping symbol is a kind of space,
1108 group_symbol not in string and # and the string to be parsed does not contain it,
1109 SPACE_CHARS_RE.search(string) # but it does contain any other kind of space instead,
1110 ):
1111 # ... it's reasonable to assume it is taking the place of the grouping symbol.
1112 string = SPACE_CHARS_RE.sub(group_symbol, string)
1114 try:
1115 parsed = decimal.Decimal(string.replace(group_symbol, '')
1116 .replace(decimal_symbol, '.'))
1117 except decimal.InvalidOperation as exc:
1118 raise NumberFormatError(f"{string!r} is not a valid decimal number") from exc
1119 if strict and group_symbol in string:
1120 proper = format_decimal(parsed, locale=locale, decimal_quantization=False, numbering_system=numbering_system)
1121 if string != proper and proper != _remove_trailing_zeros_after_decimal(string, decimal_symbol):
1122 try:
1123 parsed_alt = decimal.Decimal(string.replace(decimal_symbol, '')
1124 .replace(group_symbol, '.'))
1125 except decimal.InvalidOperation as exc:
1126 raise NumberFormatError(
1127 f"{string!r} is not a properly formatted decimal number. "
1128 f"Did you mean {proper!r}?",
1129 suggestions=[proper],
1130 ) from exc
1131 else:
1132 proper_alt = format_decimal(
1133 parsed_alt,
1134 locale=locale,
1135 decimal_quantization=False,
1136 numbering_system=numbering_system,
1137 )
1138 if proper_alt == proper:
1139 raise NumberFormatError(
1140 f"{string!r} is not a properly formatted decimal number. "
1141 f"Did you mean {proper!r}?",
1142 suggestions=[proper],
1143 )
1144 else:
1145 raise NumberFormatError(
1146 f"{string!r} is not a properly formatted decimal number. "
1147 f"Did you mean {proper!r}? Or maybe {proper_alt!r}?",
1148 suggestions=[proper, proper_alt],
1149 )
1150 return parsed
1153def _remove_trailing_zeros_after_decimal(string: str, decimal_symbol: str) -> str:
1154 """
1155 Remove trailing zeros from the decimal part of a numeric string.
1157 This function takes a string representing a numeric value and a decimal symbol.
1158 It removes any trailing zeros that appear after the decimal symbol in the number.
1159 If the decimal part becomes empty after removing trailing zeros, the decimal symbol
1160 is also removed. If the string does not contain the decimal symbol, it is returned unchanged.
1162 :param string: The numeric string from which to remove trailing zeros.
1163 :type string: str
1164 :param decimal_symbol: The symbol used to denote the decimal point.
1165 :type decimal_symbol: str
1166 :return: The numeric string with trailing zeros removed from its decimal part.
1167 :rtype: str
1169 Example:
1170 >>> _remove_trailing_zeros_after_decimal("123.4500", ".")
1171 '123.45'
1172 >>> _remove_trailing_zeros_after_decimal("100.000", ".")
1173 '100'
1174 >>> _remove_trailing_zeros_after_decimal("100", ".")
1175 '100'
1176 """
1177 integer_part, _, decimal_part = string.partition(decimal_symbol)
1179 if decimal_part:
1180 decimal_part = decimal_part.rstrip("0")
1181 if decimal_part:
1182 return integer_part + decimal_symbol + decimal_part
1183 return integer_part
1185 return string
1188PREFIX_END = r'[^0-9@#.,]'
1189NUMBER_TOKEN = r'[0-9@#.,E+]'
1191PREFIX_PATTERN = r"(?P<prefix>(?:'[^']*'|%s)*)" % PREFIX_END
1192NUMBER_PATTERN = r"(?P<number>%s*)" % NUMBER_TOKEN
1193SUFFIX_PATTERN = r"(?P<suffix>.*)"
1195number_re = re.compile(f"{PREFIX_PATTERN}{NUMBER_PATTERN}{SUFFIX_PATTERN}")
1198def parse_grouping(p: str) -> tuple[int, int]:
1199 """Parse primary and secondary digit grouping
1201 >>> parse_grouping('##')
1202 (1000, 1000)
1203 >>> parse_grouping('#,###')
1204 (3, 3)
1205 >>> parse_grouping('#,####,###')
1206 (3, 4)
1207 """
1208 width = len(p)
1209 g1 = p.rfind(',')
1210 if g1 == -1:
1211 return 1000, 1000
1212 g1 = width - g1 - 1
1213 g2 = p[:-g1 - 1].rfind(',')
1214 if g2 == -1:
1215 return g1, g1
1216 g2 = width - g1 - g2 - 2
1217 return g1, g2
1220def parse_pattern(pattern: NumberPattern | str) -> NumberPattern:
1221 """Parse number format patterns"""
1222 if isinstance(pattern, NumberPattern):
1223 return pattern
1225 def _match_number(pattern):
1226 rv = number_re.search(pattern)
1227 if rv is None:
1228 raise ValueError(f"Invalid number pattern {pattern!r}")
1229 return rv.groups()
1231 pos_pattern = pattern
1233 # Do we have a negative subpattern?
1234 if ';' in pattern:
1235 pos_pattern, neg_pattern = pattern.split(';', 1)
1236 pos_prefix, number, pos_suffix = _match_number(pos_pattern)
1237 neg_prefix, _, neg_suffix = _match_number(neg_pattern)
1238 else:
1239 pos_prefix, number, pos_suffix = _match_number(pos_pattern)
1240 neg_prefix = f"-{pos_prefix}"
1241 neg_suffix = pos_suffix
1242 if 'E' in number:
1243 number, exp = number.split('E', 1)
1244 else:
1245 exp = None
1246 if '@' in number and '.' in number and '0' in number:
1247 raise ValueError('Significant digit patterns can not contain "@" or "0"')
1248 if '.' in number:
1249 integer, fraction = number.rsplit('.', 1)
1250 else:
1251 integer = number
1252 fraction = ''
1254 def parse_precision(p):
1255 """Calculate the min and max allowed digits"""
1256 min = max = 0
1257 for c in p:
1258 if c in '@0':
1259 min += 1
1260 max += 1
1261 elif c == '#':
1262 max += 1
1263 elif c == ',':
1264 continue
1265 else:
1266 break
1267 return min, max
1269 int_prec = parse_precision(integer)
1270 frac_prec = parse_precision(fraction)
1271 if exp:
1272 exp_plus = exp.startswith('+')
1273 exp = exp.lstrip('+')
1274 exp_prec = parse_precision(exp)
1275 else:
1276 exp_plus = None
1277 exp_prec = None
1278 grouping = parse_grouping(integer)
1279 return NumberPattern(pattern, (pos_prefix, neg_prefix),
1280 (pos_suffix, neg_suffix), grouping,
1281 int_prec, frac_prec,
1282 exp_prec, exp_plus, number)
1285class NumberPattern:
1287 def __init__(
1288 self,
1289 pattern: str,
1290 prefix: tuple[str, str],
1291 suffix: tuple[str, str],
1292 grouping: tuple[int, int],
1293 int_prec: tuple[int, int],
1294 frac_prec: tuple[int, int],
1295 exp_prec: tuple[int, int] | None,
1296 exp_plus: bool | None,
1297 number_pattern: str | None = None,
1298 ) -> None:
1299 # Metadata of the decomposed parsed pattern.
1300 self.pattern = pattern
1301 self.prefix = prefix
1302 self.suffix = suffix
1303 self.number_pattern = number_pattern
1304 self.grouping = grouping
1305 self.int_prec = int_prec
1306 self.frac_prec = frac_prec
1307 self.exp_prec = exp_prec
1308 self.exp_plus = exp_plus
1309 self.scale = self.compute_scale()
1311 def __repr__(self) -> str:
1312 return f"<{type(self).__name__} {self.pattern!r}>"
1314 def compute_scale(self) -> Literal[0, 2, 3]:
1315 """Return the scaling factor to apply to the number before rendering.
1317 Auto-set to a factor of 2 or 3 if presence of a ``%`` or ``‰`` sign is
1318 detected in the prefix or suffix of the pattern. Default is to not mess
1319 with the scale at all and keep it to 0.
1320 """
1321 scale = 0
1322 if '%' in ''.join(self.prefix + self.suffix):
1323 scale = 2
1324 elif '‰' in ''.join(self.prefix + self.suffix):
1325 scale = 3
1326 return scale
1328 def scientific_notation_elements(
1329 self,
1330 value: decimal.Decimal,
1331 locale: Locale | str | None,
1332 *,
1333 numbering_system: Literal["default"] | str = "latn",
1334 ) -> tuple[decimal.Decimal, int, str]:
1335 """ Returns normalized scientific notation components of a value.
1336 """
1337 # Normalize value to only have one lead digit.
1338 exp = value.adjusted()
1339 value = value * get_decimal_quantum(exp)
1340 assert value.adjusted() == 0
1342 # Shift exponent and value by the minimum number of leading digits
1343 # imposed by the rendering pattern. And always make that number
1344 # greater or equal to 1.
1345 lead_shift = max([1, min(self.int_prec)]) - 1
1346 exp = exp - lead_shift
1347 value = value * get_decimal_quantum(-lead_shift)
1349 # Get exponent sign symbol.
1350 exp_sign = ''
1351 if exp < 0:
1352 exp_sign = get_minus_sign_symbol(locale, numbering_system=numbering_system)
1353 elif self.exp_plus:
1354 exp_sign = get_plus_sign_symbol(locale, numbering_system=numbering_system)
1356 # Normalize exponent value now that we have the sign.
1357 exp = abs(exp)
1359 return value, exp, exp_sign
1361 def apply(
1362 self,
1363 value: float | decimal.Decimal | str,
1364 locale: Locale | str | None,
1365 currency: str | None = None,
1366 currency_digits: bool = True,
1367 decimal_quantization: bool = True,
1368 force_frac: tuple[int, int] | None = None,
1369 group_separator: bool = True,
1370 *,
1371 numbering_system: Literal["default"] | str = "latn",
1372 ):
1373 """Renders into a string a number following the defined pattern.
1375 Forced decimal quantization is active by default so we'll produce a
1376 number string that is strictly following CLDR pattern definitions.
1378 :param value: The value to format. If this is not a Decimal object,
1379 it will be cast to one.
1380 :type value: decimal.Decimal|float|int
1381 :param locale: The locale to use for formatting.
1382 :type locale: str|babel.core.Locale
1383 :param currency: Which currency, if any, to format as.
1384 :type currency: str|None
1385 :param currency_digits: Whether or not to use the currency's precision.
1386 If false, the pattern's precision is used.
1387 :type currency_digits: bool
1388 :param decimal_quantization: Whether decimal numbers should be forcibly
1389 quantized to produce a formatted output
1390 strictly matching the CLDR definition for
1391 the locale.
1392 :type decimal_quantization: bool
1393 :param force_frac: DEPRECATED - a forced override for `self.frac_prec`
1394 for a single formatting invocation.
1395 :param numbering_system: The numbering system used for formatting number symbols. Defaults to "latn".
1396 The special value "default" will use the default numbering system of the locale.
1397 :return: Formatted decimal string.
1398 :rtype: str
1399 :raise UnsupportedNumberingSystemError: If the numbering system is not supported by the locale.
1400 """
1401 if not isinstance(value, decimal.Decimal):
1402 value = decimal.Decimal(str(value))
1404 value = value.scaleb(self.scale)
1406 # Separate the absolute value from its sign.
1407 is_negative = int(value.is_signed())
1408 value = abs(value).normalize()
1410 # Prepare scientific notation metadata.
1411 if self.exp_prec:
1412 value, exp, exp_sign = self.scientific_notation_elements(value, locale, numbering_system=numbering_system)
1414 # Adjust the precision of the fractional part and force it to the
1415 # currency's if necessary.
1416 if force_frac:
1417 # TODO (3.x?): Remove this parameter
1418 warnings.warn(
1419 'The force_frac parameter to NumberPattern.apply() is deprecated.',
1420 DeprecationWarning,
1421 stacklevel=2,
1422 )
1423 frac_prec = force_frac
1424 elif currency and currency_digits:
1425 frac_prec = (get_currency_precision(currency), ) * 2
1426 else:
1427 frac_prec = self.frac_prec
1429 # Bump decimal precision to the natural precision of the number if it
1430 # exceeds the one we're about to use. This adaptative precision is only
1431 # triggered if the decimal quantization is disabled or if a scientific
1432 # notation pattern has a missing mandatory fractional part (as in the
1433 # default '#E0' pattern). This special case has been extensively
1434 # discussed at https://github.com/python-babel/babel/pull/494#issuecomment-307649969 .
1435 if not decimal_quantization or (self.exp_prec and frac_prec == (0, 0)):
1436 frac_prec = (frac_prec[0], max([frac_prec[1], get_decimal_precision(value)]))
1438 # Render scientific notation.
1439 if self.exp_prec:
1440 number = ''.join([
1441 self._quantize_value(value, locale, frac_prec, group_separator, numbering_system=numbering_system),
1442 get_exponential_symbol(locale, numbering_system=numbering_system),
1443 exp_sign, # type: ignore # exp_sign is always defined here
1444 self._format_int(str(exp), self.exp_prec[0], self.exp_prec[1], locale, numbering_system=numbering_system), # type: ignore # exp is always defined here
1445 ])
1447 # Is it a significant digits pattern?
1448 elif '@' in self.pattern:
1449 text = self._format_significant(value,
1450 self.int_prec[0],
1451 self.int_prec[1])
1452 a, sep, b = text.partition(".")
1453 number = self._format_int(a, 0, 1000, locale, numbering_system=numbering_system)
1454 if sep:
1455 number += get_decimal_symbol(locale, numbering_system=numbering_system) + b
1457 # A normal number pattern.
1458 else:
1459 number = self._quantize_value(value, locale, frac_prec, group_separator, numbering_system=numbering_system)
1461 retval = ''.join([
1462 self.prefix[is_negative],
1463 number if self.number_pattern != '' else '',
1464 self.suffix[is_negative]])
1466 if '¤' in retval and currency is not None:
1467 retval = retval.replace('¤¤¤', get_currency_name(currency, value, locale))
1468 retval = retval.replace('¤¤', currency.upper())
1469 retval = retval.replace('¤', get_currency_symbol(currency, locale))
1471 # remove single quotes around text, except for doubled single quotes
1472 # which are replaced with a single quote
1473 retval = re.sub(r"'([^']*)'", lambda m: m.group(1) or "'", retval)
1475 return retval
1477 #
1478 # This is one tricky piece of code. The idea is to rely as much as possible
1479 # on the decimal module to minimize the amount of code.
1480 #
1481 # Conceptually, the implementation of this method can be summarized in the
1482 # following steps:
1483 #
1484 # - Move or shift the decimal point (i.e. the exponent) so the maximum
1485 # amount of significant digits fall into the integer part (i.e. to the
1486 # left of the decimal point)
1487 #
1488 # - Round the number to the nearest integer, discarding all the fractional
1489 # part which contained extra digits to be eliminated
1490 #
1491 # - Convert the rounded integer to a string, that will contain the final
1492 # sequence of significant digits already trimmed to the maximum
1493 #
1494 # - Restore the original position of the decimal point, potentially
1495 # padding with zeroes on either side
1496 #
1497 def _format_significant(self, value: decimal.Decimal, minimum: int, maximum: int) -> str:
1498 exp = value.adjusted()
1499 scale = maximum - 1 - exp
1500 digits = str(value.scaleb(scale).quantize(decimal.Decimal(1)))
1501 if scale <= 0:
1502 result = digits + '0' * -scale
1503 else:
1504 intpart = digits[:-scale]
1505 i = len(intpart)
1506 j = i + max(minimum - i, 0)
1507 result = "{intpart}.{pad:0<{fill}}{fracpart}{fracextra}".format(
1508 intpart=intpart or '0',
1509 pad='',
1510 fill=-min(exp + 1, 0),
1511 fracpart=digits[i:j],
1512 fracextra=digits[j:].rstrip('0'),
1513 ).rstrip('.')
1514 return result
1516 def _format_int(
1517 self,
1518 value: str,
1519 min: int,
1520 max: int,
1521 locale: Locale | str | None,
1522 *,
1523 numbering_system: Literal["default"] | str,
1524 ) -> str:
1525 width = len(value)
1526 if width < min:
1527 value = '0' * (min - width) + value
1528 gsize = self.grouping[0]
1529 ret = ''
1530 symbol = get_group_symbol(locale, numbering_system=numbering_system)
1531 while len(value) > gsize:
1532 ret = symbol + value[-gsize:] + ret
1533 value = value[:-gsize]
1534 gsize = self.grouping[1]
1535 return value + ret
1537 def _quantize_value(
1538 self,
1539 value: decimal.Decimal,
1540 locale: Locale | str | None,
1541 frac_prec: tuple[int, int],
1542 group_separator: bool,
1543 *,
1544 numbering_system: Literal["default"] | str,
1545 ) -> str:
1546 # If the number is +/-Infinity, we can't quantize it
1547 if value.is_infinite():
1548 return get_infinity_symbol(locale, numbering_system=numbering_system)
1549 quantum = get_decimal_quantum(frac_prec[1])
1550 rounded = value.quantize(quantum)
1551 a, sep, b = f"{rounded:f}".partition(".")
1552 integer_part = a
1553 if group_separator:
1554 integer_part = self._format_int(a, self.int_prec[0], self.int_prec[1], locale, numbering_system=numbering_system)
1555 number = integer_part + self._format_frac(b or '0', locale=locale, force_frac=frac_prec, numbering_system=numbering_system)
1556 return number
1558 def _format_frac(
1559 self,
1560 value: str,
1561 locale: Locale | str | None,
1562 force_frac: tuple[int, int] | None = None,
1563 *,
1564 numbering_system: Literal["default"] | str,
1565 ) -> str:
1566 min, max = force_frac or self.frac_prec
1567 if len(value) < min:
1568 value += ('0' * (min - len(value)))
1569 if max == 0 or (min == 0 and int(value) == 0):
1570 return ''
1571 while len(value) > min and value[-1] == '0':
1572 value = value[:-1]
1573 return get_decimal_symbol(locale, numbering_system=numbering_system) + value