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

438 statements  

1""" 

2 babel.numbers 

3 ~~~~~~~~~~~~~ 

4 

5 Locale dependent formatting and parsing of numeric data. 

6 

7 The default locale for the functions in this module is determined by the 

8 following environment variables, in that order: 

9 

10 * ``LC_NUMERIC``, 

11 * ``LC_ALL``, and 

12 * ``LANG`` 

13 

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 

21 

22import datetime 

23import decimal 

24import re 

25import warnings 

26from typing import TYPE_CHECKING, Any, cast, overload 

27 

28from babel.core import Locale, default_locale, get_global 

29from babel.localedata import LocaleDataDict 

30 

31if TYPE_CHECKING: 

32 from typing_extensions import Literal 

33 

34LC_NUMERIC = default_locale('LC_NUMERIC') 

35 

36 

37class UnknownCurrencyError(Exception): 

38 """Exception thrown when a currency is requested for which no data is available. 

39 """ 

40 

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}.") 

46 

47 #: The identifier of the locale that could not be found. 

48 self.identifier = identifier 

49 

50 

51def list_currencies(locale: Locale | str | None = None) -> set[str]: 

52 """ Return a `set` of normalized currency codes. 

53 

54 .. versionadded:: 2.5.0 

55 

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')) 

65 

66 

67def validate_currency(currency: str, locale: Locale | str | None = None) -> None: 

68 """ Check the currency code is recognized by Babel. 

69 

70 Accepts a ``locale`` parameter for fined-grained validation, working as 

71 the one defined above in ``list_currencies()`` method. 

72 

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) 

77 

78 

79def is_currency(currency: str, locale: Locale | str | None = None) -> bool: 

80 """ Returns `True` only if a currency is recognized by Babel. 

81 

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 

91 

92 

93def normalize_currency(currency: str, locale: Locale | str | None = None) -> str | None: 

94 """Returns the normalized identifier of any currency code. 

95 

96 Accepts a ``locale`` parameter for fined-grained validation, working as 

97 the one defined above in ``list_currencies()`` method. 

98 

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 

106 

107 

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. 

114 

115 >>> get_currency_name('USD', locale='en_US') 

116 u'US Dollar' 

117 

118 .. versionadded:: 0.9.4 

119 

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) 

139 

140 

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. 

143 

144 >>> get_currency_symbol('USD', locale='en_US') 

145 u'$' 

146 

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) 

151 

152 

153def get_currency_precision(currency: str) -> int: 

154 """Return currency's precision. 

155 

156 Precision is the number of decimals found after the decimal point in the 

157 currency's format pattern. 

158 

159 .. versionadded:: 2.5.0 

160 

161 :param currency: the currency code. 

162 """ 

163 precisions = get_global('currency_fractions') 

164 return precisions.get(currency, precisions['DEFAULT'])[0] 

165 

166 

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. 

178 

179 >>> get_currency_unit_pattern('USD', locale='en_US', count=10) 

180 u'{0} {1}' 

181 

182 .. versionadded:: 2.7.0 

183 

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 

197 

198 return loc._data['currency_unit_patterns']['other'] 

199 

200 

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 

211 

212 

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 

223 

224 

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. 

237 

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. 

241 

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: 

246 

247 >>> from datetime import date 

248 >>> get_territory_currencies('AT', date(1995, 1, 1), date(2011, 1, 1)) 

249 ['ATS', 'EUR'] 

250 

251 Likewise it's also possible to find all the currencies in use on a 

252 single date: 

253 

254 >>> get_territory_currencies('AT', date(1995, 1, 1)) 

255 ['ATS'] 

256 >>> get_territory_currencies('AT', date(2011, 1, 1)) 

257 ['EUR'] 

258 

259 By default the return value only includes tender currencies. This 

260 however can be changed: 

261 

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'] 

267 

268 .. versionadded:: 2.0 

269 

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() 

291 

292 curs = currencies.get(territory.upper(), ()) 

293 # TODO: validate that the territory exists 

294 

295 def _is_active(start, end): 

296 return (start is None or start <= end_date) and \ 

297 (end is None or end >= start_date) 

298 

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) 

316 

317 return result 

318 

319 

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 

325 

326 

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 

338 

339 

340class UnsupportedNumberingSystemError(Exception): 

341 """Exception thrown when an unsupported numbering system is requested for the given Locale.""" 

342 pass 

343 

344 

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. 

351 

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'.' 

358 

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', '.') 

365 

366 

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. 

373 

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+' 

380 

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', '+') 

387 

388 

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. 

395 

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-' 

402 

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', '-') 

409 

410 

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. 

417 

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' 

424 

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') 

431 

432 

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. 

439 

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',' 

446 

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', ',') 

453 

454 

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. 

461 

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'∞' 

468 

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', '∞') 

475 

476 

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. 

479 

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' 

484 

485 .. deprecated:: 2.6.0 

486 

487 Use babel.numbers.format_decimal() instead. 

488 

489 :param number: the number to format 

490 :param locale: the `Locale` object or locale identifier 

491 

492 

493 """ 

