← Back to branch summary

~ubuntu-branches/ubuntu/trusty/python-babel/trusty

« back to all changes in this revision

Viewing changes to doc/api/babel.dates-module.html

  • Committer: Package Import Robot
  • Author(s): Chuck Short
  • Date: 2013-10-28 10:11:31 UTC
  • mfrom: (4.1.2 sid)
  • Revision ID: package-import@ubuntu.com-20131028101131-zwbmm8sc29iemmlr
Tags: 1.3-2ubuntu1
* Merge from Debian unstable.  Remaining changes:
  - debian/rules: Run the testsuite during builds.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/api/babel.dates-module.html
1
 
<?xml version="1.0" encoding="ascii"?>
2
 
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
3
 
          "DTD/xhtml1-transitional.dtd">
4
 
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
5
 
<head>
6
 
  <title>babel.dates</title>
7
 
  <link rel="stylesheet" href="epydoc.css" type="text/css" />
8
 
  <script type="text/javascript" src="epydoc.js"></script>
9
 
</head>
10
 
 
11
 
<body bgcolor="white" text="black" link="blue" vlink="#204080"
12
 
      alink="#204080">
13
 
<!-- ==================== NAVIGATION BAR ==================== -->
14
 
<table class="navbar" border="0" width="100%" cellpadding="0"
15
 
       bgcolor="#a0c0ff" cellspacing="0">
16
 
  <tr valign="middle">
17
 
  <!-- Home link -->
18
 
      <th>&nbsp;&nbsp;&nbsp;<a
19
 
        href="babel-module.html">Home</a>&nbsp;&nbsp;&nbsp;</th>
20
 
 
21
 
  <!-- Tree link -->
22
 
      <th>&nbsp;&nbsp;&nbsp;<a
23
 
        href="module-tree.html">Trees</a>&nbsp;&nbsp;&nbsp;</th>
24
 
 
25
 
  <!-- Index link -->
26
 
      <th>&nbsp;&nbsp;&nbsp;<a
27
 
        href="identifier-index.html">Indices</a>&nbsp;&nbsp;&nbsp;</th>
28
 
 
29
 
  <!-- Help link -->
30
 
      <th>&nbsp;&nbsp;&nbsp;<a
31
 
        href="help.html">Help</a>&nbsp;&nbsp;&nbsp;</th>
32
 
 
33
 
  <!-- Project homepage -->
34
 
      <th class="navbar" align="right" width="100%">
35
 
        <table border="0" cellpadding="0" cellspacing="0">
36
 
          <tr><th class="navbar" align="center"
37
 
            ><a class="navbar" target="_top" href="../index.html">Documentation Index</a></th>
38
 
          </tr></table></th>
39
 
  </tr>
40
 
</table>
41
 
<table width="100%" cellpadding="0" cellspacing="0">
42
 
  <tr valign="top">
43
 
    <td width="100%">
44
 
      <span class="breadcrumbs">
45
 
        <a href="babel-module.html">Package&nbsp;babel</a> ::
46
 
        Module&nbsp;dates
47
 
      </span>
48
 
    </td>
49
 
    <td>
50
 
      <table cellpadding="0" cellspacing="0">
51
 
        <!-- hide/show private -->
52
 
      </table>
53
 
    </td>
54
 
  </tr>
55
 
</table>
56
 
<!-- ==================== MODULE DESCRIPTION ==================== -->
57
 
<h1 class="epydoc">Module dates</h1><p class="nomargin-top"></p>
58
 
<p>Locale dependent formatting and parsing of dates and times.</p>
59
 
<p>The default locale for the functions in this module is determined by the
60
 
following environment variables, in that order:</p>
61
 
<blockquote>
62
 
<ul class="rst-simple">
63
 
<li><tt class="rst-docutils literal">LC_TIME</tt>,</li>
64
 
<li><tt class="rst-docutils literal">LC_ALL</tt>, and</li>
65
 
<li><tt class="rst-docutils literal">LANG</tt></li>
66
 
</ul>
67
 
</blockquote>
68
 
 
69
 
<!-- ==================== FUNCTIONS ==================== -->
70
 
<a name="section-Functions"></a>
71
 
<table class="summary" border="1" cellpadding="3"
72
 
       cellspacing="0" width="100%" bgcolor="white">
73
 
<tr bgcolor="#70b0f0" class="table-header">
74
 
  <td align="left" colspan="2" class="table-header">
75
 
    <span class="table-header">Functions</span></td>
76
 
</tr>
77
 
<tr>
78
 
    <td width="15%" align="right" valign="top" class="summary">
79
 
      <span class="summary-type"><code class="link">unicode</code></span>
80
 
    </td><td class="summary">
81
 
      <table width="100%" cellpadding="0" cellspacing="0" border="0">
82
 
        <tr>
83
 
          <td><span class="summary-sig"><a href="babel.dates-module.html#get_timezone_name" class="summary-sig-name">get_timezone_name</a>(<span class="summary-sig-arg">dt_or_tzinfo</span>=<span class="summary-sig-default">None</span>,
84
 
        <span class="summary-sig-arg">width</span>=<span class="summary-sig-default"><code class="variable-quote">'</code><code class="variable-string">long</code><code class="variable-quote">'</code></span>,
85
 
        <span class="summary-sig-arg">uncommon</span>=<span class="summary-sig-default">False</span>,
86
 
        <span class="summary-sig-arg">locale</span>=<span class="summary-sig-default"><code class="variable-quote">'</code><code class="variable-string">de_DE</code><code class="variable-quote">'</code></span>)</span><br />
