Numbers and Currencies

The number module provides functionality to format numbers for different locales. This includes arbitrary numbers as well as currency.

Number Formatting

babel.numbers.format_number(number, locale='en_US_POSIX')

Return the given number formatted for a specific locale.

>>> format_number(1099, locale='en_US')
u'1,099'
>>> format_number(1099, locale='de_DE')
u'1.099'

Deprecated since version 2.6.0: Use babel.numbers.format_decimal() instead.

Parameters

  • number – the number to format

  • locale – the Locale object or locale identifier

babel.numbers.format_decimal(number, format=None, locale='en_US_POSIX', decimal_quantization=True, group_separator=True)

Return the given decimal number formatted for a specific locale.

>>> format_decimal(1.2345, locale='en_US')
u'1.234'
>>> format_decimal(1.2346, locale='en_US')
u'1.235'
>>> format_decimal(-1.2346, locale='en_US')
u'-1.235'
>>> format_decimal(1.2345, locale='sv_SE')
u'1,234'
>>> format_decimal(1.2345, locale='de')
u'1,234'

The appropriate thousands grouping and the decimal separator are used for each locale:

>>> format_decimal(12345.5, locale='en_US')
u'12,345.5'

By default the locale is allowed to truncate and round a high-precision number by forcing its format pattern onto the decimal part. You can bypass this behavior with the decimal_quantization parameter:

>>> format_decimal(1.2346, locale='en_US')
u'1.235'
>>> format_decimal(1.2346, locale='en_US', decimal_quantization=False)
u'1.2346'
>>> format_decimal(12345.67, locale='fr_CA', group_separator=False)
u'12345,67'
>>> format_decimal(12345.67, locale='en_US', group_separator=True)
u'12,345.67'
Parameters

  • number – the number to format

  • format –

  • locale – the Locale object or locale identifier

  • decimal_quantization – Truncate and round high-precision numbers to the format pattern. Defaults to True.

  • group_separator – Boolean to switch group separator on/off in a locale’s number format.

babel.numbers.format_currency(number, currency, format=None, locale='en_US_POSIX', currency_digits=True, format_type='standard', decimal_quantization=True, group_separator=True)

Return formatted currency value.

>>> format_currency(1099.98, 'USD', locale='en_US')
u'$1,099.98'
>>> format_currency(1099.98, 'USD', locale='es_CO')
u'US$\xa01.099,98'
>>> format_currency(1099.98, 'EUR', locale='de_DE')
u'1.099,98\xa0\u20ac'

The format can also be specified explicitly. The currency is placed with the ‘¤’ sign. As the sign gets repeated the format expands (¤ being the symbol, ¤¤ is the currency abbreviation and ¤¤¤ is the full name of the currency):

>>> format_currency(1099.98, 'EUR', u'¤¤ #,##0.00', locale='en_US')
u'EUR 1,099.98'
>>> format_currency(1099.98, 'EUR', u'#,##0.00 ¤¤¤', locale='en_US')
u'1,099.98 euros'

Currencies usually have a specific number of decimal digits. This function favours that information over the given format:

>>> format_currency(1099.98, 'JPY', locale='en_US')
u'\xa51,100'
>>> format_currency(1099.98, 'COP', u'#,##0.00', locale='es_ES')
u'1.099,98'

However, the number of decimal digits can be overriden from the currency information, by setting the last parameter to False:

>>> format_currency(1099.98, 'JPY', locale='en_US', currency_digits=False)
u'\xa51,099.98'
>>> format_currency(1099.98, 'COP', u'#,##0.00', locale='es_ES', currency_digits=False)
u'1.099,98'

If a format is not specified the type of currency format to use from the locale can be specified:

>>> format_currency(1099.98, 'EUR', locale='en_US', format_type='standard')
u'\u20ac1,099.98'

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

>>> format_currency('1099.98', 'EUR', locale='root', format_type='unknown')
Traceback (most recent call last):
    ...
UnknownCurrencyFormatError: "'unknown' is not a known currency format type"

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

>>> format_currency(101299.98, 'USD', locale='en_US', group_separator=True)
u'$101,299.98'

You can also pass format_type=’name’ to use long display names. The order of the number and currency name, along with the correct localized plural form of the currency name, is chosen according to locale:

