Mercurial > babel > old > babel-test
annotate doc/dates.txt @ 146:9b1336786cb5 stable-0.8.x
Initialized merge tracking via "svnmerge" with revisions "1-140" from
http://svn.edgewall.org/repos/babel/trunk
author | cmlenz |
---|---|
date | Wed, 20 Jun 2007 15:06:17 +0000 |
parents | bf1bcdf19111 |
children | bc22f5aef216 |
rev | line source |
---|---|
2 | 1 .. -*- mode: rst; encoding: utf-8 -*- |
2 | |
124 | 3 =============== |
4 Date Formatting | |
5 =============== | |
2 | 6 |
7 | |
8 .. contents:: Contents | |
9 :depth: 2 | |
10 .. sectnum:: | |
11 | |
12 | |
18
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
13 When working with date and time information in Python, you commonly use the |
98
a696e249467a
Add `--without-apidocs` switch to `build_doc` command for quicker doc-edit/review cycles.
cmlenz
parents:
40
diff
changeset
|
14 classes ``date``, ``datetime`` and/or ``time`` from the `datetime`_ package. |
18
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
15 Babel provides functions for locale-specific formatting of those objects in its |
40 | 16 ``dates`` module: |
17 | |
98
a696e249467a
Add `--without-apidocs` switch to `build_doc` command for quicker doc-edit/review cycles.
cmlenz
parents:
40
diff
changeset
|
18 .. _`datetime`: http://docs.python.org/lib/module-datetime.html |
a696e249467a
Add `--without-apidocs` switch to `build_doc` command for quicker doc-edit/review cycles.
cmlenz
parents:
40
diff
changeset
|
19 |
40 | 20 .. code-block:: pycon |
18
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
21 |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
22 >>> from datetime import date, datetime, time |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
23 >>> from babel.dates import format_date, format_datetime, format_time |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
24 |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
25 >>> d = date(2007, 4, 1) |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
26 >>> format_date(d, locale='en') |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
27 u'Apr 1, 2007' |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
28 >>> format_date(d, locale='de_DE') |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
29 u'01.04.2007' |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
30 |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
31 As this example demonstrates, Babel will automatically choose a date format |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
32 that is appropriate for the requested locale. |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
33 |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
34 The ``format_*()`` functions also accept an optional ``format`` argument, which |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
35 allows you to choose between one of four format variations: |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
36 |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
37 * ``short``, |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
38 * ``medium`` (the default), |
20 | 39 * ``long``, and |
40 * ``full``. | |
18
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
41 |
40 | 42 For example: |
43 | |
44 .. code-block:: pycon | |
18
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
45 |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
46 >>> format_date(d, format='short', locale='en') |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
47 u'4/1/07' |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
48 >>> format_date(d, format='long', locale='en') |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
49 u'April 1, 2007' |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
50 >>> format_date(d, format='full', locale='en') |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
51 u'Sunday, April 1, 2007' |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
52 |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
53 |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
54 Pattern Syntax |
124 | 55 ============== |
18
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
56 |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
57 While Babel makes it simple to use the appropriate date/time format for a given |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
58 locale, you can also force it to use custom patterns. Note that Babel uses |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
59 different patterns for specifying number and date formats compared to the |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
60 Python equivalents (such as ``time.strftime()``), which have mostly been |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
61 inherited from C and POSIX. The patterns used in Babel are based on the |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
62 `Locale Data Markup Language specification`_ (LDML), which defines them as |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
63 follows: |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
64 |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
65 A date/time pattern is a string of characters, where specific strings of |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
66 characters are replaced with date and time data from a calendar when formatting |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
67 or used to generate data for a calendar when parsing. […] |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
68 |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
69 Characters may be used multiple times. For example, if ``y`` is used for the |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
70 year, ``yy`` might produce "99", whereas ``yyyy`` produces "1999". For most |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
71 numerical fields, the number of characters specifies the field width. For |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
72 example, if ``h`` is the hour, ``h`` might produce "5", but ``hh`` produces |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
73 "05". For some characters, the count specifies whether an abbreviated or full |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
74 form should be used […] |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
75 |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
76 Two single quotes represent a literal single quote, either inside or outside |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
77 single quotes. Text within single quotes is not interpreted in any way (except |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
78 for two adjacent single quotes). |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
79 |
40 | 80 For example: |
81 | |
82 .. code-block:: pycon | |
18
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
83 |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
84 >>> d = date(2007, 4, 1) |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
85 >>> format_date(d, "EEE, MMM d, ''yy", locale='en') |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
86 u"Sun, Apr 1, '07" |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
87 >>> format_date(d, "EEEE, d.M.yyyy", locale='de') |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
88 u'Sonntag, 1.4.2007' |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
89 |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
90 >>> t = time(15, 30) |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
91 >>> format_time(t, "hh 'o''clock' a", locale='en') |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
92 u"03 o'clock PM" |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
93 >>> format_time(t, 'H:mm a', locale='de') |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
94 u'15:30 nachm.' |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
95 |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
96 >>> dt = datetime(2007, 4, 1, 15, 30) |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
97 >>> format_datetime(dt, "yyyyy.MMMM.dd GGG hh:mm a", locale='en') |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
98 u'02007.April.01 AD 03:30 PM' |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
99 |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
100 The syntax for custom datetime format patterns is described in detail in the |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
101 the `Locale Data Markup Language specification`_. The following table is just a |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
102 relatively brief overview. |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
103 |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
104 .. _`Locale Data Markup Language specification`: http://unicode.org/reports/tr35/#Date_Format_Patterns |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
105 |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
106 Date Fields |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
107 ----------- |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
108 |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
109 +----------+--------+--------------------------------------------------------+ |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
110 | Field | Symbol | Description | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
111 +==========+========+========================================================+ |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
112 | Era | ``G`` | Replaced with the era string for the current date. One | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
113 | | | to three letters for the abbreviated form, four | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
114 | | | lettersfor the long form, five for the narrow form | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
115 +----------+--------+--------------------------------------------------------+ |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
116 | Year | ``y`` | Replaced by the year. Normally the length specifies | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
117 | | | the padding, but for two letters it also specifies the | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
118 | | | maximum length. | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
119 | +--------+--------------------------------------------------------+ |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
120 | | ``Y`` | Same as ``y`` but uses the ISO year-week calendar. | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
121 | +--------+--------------------------------------------------------+ |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
122 | | ``u`` | ?? | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
123 +----------+--------+--------------------------------------------------------+ |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
124 | Quarter | ``Q`` | Use one or two for the numerical quarter, three for | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
125 | | | the abbreviation, or four for the full name. | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
126 | +--------+--------------------------------------------------------+ |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
127 | | ``q`` | Use one or two for the numerical quarter, three for | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
128 | | | the abbreviation, or four for the full name. | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
129 +----------+--------+--------------------------------------------------------+ |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
130 | Month | ``M`` | Use one or two for the numerical month, three for the | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
131 | | | abbreviation, or four for the full name, or five for | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
132 | | | the narrow name. | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
133 | +--------+--------------------------------------------------------+ |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
134 | | ``L`` | Use one or two for the numerical month, three for the | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
135 | | | abbreviation, or four for the full name, or 5 for the | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
136 | | | narrow name. | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
137 +----------+--------+--------------------------------------------------------+ |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
138 | Week | ``w`` | Week of year. | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
139 | +--------+--------------------------------------------------------+ |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
140 | | ``W`` | Week of month. | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
141 +----------+--------+--------------------------------------------------------+ |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
142 | Day | ``d`` | Day of month. | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
143 | +--------+--------------------------------------------------------+ |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
144 | | ``D`` | Day of year. | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
145 | +--------+--------------------------------------------------------+ |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
146 | | ``F`` | Day of week in month. | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
147 | +--------+--------------------------------------------------------+ |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
148 | | ``g`` | ?? | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
149 +----------+--------+--------------------------------------------------------+ |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
150 | Week day | ``E`` | Day of week. Use one through three letters for the | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
151 | | | short day, or four for the full name, or five for the | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
152 | | | narrow name. | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
153 | +--------+--------------------------------------------------------+ |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
154 | | ``e`` | Local day of week. Same as E except adds a numeric | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
155 | | | value that will depend on the local starting day of | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
156 | | | the week, using one or two letters. | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
157 | +--------+--------------------------------------------------------+ |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
158 | | ``c`` | ?? | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
159 +----------+--------+--------------------------------------------------------+ |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
160 |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
161 Time Fields |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
162 ----------- |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
163 |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
164 +----------+--------+--------------------------------------------------------+ |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
165 | Field | Symbol | Description | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
166 +==========+========+========================================================+ |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
167 | Period | ``a`` | AM or PM | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
168 +----------+--------+--------------------------------------------------------+ |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
169 | Hour | ``h`` | Hour [1-12]. | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
170 | +--------+--------------------------------------------------------+ |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
171 | | ``H`` | Hour [0-23]. | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
172 | +--------+--------------------------------------------------------+ |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
173 | | ``K`` | Hour [0-11]. | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
174 | +--------+--------------------------------------------------------+ |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
175 | | ``k`` | Hour [1-24]. | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
176 +----------+--------+--------------------------------------------------------+ |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
177 | Minute | ``m`` | Use one or two for zero places padding. | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
178 +----------+--------+--------------------------------------------------------+ |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
179 | Second | ``s`` | Use one or two for zero places padding. | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
180 | +--------+--------------------------------------------------------+ |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
181 | | ``S`` | Fractional second, rounds to the count of letters. | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
182 | +--------+--------------------------------------------------------+ |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
183 | | ``A`` | Milliseconds in day. | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
184 +----------+--------+--------------------------------------------------------+ |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
185 | Timezone | ``z`` | Use one to three letters for the short timezone or | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
186 | | | four for the full name. | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
187 | +--------+--------------------------------------------------------+ |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
188 | | ``Z`` | Use one to three letters for RFC 822, four letters for | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
189 | | | GMT format. | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
190 | +--------+--------------------------------------------------------+ |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
191 | | ``v`` | Use one letter for short wall (generic) time, four for | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
192 | | | long wall time. | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
193 +----------+--------+--------------------------------------------------------+ |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
194 |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
195 |
31 | 196 Time-Zone Support |
124 | 197 ================= |
29 | 198 |
31 | 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 | |
29 | 203 application. Babel includes a ``tzinfo`` implementation for UTC (Universal |
31 | 204 Time). |
205 | |
206 For real time-zone support, it is strongly recommended that you use the | |
29 | 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 | |
40 | 209 reliably converting from UTC to local time, and vice versa: |
210 | |
211 .. code-block:: pycon | |
29 | 212 |
213 >>> from datetime import time | |
34 | 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' | |
29 | 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. | |
34 | 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 | |
40 | 225 unchanged: |
226 | |
227 .. code-block:: pycon | |
34 | 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' | |
29 | 232 |
35 | 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 | |
29 | 239 .. _`pytz`: http://pytz.sourceforge.net/ |
240 | |
241 | |
18
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
242 Parsing Dates |
124 | 243 ============= |
18
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
244 |
40 | 245 Babel can also parse date and time information in a locale-sensitive manner: |
246 | |
247 .. code-block:: pycon | |
18
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
248 |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
249 >>> from babel.dates import parse_date, parse_datetime, parse_time |