cmlenz@4: .. -*- mode: rst; encoding: utf-8 -*-
cmlenz@4: 
cmlenz@4: ==========================
cmlenz@4: Number and Date Formatting
cmlenz@4: ==========================
cmlenz@4: 
cmlenz@4: 
cmlenz@4: .. contents:: Contents
cmlenz@4:    :depth: 2
cmlenz@4: .. sectnum::
cmlenz@4: 
cmlenz@4: 
cmlenz@20: Date Formatting
cmlenz@20: ===============
cmlenz@20: 
cmlenz@20: When working with date and time information in Python, you commonly use the
cmlenz@100: classes ``date``, ``datetime`` and/or ``time`` from the `datetime`_ package.
cmlenz@20: Babel provides functions for locale-specific formatting of those objects in its
cmlenz@42: ``dates`` module:
cmlenz@42: 
cmlenz@100: .. _`datetime`: http://docs.python.org/lib/module-datetime.html
cmlenz@100: 
cmlenz@42: .. code-block:: pycon
cmlenz@20: 
cmlenz@20:     >>> from datetime import date, datetime, time
cmlenz@20:     >>> from babel.dates import format_date, format_datetime, format_time
cmlenz@20: 
cmlenz@20:     >>> d = date(2007, 4, 1)
cmlenz@20:     >>> format_date(d, locale='en')
cmlenz@20:     u'Apr 1, 2007'
cmlenz@20:     >>> format_date(d, locale='de_DE')
cmlenz@20:     u'01.04.2007'
cmlenz@20: 
cmlenz@20: As this example demonstrates, Babel will automatically choose a date format
cmlenz@20: that is appropriate for the requested locale.
cmlenz@20: 
cmlenz@20: The ``format_*()`` functions also accept an optional ``format`` argument, which
cmlenz@20: allows you to choose between one of four format variations:
cmlenz@20: 
cmlenz@20:  * ``short``,
cmlenz@20:  * ``medium`` (the default),
cmlenz@22:  * ``long``, and
cmlenz@22:  * ``full``.
cmlenz@20: 
cmlenz@42: For example:
cmlenz@42: 
cmlenz@42: .. code-block:: pycon
cmlenz@20: 
cmlenz@20:     >>> format_date(d, format='short', locale='en')
cmlenz@20:     u'4/1/07'
cmlenz@20:     >>> format_date(d, format='long', locale='en')
cmlenz@20:     u'April 1, 2007'
cmlenz@20:     >>> format_date(d, format='full', locale='en')
cmlenz@20:     u'Sunday, April 1, 2007'
cmlenz@20: 
cmlenz@20: 
cmlenz@20: Pattern Syntax
cmlenz@20: --------------
cmlenz@20: 
cmlenz@20: While Babel makes it simple to use the appropriate date/time format for a given
cmlenz@20: locale, you can also force it to use custom patterns. Note that Babel uses
cmlenz@20: different patterns for specifying number and date formats compared to the
cmlenz@20: Python equivalents (such as ``time.strftime()``), which have mostly been
cmlenz@20: inherited from C and POSIX. The patterns used in Babel are based on the
cmlenz@20: `Locale Data Markup Language specification`_ (LDML), which defines them as
cmlenz@20: follows:
cmlenz@20: 
cmlenz@20:     A date/time pattern is a string of characters, where specific strings of
cmlenz@20:     characters are replaced with date and time data from a calendar when formatting
cmlenz@20:     or used to generate data for a calendar when parsing. […]
cmlenz@20: 
cmlenz@20:     Characters may be used multiple times. For example, if ``y`` is used for the
cmlenz@20:     year, ``yy`` might produce "99", whereas ``yyyy`` produces "1999". For most
cmlenz@20:     numerical fields, the number of characters specifies the field width. For
cmlenz@20:     example, if ``h`` is the hour, ``h`` might produce "5", but ``hh`` produces
cmlenz@20:     "05". For some characters, the count specifies whether an abbreviated or full
cmlenz@20:     form should be used […]
cmlenz@20: 
cmlenz@20:     Two single quotes represent a literal single quote, either inside or outside
cmlenz@20:     single quotes. Text within single quotes is not interpreted in any way (except
cmlenz@20:     for two adjacent single quotes).
cmlenz@20: 
cmlenz@42: For example:
cmlenz@42: 
cmlenz@42: .. code-block:: pycon
cmlenz@20: 
cmlenz@20:     >>> d = date(2007, 4, 1)
cmlenz@20:     >>> format_date(d, "EEE, MMM d, ''yy", locale='en')
cmlenz@20:     u"Sun, Apr 1, '07"
cmlenz@20:     >>> format_date(d, "EEEE, d.M.yyyy", locale='de')
cmlenz@20:     u'Sonntag, 1.4.2007'
cmlenz@20: 
cmlenz@20:     >>> t = time(15, 30)
cmlenz@20:     >>> format_time(t, "hh 'o''clock' a", locale='en')
cmlenz@20:     u"03 o'clock PM"
cmlenz@20:     >>> format_time(t, 'H:mm a', locale='de')
cmlenz@20:     u'15:30 nachm.'
cmlenz@20: 
cmlenz@20:     >>> dt = datetime(2007, 4, 1, 15, 30)
cmlenz@20:     >>> format_datetime(dt, "yyyyy.MMMM.dd GGG hh:mm a", locale='en')
cmlenz@20:     u'02007.April.01 AD 03:30 PM'
cmlenz@20: 
cmlenz@20: The syntax for custom datetime format patterns is described in detail in the
cmlenz@20: the `Locale Data Markup Language specification`_. The following table is just a
cmlenz@20: relatively brief overview.
cmlenz@20: 
cmlenz@20:  .. _`Locale Data Markup Language specification`: http://unicode.org/reports/tr35/#Date_Format_Patterns
cmlenz@20: 
cmlenz@20: -----------
cmlenz@20: Date Fields
cmlenz@20: -----------
cmlenz@20: 
cmlenz@20:   +----------+--------+--------------------------------------------------------+
cmlenz@20:   | Field    | Symbol | Description                                            |
cmlenz@20:   +==========+========+========================================================+
cmlenz@20:   | Era      | ``G``  | Replaced with the era string for the current date. One |
cmlenz@20:   |          |        | to three letters for the abbreviated form, four        |
cmlenz@20:   |          |        | lettersfor the long form, five for the narrow form     |
cmlenz@20:   +----------+--------+--------------------------------------------------------+
cmlenz@20:   | Year     | ``y``  | Replaced by the year. Normally the length specifies    |
cmlenz@20:   |          |        | the padding, but for two letters it also specifies the |
cmlenz@20:   |          |        | maximum length.                                        |
cmlenz@20:   |          +--------+--------------------------------------------------------+
cmlenz@20:   |          | ``Y``  | Same as ``y`` but uses the ISO year-week calendar.     |
cmlenz@20:   |          +--------+--------------------------------------------------------+
cmlenz@20:   |          | ``u``  | ??                                                     |
cmlenz@20:   +----------+--------+--------------------------------------------------------+
cmlenz@20:   | Quarter  | ``Q``  | Use one or two for the numerical quarter, three for    |
cmlenz@20:   |          |        | the abbreviation, or four for the full name.           |
cmlenz@20:   |          +--------+--------------------------------------------------------+
cmlenz@20:   |          | ``q``  | Use one or two for the numerical quarter, three for    |
cmlenz@20:   |          |        | the abbreviation, or four for the full name.           |
cmlenz@20:   +----------+--------+--------------------------------------------------------+
cmlenz@20:   | Month    | ``M``  | Use one or two for the numerical month, three for the  |
cmlenz@20:   |          |        | abbreviation, or four for the full name, or five for   |
cmlenz@20:   |          |        | the narrow name.                                       |
cmlenz@20:   |          +--------+--------------------------------------------------------+
cmlenz@20:   |          | ``L``  | Use one or two for the numerical month, three for the  |
cmlenz@20:   |          |        | abbreviation, or four for the full name, or 5 for the  |
cmlenz@20:   |          |        | narrow name.                                           |
cmlenz@20:   +----------+--------+--------------------------------------------------------+
cmlenz@20:   | Week     | ``w``  | Week of year.                                          |
cmlenz@20:   |          +--------+--------------------------------------------------------+
cmlenz@20:   |          | ``W``  | Week of month.                                         |
cmlenz@20:   +----------+--------+--------------------------------------------------------+
cmlenz@20:   | Day      | ``d``  | Day of month.                                          |
cmlenz@20:   |          +--------+--------------------------------------------------------+
cmlenz@20:   |          | ``D``  | Day of year.                                           |
cmlenz@20:   |          +--------+--------------------------------------------------------+
cmlenz@20:   |          | ``F``  | Day of week in month.                                  |
cmlenz@20:   |          +--------+--------------------------------------------------------+
cmlenz@20:   |          | ``g``  | ??                                                     |
cmlenz@20:   +----------+--------+--------------------------------------------------------+
cmlenz@20:   | Week day | ``E``  | Day of week. Use one through three letters for the     |
cmlenz@20:   |          |        | short day, or four for the full name, or five for the  |
cmlenz@20:   |          |        | narrow name.                                           |
cmlenz@20:   |          +--------+--------------------------------------------------------+
cmlenz@20:   |          | ``e``  | Local day of week. Same as E except adds a numeric     |
cmlenz@20:   |          |        | value that will depend on the local starting day of    |
cmlenz@20:   |          |        | the week, using one or two letters.                    |
cmlenz@20:   |          +--------+--------------------------------------------------------+
cmlenz@20:   |          | ``c``  | ??                                                     |
cmlenz@20:   +----------+--------+--------------------------------------------------------+
cmlenz@20: 
cmlenz@20: -----------
cmlenz@20: Time Fields
cmlenz@20: -----------
cmlenz@20: 
cmlenz@20:   +----------+--------+--------------------------------------------------------+
cmlenz@20:   | Field    | Symbol | Description                                            |
cmlenz@20:   +==========+========+========================================================+
cmlenz@20:   | Period   | ``a``  | AM or PM                                               |
cmlenz@20:   +----------+--------+--------------------------------------------------------+
cmlenz@20:   | Hour     | ``h``  | Hour [1-12].                                           |
cmlenz@20:   |          +--------+--------------------------------------------------------+
cmlenz@20:   |          | ``H``  | Hour [0-23].                                           |
cmlenz@20:   |          +--------+--------------------------------------------------------+
cmlenz@20:   |          | ``K``  | Hour [0-11].                                           |
cmlenz@20:   |          +--------+--------------------------------------------------------+
cmlenz@20:   |          | ``k``  | Hour [1-24].                                           |
cmlenz@20:   +----------+--------+--------------------------------------------------------+
cmlenz@20:   | Minute   | ``m``  | Use one or two for zero places padding.                |
cmlenz@20:   +----------+--------+--------------------------------------------------------+
cmlenz@20:   | Second   | ``s``  | Use one or two for zero places padding.                |
cmlenz@20:   |          +--------+--------------------------------------------------------+
cmlenz@20:   |          | ``S``  | Fractional second, rounds to the count of letters.     |
cmlenz@20:   |          +--------+--------------------------------------------------------+
cmlenz@20:   |          | ``A``  | Milliseconds in day.                                   |
cmlenz@20:   +----------+--------+--------------------------------------------------------+ 
cmlenz@20:   | Timezone | ``z``  | Use one to three letters for the short timezone or     |
cmlenz@20:   |          |        | four for the full name.                                |
cmlenz@20:   |          +--------+--------------------------------------------------------+
cmlenz@20:   |          | ``Z``  | Use one to three letters for RFC 822, four letters for |
cmlenz@20:   |          |        | GMT format.                                            |
cmlenz@20:   |          +--------+--------------------------------------------------------+
cmlenz@20:   |          | ``v``  | Use one letter for short wall (generic) time, four for |
cmlenz@20:   |          |        | long wall time.                                        |
cmlenz@20:   +----------+--------+--------------------------------------------------------+
cmlenz@20: 
cmlenz@20: 
cmlenz@33: Time-Zone Support
cmlenz@31: -----------------
cmlenz@31: 
cmlenz@33: Many of the verbose time formats include the time-zone, but time-zone
cmlenz@33: information is not by default available for the Python ``datetime`` and
cmlenz@33: ``time`` objects. The standard library includes only the abstract ``tzinfo``
cmlenz@33: class, which you need appropriate implementations for to actually use in your
cmlenz@31: application. Babel includes a ``tzinfo`` implementation for UTC (Universal
cmlenz@33: Time).
cmlenz@33: 
cmlenz@33: For real time-zone support, it is strongly recommended that you use the
cmlenz@31: third-party package `pytz`_, which includes the definitions of practically all
cmlenz@31: of the time-zones used on the world, as well as important functions for
cmlenz@42: reliably converting from UTC to local time, and vice versa:
cmlenz@42: 
cmlenz@42: .. code-block:: pycon
cmlenz@31: 
cmlenz@31:     >>> from datetime import time
cmlenz@36:     >>> from pytz import timezone, utc
cmlenz@36:     >>> dt = datetime(2007, 04, 01, 15, 30, tzinfo=utc)
cmlenz@36:     >>> eastern = timezone('US/Eastern')
cmlenz@36:     >>> format_datetime(dt, 'H:mm Z', tzinfo=eastern, locale='en_US')
cmlenz@36:     u'11:30 -0400'
cmlenz@31: 
cmlenz@31: The recommended approach to deal with different time-zones in a Python
cmlenz@31: application is to always use UTC internally, and only convert from/to the users
cmlenz@31: time-zone when accepting user input and displaying date/time data, respectively.
cmlenz@36: You can use Babel together with ``pytz`` to apply a time-zone to any
cmlenz@36: ``datetime`` or ``time`` object for display, leaving the original information
cmlenz@42: unchanged:
cmlenz@42: 
cmlenz@42: .. code-block:: pycon
cmlenz@36: 
cmlenz@36:     >>> british = timezone('Europe/London')
cmlenz@36:     >>> format_datetime(dt, 'H:mm zzzz', tzinfo=british, locale='en_US')
cmlenz@36:     u'16:30 British Summer Time'
cmlenz@31: 
cmlenz@37: Here, the given UTC time is adjusted to the "Europe/London" time-zone, and
cmlenz@37: daylight savings time is taken into account. Daylight savings time is also
cmlenz@37: applied to ``format_time``, but because the actual date is unknown in that
cmlenz@37: case, the current day is assumed to determine whether DST or standard time
cmlenz@37: should be used.
cmlenz@37: 
cmlenz@31:  .. _`pytz`: http://pytz.sourceforge.net/
cmlenz@31: 
cmlenz@31: 
cmlenz@20: Parsing Dates
cmlenz@20: -------------
cmlenz@20: 
cmlenz@42: Babel can also parse date and time information in a locale-sensitive manner:
cmlenz@42: 
cmlenz@42: .. code-block:: pycon
cmlenz@20: 
cmlenz@20:     >>> from babel.dates import parse_date, parse_datetime, parse_time
cmlenz@20: 
cmlenz@20: 
cmlenz@20: Number Formatting
cmlenz@20: =================
cmlenz@20: 
cmlenz@34: Support for locale-specific formatting and parsing of numbers is provided by
cmlenz@42: the ``babel.numbers`` module:
cmlenz@42: 
cmlenz@42: .. code-block:: pycon
cmlenz@34: 
cmlenz@34:     >>> from babel.numbers import format_number, format_decimal, format_percent
cmlenz@34: 
cmlenz@42: Examples:
cmlenz@42: 
cmlenz@42: .. code-block:: pycon
cmlenz@34: 
cmlenz@34:     >>> format_decimal(1.2345, locale='en_US')
cmlenz@34:     u'1.234'
cmlenz@34:     >>> format_decimal(1.2345, locale='sv_SE')
cmlenz@34:     u'1,234'
cmlenz@34:     >>> format_decimal(12345, locale='de_DE')
cmlenz@34:     u'12.345'
cmlenz@34: 
cmlenz@20: 
cmlenz@20: Pattern Syntax
cmlenz@20: --------------
cmlenz@20: 
cmlenz@34: While Babel makes it simple to use the appropriate number format for a given
cmlenz@34: locale, you can also force it to use custom patterns. As with date/time
cmlenz@34: formatting patterns, the patterns Babel supports for number formatting are
cmlenz@34: based on the `Locale Data Markup Language specification`_ (LDML).
cmlenz@34: 
cmlenz@42: Examples:
cmlenz@42: 
cmlenz@42: .. code-block:: pycon
cmlenz@34: 
cmlenz@34:     >>> format_decimal(-1.2345, format='#,##0.##;-#', locale='en')
cmlenz@34:     u'-1.23'
cmlenz@34:     >>> format_decimal(-1.2345, format='#,##0.##;(#)', locale='en')
cmlenz@34:     u'(1.23)'
cmlenz@34: 
cmlenz@34: The syntax for custom number format patterns is described in detail in the
cmlenz@34: the specification. The following table is just a relatively brief overview.
cmlenz@34: 
cmlenz@34:   +----------+-----------------------------------------------------------------+
cmlenz@34:   | Symbol   | Description                                                     |
cmlenz@34:   +==========+=================================================================+
cmlenz@34:   | ``0``    | Digit                                                           |
cmlenz@34:   +----------+-----------------------------------------------------------------+
cmlenz@34:   | ``1-9``  | '1' through '9' indicate rounding.                              |
cmlenz@34:   +----------+-----------------------------------------------------------------+
cmlenz@34:   | ``@``    | Significant digit                                               |
cmlenz@34:   +----------+-----------------------------------------------------------------+
cmlenz@34:   | ``#``    | Digit, zero shows as absent                                     |
cmlenz@34:   +----------+-----------------------------------------------------------------+
cmlenz@34:   | ``.``    | Decimal separator or monetary decimal separator                 |
cmlenz@34:   +----------+-----------------------------------------------------------------+
cmlenz@34:   | ``-``    | Minus sign                                                      |
cmlenz@34:   +----------+-----------------------------------------------------------------+
cmlenz@34:   | ``,``    | Grouping separator                                              |
cmlenz@34:   +----------+-----------------------------------------------------------------+
cmlenz@34:   | ``E``    | Separates mantissa and exponent in scientific notation          |
cmlenz@34:   +----------+-----------------------------------------------------------------+
cmlenz@34:   | ``+``    | Prefix positive exponents with localized plus sign              |
cmlenz@34:   +----------+-----------------------------------------------------------------+
cmlenz@34:   | ``;``    | Separates positive and negative subpatterns                     |
cmlenz@34:   +----------+-----------------------------------------------------------------+
cmlenz@34:   | ``%``    | Multiply by 100 and show as percentage                          |
cmlenz@34:   +----------+-----------------------------------------------------------------+
cmlenz@34:   | ``‰``    | Multiply by 1000 and show as per mille                          |
cmlenz@34:   +----------+-----------------------------------------------------------------+
cmlenz@34:   | ``¤``    | Currency sign, replaced by currency symbol. If doubled,         |
cmlenz@34:   |          | replaced by international currency symbol. If tripled, uses the |
cmlenz@34:   |          | long form of the decimal symbol.                                |
cmlenz@34:   +----------+-----------------------------------------------------------------+
cmlenz@34:   | ``'``    | Used to quote special characters in a prefix or suffix          |
cmlenz@34:   +----------+-----------------------------------------------------------------+
cmlenz@34:   | ``*``    | Pad escape, precedes pad character                              |
cmlenz@34:   +----------+-----------------------------------------------------------------+
cmlenz@34: 
cmlenz@20: 
cmlenz@20: Parsing Numbers
cmlenz@20: ---------------
cmlenz@34: 
cmlenz@42: Babel can also parse numeric data in a locale-sensitive manner:
cmlenz@42: 
cmlenz@42: .. code-block:: pycon
cmlenz@34: 
cmlenz@36:     >>> from babel.numbers import parse_decimal, parse_number
cmlenz@34: 
cmlenz@42: Examples:
cmlenz@42: 
cmlenz@42: .. code-block:: pycon
cmlenz@34: 
cmlenz@34:     >>> parse_decimal('1,099.98', locale='en_US')
cmlenz@34:     1099.98
cmlenz@34:     >>> parse_decimal('1.099,98', locale='de')
cmlenz@34:     1099.98
cmlenz@34:     >>> parse_decimal('2,109,998', locale='de')
cmlenz@34:     Traceback (most recent call last):
cmlenz@42:       ...
cmlenz@34:     NumberFormatError: '2,109,998' is not a valid decimal number