87
 
      Return the localized display name for the given timezone.</td>
88
 
          <td align="right" valign="top">
89
 
            
90
 
            
91
 
          </td>
92
 
        </tr>
93
 
      </table>
94
 
      
95
 
    </td>
96
 
  </tr>
97
 
<tr>
98
 
    <td width="15%" align="right" valign="top" class="summary">
99
 
      <span class="summary-type"><code class="link">unicode</code></span>
100
 
    </td><td class="summary">
101
 
      <table width="100%" cellpadding="0" cellspacing="0" border="0">
102
 
        <tr>
103
 
          <td><span class="summary-sig"><a href="babel.dates-module.html#format_date" class="summary-sig-name">format_date</a>(<span class="summary-sig-arg">date</span>=<span class="summary-sig-default">None</span>,
104
 
        <span class="summary-sig-arg">format</span>=<span class="summary-sig-default"><code class="variable-quote">'</code><code class="variable-string">medium</code><code class="variable-quote">'</code></span>,
105
 
        <span class="summary-sig-arg">locale</span>=<span class="summary-sig-default"><code class="variable-quote">'</code><code class="variable-string">de_DE</code><code class="variable-quote">'</code></span>)</span><br />
106
 
      Return a date formatted according to the given pattern.</td>
107
 
          <td align="right" valign="top">
108
 
            
109
 
            
110
 
          </td>
111
 
        </tr>
112
 
      </table>
113
 
      
114
 
    </td>
115
 
  </tr>
116
 
<tr>
117
 
    <td width="15%" align="right" valign="top" class="summary">
118
 
      <span class="summary-type"><code class="link">unicode</code></span>
119
 
    </td><td class="summary">
120
 
      <table width="100%" cellpadding="0" cellspacing="0" border="0">
121
 
        <tr>
122
 
          <td><span class="summary-sig"><a href="babel.dates-module.html#format_datetime" class="summary-sig-name">format_datetime</a>(<span class="summary-sig-arg">datetime</span>=<span class="summary-sig-default">None</span>,
123
 
        <span class="summary-sig-arg">format</span>=<span class="summary-sig-default"><code class="variable-quote">'</code><code class="variable-string">medium</code><code class="variable-quote">'</code></span>,
124
 
        <span class="summary-sig-arg">tzinfo</span>=<span class="summary-sig-default">None</span>,
125
 
        <span class="summary-sig-arg">locale</span>=<span class="summary-sig-default"><code class="variable-quote">'</code><code class="variable-string">de_DE</code><code class="variable-quote">'</code></span>)</span><br />
126
 
      Return a date formatted according to the given pattern.</td>
127
 
          <td align="right" valign="top">
128
 
            
129
 
            
130
 
          </td>
131
 
        </tr>
132
 
      </table>
133
 
      
134
 
    </td>
135
 
  </tr>
136
 
<tr>
137
 
    <td width="15%" align="right" valign="top" class="summary">
138
 
      <span class="summary-type"><code class="link">unicode</code></span>
139
 
    </td><td class="summary">
140
 
      <table width="100%" cellpadding="0" cellspacing="0" border="0">
141
 
        <tr>
142
 
          <td><span class="summary-sig"><a href="babel.dates-module.html#format_time" class="summary-sig-name">format_time</a>(<span class="summary-sig-arg">time</span>=<span class="summary-sig-default">None</span>,
143
 
        <span class="summary-sig-arg">format</span>=<span class="summary-sig-default"><code class="variable-quote">'</code><code class="variable-string">medium</code><code class="variable-quote">'</code></span>,
144
 
        <span class="summary-sig-arg">tzinfo</span>=<span class="summary-sig-default">None</span>,
145
 
        <span class="summary-sig-arg">locale</span>=<span class="summary-sig-default"><code class="variable-quote">'</code><code class="variable-string">de_DE</code><code class="variable-quote">'</code></span>)</span><br />
146
 
      Return a time formatted according to the given pattern.</td>
147
 
          <td align="right" valign="top">
148
 
            
149
 
            
150
 
          </td>
151
 
        </tr>
152
 
      </table>
153
 
      
154
 
    </td>
155
 
  </tr>
156
 
<tr>
157
 
    <td width="15%" align="right" valign="top" class="summary">
158
 
      <span class="summary-type">date</span>
159
 
    </td><td class="summary">
160
 
      <table width="100%" cellpadding="0" cellspacing="0" border="0">
161
 
        <tr>
162
 
          <td><span class="summary-sig"><a href="babel.dates-module.html#parse_date" class="summary-sig-name">parse_date</a>(<span class="summary-sig-arg">string</span>,
163
 
        <span class="summary-sig-arg">locale</span>=<span class="summary-sig-default"><code class="variable-quote">'</code><code class="variable-string">de_DE</code><code class="variable-quote">'</code></span>)</span><br />
164
 
      Parse a date from a string.</td>
165
 
          <td align="right" valign="top">
166
 
            
167
 
            
168
 
          </td>
169
 
        </tr>
170
 
      </table>
171
 
      
172
 
    </td>
173
 
  </tr>
174
 
<tr>
175
 
    <td width="15%" align="right" valign="top" class="summary">
176
 
      <span class="summary-type">datetime</span>
177
 
    </td><td class="summary">
178
 
      <table width="100%" cellpadding="0" cellspacing="0" border="0">