494 warnings.warn('Use babel.numbers.format_decimal() instead.', DeprecationWarning, stacklevel=2) 

495 return format_decimal(number, locale=locale) 

496 

497 

498def get_decimal_precision(number: decimal.Decimal) -> int: 

499 """Return maximum precision of a decimal instance's fractional part. 

500 

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) 

510 

511 

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) 

516 

517 

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. 

528 

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' 

543 

544 The appropriate thousands grouping and the decimal separator are used for 

545 each locale: 

546 

547 >>> format_decimal(12345.5, locale='en_US') 

548 u'12,345.5' 

549 

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: 

553 

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' 

562 

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) 

580 

581 

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. 

591 

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ألف' 

606 

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) 

623 

624 

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 

663 

664 

665class UnknownCurrencyFormatError(KeyError): 

666 """Exception raised when an unknown currency format is requested.""" 

667 

668 

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. 

682 

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' 

691 

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): 

696 

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' 

701 

702 Currencies usually have a specific number of decimal digits. This function 

703 favours that information over the given format: 

704 

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' 

709 

710 However, the number of decimal digits can be overridden from the currency 

711 information, by setting the last parameter to ``False``: 

712 

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' 

717 

718 If a format is not specified the type of currency format to use 

719 from the locale can be specified: 

720 

721 >>> format_currency(1099.98, 'EUR', locale='en_US', format_type='standard') 

722 u'\\u20ac1,099.98' 

723 

724 When the given currency format type is not available, an exception is 

725 raised: 

726 

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" 

731 

732 >>> format_currency(101299.98, 'USD', locale='en_US', group_separator=False) 

733 u'$101299.98' 

734 

735 >>> format_currency(101299.98, 'USD', locale='en_US', group_separator=True) 

736 u'$101,299.98' 

737 

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: 

741 

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' 

748 

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: 

752 

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' 

757 

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 

785 

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) 

789 

790 

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. 

810 

811 # Correct number to numeric type, important for looking up plural rules: 

812 number_n = float(number) if isinstance(number, str) else number 

813 

814 # Step 3. 

815 unit_pattern = get_currency_unit_pattern(currency, count=number_n, locale=locale) 

816 

817 # Step 4. 

818 display_name = get_currency_name(currency, count=number_n, locale=locale) 

819 

820 # Step 5. 

821 if not format: 

822 format = locale.decimal_formats[None] 

823 

824 pattern = parse_pattern(format) 

825 

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) 

829 

830 return unit_pattern.format(number_part, display_name) 

831 

832 

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. 

843 

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€' 

850 

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) 

883 

884 

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. 

895 

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%' 

904 

905 The format pattern can also be specified explicitly: 

906 

907 >>> format_percent(25.1234, u'#,##0\u2030', locale='en_US') 

908 u'25,123\u2030' 

909 

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: 

913 

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%' 

918 

919 >>> format_percent(229291.1234, locale='pt_BR', group_separator=False) 

920 u'22929112%' 

921 

922 >>> format_percent(229291.1234, locale='pt_BR', group_separator=True) 

923 u'22.929.112%' 

924 

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 ) 

944 

945 

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. 

955 

956 >>> format_scientific(10000, locale='en_US') 

957 u'1E4' 

958 >>> format_scientific(10000, locale='ar_EG', numbering_system='default') 

959 u'1أس4' 

960 

961 The format pattern can also be specified explicitly: 

962 

963 >>> format_scientific(1234567, u'##0.##E00', locale='en_US') 

964 u'1.23E06' 

965 

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: 

969 

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' 

974 

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) 

990 

991 

992class NumberFormatError(ValueError): 

993 """Exception raised when a string cannot be parsed into a number.""" 

994 

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 

999 

1000 

1001SPACE_CHARS = { 

1002 ' ', # space 

1003 '\xa0', # no-break space 

1004 '\u202f', # narrow no-break space 

1005} 

1006 

1007SPACE_CHARS_RE = re.compile('|'.join(SPACE_CHARS)) 

1008 

1009 

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. 

1017 

1018 >>> parse_number('1,099', locale='en_US') 

1019 1099 

1020 >>> parse_number('1.099', locale='de_DE') 

1021 1099 

1022 

1023 When the given string cannot be parsed, an exception is raised: 

1024 

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 

1029 

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) 

1039 

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) 

1047 

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 

1052 

1053 

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. 

1062 

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') 

1071 

1072 When the given string cannot be parsed, an exception is raised: 

1073 

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 

1078 

1079 If `strict` is set to `True` and the given string contains a number 

1080 formatted in an irregular way, an exception is raised: 

1081 

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'? 

1086 

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'? 

1091 

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) 

1105 

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) 

1113 

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 

1151 

1152 

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. 

1156 

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. 

1161 

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 

1168 

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) 

1178 

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 

1184 

1185 return string 

1186 

1187 

1188PREFIX_END = r'[^0-9@#.,]' 

1189NUMBER_TOKEN = r'[0-9@#.,E+]' 

1190 

1191PREFIX_PATTERN = r"(?P<prefix>(?:'[^']*'|%s)*)" % PREFIX_END 

1192NUMBER_PATTERN = r"(?P<number>%s*)" % NUMBER_TOKEN 

1193SUFFIX_PATTERN = r"(?P<suffix>.*)" 

1194 

1195number_re = re.compile(f"{PREFIX_PATTERN}{NUMBER_PATTERN}{SUFFIX_PATTERN}") 

1196 

1197 

1198def parse_grouping(p: str) -> tuple[int, int]: 

1199 """Parse primary and secondary digit grouping 

