1
.. -*- mode: rst; encoding: utf-8 -*-
13
When working with date and time information in Python, you commonly use the
14
classes ``date``, ``datetime`` and/or ``time`` from the `datetime`_ package.
15
Babel provides functions for locale-specific formatting of those objects in its
18
.. _`datetime`: http://docs.python.org/lib/module-datetime.html
22
>>> from datetime import date, datetime, time
23
>>> from babel.dates import format_date, format_datetime, format_time
25
>>> d = date(2007, 4, 1)
26
>>> format_date(d, locale='en')
28
>>> format_date(d, locale='de_DE')
31
As this example demonstrates, Babel will automatically choose a date format
32
that is appropriate for the requested locale.
34
The ``format_*()`` functions also accept an optional ``format`` argument, which
35
allows you to choose between one of four format variations:
38
* ``medium`` (the default),
46
>>> format_date(d, format='short', locale='en')
48
>>> format_date(d, format='long', locale='en')
50
>>> format_date(d, format='full', locale='en')
51
u'Sunday, April 1, 2007'
57
While Babel makes it simple to use the appropriate date/time format for a given
58
locale, you can also force it to use custom patterns. Note that Babel uses
59
different patterns for specifying number and date formats compared to the
60
Python equivalents (such as ``time.strftime()``), which have mostly been
61
inherited from C and POSIX. The patterns used in Babel are based on the
62
`Locale Data Markup Language specification`_ (LDML), which defines them as
65
A date/time pattern is a string of characters, where specific strings of
66
characters are replaced with date and time data from a calendar when formatting
67
or used to generate data for a calendar when parsing. […]
69
Characters may be used multiple times. For example, if ``y`` is used for the
70
year, ``yy`` might produce "99", whereas ``yyyy`` produces "1999". For most
71
numerical fields, the number of characters specifies the field width. For
72
example, if ``h`` is the hour, ``h`` might produce "5", but ``hh`` produces
73
"05". For some characters, the count specifies whether an abbreviated or full
74
form should be used […]
76
Two single quotes represent a literal single quote, either inside or outside
77
single quotes. Text within single quotes is not interpreted in any way (except
78
for two adjacent single quotes).
84
>>> d = date(2007, 4, 1)
85
>>> format_date(d, "EEE, MMM d, ''yy", locale='en')
87
>>> format_date(d, "EEEE, d.M.yyyy", locale='de')
91
>>> format_time(t, "hh 'o''clock' a", locale='en')
93
>>> format_time(t, 'H:mm a', locale='de')
96
>>> dt = datetime(2007, 4, 1, 15, 30)
97
>>> format_datetime(dt, "yyyyy.MMMM.dd GGG hh:mm a", locale='en')
98
u'02007.April.01 AD 03:30 PM'
100
The syntax for custom datetime format patterns is described in detail in the
101
the `Locale Data Markup Language specification`_. The following table is just a
102
relatively brief overview.
104
.. _`Locale Data Markup Language specification`: http://unicode.org/reports/tr35/#Date_Format_Patterns
109
+----------+--------+--------------------------------------------------------+
110
| Field | Symbol | Description |
111
+==========+========+========================================================+
112
| Era | ``G`` | Replaced with the era string for the current date. One |
113
| | | to three letters for the abbreviated form, four |
114
| | | lettersfor the long form, five for the narrow form |
115
+----------+--------+--------------------------------------------------------+
116
| Year | ``y`` | Replaced by the year. Normally the length specifies |
117
| | | the padding, but for two letters it also specifies the |
118
| | | maximum length. |
119
| +--------+--------------------------------------------------------+
120
| | ``Y`` | Same as ``y`` but uses the ISO year-week calendar. |
121
| +--------+--------------------------------------------------------+
123
+----------+--------+--------------------------------------------------------+
124
| Quarter | ``Q`` | Use one or two for the numerical quarter, three for |
125
| | | the abbreviation, or four for the full name. |
126
| +--------+--------------------------------------------------------+
127
| | ``q`` | Use one or two for the numerical quarter, three for |
128
| | | the abbreviation, or four for the full name. |
129
+----------+--------+--------------------------------------------------------+
130
| Month | ``M`` | Use one or two for the numerical month, three for the |
131
| | | abbreviation, or four for the full name, or five for |
132
| | | the narrow name. |
133
| +--------+--------------------------------------------------------+
134
| | ``L`` | Use one or two for the numerical month, three for the |
135
| | | abbreviation, or four for the full name, or 5 for the |
137
+----------+--------+--------------------------------------------------------+
138
| Week | ``w`` | Week of year. |
139
| +--------+--------------------------------------------------------+
140
| | ``W`` | Week of month. |
141
+----------+--------+--------------------------------------------------------+
142
| Day | ``d`` | Day of month. |
143
| +--------+--------------------------------------------------------+
144
| | ``D`` | Day of year. |
145
| +--------+--------------------------------------------------------+
146
| | ``F`` | Day of week in month. |
147
| +--------+--------------------------------------------------------+
149
+----------+--------+--------------------------------------------------------+
150
| Week day | ``E`` | Day of week. Use one through three letters for the |
151
| | | short day, or four for the full name, or five for the |
153
| +--------+--------------------------------------------------------+
154
| | ``e`` | Local day of week. Same as E except adds a numeric |
155
| | | value that will depend on the local starting day of |
156
| | | the week, using one or two letters. |
157
| +--------+--------------------------------------------------------+
159
+----------+--------+--------------------------------------------------------+
164
+----------+--------+--------------------------------------------------------+
165
| Field | Symbol | Description |
166
+==========+========+========================================================+
167
| Period | ``a`` | AM or PM |
168
+----------+--------+--------------------------------------------------------+
169
| Hour | ``h`` | Hour [1-12]. |
170
| +--------+--------------------------------------------------------+
171
| | ``H`` | Hour [0-23]. |
172
| +--------+--------------------------------------------------------+
173
| | ``K`` | Hour [0-11]. |
174
| +--------+--------------------------------------------------------+
175
| | ``k`` | Hour [1-24]. |
176
+----------+--------+--------------------------------------------------------+
177
| Minute | ``m`` | Use one or two for zero places padding. |
178
+----------+--------+--------------------------------------------------------+
179
| Second | ``s`` | Use one or two for zero places padding. |
180
| +--------+--------------------------------------------------------+
181
| | ``S`` | Fractional second, rounds to the count of letters. |
182
| +--------+--------------------------------------------------------+
183
| | ``A`` | Milliseconds in day. |
184
+----------+--------+--------------------------------------------------------+
185
| Timezone | ``z`` | Use one to three letters for the short timezone or |
186
| | | four for the full name. |
187
| +--------+--------------------------------------------------------+
188
| | ``Z`` | Use one to three letters for RFC 822, four letters for |
190
| +--------+--------------------------------------------------------+
191
| | ``v`` | Use one letter for short wall (generic) time, four for |
192
| | | long wall time. |
193
| +--------+--------------------------------------------------------+
194
| | ``V`` | Same as ``z``, except that timezone abbreviations |
195
| | | should be used regardless of whether they are in |
196
| | | common use by the locale. |
197
+----------+--------+--------------------------------------------------------+
203
Many of the verbose time formats include the time-zone, but time-zone
204
information is not by default available for the Python ``datetime`` and
205
``time`` objects. The standard library includes only the abstract ``tzinfo``
206
class, which you need appropriate implementations for to actually use in your
207
application. Babel includes a ``tzinfo`` implementation for UTC (Universal
210
For real time-zone support, it is strongly recommended that you use the
211
third-party package `pytz`_, which includes the definitions of practically all
212
of the time-zones used on the world, as well as important functions for
213
reliably converting from UTC to local time, and vice versa:
215
.. code-block:: pycon
217
>>> from datetime import time
218
>>> from pytz import timezone, utc
219
>>> dt = datetime(2007, 04, 01, 15, 30, tzinfo=utc)
220
>>> eastern = timezone('US/Eastern')
221
>>> format_datetime(dt, 'H:mm Z', tzinfo=eastern, locale='en_US')
224
The recommended approach to deal with different time-zones in a Python
225
application is to always use UTC internally, and only convert from/to the users
226
time-zone when accepting user input and displaying date/time data, respectively.
227
You can use Babel together with ``pytz`` to apply a time-zone to any
228
``datetime`` or ``time`` object for display, leaving the original information
231
.. code-block:: pycon
233
>>> british = timezone('Europe/London')
234
>>> format_datetime(dt, 'H:mm zzzz', tzinfo=british, locale='en_US')
235
u'16:30 British Summer Time'
237
Here, the given UTC time is adjusted to the "Europe/London" time-zone, and
238
daylight savings time is taken into account. Daylight savings time is also
239
applied to ``format_time``, but because the actual date is unknown in that
240
case, the current day is assumed to determine whether DST or standard time
243
.. _`pytz`: http://pytz.sourceforge.net/
246
Localized Time-zone Names
247
-------------------------
249
While the ``Locale`` class provides access to various locale display names
250
related to time-zones, the process of building a localized name of a time-zone
251
is actually quite complicated. Babel implements it in separately usable
252
functions in the ``babel.dates`` module, most importantly the
253
``get_timezone_name`` function:
255
.. code-block:: pycon
257
>>> from pytz import timezone
258
>>> from babel import Locale
259
>>> from babel.dates import get_timezone_name
261
>>> tz = timezone('Europe/Berlin')
262
>>> get_timezone_name(tz, locale=Locale.parse('pt_PT'))
263
u'Hor\xe1rio Alemanha'
265
You can pass the function either a ``datetime.tzinfo`` object, or a
266
``datetime.date`` or ``datetime.datetime`` object. If you pass an actual date,
267
the function will be able to take daylight savings time into account. If you
268
pass just the time-zone, Babel does not know whether daylight savings time is
269
in effect, so it uses a generic representation, which is useful for example to
270
display a list of time-zones to the user.
272
.. code-block:: pycon
274
>>> from datetime import datetime
276
>>> dt = tz.localize(datetime(2007, 8, 15))
277
>>> get_timezone_name(dt, locale=Locale.parse('de_DE'))
278
u'Mitteleurop\xe4ische Sommerzeit'
279
>>> get_timezone_name(tz, locale=Locale.parse('de_DE'))
286
Babel can also parse date and time information in a locale-sensitive manner:
288
.. code-block:: pycon
290
>>> from babel.dates import parse_date, parse_datetime, parse_time
292
.. note:: Date/time parsing is not properly implemented yet
added
removed
doc/dates.txt