179
 
        <tr>
180
 
          <td><span class="summary-sig"><a href="babel.dates-module.html#parse_datetime" class="summary-sig-name">parse_datetime</a>(<span class="summary-sig-arg">string</span>,
181
 
        <span class="summary-sig-arg">locale</span>=<span class="summary-sig-default"><code class="variable-quote">'</code><code class="variable-string">de_DE</code><code class="variable-quote">'</code></span>)</span><br />
182
 
      Parse a date and time from a string.</td>
183
 
          <td align="right" valign="top">
184
 
            
185
 
            
186
 
          </td>
187
 
        </tr>
188
 
      </table>
189
 
      
190
 
    </td>
191
 
  </tr>
192
 
<tr>
193
 
    <td width="15%" align="right" valign="top" class="summary">
194
 
      <span class="summary-type">time</span>
195
 
    </td><td class="summary">
196
 
      <table width="100%" cellpadding="0" cellspacing="0" border="0">
197
 
        <tr>
198
 
          <td><span class="summary-sig"><a href="babel.dates-module.html#parse_time" class="summary-sig-name">parse_time</a>(<span class="summary-sig-arg">string</span>,
199
 
        <span class="summary-sig-arg">locale</span>=<span class="summary-sig-default"><code class="variable-quote">'</code><code class="variable-string">de_DE</code><code class="variable-quote">'</code></span>)</span><br />
200
 
      Parse a time from a string.</td>
201
 
          <td align="right" valign="top">
202
 
            
203
 
            
204
 
          </td>
205
 
        </tr>
206
 
      </table>
207
 
      
208
 
    </td>
209
 
  </tr>
210
 
</table>
211
 
<!-- ==================== FUNCTION DETAILS ==================== -->
212
 
<a name="section-FunctionDetails"></a>
213
 
<table class="details" border="1" cellpadding="3"
214
 
       cellspacing="0" width="100%" bgcolor="white">
215
 
<tr bgcolor="#70b0f0" class="table-header">
216
 
  <td align="left" colspan="2" class="table-header">
217
 
    <span class="table-header">Function Details</span></td>
218
 
</tr>
219
 
</table>
220
 
<a name="get_timezone_name"></a>
221
 
<div>
222
 
<table class="details" border="1" cellpadding="3"
223
 
       cellspacing="0" width="100%" bgcolor="white">
224
 
<tr><td>
225
 
  <table width="100%" cellpadding="0" cellspacing="0" border="0">
226
 
  <tr valign="top"><td>
227
 
  <h3 class="epydoc"><span class="sig"><span class="sig-name">get_timezone_name</span>(<span class="sig-arg">dt_or_tzinfo</span>=<span class="sig-default">None</span>,
228
 
        <span class="sig-arg">width</span>=<span class="sig-default"><code class="variable-quote">'</code><code class="variable-string">long</code><code class="variable-quote">'</code></span>,
229
 
        <span class="sig-arg">uncommon</span>=<span class="sig-default">False</span>,
230
 
        <span class="sig-arg">locale</span>=<span class="sig-default"><code class="variable-quote">'</code><code class="variable-string">de_DE</code><code class="variable-quote">'</code></span>)</span>
231
 
  </h3>
232
 
  </td><td align="right" valign="top"
233
 
    >&nbsp;
234
 
    </td>
235
 
  </tr></table>
236
 
  
237
 
  <p>Return the localized display name for the given timezone. The timezone
238
 
may be specified using a <tt class="rst-docutils literal">datetime</tt> or tzinfo object.</p>
239
 
<pre class="py-doctest">
240
 
<span class="py-prompt">&gt;&gt;&gt; </span><span class="py-keyword">from</span> pytz <span class="py-keyword">import</span> timezone
241
 
<span class="py-prompt">&gt;&gt;&gt; </span>dt = time(15, 30, tzinfo=timezone(<span class="py-string">'America/Los_Angeles'</span>))
242
 
<span class="py-prompt">&gt;&gt;&gt; </span>get_timezone_name(dt, locale=<span class="py-string">'en_US'</span>)
243
 
<span class="py-output">u'Pacific Standard Time'</span>
244
 
<span class="py-output"></span><span class="py-prompt">&gt;&gt;&gt; </span>get_timezone_name(dt, width=<span class="py-string">'short'</span>, locale=<span class="py-string">'en_US'</span>)
245
 
<span class="py-output">u'PST'</span></pre>
246
 
<p>If this function gets passed only a tzinfo object and no concrete
247
 
datetime,  the returned display name is indenpendent of daylight savings
248
 
time. This can be used for example for selecting timezones, or to set the
249
 
time of events that recur across DST changes:</p>
250
 
<pre class="py-doctest">
251
 
<span class="py-prompt">&gt;&gt;&gt; </span>tz = timezone(<span class="py-string">'America/Los_Angeles'</span>)
252
 
<span class="py-prompt">&gt;&gt;&gt; </span>get_timezone_name(tz, locale=<span class="py-string">'en_US'</span>)
253
 
<span class="py-output">u'Pacific Time'</span>
254
 
<span class="py-output"></span><span class="py-prompt">&gt;&gt;&gt; </span>get_timezone_name(tz, <span class="py-string">'short'</span>, locale=<span class="py-string">'en_US'</span>)
255
 
<span class="py-output">u'PT'</span></pre>
256
 
<p>If no localized display name for the timezone is available, and the timezone
257
 