>>> format_currency(1, 'USD', locale='en_US', format_type='name')
u'1.00 US dollar'
>>> format_currency(1099.98, 'USD', locale='en_US', format_type='name')
u'1,099.98 US dollars'
>>> format_currency(1099.98, 'USD', locale='ee', format_type='name')
u'us ga dollar 1,099.98'

By default the locale is allowed to truncate and round a high-precision number by forcing its format pattern onto the decimal part. You can bypass this behavior with the decimal_quantization parameter:

>>> format_currency(1099.9876, 'USD', locale='en_US')
u'$1,099.99'
>>> format_currency(1099.9876, 'USD', locale='en_US', decimal_quantization=False)
u'$1,099.9876'
Parameters

  • number – the number to format

  • currency – the currency code

  • format – the format string to use

  • locale – the Locale object or locale identifier

  • currency_digits – use the currency’s natural number of decimal digits

  • format_type – the currency format type to use

  • decimal_quantization – Truncate and round high-precision numbers to the format pattern. Defaults to True.

  • group_separator – Boolean to switch group separator on/off in a locale’s number format.

babel.numbers.format_percent(number, format=None, locale='en_US_POSIX', decimal_quantization=True, group_separator=True)

Return formatted percent value for a specific locale.

>>> format_percent(0.34, locale='en_US')
u'34%'
>>> format_percent(25.1234, locale='en_US')
u'2,512%'
>>> format_percent(25.1234, locale='sv_SE')
u'2\xa0512\xa0%'

The format pattern can also be specified explicitly:

>>> format_percent(25.1234, u'#,##0‰', locale='en_US')
u'25,123‰'

By default the locale is allowed to truncate and round a high-precision number by forcing its format pattern onto the decimal part. You can bypass this behavior with the decimal_quantization parameter:

>>> format_percent(23.9876, locale='en_US')
u'2,399%'
>>> format_percent(23.9876, locale='en_US', decimal_quantization=False)
u'2,398.76%'

>>> format_percent(229291.1234, locale='pt_BR', group_separator=False)
u'22929112%'

>>> format_percent(229291.1234, locale='pt_BR', group_separator=True)
u'22.929.112%'
Parameters

  • number – the percent number to format

  • format –

  • locale – the Locale object or locale identifier

  • decimal_quantization – Truncate and round high-precision numbers to the format pattern. Defaults to True.

  • group_separator – Boolean to switch group separator on/off in a locale’s number format.

babel.numbers.format_scientific(number, format=None, locale='en_US_POSIX', decimal_quantization=True)

Return value formatted in scientific notation for a specific locale.

>>> format_scientific(10000, locale='en_US')
u'1E4'

The format pattern can also be specified explicitly:

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

By default the locale is allowed to truncate and round a high-precision number by forcing its format pattern onto the decimal part. You can bypass this behavior with the decimal_quantization parameter:

>>> format_scientific(1234.9876, u'#.##E0', locale='en_US')
u'1.23E3'
>>> format_scientific(1234.9876, u'#.##E0', locale='en_US', decimal_quantization=False)
u'1.2349876E3'
Parameters

  • number – the number to format

  • format –

  • locale – the Locale object or locale identifier

  • decimal_quantization – Truncate and round high-precision numbers to the format pattern. Defaults to True.

Number Parsing

babel.numbers.parse_number(string, locale='en_US_POSIX')

Parse localized number string into an integer.

>>> parse_number('1,099', locale='en_US')
1099
>>> parse_number('1.099', locale='de_DE')
1099

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

>>> parse_number('1.099,98', locale='de')
Traceback (most recent call last):
    ...
NumberFormatError: '1.099,98' is not a valid number
Parameters

  • string – the string to parse

  • locale – the Locale object or locale identifier

Returns

the parsed number

Raises

NumberFormatError – if the string can not be converted to a number

babel.numbers.parse_decimal(string, locale='en_US_POSIX', strict=False)

Parse localized decimal string into a decimal.

>>> parse_decimal('1,099.98', locale='en_US')
Decimal('1099.98')
>>> parse_decimal('1.099,98', locale='de')
Decimal('1099.98')
>>> parse_decimal('12 345,123', locale='ru')
Decimal('12345.123')

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

>>> parse_decimal('2,109,998', locale='de')
Traceback (most recent call last):
    ...
NumberFormatError: '2,109,998' is not a valid decimal number

If strict is set to True and the given string contains a number formatted in an irregular way, an exception is raised:

