|
263
|
1 .. -*- mode: rst; encoding: utf-8 -*-
|
|
|
2
|
|
|
3 ===============
|
|
|
4 Date Formatting
|
|
|
5 ===============
|
|
|
6
|
|
|
7
|
|
|
8 .. contents:: Contents
|
|
|
9 :depth: 2
|
|
|
10 .. sectnum::
|
|
|
11
|
|
|
12
|
|
|
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
|
|
|
16 ``dates`` module:
|
|
|
17
|
|
|
18 .. _`datetime`: http://docs.python.org/lib/module-datetime.html
|
|
|
19
|
|
|
20 .. code-block:: pycon
|
|
|
21
|
|
|
22 >>> from datetime import date, datetime, time
|
|
|
23 >>> from babel.dates import format_date, format_datetime, format_time
|
|
|
24
|
|
|
25 >>> d = date(2007, 4, 1)
|
|
|
26 >>> format_date(d, locale='en')
|
|
|
27 u'Apr 1, 2007'
|
|
|
28 >>> format_date(d, locale='de_DE')
|
|
|
29 u'01.04.2007'
|
|
|
30
|
|
|
31 As this example demonstrates, Babel will automatically choose a date format
|
|
|
32 that is appropriate for the requested locale.
|
|
|
33
|
|
|
34 The ``format_*()`` functions also accept an optional ``format`` argument, which
|
|
|
35 allows you to choose between one of four format variations:
|
|
|
36
|
|
|
37 * ``short``,
|
|
|
38 * ``medium`` (the default),
|
|
|
39 * ``long``, and
|
|
|
40 * ``full``.
|
|
|
41
|
|
|
42 For example:
|
|
|
43
|
|
|
44 .. code-block:: pycon
|
|
|
45
|
|
|
46 >>> format_date(d, format='short', locale='en')
|
|
|
47 u'4/1/07'
|
|
|
48 >>> format_date(d, format='long', locale='en')
|
|
|
49 u'April 1, 2007'
|
|
|
50 >>> format_date(d, format='full', locale='en')
|
|
|
51 u'Sunday, April 1, 2007'
|
|
|
52
|
|
|
53
|
|
|
54 Pattern Syntax
|
|
|
55 ==============
|
|
|
56
|
|
|
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
|
|
|
63 follows:
|
|
|
64
|
|
|
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. […]
|
|
|
68
|
|
|
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 […]
|
|
|
75
|
|
|
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).
|
|
|
79
|
|
|
80 For example:
|
|
|
81
|
|
|
82 .. code-block:: pycon
|
|
|
83
|
|
|
84 >>> d = date(2007, 4, 1)
|
|
|
85 >>> format_date(d, "EEE, MMM d, ''yy", locale='en')
|
|
|
86 u"Sun, Apr 1, '07"
|
|
|
87 >>> format_date(d, "EEEE, d.M.yyyy", locale='de')
|
|
|
88 u'Sonntag, 1.4.2007'
|
|
|
89
|
|
|
90 >>> t = time(15, 30)
|
|
|
91 >>> format_time(t, "hh 'o''clock' a", locale='en')
|
|
|
92 u"03 o'clock PM"
|
|
|
93 >>> format_time(t, 'H:mm a', locale='de')
|
|
|
94 u'15:30 nachm.'
|
|
|
95
|
|
|
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'
|
|
|
99
|
|
|
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.
|
|
|
103
|
|
|
104 .. _`Locale Data Markup Language specification`: http://unicode.org/reports/tr35/#Date_Format_Patterns
|
|
|
105
|
|
|
106 Date Fields
|
|
|
107 -----------
|
|
|
108
|
|
|
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 | +--------+--------------------------------------------------------+
|
|
|
122 | | ``u`` | ?? |
|
|
|
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 |
|
|
|
136 | | | narrow name. |
|
|
|
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 | +--------+--------------------------------------------------------+
|
|
|
148 | | ``g`` | ?? |
|
|
|
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 |
|
|
|
152 | | | narrow name. |
|
|
|
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 | +--------+--------------------------------------------------------+
|
|
|
158 | | ``c`` | ?? |
|
|
|
159 +----------+--------+--------------------------------------------------------+
|
|
|
160
|
|
|
161 Time Fields
|
|
|
162 -----------
|
|
|
163
|
|
|
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 |
|
|
|
189 | | | GMT format. |
|
|
|
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 +----------+--------+--------------------------------------------------------+
|
|
|
198
|
|
|
199
|
|
|
200 Time-zone Support
|
|
|
201 =================
|
|
|
202
|
|
|
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
|
|
|
208 Time).
|
|
|
209
|
|
|
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:
|
|
|
214
|
|
|
215 .. code-block:: pycon
|
|
|
216
|
|
|
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')
|
|
|
222 u'11:30 -0400'
|
|
|
223
|
|
|
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
|
|
|
229 unchanged:
|
|
|
230
|
|
|
231 .. code-block:: pycon
|
|
|
232
|
|
|
233 >>> british = timezone('Europe/London')
|
|
|
234 >>> format_datetime(dt, 'H:mm zzzz', tzinfo=british, locale='en_US')
|
|
|
235 u'16:30 British Summer Time'
|
|
|
236
|
|
|
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
|
|
|
241 should be used.
|
|
|
242
|
|
|
243 .. _`pytz`: http://pytz.sourceforge.net/
|
|
|
244
|
|
|
245
|
|
|
246 Localized Time-zone Names
|
|
|
247 -------------------------
|
|
|
248
|
|
|
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:
|
|
|
254
|
|
|
255 .. code-block:: pycon
|
|
|
256
|
|
|
257 >>> from pytz import timezone
|
|
|
258 >>> from babel import Locale
|
|
|
259 >>> from babel.dates import get_timezone_name
|
|
|
260
|
|
|
261 >>> tz = timezone('Europe/Berlin')
|
|
|
262 >>> get_timezone_name(tz, locale=Locale.parse('pt_PT'))
|
|
|
263 u'Hor\xe1rio Alemanha'
|
|
|
264
|
|
|
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.
|
|
|
271
|
|
|
272 .. code-block:: pycon
|
|
|
273
|
|
|
274 >>> from datetime import datetime
|
|
|
275
|
|
|
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'))
|
|
|
280 u'Deutschland'
|
|
|
281
|
|
|
282
|
|
|
283 Parsing Dates
|
|
|
284 =============
|
|
|
285
|
|
|
286 Babel can also parse date and time information in a locale-sensitive manner:
|
|
|
287
|
|
|
288 .. code-block:: pycon
|
|
|
289
|
|
|
290 >>> from babel.dates import parse_date, parse_datetime, parse_time
|
|
|
291
|
|
|
292 .. note:: Date/time parsing is not properly implemented yet
|