1200 

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 

1218 

1219 

1220def parse_pattern(pattern: NumberPattern | str) -> NumberPattern: 

1221 """Parse number format patterns""" 

1222 if isinstance(pattern, NumberPattern): 

1223 return pattern 

1224 

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() 

1230 

1231 pos_pattern = pattern 

1232 

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 = '' 

1253 

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 

1268 

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) 

1283 

1284 

1285class NumberPattern: 

1286 

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() 

1310 

1311 def __repr__(self) -> str: 

1312 return f"<{type(self).__name__} {self.pattern!r}>" 

1313 

1314 def compute_scale(self) -> Literal[0, 2, 3]: 

1315 """Return the scaling factor to apply to the number before rendering. 

1316 

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 

1327 

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 

1341 

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) 

1348 

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) 

1355 

1356 # Normalize exponent value now that we have the sign. 

1357 exp = abs(exp) 

1358 

1359 return value, exp, exp_sign 

1360 

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. 

1374 

1375 Forced decimal quantization is active by default so we'll produce a 

1376 number string that is strictly following CLDR pattern definitions. 

1377 

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)) 

1403 

1404 value = value.scaleb(self.scale) 

1405 

1406 # Separate the absolute value from its sign. 

1407 is_negative = int(value.is_signed()) 

1408 value = abs(value).normalize() 

1409 

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) 

1413 

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 

1428 

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)])) 

1437 

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 ]) 

1446 

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 

1456 

1457 # A normal number pattern. 

1458 else: 

1459 number = self._quantize_value(value, locale, frac_prec, group_separator, numbering_system=numbering_system) 

1460 

1461 retval = ''.join([ 

1462 self.prefix[is_negative], 

1463 number if self.number_pattern != '' else '', 

1464 self.suffix[is_negative]]) 

1465 

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)) 

1470 

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) 

1474 

1475 return retval 

1476 

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 

1515 

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 

1536 

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 

1557 

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