>>> parse_decimal('30.00', locale='de', strict=True)
Traceback (most recent call last):
    ...
NumberFormatError: '30.00' is not a properly formatted decimal number. Did you mean '3.000'? Or maybe '30,00'?

>>> parse_decimal('0.00', locale='de', strict=True)
Traceback (most recent call last):
    ...
NumberFormatError: '0.00' is not a properly formatted decimal number. Did you mean '0'?
Parameters

  • string – the string to parse

  • locale – the Locale object or locale identifier

  • strict – controls whether numbers formatted in a weird way are accepted or rejected

Raises

NumberFormatError – if the string can not be converted to a decimal number

Exceptions

exception babel.numbers.NumberFormatError(message, suggestions=None)

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

suggestions

a list of properly formatted numbers derived from the invalid input

Data Access

babel.numbers.get_currency_name(currency, count=None, locale='en_US_POSIX')

Return the name used by the locale for the specified currency.

>>> get_currency_name('USD', locale='en_US')
u'US Dollar'

New in version 0.9.4.

Parameters

  • currency – the currency code.

  • count – the optional count. If provided the currency name will be pluralized to that number if possible.

  • locale – the Locale object or locale identifier.

babel.numbers.get_currency_symbol(currency, locale='en_US_POSIX')

Return the symbol used by the locale for the specified currency.

>>> get_currency_symbol('USD', locale='en_US')
u'$'
Parameters

  • currency – the currency code.

  • locale – the Locale object or locale identifier.

babel.numbers.get_currency_unit_pattern(currency, count=None, locale='en_US_POSIX')

Return the unit pattern used for long display of a currency value for a given locale. This is a string containing {0} where the numeric part should be substituted and {1} where the currency long display name should be substituted.

>>> get_currency_unit_pattern('USD', locale='en_US', count=10)
u'{0} {1}'

New in version 2.7.0.

Parameters

  • currency – the currency code.

  • count – the optional count. If provided the unit pattern for that number will be returned.

  • locale – the Locale object or locale identifier.

babel.numbers.get_decimal_symbol(locale='en_US_POSIX')

Return the symbol used by the locale to separate decimal fractions.

>>> get_decimal_symbol('en_US')
u'.'
Parameters

locale – the Locale object or locale identifier

babel.numbers.get_plus_sign_symbol(locale='en_US_POSIX')

Return the plus sign symbol used by the current locale.

>>> get_plus_sign_symbol('en_US')
u'+'
Parameters

locale – the Locale object or locale identifier

babel.numbers.get_minus_sign_symbol(locale='en_US_POSIX')

Return the plus sign symbol used by the current locale.

>>> get_minus_sign_symbol('en_US')
u'-'
Parameters

locale – the Locale object or locale identifier

babel.numbers.get_territory_currencies(territory, start_date=None, end_date=None, tender=True, non_tender=False, include_details=False)

Returns the list of currencies for the given territory that are valid for the given date range. In addition to that the currency database distinguishes between tender and non-tender currencies. By default only tender currencies are returned.

The return value is a list of all currencies roughly ordered by the time of when the currency became active. The longer the currency is being in use the more to the left of the list it will be.

The start date defaults to today. If no end date is given it will be the same as the start date. Otherwise a range can be defined. For instance this can be used to find the currencies in use in Austria between 1995 and 2011:

>>> from datetime import date
>>> get_territory_currencies('AT', date(1995, 1, 1), date(2011, 1, 1))
['ATS', 'EUR']

Likewise it’s also possible to find all the currencies in use on a single date:

>>> get_territory_currencies('AT', date(1995, 1, 1))
['ATS']
>>> get_territory_currencies('AT', date(2011, 1, 1))
['EUR']

By default the return value only includes tender currencies. This however can be changed:

>>> get_territory_currencies('US')
['USD']
>>> get_territory_currencies('US', tender=False, non_tender=True,
...                          start_date=date(2014, 1, 1))
['USN', 'USS']

New in version 2.0.

Parameters

  • territory – the name of the territory to find the currency for.

  • start_date – the start date. If not given today is assumed.

  • end_date – the end date. If not given the start date is assumed.

  • tender – controls whether tender currencies should be included.

  • non_tender – controls whether non-tender currencies should be included.

  • include_details – if set to True, instead of returning currency codes the return value will be dictionaries with detail information. In that case each dictionary will have the keys 'currency', 'from', 'to', and 'tender'.