Mercurial > babel > old > mirror

annotate doc/formatting.txt @ 33:df1e2f0ef627

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Raise error on unsupported locales. Closes #5.
author cmlenz
date Mon, 04 Jun 2007 11:29:55 +0000
parents 3956bb7ff93b
children 8b6804eac9e5
rev   line source
4
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
1 .. -*- mode: rst; encoding: utf-8 -*-
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
2
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
3 ==========================
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
4 Number and Date Formatting
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
5 ==========================
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
6
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
7
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
8 .. contents:: Contents
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
9 :depth: 2
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
10 .. sectnum::
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
11
2cada72b40ae Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
12
20
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
13 Date Formatting
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
14 ===============
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
15
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
16 When working with date and time information in Python, you commonly use the
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
17 classes ``date``, ``datetime`` and/or ``time`` from the `datetime package`_.
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
18 Babel provides functions for locale-specific formatting of those objects in its
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
19 ``dates`` module::
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
20
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
21 >>> from datetime import date, datetime, time
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
22 >>> from babel.dates import format_date, format_datetime, format_time
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
23
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
24 >>> d = date(2007, 4, 1)
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
25 >>> format_date(d, locale='en')
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
26 u'Apr 1, 2007'
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
27 >>> format_date(d, locale='de_DE')
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
28 u'01.04.2007'
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
29
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
30 As this example demonstrates, Babel will automatically choose a date format
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
31 that is appropriate for the requested locale.
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
32
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
33 The ``format_*()`` functions also accept an optional ``format`` argument, which
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
34 allows you to choose between one of four format variations:
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
35
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
36 * ``short``,
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
37 * ``medium`` (the default),
22
9ed365f4cbc8 Fix typo in doc.
cmlenz
parents: 20
diff changeset
38 * ``long``, and
9ed365f4cbc8 Fix typo in doc.
cmlenz
parents: 20
diff changeset
39 * ``full``.
20
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
40
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
41 For example::
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
42
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
43 >>> format_date(d, format='short', locale='en')
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
44 u'4/1/07'
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
45 >>> format_date(d, format='long', locale='en')
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
46 u'April 1, 2007'
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
47 >>> format_date(d, format='full', locale='en')
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
48 u'Sunday, April 1, 2007'
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
49
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
50 .. _`datetime package`: http://docs.python.org/lib/module-datetime.html
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
51
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
52
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
53 Pattern Syntax
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
54 --------------
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
55
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
56 While Babel makes it simple to use the appropriate date/time format for a given
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
57 locale, you can also force it to use custom patterns. Note that Babel uses
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
58 different patterns for specifying number and date formats compared to the
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
59 Python equivalents (such as ``time.strftime()``), which have mostly been
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
60 inherited from C and POSIX. The patterns used in Babel are based on the
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
61 `Locale Data Markup Language specification`_ (LDML), which defines them as
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
62 follows:
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
63
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
64 A date/time pattern is a string of characters, where specific strings of
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
65 characters are replaced with date and time data from a calendar when formatting
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
66 or used to generate data for a calendar when parsing. […]
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
67
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
68 Characters may be used multiple times. For example, if ``y`` is used for the
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
69 year, ``yy`` might produce "99", whereas ``yyyy`` produces "1999". For most
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
70 numerical fields, the number of characters specifies the field width. For
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
71 example, if ``h`` is the hour, ``h`` might produce "5", but ``hh`` produces
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
72 "05". For some characters, the count specifies whether an abbreviated or full
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
73 form should be used […]
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
74
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
75 Two single quotes represent a literal single quote, either inside or outside
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
76 single quotes. Text within single quotes is not interpreted in any way (except
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
77 for two adjacent single quotes).
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
78
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
79 For example::
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
80
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
81 >>> d = date(2007, 4, 1)
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
82 >>> format_date(d, "EEE, MMM d, ''yy", locale='en')
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
83 u"Sun, Apr 1, '07"
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
84 >>> format_date(d, "EEEE, d.M.yyyy", locale='de')
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
85 u'Sonntag, 1.4.2007'
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
86
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
87 >>> t = time(15, 30)
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
88 >>> format_time(t, "hh 'o''clock' a", locale='en')
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
89 u"03 o'clock PM"
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
90 >>> format_time(t, 'H:mm a', locale='de')
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
91 u'15:30 nachm.'
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
92
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
93 >>> dt = datetime(2007, 4, 1, 15, 30)
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
94 >>> format_datetime(dt, "yyyyy.MMMM.dd GGG hh:mm a", locale='en')
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
95 u'02007.April.01 AD 03:30 PM'
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
96
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
97 The syntax for custom datetime format patterns is described in detail in the
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
98 the `Locale Data Markup Language specification`_. The following table is just a
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
99 relatively brief overview.
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
100
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
101 .. _`Locale Data Markup Language specification`: http://unicode.org/reports/tr35/#Date_Format_Patterns
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
102
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
103 -----------
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
104 Date Fields
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
105 -----------
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
106
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
107 +----------+--------+--------------------------------------------------------+
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
108 | Field | Symbol | Description |
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
109 +==========+========+========================================================+
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
110 | Era | ``G`` | Replaced with the era string for the current date. One |
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
111 | | | to three letters for the abbreviated form, four |
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
112 | | | lettersfor the long form, five for the narrow form |
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
113 +----------+--------+--------------------------------------------------------+
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
114 | Year | ``y`` | Replaced by the year. Normally the length specifies |
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
115 | | | the padding, but for two letters it also specifies the |
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
116 | | | maximum length. |
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
117 | +--------+--------------------------------------------------------+
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
118 | | ``Y`` | Same as ``y`` but uses the ISO year-week calendar. |
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
119 | +--------+--------------------------------------------------------+
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
120 | | ``u`` | ?? |
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
121 +----------+--------+--------------------------------------------------------+
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
122 | Quarter | ``Q`` | Use one or two for the numerical quarter, three for |
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
123 | | | the abbreviation, or four for the full name. |
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
124 | +--------+--------------------------------------------------------+
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
125 | | ``q`` | Use one or two for the numerical quarter, three for |
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
126 | | | the abbreviation, or four for the full name. |
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
127 +----------+--------+--------------------------------------------------------+
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
128 | Month | ``M`` | Use one or two for the numerical month, three for the |
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
129 | | | abbreviation, or four for the full name, or five for |
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
130 | | | the narrow name. |
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
131 | +--------+--------------------------------------------------------+
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
132 | | ``L`` | Use one or two for the numerical month, three for the |
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
133 | | | abbreviation, or four for the full name, or 5 for the |
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
134 | | | narrow name. |
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
135 +----------+--------+--------------------------------------------------------+
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
136 | Week | ``w`` | Week of year. |
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
137 | +--------+--------------------------------------------------------+
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
138 | | ``W`` | Week of month. |
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
139 +----------+--------+--------------------------------------------------------+
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
140 | Day | ``d`` | Day of month. |
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
141 | +--------+--------------------------------------------------------+
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
142 | | ``D`` | Day of year. |
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
143 | +--------+--------------------------------------------------------+
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
144 | | ``F`` | Day of week in month. |
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
145 | +--------+--------------------------------------------------------+
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
146 | | ``g`` | ?? |
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
147 +----------+--------+--------------------------------------------------------+
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
148 | Week day | ``E`` | Day of week. Use one through three letters for the |
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
149 | | | short day, or four for the full name, or five for the |
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
150 | | | narrow name. |
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
151 | +--------+--------------------------------------------------------+
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
152 | | ``e`` | Local day of week. Same as E except adds a numeric |
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
153 | | | value that will depend on the local starting day of |
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
154 | | | the week, using one or two letters. |
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
155 | +--------+--------------------------------------------------------+
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
156 | | ``c`` | ?? |
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
157 +----------+--------+--------------------------------------------------------+
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
158
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
159 -----------
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
160 Time Fields
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
161 -----------
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
162
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
163 +----------+--------+--------------------------------------------------------+
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
164 | Field | Symbol | Description |
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
165 +==========+========+========================================================+
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
166 | Period | ``a`` | AM or PM |
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
167 +----------+--------+--------------------------------------------------------+
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
168 | Hour | ``h`` | Hour [1-12]. |
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
169 | +--------+--------------------------------------------------------+
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
170 | | ``H`` | Hour [0-23]. |
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
171 | +--------+--------------------------------------------------------+
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
172 | | ``K`` | Hour [0-11]. |
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
173 | +--------+--------------------------------------------------------+
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
174 | | ``k`` | Hour [1-24]. |
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
175 +----------+--------+--------------------------------------------------------+
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
176 | Minute | ``m`` | Use one or two for zero places padding. |
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
177 +----------+--------+--------------------------------------------------------+
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
178 | Second | ``s`` | Use one or two for zero places padding. |
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
179 | +--------+--------------------------------------------------------+
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
180 | | ``S`` | Fractional second, rounds to the count of letters. |
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
181 | +--------+--------------------------------------------------------+
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
182 | | ``A`` | Milliseconds in day. |
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
183 +----------+--------+--------------------------------------------------------+
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
184 | Timezone | ``z`` | Use one to three letters for the short timezone or |
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
185 | | | four for the full name. |
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
186 | +--------+--------------------------------------------------------+
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
187 | | ``Z`` | Use one to three letters for RFC 822, four letters for |
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
188 | | | GMT format. |
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
189 | +--------+--------------------------------------------------------+
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
190 | | ``v`` | Use one letter for short wall (generic) time, four for |
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
191 | | | long wall time. |
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
192 +----------+--------+--------------------------------------------------------+
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
193
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
194
33
df1e2f0ef627 Raise error on unsupported locales. Closes #5.
cmlenz
parents: 31
diff changeset
195 Time-Zone Support
31
3956bb7ff93b More work on timezones.
cmlenz
parents: 22
diff changeset
196 -----------------
3956bb7ff93b More work on timezones.
cmlenz
parents: 22
diff changeset
197
33
df1e2f0ef627 Raise error on unsupported locales. Closes #5.
cmlenz
parents: 31
diff changeset
198 Many of the verbose time formats include the time-zone, but time-zone
df1e2f0ef627 Raise error on unsupported locales. Closes #5.
cmlenz
parents: 31
diff changeset
199 information is not by default available for the Python ``datetime`` and
df1e2f0ef627 Raise error on unsupported locales. Closes #5.
cmlenz
parents: 31
diff changeset
200 ``time`` objects. The standard library includes only the abstract ``tzinfo``
df1e2f0ef627 Raise error on unsupported locales. Closes #5.
cmlenz
parents: 31
diff changeset
201 class, which you need appropriate implementations for to actually use in your
31
3956bb7ff93b More work on timezones.
cmlenz
parents: 22
diff changeset
202 application. Babel includes a ``tzinfo`` implementation for UTC (Universal
33
df1e2f0ef627 Raise error on unsupported locales. Closes #5.
cmlenz
parents: 31
diff changeset
203 Time).
df1e2f0ef627 Raise error on unsupported locales. Closes #5.
cmlenz
parents: 31
diff changeset
204
df1e2f0ef627 Raise error on unsupported locales. Closes #5.
cmlenz
parents: 31
diff changeset
205 For real time-zone support, it is strongly recommended that you use the
31
3956bb7ff93b More work on timezones.
cmlenz
parents: 22
diff changeset
206 third-party package `pytz`_, which includes the definitions of practically all
3956bb7ff93b More work on timezones.
cmlenz
parents: 22
diff changeset
207 of the time-zones used on the world, as well as important functions for
3956bb7ff93b More work on timezones.
cmlenz
parents: 22
diff changeset
208 reliably converting from UTC to local time, and vice versa::
3956bb7ff93b More work on timezones.
cmlenz
parents: 22
diff changeset
209
3956bb7ff93b More work on timezones.
cmlenz
parents: 22
diff changeset
210 >>> from datetime import time
3956bb7ff93b More work on timezones.
cmlenz
parents: 22
diff changeset
211 >>> t = time(15, 30)
3956bb7ff93b More work on timezones.
cmlenz
parents: 22
diff changeset
212
3956bb7ff93b More work on timezones.
cmlenz
parents: 22
diff changeset
213 >>> from pytz import timezone
3956bb7ff93b More work on timezones.
cmlenz
parents: 22
diff changeset
214 >>> cet = timezone('Europe/Berlin')
3956bb7ff93b More work on timezones.
cmlenz
parents: 22
diff changeset
215 >>> format_time(t, 'H:mm Z', tzinfo=cet, locale='de_DE')
3956bb7ff93b More work on timezones.
cmlenz
parents: 22
diff changeset
216 u'15:30 +0100'
3956bb7ff93b More work on timezones.
cmlenz
parents: 22
diff changeset
217
3956bb7ff93b More work on timezones.
cmlenz
parents: 22
diff changeset
218 The recommended approach to deal with different time-zones in a Python
3956bb7ff93b More work on timezones.
cmlenz
parents: 22
diff changeset
219 application is to always use UTC internally, and only convert from/to the users
3956bb7ff93b More work on timezones.
cmlenz
parents: 22
diff changeset
220 time-zone when accepting user input and displaying date/time data, respectively.
3956bb7ff93b More work on timezones.
cmlenz
parents: 22
diff changeset
221
3956bb7ff93b More work on timezones.
cmlenz
parents: 22
diff changeset
222 .. _`pytz`: http://pytz.sourceforge.net/
3956bb7ff93b More work on timezones.
cmlenz
parents: 22
diff changeset
223
3956bb7ff93b More work on timezones.
cmlenz
parents: 22
diff changeset
224
3956bb7ff93b More work on timezones.
cmlenz
parents: 22
diff changeset
225
20
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
226 Parsing Dates
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
227 -------------
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
228
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
229 Babel can also parse date and time information in a locale-sensitive manner::
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
230
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
231 >>> from babel.dates import parse_date, parse_datetime, parse_time
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
232
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
233
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
234 Number Formatting
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
235 =================
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
236
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
237
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
238 Pattern Syntax
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
239 --------------
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
240
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
241
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
242 Parsing Numbers
dce4cfd4ba5d Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 4
diff changeset
243 ---------------
Copyright (C) 2012-2017 Edgewall Software