numbers.rst 6.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163
  1. .. -*- mode: rst; encoding: utf-8 -*-
  2. .. _numbers:
  3. =================
  4. Number Formatting
  5. =================
  6. Support for locale-specific formatting and parsing of numbers is provided by
  7. the ``babel.numbers`` module:
  8. .. code-block:: pycon
  9. >>> from babel.numbers import format_number, format_decimal, format_percent
  10. Examples:
  11. .. code-block:: pycon
  12. >>> format_decimal(1.2345, locale='en_US')
  13. u'1.234'
  14. >>> format_decimal(1.2345, locale='sv_SE')
  15. u'1,234'
  16. >>> format_decimal(12345, locale='de_DE')
  17. u'12.345'
  18. Pattern Syntax
  19. ==============
  20. While Babel makes it simple to use the appropriate number format for a given
  21. locale, you can also force it to use custom patterns. As with date/time
  22. formatting patterns, the patterns Babel supports for number formatting are
  23. based on the `Locale Data Markup Language specification`_ (LDML).
  24. Examples:
  25. .. code-block:: pycon
  26. >>> format_decimal(-1.2345, format='#,##0.##;-#', locale='en')
  27. u'-1.23'
  28. >>> format_decimal(-1.2345, format='#,##0.##;(#)', locale='en')
  29. u'(1.23)'
  30. The syntax for custom number format patterns is described in detail in the
  31. the specification. The following table is just a relatively brief overview.
  32. .. _`Locale Data Markup Language specification`:
  33. http://unicode.org/reports/tr35/#Number_Format_Patterns
  34. +----------+-----------------------------------------------------------------+
  35. | Symbol | Description |
  36. +==========+=================================================================+
  37. | ``0`` | Digit |
  38. +----------+-----------------------------------------------------------------+
  39. | ``1-9`` | '1' through '9' indicate rounding. |
  40. +----------+-----------------------------------------------------------------+
  41. | ``@`` | Significant digit |
  42. +----------+-----------------------------------------------------------------+
  43. | ``#`` | Digit, zero shows as absent |
  44. +----------+-----------------------------------------------------------------+
  45. | ``.`` | Decimal separator or monetary decimal separator |
  46. +----------+-----------------------------------------------------------------+
  47. | ``-`` | Minus sign |
  48. +----------+-----------------------------------------------------------------+
  49. | ``,`` | Grouping separator |
  50. +----------+-----------------------------------------------------------------+
  51. | ``E`` | Separates mantissa and exponent in scientific notation |
  52. +----------+-----------------------------------------------------------------+
  53. | ``+`` | Prefix positive exponents with localized plus sign |
  54. +----------+-----------------------------------------------------------------+
  55. | ``;`` | Separates positive and negative subpatterns |
  56. +----------+-----------------------------------------------------------------+
  57. | ``%`` | Multiply by 100 and show as percentage |
  58. +----------+-----------------------------------------------------------------+
  59. | ``‰`` | Multiply by 1000 and show as per mille |
  60. +----------+-----------------------------------------------------------------+
  61. | ``¤`` | Currency sign, replaced by currency symbol. If doubled, |
  62. | | replaced by international currency symbol. If tripled, uses the |
  63. | | long form of the decimal symbol. |
  64. +----------+-----------------------------------------------------------------+
  65. | ``'`` | Used to quote special characters in a prefix or suffix |
  66. +----------+-----------------------------------------------------------------+
  67. | ``*`` | Pad escape, precedes pad character |
  68. +----------+-----------------------------------------------------------------+
  69. Rounding Modes
  70. ==============
  71. Since Babel makes full use of Python's `Decimal`_ type to perform number
  72. rounding before formatting, users have the chance to control the rounding mode
  73. and other configurable parameters through the active `Context`_ instance.
  74. By default, Python rounding mode is ``ROUND_HALF_EVEN`` which complies with
  75. `UTS #35 section 3.3`_. Yet, the caller has the opportunity to tweak the
  76. current context before formatting a number or currency:
  77. .. code-block:: pycon
  78. >>> from babel.numbers import decimal, format_decimal
  79. >>> with decimal.localcontext(decimal.Context(rounding=decimal.ROUND_DOWN)):
  80. >>> txt = format_decimal(123.99, format='#', locale='en_US')
  81. >>> txt
  82. u'123'
  83. It is also possible to use ``decimal.setcontext`` or directly modifying the
  84. instance returned by ``decimal.getcontext``. However, using a context manager
  85. is always more convenient due to the automatic restoration and the ability to
  86. nest them.
  87. Whatever mechanism is chosen, always make use of the ``decimal`` module imported
  88. from ``babel.numbers``. For efficiency reasons, Babel uses the fastest decimal
  89. implementation available, such as `cdecimal`_. These various implementation
  90. offer an identical API, but their types and instances do **not** interoperate
  91. with each other.
  92. For example, the previous example can be slightly modified to generate
  93. unexpected results on Python 2.7, with the `cdecimal`_ module installed:
  94. .. code-block:: pycon
  95. >>> from decimal import localcontext, Context, ROUND_DOWN
  96. >>> from babel.numbers import format_decimal
  97. >>> with localcontext(Context(rounding=ROUND_DOWN)):
  98. >>> txt = format_decimal(123.99, format='#', locale='en_US')
  99. >>> txt
  100. u'124'
  101. Changing other parameters such as the precision may also alter the results of
  102. the number formatting functions. Remember to test your code to make sure it
  103. behaves as desired.
  104. .. _Decimal: https://docs.python.org/3/library/decimal.html#decimal-objects
  105. .. _Context: https://docs.python.org/3/library/decimal.html#context-objects
  106. .. _`UTS #35 section 3.3`: http://www.unicode.org/reports/tr35/tr35-numbers.html#Formatting
  107. .. _cdecimal: https://pypi.python.org/pypi/cdecimal
  108. Parsing Numbers
  109. ===============
  110. Babel can also parse numeric data in a locale-sensitive manner:
  111. .. code-block:: pycon
  112. >>> from babel.numbers import parse_decimal, parse_number
  113. Examples:
  114. .. code-block:: pycon
  115. >>> parse_decimal('1,099.98', locale='en_US')
  116. 1099.98
  117. >>> parse_decimal('1.099,98', locale='de')
  118. 1099.98
  119. >>> parse_decimal('2,109,998', locale='de')
  120. Traceback (most recent call last):
  121. ...
  122. NumberFormatError: '2,109,998' is not a valid decimal number
  123. .. note:: Number parsing is not properly implemented yet