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'
Parameters:
  • number – the number to format
  • locale – the Locale object or locale identifier
babel.numbers.format_decimal(number, format=None, locale='en_US_POSIX')

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'
Parameters:
  • number – the number to format
  • format
  • locale – the Locale object or locale identifier
babel.numbers.format_currency(number, currency, format=None, locale='en_US_POSIX', currency_digits=True, format_type='standard')

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

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"
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 number of decimal digits
  • format_type – the currency format type to use
babel.numbers.format_percent(number, format=None, locale='en_US_POSIX')

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\u2030', locale='en_US')
u'25,123\u2030'
Parameters:
  • number – the percent number to format
  • format
  • locale – the Locale object or locale identifier
babel.numbers.format_scientific(number, format=None, locale='en_US_POSIX')

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'##0E00', locale='en_US')
u'1.23E06'
Parameters:
  • number – the number to format
  • format
  • locale – the Locale object or locale identifier

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

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

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
Parameters:
  • string – the string to parse
  • locale – the Locale object or locale identifier
Raises:

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

Exceptions

exception babel.numbers.NumberFormatError

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

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_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 fo
  • 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'.