Mercurial > babel > mirror
comparison doc/dates.txt @ 124:98dcabc99308 trunk
Split docs on date and number formatting.
author | cmlenz |
---|---|
date | Mon, 18 Jun 2007 15:15:31 +0000 |
parents | doc/formatting.txt@f5cfd37ec37e |
children | da97a3138239 |
comparison
equal
deleted
inserted
replaced
123:31ca37101a24 | 124:98dcabc99308 |
---|---|
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 |