Mercurial > babel > old > babel-test
annotate doc/formatting.txt @ 114:5ec3364f250a
Added some minor distutils frontend tests, corrected and moved mapping.cfg to the appropriate place.
author | palgarvio |
---|---|
date | Thu, 14 Jun 2007 21:55:18 +0000 |
parents | a696e249467a |
children |
rev | line source |
---|---|
2 | 1 .. -*- mode: rst; encoding: utf-8 -*- |
2 | |
3 ========================== | |
4 Number and Date Formatting | |
5 ========================== | |
6 | |
7 | |
8 .. contents:: Contents | |
9 :depth: 2 | |
10 .. sectnum:: | |
11 | |
12 | |
18
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
13 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 |
98
a696e249467a
Add `--without-apidocs` switch to `build_doc` command for quicker doc-edit/review cycles.
cmlenz
parents:
40
diff
changeset
|
17 classes ``date``, ``datetime`` and/or ``time`` from the `datetime`_ package. |
18
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
18 Babel provides functions for locale-specific formatting of those objects in its |
40 | 19 ``dates`` module: |
20 | |
98
a696e249467a
Add `--without-apidocs` switch to `build_doc` command for quicker doc-edit/review cycles.
cmlenz
parents:
40
diff
changeset
|
21 .. _`datetime`: http://docs.python.org/lib/module-datetime.html |
a696e249467a
Add `--without-apidocs` switch to `build_doc` command for quicker doc-edit/review cycles.
cmlenz
parents:
40
diff
changeset
|
22 |
40 | 23 .. code-block:: pycon |
18
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
24 |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
25 >>> from datetime import date, datetime, time |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
26 >>> 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
|
27 |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
28 >>> d = date(2007, 4, 1) |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
29 >>> format_date(d, locale='en') |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
30 u'Apr 1, 2007' |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
31 >>> format_date(d, locale='de_DE') |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
32 u'01.04.2007' |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
33 |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
34 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
|
35 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
|
36 |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
37 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
|
38 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
|
39 |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
40 * ``short``, |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
41 * ``medium`` (the default), |
20 | 42 * ``long``, and |
43 * ``full``. | |
18
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
44 |
40 | 45 For example: |
46 | |
47 .. code-block:: pycon | |
18
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
48 |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
49 >>> 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
|
50 u'4/1/07' |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
51 >>> 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
|
52 u'April 1, 2007' |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
53 >>> 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
|
54 u'Sunday, April 1, 2007' |
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 |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
57 Pattern Syntax |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
58 -------------- |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
59 |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
60 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
|
61 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
|
62 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
|
63 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
|
64 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
|
65 `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
|
66 follows: |
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 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
|
69 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
|
70 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
|
71 |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
72 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
|
73 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
|
74 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
|
75 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
|
76 "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
|
77 form should be used […] |
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 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
|
80 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
|
81 for two adjacent single quotes). |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
82 |
40 | 83 For example: |
84 | |
85 .. code-block:: pycon | |
18
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 >>> d = date(2007, 4, 1) |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
88 >>> 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
|
89 u"Sun, Apr 1, '07" |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
90 >>> 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
|
91 u'Sonntag, 1.4.2007' |
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 >>> t = time(15, 30) |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
94 >>> 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
|
95 u"03 o'clock PM" |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
96 >>> 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
|
97 u'15:30 nachm.' |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
98 |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
99 >>> 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
|
100 >>> 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
|
101 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
|
102 |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
103 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
|
104 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
|
105 relatively brief overview. |
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 .. _`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
|
108 |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
109 ----------- |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
110 Date Fields |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
111 ----------- |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
112 |
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 | Field | Symbol | Description | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
115 +==========+========+========================================================+ |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
116 | 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
|
117 | | | 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
|
118 | | | 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
|
119 +----------+--------+--------------------------------------------------------+ |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
120 | 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
|
121 | | | 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
|
122 | | | maximum length. | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
123 | +--------+--------------------------------------------------------+ |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
124 | | ``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
|
125 | +--------+--------------------------------------------------------+ |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
126 | | ``u`` | ?? | |
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 | 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
|
129 | | | 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
|
130 | +--------+--------------------------------------------------------+ |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
131 | | ``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
|
132 | | | 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
|
133 +----------+--------+--------------------------------------------------------+ |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
134 | 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
|
135 | | | 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
|
136 | | | the narrow name. | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
137 | +--------+--------------------------------------------------------+ |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
138 | | ``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
|
139 | | | 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
|
140 | | | narrow name. | |
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 | Week | ``w`` | Week 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 | | ``W`` | Week of 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 | Day | ``d`` | Day of month. | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
147 | +--------+--------------------------------------------------------+ |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
148 | | ``D`` | Day of year. | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
149 | +--------+--------------------------------------------------------+ |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
150 | | ``F`` | Day of week in month. | |
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 | | ``g`` | ?? | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
153 +----------+--------+--------------------------------------------------------+ |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
154 | 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
|
155 | | | 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
|
156 | | | narrow name. | |
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 | | ``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
|
159 | | | 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
|
160 | | | 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
|
161 | +--------+--------------------------------------------------------+ |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
162 | | ``c`` | ?? | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
163 +----------+--------+--------------------------------------------------------+ |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
164 |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
165 ----------- |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
166 Time Fields |
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 |
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 | Field | Symbol | Description | |
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 | Period | ``a`` | AM or PM | |
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 | Hour | ``h`` | Hour [1-12]. | |
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 | | ``H`` | Hour [0-23]. | |
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 | | ``K`` | Hour [0-11]. | |
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 | | ``k`` | Hour [1-24]. | |
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 | 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
|
183 +----------+--------+--------------------------------------------------------+ |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
184 | 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
|
185 | +--------+--------------------------------------------------------+ |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
186 | | ``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
|
187 | +--------+--------------------------------------------------------+ |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
188 | | ``A`` | Milliseconds in day. | |
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 | 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
|
191 | | | four for the full name. | |
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 | | ``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
|
194 | | | GMT format. | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
195 | +--------+--------------------------------------------------------+ |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
196 | | ``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
|
197 | | | long wall time. | |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
198 +----------+--------+--------------------------------------------------------+ |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
199 |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
200 |
31 | 201 Time-Zone Support |
29 | 202 ----------------- |
203 | |
31 | 204 Many of the verbose time formats include the time-zone, but time-zone |
205 information is not by default available for the Python ``datetime`` and | |
206 ``time`` objects. The standard library includes only the abstract ``tzinfo`` | |
207 class, which you need appropriate implementations for to actually use in your | |
29 | 208 application. Babel includes a ``tzinfo`` implementation for UTC (Universal |
31 | 209 Time). |
210 | |
211 For real time-zone support, it is strongly recommended that you use the | |
29 | 212 third-party package `pytz`_, which includes the definitions of practically all |
213 of the time-zones used on the world, as well as important functions for | |
40 | 214 reliably converting from UTC to local time, and vice versa: |
215 | |
216 .. code-block:: pycon | |
29 | 217 |
218 >>> from datetime import time | |
34 | 219 >>> from pytz import timezone, utc |
220 >>> dt = datetime(2007, 04, 01, 15, 30, tzinfo=utc) | |
221 >>> eastern = timezone('US/Eastern') | |
222 >>> format_datetime(dt, 'H:mm Z', tzinfo=eastern, locale='en_US') | |
223 u'11:30 -0400' | |
29 | 224 |
225 The recommended approach to deal with different time-zones in a Python | |
226 application is to always use UTC internally, and only convert from/to the users | |
227 time-zone when accepting user input and displaying date/time data, respectively. | |
34 | 228 You can use Babel together with ``pytz`` to apply a time-zone to any |
229 ``datetime`` or ``time`` object for display, leaving the original information | |
40 | 230 unchanged: |
231 | |
232 .. code-block:: pycon | |
34 | 233 |
234 >>> british = timezone('Europe/London') | |
235 >>> format_datetime(dt, 'H:mm zzzz', tzinfo=british, locale='en_US') | |
236 u'16:30 British Summer Time' | |
29 | 237 |
35 | 238 Here, the given UTC time is adjusted to the "Europe/London" time-zone, and |
239 daylight savings time is taken into account. Daylight savings time is also | |
240 applied to ``format_time``, but because the actual date is unknown in that | |
241 case, the current day is assumed to determine whether DST or standard time | |
242 should be used. | |
243 | |
29 | 244 .. _`pytz`: http://pytz.sourceforge.net/ |
245 | |
246 | |
18
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
247 Parsing Dates |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
248 ------------- |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
249 |
40 | 250 Babel can also parse date and time information in a locale-sensitive manner: |
251 | |
252 .. code-block:: pycon | |
18
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
253 |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
254 >>> 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
|
255 |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
256 |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
257 Number Formatting |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
258 ================= |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
259 |
32 | 260 Support for locale-specific formatting and parsing of numbers is provided by |
40 | 261 the ``babel.numbers`` module: |
262 | |
263 .. code-block:: pycon | |
32 | 264 |
265 >>> from babel.numbers import format_number, format_decimal, format_percent | |
266 | |
40 | 267 Examples: |
268 | |
269 .. code-block:: pycon | |
32 | 270 |
271 >>> format_decimal(1.2345, locale='en_US') | |
272 u'1.234' | |
273 >>> format_decimal(1.2345, locale='sv_SE') | |
274 u'1,234' | |
275 >>> format_decimal(12345, locale='de_DE') | |
276 u'12.345' | |
277 | |
18
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
278 |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
279 Pattern Syntax |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
280 -------------- |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
281 |
32 | 282 While Babel makes it simple to use the appropriate number format for a given |
283 locale, you can also force it to use custom patterns. As with date/time | |
284 formatting patterns, the patterns Babel supports for number formatting are | |
285 based on the `Locale Data Markup Language specification`_ (LDML). | |
286 | |
40 | 287 Examples: |
288 | |
289 .. code-block:: pycon | |
32 | 290 |
291 >>> format_decimal(-1.2345, format='#,##0.##;-#', locale='en') | |
292 u'-1.23' | |
293 >>> format_decimal(-1.2345, format='#,##0.##;(#)', locale='en') | |
294 u'(1.23)' | |
295 | |
296 The syntax for custom number format patterns is described in detail in the | |
297 the specification. The following table is just a relatively brief overview. | |
298 | |
299 +----------+-----------------------------------------------------------------+ | |
300 | Symbol | Description | | |
301 +==========+=================================================================+ | |
302 | ``0`` | Digit | | |
303 +----------+-----------------------------------------------------------------+ | |
304 | ``1-9`` | '1' through '9' indicate rounding. | | |
305 +----------+-----------------------------------------------------------------+ | |
306 | ``@`` | Significant digit | | |
307 +----------+-----------------------------------------------------------------+ | |
308 | ``#`` | Digit, zero shows as absent | | |
309 +----------+-----------------------------------------------------------------+ | |
310 | ``.`` | Decimal separator or monetary decimal separator | | |
311 +----------+-----------------------------------------------------------------+ | |
312 | ``-`` | Minus sign | | |
313 +----------+-----------------------------------------------------------------+ | |
314 | ``,`` | Grouping separator | | |
315 +----------+-----------------------------------------------------------------+ | |
316 | ``E`` | Separates mantissa and exponent in scientific notation | | |
317 +----------+-----------------------------------------------------------------+ | |
318 | ``+`` | Prefix positive exponents with localized plus sign | | |
319 +----------+-----------------------------------------------------------------+ | |
320 | ``;`` | Separates positive and negative subpatterns | | |
321 +----------+-----------------------------------------------------------------+ | |
322 | ``%`` | Multiply by 100 and show as percentage | | |
323 +----------+-----------------------------------------------------------------+ | |
324 | ``‰`` | Multiply by 1000 and show as per mille | | |
325 +----------+-----------------------------------------------------------------+ | |
326 | ``¤`` | Currency sign, replaced by currency symbol. If doubled, | | |
327 | | replaced by international currency symbol. If tripled, uses the | | |
328 | | long form of the decimal symbol. | | |
329 +----------+-----------------------------------------------------------------+ | |
330 | ``'`` | Used to quote special characters in a prefix or suffix | | |
331 +----------+-----------------------------------------------------------------+ | |
332 | ``*`` | Pad escape, precedes pad character | | |
333 +----------+-----------------------------------------------------------------+ | |
334 | |
18
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
335 |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
336 Parsing Numbers |
77a68f88f6bc
Started documentation for date formatting, plus some code tweaks in that area.
cmlenz
parents:
2
diff
changeset
|
337 --------------- |
32 | 338 |
40 | 339 Babel can also parse numeric data in a locale-sensitive manner: |
340 | |
341 .. code-block:: pycon | |
32 | 342 |
34 | 343 >>> from babel.numbers import parse_decimal, parse_number |
32 | 344 |
40 | 345 Examples: |
346 | |
347 .. code-block:: pycon | |
32 | 348 |
349 >>> parse_decimal('1,099.98', locale='en_US') | |
350 1099.98 | |
351 >>> parse_decimal('1.099,98', locale='de') | |
352 1099.98 | |
353 >>> parse_decimal('2,109,998', locale='de') | |
354 Traceback (most recent call last): | |
40 | 355 ... |
32 | 356 NumberFormatError: '2,109,998' is not a valid decimal number |