Mercurial > babel > old > babel-test

annotate doc/formatting.txt @ 30:6b388baae20c

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add missing import.
author cmlenz
date Mon, 04 Jun 2007 10:54:26 +0000
parents da1c9610e751
children b6ff3e4b43e5
rev   line source
2
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
1 .. -*- mode: rst; encoding: utf-8 -*-
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
2
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
3 ==========================
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
4 Number and Date Formatting
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
5 ==========================
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
6
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
7
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
8 .. contents:: Contents
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
9 :depth: 2
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
10 .. sectnum::
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
11
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
12
18
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
13 Date Formatting
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
14 ===============
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
15
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
16 When working with date and time information in Python, you commonly use the
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
17 classes ``date``, ``datetime`` and/or ``time`` from the `datetime package`_.
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
18 Babel provides functions for locale-specific formatting of those objects in its
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
19 ``dates`` module::
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
20
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
21 >>> from datetime import date, datetime, time
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
22 >>> 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
23
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
24 >>> d = date(2007, 4, 1)
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
25 >>> format_date(d, locale='en')
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
26 u'Apr 1, 2007'
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
27 >>> format_date(d, locale='de_DE')
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
28 u'01.04.2007'
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
29
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
30 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
31 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
32
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
33 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
34 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
35
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
36 * ``short``,
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
37 * ``medium`` (the default),
20
2fdc2b500347 Fix typo in doc.
cmlenz
parents: 18
diff changeset
38 * ``long``, and
2fdc2b500347 Fix typo in doc.
cmlenz
parents: 18
diff changeset
39 * ``full``.
18
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
40
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
41 For example::
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
42
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
43 >>> 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
44 u'4/1/07'
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
45 >>> 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
46 u'April 1, 2007'
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
47 >>> 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
48 u'Sunday, April 1, 2007'
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
49
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
50 .. _`datetime package`: http://docs.python.org/lib/module-datetime.html
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
51
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 Pattern Syntax
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
54 --------------
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
55
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
56 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
57 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
58 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
59 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
60 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
61 `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
62 follows:
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
63
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
64 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
65 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
66 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
67
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
68 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
69 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
70 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
71 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
72 "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
73 form should be used […]
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
74
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
75 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
76 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
77 for two adjacent single quotes).
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
78
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
79 For example::
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
80
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
81 >>> d = date(2007, 4, 1)
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
82 >>> 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
83 u"Sun, Apr 1, '07"
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
84 >>> 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
85 u'Sonntag, 1.4.2007'
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
86
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
87 >>> t = time(15, 30)
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
88 >>> 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
89 u"03 o'clock PM"
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
90 >>> 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
91 u'15:30 nachm.'
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
92
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
93 >>> 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
94 >>> 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
95 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
96
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
97 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
98 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
99 relatively brief overview.
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
100
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
101 .. _`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
102
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 Date Fields
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
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 | Field | Symbol | Description |
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 | 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
111 | | | 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
112 | | | 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
113 +----------+--------+--------------------------------------------------------+
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
114 | 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
115 | | | 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
116 | | | maximum length. |
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
117 | +--------+--------------------------------------------------------+
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
118 | | ``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
119 | +--------+--------------------------------------------------------+
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
120 | | ``u`` | ?? |
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 | 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
123 | | | 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
124 | +--------+--------------------------------------------------------+
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
125 | | ``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
126 | | | 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
127 +----------+--------+--------------------------------------------------------+
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
128 | 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
129 | | | 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
130 | | | the narrow name. |
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
131 | +--------+--------------------------------------------------------+
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
132 | | ``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
133 | | | 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
134 | | | narrow name. |
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
135 +----------+--------+--------------------------------------------------------+
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
136 | Week | ``w`` | Week of year. |
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 | | ``W`` | Week of month. |
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 | Day | ``d`` | Day 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 | | ``D`` | Day of year. |
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 | | ``F`` | Day of week in month. |
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 | | ``g`` | ?? |
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 | 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
149 | | | 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
150 | | | narrow name. |
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
151 | +--------+--------------------------------------------------------+
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
152 | | ``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
153 | | | 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
154 | | | 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
155 | +--------+--------------------------------------------------------+
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
156 | | ``c`` | ?? |
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
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 Time Fields
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
161 -----------
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 | Field | Symbol | Description |
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
165 +==========+========+========================================================+
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
166 | Period | ``a`` | AM or PM |
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
167 +----------+--------+--------------------------------------------------------+
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
168 | Hour | ``h`` | Hour [1-12]. |
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
169 | +--------+--------------------------------------------------------+
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
170 | | ``H`` | Hour [0-23]. |
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
171 | +--------+--------------------------------------------------------+
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
172 | | ``K`` | Hour [0-11]. |
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
173 | +--------+--------------------------------------------------------+
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
174 | | ``k`` | Hour [1-24]. |
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
175 +----------+--------+--------------------------------------------------------+
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
176 | 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
177 +----------+--------+--------------------------------------------------------+
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
178 | 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
179 | +--------+--------------------------------------------------------+
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
180 | | ``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
181 | +--------+--------------------------------------------------------+
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
182 | | ``A`` | Milliseconds in day. |
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
183 +----------+--------+--------------------------------------------------------+
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
184 | 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
185 | | | four for the full name. |
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
186 | +--------+--------------------------------------------------------+
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
187 | | ``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
188 | | | GMT format. |
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
189 | +--------+--------------------------------------------------------+
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
190 | | ``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
191 | | | long wall time. |
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
192 +----------+--------+--------------------------------------------------------+
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
29
da1c9610e751 More work on timezones.
cmlenz
parents: 20
diff changeset
195 Time-zone Support
da1c9610e751 More work on timezones.
cmlenz
parents: 20
diff changeset
196 -----------------
da1c9610e751 More work on timezones.
cmlenz
parents: 20
diff changeset
197
da1c9610e751 More work on timezones.
cmlenz
parents: 20
diff changeset
198 Many of the verbose default time formats include the time-zone, but the
da1c9610e751 More work on timezones.
cmlenz
parents: 20
diff changeset
199 time-zone is not by default available for the Python ``datetime`` and ``time``
da1c9610e751 More work on timezones.
cmlenz
parents: 20
diff changeset
200 objects. The standard library includes only the abstract ``tzinfo`` class,
da1c9610e751 More work on timezones.
cmlenz
parents: 20
diff changeset
201 which you need appropriate implementations for to actually use in your
da1c9610e751 More work on timezones.
cmlenz
parents: 20
diff changeset
202 application. Babel includes a ``tzinfo`` implementation for UTC (Universal
da1c9610e751 More work on timezones.
cmlenz
parents: 20
diff changeset
203 Time). For actual time-zones, it is strongly recommended that you use the
da1c9610e751 More work on timezones.
cmlenz
parents: 20
diff changeset
204 third-party package `pytz`_, which includes the definitions of practically all
da1c9610e751 More work on timezones.
cmlenz
parents: 20
diff changeset
205 of the time-zones used on the world, as well as important functions for
da1c9610e751 More work on timezones.
cmlenz
parents: 20
diff changeset
206 reliably converting from UTC to local time, and vice versa::
da1c9610e751 More work on timezones.
cmlenz
parents: 20
diff changeset
207
da1c9610e751 More work on timezones.
cmlenz
parents: 20
diff changeset
208 >>> from datetime import time
da1c9610e751 More work on timezones.
cmlenz
parents: 20
diff changeset
209 >>> t = time(15, 30)
da1c9610e751 More work on timezones.
cmlenz
parents: 20
diff changeset
210
da1c9610e751 More work on timezones.
cmlenz
parents: 20
diff changeset
211 >>> from pytz import timezone
da1c9610e751 More work on timezones.
cmlenz
parents: 20
diff changeset
212 >>> cet = timezone('Europe/Berlin')
da1c9610e751 More work on timezones.
cmlenz
parents: 20
diff changeset
213 >>> format_time(t, 'H:mm Z', tzinfo=cet, locale='de_DE')
da1c9610e751 More work on timezones.
cmlenz
parents: 20
diff changeset
214 u'15:30 +0100'
da1c9610e751 More work on timezones.
cmlenz
parents: 20
diff changeset
215
da1c9610e751 More work on timezones.
cmlenz
parents: 20
diff changeset
216 The recommended approach to deal with different time-zones in a Python
da1c9610e751 More work on timezones.
cmlenz
parents: 20
diff changeset
217 application is to always use UTC internally, and only convert from/to the users
da1c9610e751 More work on timezones.
cmlenz
parents: 20
diff changeset
218 time-zone when accepting user input and displaying date/time data, respectively.
da1c9610e751 More work on timezones.
cmlenz
parents: 20
diff changeset
219
da1c9610e751 More work on timezones.
cmlenz
parents: 20
diff changeset
220 .. _`pytz`: http://pytz.sourceforge.net/
da1c9610e751 More work on timezones.
cmlenz
parents: 20
diff changeset
221
da1c9610e751 More work on timezones.
cmlenz
parents: 20
diff changeset
222
da1c9610e751 More work on timezones.
cmlenz
parents: 20
diff changeset
223
18
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
224 Parsing Dates
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
225 -------------
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
226
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
227 Babel can also parse date and time information in a locale-sensitive manner::
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
228
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
229 >>> from babel.dates import parse_date, parse_datetime, parse_time
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
230
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
231
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
232 Number Formatting
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
233 =================
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
234
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
235
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
236 Pattern Syntax
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
237 --------------
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
238
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
239
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
240 Parsing Numbers
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents: 2
diff changeset
241 ---------------
Copyright (C) 2012-2017 Edgewall Software