Mercurial > babel > mirror

annotate doc/dates.txt @ 233:da97a3138239 trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Upgraded to CLDR 1.5 and improved timezone formatting.
author cmlenz
date Wed, 01 Aug 2007 12:32:20 +0000
parents 98dcabc99308
children f9f6f740b595
rev   line source
2
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
1 .. -*- mode: rst; encoding: utf-8 -*-
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
2
124
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents: 98
diff changeset
3 ===============
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents: 98
diff changeset
4 Date Formatting
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents: 98
diff changeset
5 ===============
2
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
6
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
7
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
8 .. contents:: Contents
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
9 :depth: 2
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
10 .. sectnum::
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
11
20896f1e91c6 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
12
18
990909fdf98b 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
f5cfd37ec37e 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
990909fdf98b 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
0739bc8e7210 Syntax highlighting for the docs.
cmlenz
parents: 35
diff changeset
16 ``dates`` module:
0739bc8e7210 Syntax highlighting for the docs.
cmlenz
parents: 35
diff changeset
17
98
f5cfd37ec37e 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
f5cfd37ec37e Add `--without-apidocs` switch to `build_doc` command for quicker doc-edit/review cycles.
cmlenz
parents: 40
diff changeset
19
40
0739bc8e7210 Syntax highlighting for the docs.
cmlenz
parents: 35
diff changeset
20 .. code-block:: pycon
18
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
21
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
22 >>> from datetime import date, datetime, time
990909fdf98b 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
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
24
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
25 >>> d = date(2007, 4, 1)
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
26 >>> format_date(d, locale='en')
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
27 u'Apr 1, 2007'
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
28 >>> format_date(d, locale='de_DE')
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
29 u'01.04.2007'
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
30
990909fdf98b 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
990909fdf98b 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.
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
33
990909fdf98b 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
990909fdf98b 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:
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
36
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
37 * ``short``,
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
38 * ``medium`` (the default),
20
c4fc7b88206e Fix typo in doc.
cmlenz
parents: 18
diff changeset
39 * ``long``, and
c4fc7b88206e Fix typo in doc.
cmlenz
parents: 18
diff changeset
40 * ``full``.
18
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
41
40
0739bc8e7210 Syntax highlighting for the docs.
cmlenz
parents: 35
diff changeset
42 For example:
0739bc8e7210 Syntax highlighting for the docs.
cmlenz
parents: 35
diff changeset
43
0739bc8e7210 Syntax highlighting for the docs.
cmlenz
parents: 35
diff changeset
44 .. code-block:: pycon
18
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
45
990909fdf98b 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')
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
47 u'4/1/07'
990909fdf98b 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')
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
49 u'April 1, 2007'
990909fdf98b 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')
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
51 u'Sunday, April 1, 2007'
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
52
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
53
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
54 Pattern Syntax
124
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents: 98
diff changeset
55 ==============
18
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
56
990909fdf98b 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
990909fdf98b 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
990909fdf98b 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
990909fdf98b 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
990909fdf98b 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
990909fdf98b 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
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
63 follows:
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
64
990909fdf98b 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
990909fdf98b 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
990909fdf98b 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. […]
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
68
990909fdf98b 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
990909fdf98b 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
990909fdf98b 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
990909fdf98b 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
990909fdf98b 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
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
74 form should be used […]
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
75
990909fdf98b 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
990909fdf98b 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
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
78 for two adjacent single quotes).
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
79
40
0739bc8e7210 Syntax highlighting for the docs.
cmlenz
parents: 35
diff changeset
80 For example:
0739bc8e7210 Syntax highlighting for the docs.
cmlenz
parents: 35
diff changeset
81
0739bc8e7210 Syntax highlighting for the docs.
cmlenz
parents: 35
diff changeset
82 .. code-block:: pycon
18
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
83
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
84 >>> d = date(2007, 4, 1)
990909fdf98b 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')
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
86 u"Sun, Apr 1, '07"
990909fdf98b 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')
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
88 u'Sonntag, 1.4.2007'
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
89
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
90 >>> t = time(15, 30)
990909fdf98b 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')
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
92 u"03 o'clock PM"
990909fdf98b 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')
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
94 u'15:30 nachm.'
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
95
990909fdf98b 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)
990909fdf98b 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')
990909fdf98b 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'
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
99
990909fdf98b 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
990909fdf98b 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
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
102 relatively brief overview.
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
103
990909fdf98b 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
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
105
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
106 Date Fields
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
107 -----------
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
108
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
109 +----------+--------+--------------------------------------------------------+
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
110 | Field | Symbol | Description |
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
111 +==========+========+========================================================+
990909fdf98b 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 |
990909fdf98b 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 |
990909fdf98b 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 |
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
115 +----------+--------+--------------------------------------------------------+
990909fdf98b 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 |
990909fdf98b 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 |
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
118 | | | maximum length. |
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
119 | +--------+--------------------------------------------------------+
990909fdf98b 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. |
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
121 | +--------+--------------------------------------------------------+
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
122 | | ``u`` | ?? |
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
123 +----------+--------+--------------------------------------------------------+
990909fdf98b 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 |
990909fdf98b 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. |
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
126 | +--------+--------------------------------------------------------+
990909fdf98b 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 |
990909fdf98b 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. |
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
129 +----------+--------+--------------------------------------------------------+
990909fdf98b 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 |
990909fdf98b 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 |
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
132 | | | the narrow name. |
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
133 | +--------+--------------------------------------------------------+
990909fdf98b 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 |
990909fdf98b 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 |
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
136 | | | narrow name. |
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
137 +----------+--------+--------------------------------------------------------+
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
138 | Week | ``w`` | Week of year. |
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
139 | +--------+--------------------------------------------------------+
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
140 | | ``W`` | Week of month. |
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
141 +----------+--------+--------------------------------------------------------+
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
142 | Day | ``d`` | Day of month. |
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
143 | +--------+--------------------------------------------------------+
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
144 | | ``D`` | Day of year. |
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
145 | +--------+--------------------------------------------------------+
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
146 | | ``F`` | Day of week in month. |
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
147 | +--------+--------------------------------------------------------+
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
148 | | ``g`` | ?? |
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
149 +----------+--------+--------------------------------------------------------+
990909fdf98b 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 |
990909fdf98b 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 |
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
152 | | | narrow name. |
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
153 | +--------+--------------------------------------------------------+
990909fdf98b 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 |
990909fdf98b 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 |
990909fdf98b 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. |
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
157 | +--------+--------------------------------------------------------+
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
158 | | ``c`` | ?? |
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
159 +----------+--------+--------------------------------------------------------+
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
160
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
161 Time Fields
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
162 -----------
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
163
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
164 +----------+--------+--------------------------------------------------------+
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
165 | Field | Symbol | Description |
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
166 +==========+========+========================================================+
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
167 | Period | ``a`` | AM or PM |
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
168 +----------+--------+--------------------------------------------------------+
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
169 | Hour | ``h`` | Hour [1-12]. |
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
170 | +--------+--------------------------------------------------------+
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
171 | | ``H`` | Hour [0-23]. |
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
172 | +--------+--------------------------------------------------------+
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
173 | | ``K`` | Hour [0-11]. |
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
174 | +--------+--------------------------------------------------------+
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
175 | | ``k`` | Hour [1-24]. |
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
176 +----------+--------+--------------------------------------------------------+
990909fdf98b 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. |
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
178 +----------+--------+--------------------------------------------------------+
990909fdf98b 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. |
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
180 | +--------+--------------------------------------------------------+
990909fdf98b 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. |
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
182 | +--------+--------------------------------------------------------+
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
183 | | ``A`` | Milliseconds in day. |
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
184 +----------+--------+--------------------------------------------------------+
990909fdf98b 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 |
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
186 | | | four for the full name. |
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
187 | +--------+--------------------------------------------------------+
990909fdf98b 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 |
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
189 | | | GMT format. |
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
190 | +--------+--------------------------------------------------------+
990909fdf98b 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 |
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
192 | | | long wall time. |
233
da97a3138239 Upgraded to CLDR 1.5 and improved timezone formatting.
cmlenz
parents: 124
diff changeset
193 | +--------+--------------------------------------------------------+
da97a3138239 Upgraded to CLDR 1.5 and improved timezone formatting.
cmlenz
parents: 124
diff changeset
194 | | ``V`` | Same as ``z``, except that timezone abbreviations |
da97a3138239 Upgraded to CLDR 1.5 and improved timezone formatting.
cmlenz
parents: 124
diff changeset
195 | | | should be used regardless of whether they are in |
da97a3138239 Upgraded to CLDR 1.5 and improved timezone formatting.
cmlenz
parents: 124
diff changeset
196 | | | common use by the locale. |
18
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
197 +----------+--------+--------------------------------------------------------+
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
198
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
199
31
f3049ca45daa Raise error on unsupported locales. Closes #5.
cmlenz
parents: 29
diff changeset
200 Time-Zone Support
124
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents: 98
diff changeset
201 =================
29
72bf45adb926 More work on timezones.
cmlenz
parents: 20
diff changeset
202
31
f3049ca45daa Raise error on unsupported locales. Closes #5.
cmlenz
parents: 29
diff changeset
203 Many of the verbose time formats include the time-zone, but time-zone
f3049ca45daa Raise error on unsupported locales. Closes #5.
cmlenz
parents: 29
diff changeset
204 information is not by default available for the Python ``datetime`` and
f3049ca45daa Raise error on unsupported locales. Closes #5.
cmlenz
parents: 29
diff changeset
205 ``time`` objects. The standard library includes only the abstract ``tzinfo``
f3049ca45daa Raise error on unsupported locales. Closes #5.
cmlenz
parents: 29
diff changeset
206 class, which you need appropriate implementations for to actually use in your
29
72bf45adb926 More work on timezones.
cmlenz
parents: 20
diff changeset
207 application. Babel includes a ``tzinfo`` implementation for UTC (Universal
31
f3049ca45daa Raise error on unsupported locales. Closes #5.
cmlenz
parents: 29
diff changeset
208 Time).
f3049ca45daa Raise error on unsupported locales. Closes #5.
cmlenz
parents: 29
diff changeset
209
f3049ca45daa Raise error on unsupported locales. Closes #5.
cmlenz
parents: 29
diff changeset
210 For real time-zone support, it is strongly recommended that you use the
29
72bf45adb926 More work on timezones.
cmlenz
parents: 20
diff changeset
211 third-party package `pytz`_, which includes the definitions of practically all
72bf45adb926 More work on timezones.
cmlenz
parents: 20
diff changeset
212 of the time-zones used on the world, as well as important functions for
40
0739bc8e7210 Syntax highlighting for the docs.
cmlenz
parents: 35
diff changeset
213 reliably converting from UTC to local time, and vice versa:
0739bc8e7210 Syntax highlighting for the docs.
cmlenz
parents: 35
diff changeset
214
0739bc8e7210 Syntax highlighting for the docs.
cmlenz
parents: 35
diff changeset
215 .. code-block:: pycon
29
72bf45adb926 More work on timezones.
cmlenz
parents: 20
diff changeset
216
72bf45adb926 More work on timezones.
cmlenz
parents: 20
diff changeset
217 >>> from datetime import time
34
464fbcefedde Extended time-zone support.
cmlenz
parents: 32
diff changeset
218 >>> from pytz import timezone, utc
464fbcefedde Extended time-zone support.
cmlenz
parents: 32
diff changeset
219 >>> dt = datetime(2007, 04, 01, 15, 30, tzinfo=utc)
464fbcefedde Extended time-zone support.
cmlenz
parents: 32
diff changeset
220 >>> eastern = timezone('US/Eastern')
464fbcefedde Extended time-zone support.
cmlenz
parents: 32
diff changeset
221 >>> format_datetime(dt, 'H:mm Z', tzinfo=eastern, locale='en_US')
464fbcefedde Extended time-zone support.
cmlenz
parents: 32
diff changeset
222 u'11:30 -0400'
29
72bf45adb926 More work on timezones.
cmlenz
parents: 20
diff changeset
223
72bf45adb926 More work on timezones.
cmlenz
parents: 20
diff changeset
224 The recommended approach to deal with different time-zones in a Python
72bf45adb926 More work on timezones.
cmlenz
parents: 20
diff changeset
225 application is to always use UTC internally, and only convert from/to the users
72bf45adb926 More work on timezones.
cmlenz
parents: 20
diff changeset
226 time-zone when accepting user input and displaying date/time data, respectively.
34
464fbcefedde Extended time-zone support.
cmlenz
parents: 32
diff changeset
227 You can use Babel together with ``pytz`` to apply a time-zone to any
464fbcefedde Extended time-zone support.
cmlenz
parents: 32
diff changeset
228 ``datetime`` or ``time`` object for display, leaving the original information
40
0739bc8e7210 Syntax highlighting for the docs.
cmlenz
parents: 35
diff changeset
229 unchanged:
0739bc8e7210 Syntax highlighting for the docs.
cmlenz
parents: 35
diff changeset
230
0739bc8e7210 Syntax highlighting for the docs.
cmlenz
parents: 35
diff changeset
231 .. code-block:: pycon
34
464fbcefedde Extended time-zone support.
cmlenz
parents: 32
diff changeset
232
464fbcefedde Extended time-zone support.
cmlenz
parents: 32
diff changeset
233 >>> british = timezone('Europe/London')
464fbcefedde Extended time-zone support.
cmlenz
parents: 32
diff changeset
234 >>> format_datetime(dt, 'H:mm zzzz', tzinfo=british, locale='en_US')
464fbcefedde Extended time-zone support.
cmlenz
parents: 32
diff changeset
235 u'16:30 British Summer Time'
29
72bf45adb926 More work on timezones.
cmlenz
parents: 20
diff changeset
236
35
0df10113d5c2 Add note on daylight savings time.
cmlenz
parents: 34
diff changeset
237 Here, the given UTC time is adjusted to the "Europe/London" time-zone, and
0df10113d5c2 Add note on daylight savings time.
cmlenz
parents: 34
diff changeset
238 daylight savings time is taken into account. Daylight savings time is also
0df10113d5c2 Add note on daylight savings time.
cmlenz
parents: 34
diff changeset
239 applied to ``format_time``, but because the actual date is unknown in that
0df10113d5c2 Add note on daylight savings time.
cmlenz
parents: 34
diff changeset
240 case, the current day is assumed to determine whether DST or standard time
0df10113d5c2 Add note on daylight savings time.
cmlenz
parents: 34
diff changeset
241 should be used.
0df10113d5c2 Add note on daylight savings time.
cmlenz
parents: 34
diff changeset
242
29
72bf45adb926 More work on timezones.
cmlenz
parents: 20
diff changeset
243 .. _`pytz`: http://pytz.sourceforge.net/
72bf45adb926 More work on timezones.
cmlenz
parents: 20
diff changeset
244
72bf45adb926 More work on timezones.
cmlenz
parents: 20
diff changeset
245
18
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
246 Parsing Dates
124
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents: 98
diff changeset
247 =============
18
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
248
40
0739bc8e7210 Syntax highlighting for the docs.
cmlenz
parents: 35
diff changeset
249 Babel can also parse date and time information in a locale-sensitive manner:
0739bc8e7210 Syntax highlighting for the docs.
cmlenz
parents: 35
diff changeset
250
0739bc8e7210 Syntax highlighting for the docs.
cmlenz
parents: 35
diff changeset
251 .. code-block:: pycon
18
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
252
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
253 >>> from babel.dates import parse_date, parse_datetime, parse_time
Copyright (C) 2012-2017 Edgewall Software