Mercurial > babel > old > mirror

comparison doc/dates.txt @ 126:b12c6a776c44

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Split docs on date and number formatting.
author cmlenz
date Mon, 18 Jun 2007 15:15:31 +0000
parents doc/formatting.txt@3eaa652b1216
children d0cd235ede46
comparison
equal deleted inserted replaced
125:0053443e7cb2 126:b12c6a776c44
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
195
196 Time-Zone Support
197 =================
198
199 Many of the verbose time formats include the time-zone, but time-zone
200 information is not by default available for the Python ``datetime`` and
201 ``time`` objects. The standard library includes only the abstract ``tzinfo``
202 class, which you need appropriate implementations for to actually use in your
203 application. Babel includes a ``tzinfo`` implementation for UTC (Universal
204 Time).
205
206 For real time-zone support, it is strongly recommended that you use the
207 third-party package `pytz`_, which includes the definitions of practically all
208 of the time-zones used on the world, as well as important functions for
209 reliably converting from UTC to local time, and vice versa:
210
211 .. code-block:: pycon
212
213 >>> from datetime import time
214 >>> from pytz import timezone, utc
215 >>> dt = datetime(2007, 04, 01, 15, 30, tzinfo=utc)
216 >>> eastern = timezone('US/Eastern')
217 >>> format_datetime(dt, 'H:mm Z', tzinfo=eastern, locale='en_US')
218 u'11:30 -0400'
219
220 The recommended approach to deal with different time-zones in a Python
221 application is to always use UTC internally, and only convert from/to the users
222 time-zone when accepting user input and displaying date/time data, respectively.
223 You can use Babel together with ``pytz`` to apply a time-zone to any
224 ``datetime`` or ``time`` object for display, leaving the original information
225 unchanged:
226
227 .. code-block:: pycon
228
229 >>> british = timezone('Europe/London')
230 >>> format_datetime(dt, 'H:mm zzzz', tzinfo=british, locale='en_US')
231 u'16:30 British Summer Time'
232
233 Here, the given UTC time is adjusted to the "Europe/London" time-zone, and
234 daylight savings time is taken into account. Daylight savings time is also
235 applied to ``format_time``, but because the actual date is unknown in that
236 case, the current day is assumed to determine whether DST or standard time
237 should be used.
238
239 .. _`pytz`: http://pytz.sourceforge.net/
240
241
242 Parsing Dates
243 =============
244
245 Babel can also parse date and time information in a locale-sensitive manner:
246
247 .. code-block:: pycon
248
249 >>> from babel.dates import parse_date, parse_datetime, parse_time
Copyright (C) 2012-2017 Edgewall Software