| Current File : //proc/self/root/proc/self/root/usr/share/doc/python-babel-0.9.6/doc/dates.txt |
.. -*- mode: rst; encoding: utf-8 -*-
===============
Date Formatting
===============
.. contents:: Contents
:depth: 2
.. sectnum::
When working with date and time information in Python, you commonly use the
classes ``date``, ``datetime`` and/or ``time`` from the `datetime`_ package.
Babel provides functions for locale-specific formatting of those objects in its
``dates`` module:
.. _`datetime`: http://docs.python.org/lib/module-datetime.html
.. code-block:: pycon
>>> from datetime import date, datetime, time
>>> from babel.dates import format_date, format_datetime, format_time
>>> d = date(2007, 4, 1)
>>> format_date(d, locale='en')
u'Apr 1, 2007'
>>> format_date(d, locale='de_DE')
u'01.04.2007'
As this example demonstrates, Babel will automatically choose a date format
that is appropriate for the requested locale.
The ``format_*()`` functions also accept an optional ``format`` argument, which
allows you to choose between one of four format variations:
* ``short``,
* ``medium`` (the default),
* ``long``, and
* ``full``.
For example:
.. code-block:: pycon
>>> format_date(d, format='short', locale='en')
u'4/1/07'
>>> format_date(d, format='long', locale='en')
u'April 1, 2007'
>>> format_date(d, format='full', locale='en')
u'Sunday, April 1, 2007'
Pattern Syntax
==============
While Babel makes it simple to use the appropriate date/time format for a given
locale, you can also force it to use custom patterns. Note that Babel uses
different patterns for specifying number and date formats compared to the
Python equivalents (such as ``time.strftime()``), which have mostly been
inherited from C and POSIX. The patterns used in Babel are based on the
`Locale Data Markup Language specification`_ (LDML), which defines them as
follows:
A date/time pattern is a string of characters, where specific strings of
characters are replaced with date and time data from a calendar when formatting
or used to generate data for a calendar when parsing. […]
Characters may be used multiple times. For example, if ``y`` is used for the
year, ``yy`` might produce "99", whereas ``yyyy`` produces "1999". For most
numerical fields, the number of characters specifies the field width. For
example, if ``h`` is the hour, ``h`` might produce "5", but ``hh`` produces
"05". For some characters, the count specifies whether an abbreviated or full
form should be used […]
Two single quotes represent a literal single quote, either inside or outside
single quotes. Text within single quotes is not interpreted in any way (except
for two adjacent single quotes).
For example:
.. code-block:: pycon
>>> d = date(2007, 4, 1)
>>> format_date(d, "EEE, MMM d, ''yy", locale='en')
u"Sun, Apr 1, '07"
>>> format_date(d, "EEEE, d.M.yyyy", locale='de')
u'Sonntag, 1.4.2007'
>>> t = time(15, 30)
>>> format_time(t, "hh 'o''clock' a", locale='en')
u"03 o'clock PM"
>>> format_time(t, 'H:mm a', locale='de')
u'15:30 nachm.'
>>> dt = datetime(2007, 4, 1, 15, 30)
>>> format_datetime(dt, "yyyyy.MMMM.dd GGG hh:mm a", locale='en')
u'02007.April.01 AD 03:30 PM'
The syntax for custom datetime format patterns is described in detail in the
the `Locale Data Markup Language specification`_. The following table is just a
relatively brief overview.
.. _`Locale Data Markup Language specification`: http://unicode.org/reports/tr35/#Date_Format_Patterns
Date Fields
-----------
+----------+--------+--------------------------------------------------------+
| Field | Symbol | Description |
+==========+========+========================================================+
| Era | ``G`` | Replaced with the era string for the current date. One |
| | | to three letters for the abbreviated form, four |
| | | lettersfor the long form, five for the narrow form |
+----------+--------+--------------------------------------------------------+
| Year | ``y`` | Replaced by the year. Normally the length specifies |
| | | the padding, but for two letters it also specifies the |
| | | maximum length. |
| +--------+--------------------------------------------------------+
| | ``Y`` | Same as ``y`` but uses the ISO year-week calendar. |
| +--------+--------------------------------------------------------+
| | ``u`` | ?? |
+----------+--------+--------------------------------------------------------+
| Quarter | ``Q`` | Use one or two for the numerical quarter, three for |
| | | the abbreviation, or four for the full name. |
| +--------+--------------------------------------------------------+
| | ``q`` | Use one or two for the numerical quarter, three for |
| | | the abbreviation, or four for the full name. |
+----------+--------+--------------------------------------------------------+
| Month | ``M`` | Use one or two for the numerical month, three for the |
| | | abbreviation, or four for the full name, or five for |
| | | the narrow name. |
| +--------+--------------------------------------------------------+
| | ``L`` | Use one or two for the numerical month, three for the |
| | | abbreviation, or four for the full name, or 5 for the |
| | | narrow name. |
+----------+--------+--------------------------------------------------------+
| Week | ``w`` | Week of year. |
| +--------+--------------------------------------------------------+
| | ``W`` | Week of month. |
+----------+--------+--------------------------------------------------------+
| Day | ``d`` | Day of month. |
| +--------+--------------------------------------------------------+
| | ``D`` | Day of year. |
| +--------+--------------------------------------------------------+
| | ``F`` | Day of week in month. |
| +--------+--------------------------------------------------------+
| | ``g`` | ?? |
+----------+--------+--------------------------------------------------------+
| Week day | ``E`` | Day of week. Use one through three letters for the |
| | | short day, or four for the full name, or five for the |
| | | narrow name. |
| +--------+--------------------------------------------------------+
| | ``e`` | Local day of week. Same as E except adds a numeric |
| | | value that will depend on the local starting day of |
| | | the week, using one or two letters. |
| +--------+--------------------------------------------------------+
| | ``c`` | ?? |
+----------+--------+--------------------------------------------------------+
Time Fields
-----------
+----------+--------+--------------------------------------------------------+
| Field | Symbol | Description |
+==========+========+========================================================+
| Period | ``a`` | AM or PM |
+----------+--------+--------------------------------------------------------+
| Hour | ``h`` | Hour [1-12]. |
| +--------+--------------------------------------------------------+
| | ``H`` | Hour [0-23]. |
| +--------+--------------------------------------------------------+
| | ``K`` | Hour [0-11]. |
| +--------+--------------------------------------------------------+
| | ``k`` | Hour [1-24]. |
+----------+--------+--------------------------------------------------------+
| Minute | ``m`` | Use one or two for zero places padding. |
+----------+--------+--------------------------------------------------------+
| Second | ``s`` | Use one or two for zero places padding. |
| +--------+--------------------------------------------------------+
| | ``S`` | Fractional second, rounds to the count of letters. |
| +--------+--------------------------------------------------------+
| | ``A`` | Milliseconds in day. |
+----------+--------+--------------------------------------------------------+
| Timezone | ``z`` | Use one to three letters for the short timezone or |
| | | four for the full name. |
| +--------+--------------------------------------------------------+
| | ``Z`` | Use one to three letters for RFC 822, four letters for |
| | | GMT format. |
| +--------+--------------------------------------------------------+
| | ``v`` | Use one letter for short wall (generic) time, four for |
| | | long wall time. |
| +--------+--------------------------------------------------------+
| | ``V`` | Same as ``z``, except that timezone abbreviations |
| | | should be used regardless of whether they are in |
| | | common use by the locale. |
+----------+--------+--------------------------------------------------------+
Time-zone Support
=================
Many of the verbose time formats include the time-zone, but time-zone
information is not by default available for the Python ``datetime`` and
``time`` objects. The standard library includes only the abstract ``tzinfo``
class, which you need appropriate implementations for to actually use in your
application. Babel includes a ``tzinfo`` implementation for UTC (Universal
Time).
For real time-zone support, it is strongly recommended that you use the
third-party package `pytz`_, which includes the definitions of practically all
of the time-zones used on the world, as well as important functions for
reliably converting from UTC to local time, and vice versa:
.. code-block:: pycon
>>> from datetime import time
>>> from pytz import timezone, utc
>>> dt = datetime(2007, 04, 01, 15, 30, tzinfo=utc)
>>> eastern = timezone('US/Eastern')
>>> format_datetime(dt, 'H:mm Z', tzinfo=eastern, locale='en_US')
u'11:30 -0400'
The recommended approach to deal with different time-zones in a Python
application is to always use UTC internally, and only convert from/to the users
time-zone when accepting user input and displaying date/time data, respectively.
You can use Babel together with ``pytz`` to apply a time-zone to any
``datetime`` or ``time`` object for display, leaving the original information
unchanged:
.. code-block:: pycon
>>> british = timezone('Europe/London')
>>> format_datetime(dt, 'H:mm zzzz', tzinfo=british, locale='en_US')
u'16:30 British Summer Time'
Here, the given UTC time is adjusted to the "Europe/London" time-zone, and
daylight savings time is taken into account. Daylight savings time is also
applied to ``format_time``, but because the actual date is unknown in that
case, the current day is assumed to determine whether DST or standard time
should be used.
.. _`pytz`: http://pytz.sourceforge.net/
Localized Time-zone Names
-------------------------
While the ``Locale`` class provides access to various locale display names
related to time-zones, the process of building a localized name of a time-zone
is actually quite complicated. Babel implements it in separately usable
functions in the ``babel.dates`` module, most importantly the
``get_timezone_name`` function:
.. code-block:: pycon
>>> from pytz import timezone
>>> from babel import Locale
>>> from babel.dates import get_timezone_name
>>> tz = timezone('Europe/Berlin')
>>> get_timezone_name(tz, locale=Locale.parse('pt_PT'))
u'Hor\xe1rio Alemanha'
You can pass the function either a ``datetime.tzinfo`` object, or a
``datetime.date`` or ``datetime.datetime`` object. If you pass an actual date,
the function will be able to take daylight savings time into account. If you
pass just the time-zone, Babel does not know whether daylight savings time is
in effect, so it uses a generic representation, which is useful for example to
display a list of time-zones to the user.
.. code-block:: pycon
>>> from datetime import datetime
>>> dt = tz.localize(datetime(2007, 8, 15))
>>> get_timezone_name(dt, locale=Locale.parse('de_DE'))
u'Mitteleurop\xe4ische Sommerzeit'
>>> get_timezone_name(tz, locale=Locale.parse('de_DE'))
u'Deutschland'
Parsing Dates
=============
Babel can also parse date and time information in a locale-sensitive manner:
.. code-block:: pycon
>>> from babel.dates import parse_date, parse_datetime, parse_time
.. note:: Date/time parsing is not properly implemented yet