is associated with a country that uses only a single timezone, the name of
258
 
that country is returned, formatted according to the locale:</p>
259
 
<pre class="py-doctest">
260
 
<span class="py-prompt">&gt;&gt;&gt; </span>tz = timezone(<span class="py-string">'Europe/Berlin'</span>)
261
 
<span class="py-prompt">&gt;&gt;&gt; </span>get_timezone_name(tz, locale=<span class="py-string">'de_DE'</span>)
262
 
<span class="py-output">u'Deutschland'</span>
263
 
<span class="py-output"></span><span class="py-prompt">&gt;&gt;&gt; </span>get_timezone_name(tz, locale=<span class="py-string">'pt_BR'</span>)
264
 
<span class="py-output">u'Hor\xe1rio Alemanha'</span></pre>
265
 
<p>On the other hand, if the country uses multiple timezones, the city is also
266
 
included in the representation:</p>
267
 
<pre class="py-doctest">
268
 
<span class="py-prompt">&gt;&gt;&gt; </span>tz = timezone(<span class="py-string">'America/St_Johns'</span>)
269
 
<span class="py-prompt">&gt;&gt;&gt; </span>get_timezone_name(tz, locale=<span class="py-string">'de_DE'</span>)
270
 
<span class="py-output">u&quot;Kanada (St. John's)&quot;</span></pre>
271
 
<p>The <code class="link">uncommon</code> parameter can be set to <code class="link">True</code> to enable the use of timezone
272
 
representations that are not commonly used by the requested locale. For
273
 
example, while in French the central European timezone is usually
274
 
abbreviated as &quot;HEC&quot;, in Canadian French, this abbreviation is not in
275
 
common use, so a generic name would be chosen by default:</p>
276
 
<pre class="py-doctest">
277
 
<span class="py-prompt">&gt;&gt;&gt; </span>tz = timezone(<span class="py-string">'Europe/Paris'</span>)
278
 
<span class="py-prompt">&gt;&gt;&gt; </span>get_timezone_name(tz, <span class="py-string">'short'</span>, locale=<span class="py-string">'fr_CA'</span>)
279
 
<span class="py-output">u'France'</span>
280
 
<span class="py-output"></span><span class="py-prompt">&gt;&gt;&gt; </span>get_timezone_name(tz, <span class="py-string">'short'</span>, uncommon=True, locale=<span class="py-string">'fr_CA'</span>)
281
 
<span class="py-output">u'HEC'</span></pre>
282
 
  <dl class="fields">
283
 
    <dt>Parameters:</dt>
284
 
    <dd><ul class="nomargin-top">
285
 
        <li><strong class="pname"><code>dt_or_tzinfo</code></strong> - the <tt class="rst-docutils literal">datetime</tt> or <tt class="rst-docutils literal">tzinfo</tt> object that determines
286
 
the timezone; if a <tt class="rst-docutils literal">tzinfo</tt> object is used, the
287
 
resulting display name will be generic, i.e.
288
 
independent of daylight savings time; if <code class="link">None</code>, the
289
 
current date in UTC is assumed</li>
290
 
        <li><strong class="pname"><code>width</code></strong> - either &quot;long&quot; or &quot;short&quot;</li>
291
 
        <li><strong class="pname"><code>uncommon</code></strong> - whether even uncommon timezone abbreviations should be used</li>
292
 
        <li><strong class="pname"><code>locale</code></strong> - the <a href="babel.core.Locale-class.html" class="link">Locale</a> object, or a locale string</li>
293
 
    </ul></dd>
294
 
    <dt>Returns: <code class="link">unicode</code></dt>
295
 
        <dd>the timezone display name</dd>
296
 
  </dl>
297
 
<div class="fields">      <p><strong>Since:</strong>
298
 
        version 0.9
299
 
      </p>
300
 
      <p><strong>See Also:</strong>
301
 
        <a class="rst-reference external" href="http://www.unicode.org/reports/tr35/#Time_Zone_Fallback" target="_top">LDML Appendix J: Time Zone Display Names</a>
302
 
      </p>
303
 
</div></td></tr></table>
304
 
</div>
305
 
<a name="format_date"></a>
306
 
<div>
307
 
<table class="details" border="1" cellpadding="3"
308
 
       cellspacing="0" width="100%" bgcolor="white">
309
 
<tr><td>
310
 
  <table width="100%" cellpadding="0" cellspacing="0" border="0">
311
 
  <tr valign="top"><td>
312
 
  <h3 class="epydoc"><span class="sig"><span class="sig-name">format_date</span>(<span class="sig-arg">date</span>=<span class="sig-default">None</span>,
313
 
        <span class="sig-arg">format</span>=<span class="sig-default"><code class="variable-quote">'</code><code class="variable-string">medium</code><code class="variable-quote">'</code></span>,
314
 
        <span class="sig-arg">locale</span>=<span class="sig-default"><code class="variable-quote">'</code><code class="variable-string">de_DE</code><code class="variable-quote">'</code></span>)</span>
315
 
  </h3>
316
 
  </td><td align="right" valign="top"
317
 
    >&nbsp;
318
 
    </td>
319
 
  </tr></table>
320
 
  
321
 
  <p>Return a date formatted according to the given pattern.</p>
322
 
<pre class="py-doctest">
323
 
<span class="py-prompt">&gt;&gt;&gt; </span>d = date(2007, 04, 01)
324
 
<span class="py-prompt">&gt;&gt;&gt; </span>format_date(d, locale=<span class="py-string">'en_US'</span>)
325
 
<span class="py-output">u'Apr 1, 2007'</span>
326
 
<span class="py-output"></span><span class="py-prompt">&gt;&gt;&gt; </span>format_date(d, format=<span class="py-string">'full'</span>, locale=<span class="py-string">'de_DE'</span>)
327
 
<span class="py-output">u'Sonntag, 1. April 2007'</span></pre>
328
 
<p>If you don't want to use the locale default formats, you can specify a
329
 
custom date pattern:</p>
330
 
<pre class="py-doctest">
331
 
<span class="py-prompt">&gt;&gt;&gt; </span>format_date(d, <span class="py-string">&quot;EEE, MMM d, ''yy&quot;</span>, locale=<span class="py-string">'en'</span>)
332
 
<span class="py-output">u&quot;Sun, Apr 1, '07&quot;</span></pre>
333
 
  <dl class="fields">
334
 
    <dt>Parameters:</dt>
335
 
    <dd><ul class="nomargin-top">
336
 
        <li><strong class="pname"><code>date</code></strong> - the <tt class="rst-docutils literal">date</tt> or <tt class="rst-docutils literal">datetime</tt> object; if <code class="link">None</code>, the current
337
 
date is used</li>
338
 
        <li><strong class="pname"><code>format</code></strong> - one of &quot;full&quot;, &quot;long&quot;, &quot;medium&quot;, or &quot;short&quot;, or a custom
339
 
date/time pattern</li>
340
 
        <li><strong class="pname"><code>locale</code></strong> - a <a href="babel.core.Locale-class.html" class="link">Locale</a> object or a locale identifier</li>
341
 
    </ul></dd>
342
 
    <dt>Returns: <code class="link">unicode</code></dt>
343
 
  </dl>
344
 
<div class="fields">      <p><strong>Note:</strong>
345
 
        If the pattern contains time fields, an <code class="link">AttributeError</code> will be
346
 
raised when trying to apply the formatting. This is also true if
347
 
the value of <tt class="rst-docutils literal">date</tt> parameter is actually a <tt class="rst-docutils literal">datetime</tt> object,
348
 
as this function automatically converts that to a <tt class="rst-docutils literal">date</tt>.
349
 
      </p>
350
 
</div></td></tr></table>
351
 
</div>
352
 
<a name="format_datetime"></a>
353
 
<div>
354
 
<table class="details" border="1" cellpadding="3"
355
 
       cellspacing="0" width="100%" bgcolor="white">
356
 
<tr><td>
357
 
  <table width="100%" cellpadding="0" cellspacing="0" border="0">
358
 
  <tr valign="top"><td>
359
 
  <h3 class="epydoc"><span class="sig"><span class="sig-name">format_datetime</span>(<span class="sig-arg">datetime</span>=<span class="sig-default">None</span>,
360
 
        <span class="sig-arg">format</span>=<span class="sig-default"><code class="variable-quote">'</code><code class="variable-string">medium</code><code class="variable-quote">'</code></span>,
361
 
        <span class="sig-arg">tzinfo</span>=<span class="sig-default">None</span>,
362
 
        <span class="sig-arg">locale</span>=<span class="sig-default"><code class="variable-quote">'</code><code class="variable-string">de_DE</code><code class="variable-quote">'</code></span>)</span>
363
 
  </h3>
364
 
  </td><td align="right" valign="top"
365
 
    >&nbsp;
366
 
    </td>
367
 
  </tr></table>
368
 
  
369
 
  <p>Return a date formatted according to the given pattern.</p>
370
 
<pre class="py-doctest">
371
 
<span class="py-prompt">&gt;&gt;&gt; </span>dt = datetime(2007, 04, 01, 15, 30)
372
 
<span class="py-prompt">&gt;&gt;&gt; </span>format_datetime(dt, locale=<span class="py-string">'en_US'</span>)
373
 
<span class="py-output">u'Apr 1, 2007 3:30:00 PM'</span></pre>
374
 
<p>For any pattern requiring the display of the time-zone, the third-party
375
 
<tt class="rst-docutils literal">pytz</tt> package is needed to explicitly specify the time-zone:</p>
376
 
<pre class="py-doctest">
377
 
<span class="py-prompt">&gt;&gt;&gt; </span><span class="py-keyword">from</span> pytz <span class="py-keyword">import</span> timezone
378
 
<span class="py-prompt">&gt;&gt;&gt; </span>format_datetime(dt, <span class="py-string">'full'</span>, tzinfo=timezone(<span class="py-string">'Europe/Paris'</span>),
379
 
<span class="py-more">... </span>                locale=<span class="py-string">'fr_FR'</span>)
380
 
<span class="py-output">u'dimanche 1 avril 2007 17:30:00 HEC'</span>
381
 
<span class="py-output"></span><span class="py-prompt">&gt;&gt;&gt; </span>format_datetime(dt, <span class="py-string">&quot;yyyy.MM.dd G 'at' HH:mm:ss zzz&quot;</span>,
382
 
<span class="py-more">... </span>                tzinfo=timezone(<span class="py-string">'US/Eastern'</span>), locale=<span class="py-string">'en'</span>)
383
 
<span class="py-output">u'2007.04.01 AD at 11:30:00 EDT'</span></pre>
384
 
  <dl class="fields">
385
 
    <dt>Parameters:</dt>
386
 
    <dd><ul class="nomargin-top">
387
 
        <li><strong class="pname"><code>datetime</code></strong> - the datetime object; if <code class="link">None</code>, the current date and
388
 
time is used</li>
389
 
        <li><strong class="pname"><code>format</code></strong> - one of &quot;full&quot;, &quot;long&quot;, &quot;medium&quot;, or &quot;short&quot;, or a custom
390
 
date/time pattern</li>
391
 
        <li><strong class="pname"><code>tzinfo</code></strong> - the timezone to apply to the time for display</li>
392
 
        <li><strong class="pname"><code>locale</code></strong> - a <a href="babel.core.Locale-class.html" class="link">Locale</a> object or a locale identifier</li>
393
 
    </ul></dd>
394
 
    <dt>Returns: <code class="link">unicode</code></dt>
395
 
  </dl>
396
 
</td></tr></table>
397
 
</div>
398
 
<a name="format_time"></a>
399
 
<div>
400
 
<table class="details" border="1" cellpadding="3"
401
 
       cellspacing="0" width="100%" bgcolor="white">
402
 
<tr><td>
403
 
  <table width="100%" cellpadding="0" cellspacing="0" border="0">
404
 
  <tr valign="top"><td>
405
 
  <h3 class="epydoc"><span class="sig"><span class="sig-name">format_time</span>(<span class="sig-arg">time</span>=<span class="sig-default">None</span>,
406
 
        <span class="sig-arg">format</span>=<span class="sig-default"><code class="variable-quote">'</code><code class="variable-string">medium</code><code class="variable-quote">'</code></span>,
407
 
        <span class="sig-arg">tzinfo</span>=<span class="sig-default">None</span>,
408
 
        <span class="sig-arg">locale</span>=<span class="sig-default"><code class="variable-quote">'</code><code class="variable-string">de_DE</code><code class="variable-quote">'</code></span>)</span>
409
 
  </h3>
410
 
  </td><td align="right" valign="top"
411
 
    >&nbsp;
412
 
    </td>
413
 
  </tr></table>
414
 
  
415
 
  <p>Return a time formatted according to the given pattern.</p>
416
 
<pre class="py-doctest">
417
 
<span class="py-prompt">&gt;&gt;&gt; </span>t = time(15, 30)
418
 
<span class="py-prompt">&gt;&gt;&gt; </span>format_time(t, locale=<span class="py-string">'en_US'</span>)
419
 
<span class="py-output">u'3:30:00 PM'</span>
420
 
<span class="py-output"></span><span class="py-prompt">&gt;&gt;&gt; </span>format_time(t, format=<span class="py-string">'short'</span>, locale=<span class="py-string">'de_DE'</span>)
421
 
<span class="py-output">u'15:30'</span></pre>
422
 
<p>If you don't want to use the locale default formats, you can specify a
423
 
custom time pattern:</p>
424
 
<pre class="py-doctest">
425
 
<span class="py-prompt">&gt;&gt;&gt; </span>format_time(t, <span class="py-string">&quot;hh 'o''clock' a&quot;</span>, locale=<span class="py-string">'en'</span>)
426
 
<span class="py-output">u&quot;03 o'clock PM&quot;</span></pre>
427
 
<p>For any pattern requiring the display of the time-zone, the third-party
428
 
<tt class="rst-docutils literal">pytz</tt> package is needed to explicitly specify the time-zone:</p>
429
 
<pre class="py-doctest">
430
 
<span class="py-prompt">&gt;&gt;&gt; </span><span class="py-keyword">from</span> pytz <span class="py-keyword">import</span> timezone
431
 
<span class="py-prompt">&gt;&gt;&gt; </span>t = datetime(2007, 4, 1, 15, 30)
432
 
<span class="py-prompt">&gt;&gt;&gt; </span>tzinfo = timezone(<span class="py-string">'Europe/Paris'</span>)
433
 
<span class="py-prompt">&gt;&gt;&gt; </span>t = tzinfo.localize(t)
434
 
<span class="py-prompt">&gt;&gt;&gt; </span>format_time(t, format=<span class="py-string">'full'</span>, tzinfo=tzinfo, locale=<span class="py-string">'fr_FR'</span>)
435
 
<span class="py-output">u'15:30:00 HEC'</span>
436
 
<span class="py-output"></span><span class="py-prompt">&gt;&gt;&gt; </span>format_time(t, <span class="py-string">&quot;hh 'o''clock' a, zzzz&quot;</span>, tzinfo=timezone(<span class="py-string">'US/Eastern'</span>),
437
 
<span class="py-more">... </span>            locale=<span class="py-string">'en'</span>)
438
 
<span class="py-output">u&quot;09 o'clock AM, Eastern Daylight Time&quot;</span></pre>
439
 
<p>As that example shows, when this function gets passed a
440
 
<tt class="rst-docutils literal">datetime.datetime</tt> value, the actual time in the formatted string is
441
 
adjusted to the timezone specified by the tzinfo parameter. If the
442
 
<tt class="rst-docutils literal">datetime</tt> is &quot;naive&quot; (i.e. it has no associated timezone information),
443
 
it is assumed to be in UTC.</p>
444
 
<p>These timezone calculations are <strong>not</strong> performed if the value is of type
445
 
<tt class="rst-docutils literal">datetime.time</tt>, as without date information there's no way to determine
446
 
what a given time would translate to in a different timezone without
447
 
information about whether daylight savings time is in effect or not. This
448
 
means that time values are left as-is, and the value of the tzinfo
449
 
parameter is only used to display the timezone name if needed:</p>
450
 
<pre class="py-doctest">
451
 
<span class="py-prompt">&gt;&gt;&gt; </span>t = time(15, 30)
452
 
<span class="py-prompt">&gt;&gt;&gt; </span>format_time(t, format=<span class="py-string">'full'</span>, tzinfo=timezone(<span class="py-string">'Europe/Paris'</span>),
453
 
<span class="py-more">... </span>            locale=<span class="py-string">'fr_FR'</span>)
454
 
<span class="py-output">u'15:30:00 HEC'</span>
455
 
<span class="py-output"></span><span class="py-prompt">&gt;&gt;&gt; </span>format_time(t, format=<span class="py-string">'full'</span>, tzinfo=timezone(<span class="py-string">'US/Eastern'</span>),
456
 
<span class="py-more">... </span>            locale=<span class="py-string">'en_US'</span>)
457
 
<span class="py-output">u'3:30:00 PM ET'</span></pre>
458
 
  <dl class="fields">
459
 
    <dt>Parameters:</dt>
460
 
    <dd><ul class="nomargin-top">
461
 
        <li><strong class="pname"><code>time</code></strong> - the <tt class="rst-docutils literal">time</tt> or <tt class="rst-docutils literal">datetime</tt> object; if <code class="link">None</code>, the current
462
 
time in UTC is used</li>
463
 
        <li><strong class="pname"><code>format</code></strong> - one of &quot;full&quot;, &quot;long&quot;, &quot;medium&quot;, or &quot;short&quot;, or a custom
464
 
date/time pattern</li>
465
 
        <li><strong class="pname"><code>tzinfo</code></strong> - the time-zone to apply to the time for display</li>
466
 
        <li><strong class="pname"><code>locale</code></strong> - a <a href="babel.core.Locale-class.html" class="link">Locale</a> object or a locale identifier</li>
467
 
    </ul></dd>
468
 
    <dt>Returns: <code class="link">unicode</code></dt>
469
 
  </dl>
470
 
<div class="fields">      <p><strong>Note:</strong>
471
 
        If the pattern contains date fields, an <code class="link">AttributeError</code> will be
472
 
raised when trying to apply the formatting. This is also true if
473
 
the value of <tt class="rst-docutils literal">time</tt> parameter is actually a <tt class="rst-docutils literal">datetime</tt> object,
474
 
as this function automatically converts that to a <tt class="rst-docutils literal">time</tt>.
475
 
      </p>
476
 
</div></td></tr></table>
477
 
</div>
478
 
<a name="parse_date"></a>
479
 
<div>
480
 
<table class="details" border="1" cellpadding="3"
481
 
       cellspacing="0" width="100%" bgcolor="white">
482
 
<tr><td>
483
 
  <table width="100%" cellpadding="0" cellspacing="0" border="0">
484
 
  <tr valign="top"><td>
485
 
  <h3 class="epydoc"><span class="sig"><span class="sig-name">parse_date</span>(<span class="sig-arg">string</span>,
486
 
        <span class="sig-arg">locale</span>=<span class="sig-default"><code class="variable-quote">'</code><code class="variable-string">de_DE</code><code class="variable-quote">'</code></span>)</span>
487
 
  </h3>
488
 
  </td><td align="right" valign="top"
489
 
    >&nbsp;
490
 
    </td>
491
 
  </tr></table>
492
 
  
493
 
  <p>Parse a date from a string.</p>
494
 
<p>This function uses the date format for the locale as a hint to determine
495
 
the order in which the date fields appear in the string.</p>
496
 
<pre class="py-doctest">
497
 
<span class="py-prompt">&gt;&gt;&gt; </span>parse_date(<span class="py-string">'4/1/04'</span>, locale=<span class="py-string">'en_US'</span>)
498
 
<span class="py-output">datetime.date(2004, 4, 1)</span>
499
 
<span class="py-output"></span><span class="py-prompt">&gt;&gt;&gt; </span>parse_date(<span class="py-string">'01.04.2004'</span>, locale=<span class="py-string">'de_DE'</span>)
500
 
<span class="py-output">datetime.date(2004, 4, 1)</span></pre>
501
 
  <dl class="fields">
502
 
    <dt>Parameters:</dt>
503
 
    <dd><ul class="nomargin-top">
504
 
        <li><strong class="pname"><code>string</code></strong> - the string containing the date</li>
505
 
        <li><strong class="pname"><code>locale</code></strong> - a <a href="babel.core.Locale-class.html" class="link">Locale</a> object or a locale identifier</li>
506
 
    </ul></dd>
507
 
    <dt>Returns: date</dt>
508
 
        <dd>the parsed date</dd>
509
 
  </dl>
510
 
</td></tr></table>
511
 
</div>
512
 
<a name="parse_datetime"></a>
513
 
<div>
514
 
<table class="details" border="1" cellpadding="3"
515
 
       cellspacing="0" width="100%" bgcolor="white">
516
 
<tr><td>
517
 
  <table width="100%" cellpadding="0" cellspacing="0" border="0">
518
 
  <tr valign="top"><td>
519
 
  <h3 class="epydoc"><span class="sig"><span class="sig-name">parse_datetime</span>(<span class="sig-arg">string</span>,
520
 
        <span class="sig-arg">locale</span>=<span class="sig-default"><code class="variable-quote">'</code><code class="variable-string">de_DE</code><code class="variable-quote">'</code></span>)</span>
521
 
  </h3>
522
 
  </td><td align="right" valign="top"
523
 
    >&nbsp;
524
 
    </td>
525
 
  </tr></table>
526
 
  
527
 
  <p>Parse a date and time from a string.</p>
528
 
<p>This function uses the date and time formats for the locale as a hint to
529
 
determine the order in which the time fields appear in the string.</p>
530
 
  <dl class="fields">
531
 
    <dt>Parameters:</dt>
532
 
    <dd><ul class="nomargin-top">
533
 
        <li><strong class="pname"><code>string</code></strong> - the string containing the date and time</li>
534
 
        <li><strong class="pname"><code>locale</code></strong> - a <a href="babel.core.Locale-class.html" class="link">Locale</a> object or a locale identifier</li>
535
 
    </ul></dd>
536
 
    <dt>Returns: datetime</dt>
537
 
        <dd>the parsed date/time</dd>
538
 
  </dl>
539
 
</td></tr></table>
540
 
</div>
541
 
<a name="parse_time"></a>
542
 
<div>
543
 
<table class="details" border="1" cellpadding="3"
544
 
       cellspacing="0" width="100%" bgcolor="white">
545
 
<tr><td>
546
 
  <table width="100%" cellpadding="0" cellspacing="0" border="0">
547
 
  <tr valign="top"><td>
548
 
  <h3 class="epydoc"><span class="sig"><span class="sig-name">parse_time</span>(<span class="sig-arg">string</span>,
549
 
        <span class="sig-arg">locale</span>=<span class="sig-default"><code class="variable-quote">'</code><code class="variable-string">de_DE</code><code class="variable-quote">'</code></span>)</span>
550
 
  </h3>
551
 
  </td><td align="right" valign="top"
552
 
    >&nbsp;
553
 
    </td>
554
 
  </tr></table>
555
 
  
556
 
  <p>Parse a time from a string.</p>
557
 
<p>This function uses the time format for the locale as a hint to determine
558
 
the order in which the time fields appear in the string.</p>
559
 
<pre class="py-doctest">
560
 
<span class="py-prompt">&gt;&gt;&gt; </span>parse_time(<span class="py-string">'15:30:00'</span>, locale=<span class="py-string">'en_US'</span>)
561
 
<span class="py-output">datetime.time(15, 30)</span></pre>
562
 
  <dl class="fields">
563
 
    <dt>Parameters:</dt>
564
 
    <dd><ul class="nomargin-top">
565
 
        <li><strong class="pname"><code>string</code></strong> - the string containing the time</li>
566
 
        <li><strong class="pname"><code>locale</code></strong> - a <a href="babel.core.Locale-class.html" class="link">Locale</a> object or a locale identifier</li>
567
 
    </ul></dd>
568
 
    <dt>Returns: time</dt>
569
 
        <dd>the parsed time</dd>
570
 
  </dl>
571
 
</td></tr></table>
572
 
</div>
573
 
<br />
574
 
<!-- ==================== NAVIGATION BAR ==================== -->
575
 
<table class="navbar" border="0" width="100%" cellpadding="0"
576
 
       bgcolor="#a0c0ff" cellspacing="0">
577
 
  <tr valign="middle">
578
 
  <!-- Home link -->
579
 
      <th>&nbsp;&nbsp;&nbsp;<a
580
 
        href="babel-module.html">Home</a>&nbsp;&nbsp;&nbsp;</th>
581
 
 
582
 
  <!-- Tree link -->
583
 
      <th>&nbsp;&nbsp;&nbsp;<a
584
 
        href="module-tree.html">Trees</a>&nbsp;&nbsp;&nbsp;</th>
585
 
 
586
 
  <!-- Index link -->
587
 
      <th>&nbsp;&nbsp;&nbsp;<a
588
 
        href="identifier-index.html">Indices</a>&nbsp;&nbsp;&nbsp;</th>
589
 
 
590
 
  <!-- Help link -->
591
 
      <th>&nbsp;&nbsp;&nbsp;<a
592
 
        href="help.html">Help</a>&nbsp;&nbsp;&nbsp;</th>
593
 
 
594
 
  <!-- Project homepage -->
595
 
      <th class="navbar" align="right" width="100%">
596
 
        <table border="0" cellpadding="0" cellspacing="0">
597
 
          <tr><th class="navbar" align="center"
598
 
            ><a class="navbar" target="_top" href="../index.html">Documentation Index</a></th>
599
 
          </tr></table></th>
600
 
  </tr>
601
 
</table>
602
 
<table border="0" cellpadding="0" cellspacing="0" width="100%%">
603
 
  <tr>
604
 
    <td align="left" class="footer">
605
 
    Generated by Epydoc 3.0.1 on Thu Mar 17 15:12:44 2011
606
 
    </td>
607
 
    <td align="right" class="footer">
608
 
      <a target="mainFrame" href="http://epydoc.sourceforge.net"
609
 
        >http://epydoc.sourceforge.net</a>
610
 
    </td>
611
 
  </tr>
612
 
</table>
613
 
 
614
 
<script type="text/javascript">
615
 
  <!--
616
 
  // Private objects are initially displayed (because if
617
 
  // javascript is turned off then we want them to be
618
 
  // visible); but by default, we want to hide them.  So hide
619
 
  // them unless we have a cookie that says to show them.
620
 
  checkCookie();
621
 
  // -->
622
 
</script>
623
 
</body>
624
 
</html>