X7ROOT File Manager
Current Path:
/usr/share/doc/python-babel-0.9.6/doc
usr
/
share
/
doc
/
python-babel-0.9.6
/
doc
/
📁
..
📁
api
📄
cmdline.html
(8.19 KB)
📄
cmdline.txt
(6.57 KB)
📁
common
📄
dates.html
(16.4 KB)
📄
dates.txt
(13.66 KB)
📄
display.html
(4.33 KB)
📄
display.txt
(2.36 KB)
📄
index.html
(1.88 KB)
📄
index.txt
(882 B)
📄
intro.html
(3.81 KB)
📄
intro.txt
(2.44 KB)
📄
logo.pdf
(43.93 KB)
📄
logo.png
(15.12 KB)
📄
logo_small.png
(5.97 KB)
📄
messages.html
(17.44 KB)
📄
messages.txt
(11.7 KB)
📄
numbers.html
(6.05 KB)
📄
numbers.txt
(4.66 KB)
📄
setup.html
(18.86 KB)
📄
setup.txt
(14.84 KB)
📄
support.html
(3.17 KB)
📄
support.txt
(1.73 KB)
Editing: dates.html
<!DOCTYPE html> <html lang="en"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> <meta name="generator" content="Docutils 0.7: http://docutils.sourceforge.net/"> <title>Babel: Date Formatting</title> <link rel="stylesheet" href="common/style/edgewall.css" type="text/css"> </head> <body> <div class="document" id="date-formatting"> <div id="navigation"> <span class="projinfo">Babel 0.9.6</span> <a href="index.html">Documentation Index</a> </div> <h1 class="title">Date Formatting</h1> <div class="contents topic" id="contents"> <p class="topic-title first">Contents</p> <ul class="auto-toc simple"> <li><a class="reference internal" href="#pattern-syntax" id="id1">1 Pattern Syntax</a><ul class="auto-toc"> <li><a class="reference internal" href="#date-fields" id="id2">1.1 Date Fields</a></li> <li><a class="reference internal" href="#time-fields" id="id3">1.2 Time Fields</a></li> </ul> </li> <li><a class="reference internal" href="#time-zone-support" id="id4">2 Time-zone Support</a><ul class="auto-toc"> <li><a class="reference internal" href="#localized-time-zone-names" id="id5">2.1 Localized Time-zone Names</a></li> </ul> </li> <li><a class="reference internal" href="#parsing-dates" id="id6">3 Parsing Dates</a></li> </ul> </div> <p>When working with date and time information in Python, you commonly use the classes <tt class="docutils literal">date</tt>, <tt class="docutils literal">datetime</tt> and/or <tt class="docutils literal">time</tt> from the <a class="reference external" href="http://docs.python.org/lib/module-datetime.html">datetime</a> package. Babel provides functions for locale-specific formatting of those objects in its <tt class="docutils literal">dates</tt> module:</p> <div class="system-message"> <p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">doc/dates.txt</tt>, line 20)</p> <p>Unknown directive type "code-block".</p> <pre class="literal-block"> .. code-block:: pycon >>> from datetime import date, datetime, time >>> from babel.dates import format_date, format_datetime, format_time >>> d = date(2007, 4, 1) >>> format_date(d, locale='en') u'Apr 1, 2007' >>> format_date(d, locale='de_DE') u'01.04.2007' </pre> </div> <p>As this example demonstrates, Babel will automatically choose a date format that is appropriate for the requested locale.</p> <p>The <tt class="docutils literal"><span class="pre">format_*()</span></tt> functions also accept an optional <tt class="docutils literal">format</tt> argument, which allows you to choose between one of four format variations:</p> <blockquote> <ul class="simple"> <li><tt class="docutils literal">short</tt>,</li> <li><tt class="docutils literal">medium</tt> (the default),</li> <li><tt class="docutils literal">long</tt>, and</li> <li><tt class="docutils literal">full</tt>.</li> </ul> </blockquote> <p>For example:</p> <div class="system-message"> <p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">doc/dates.txt</tt>, line 44)</p> <p>Unknown directive type "code-block".</p> <pre class="literal-block"> .. code-block:: pycon >>> format_date(d, format='short', locale='en') u'4/1/07' >>> format_date(d, format='long', locale='en') u'April 1, 2007' >>> format_date(d, format='full', locale='en') u'Sunday, April 1, 2007' </pre> </div> <div class="section" id="pattern-syntax"> <h1>1 Pattern Syntax</h1> <p>While Babel makes it simple to use the appropriate date/time format for a given locale, you can also force it to use custom patterns. Note that Babel uses different patterns for specifying number and date formats compared to the Python equivalents (such as <tt class="docutils literal">time.strftime()</tt>), which have mostly been inherited from C and POSIX. The patterns used in Babel are based on the <a class="reference external" href="http://unicode.org/reports/tr35/#Date_Format_Patterns">Locale Data Markup Language specification</a> (LDML), which defines them as follows:</p> <blockquote> <p>A date/time pattern is a string of characters, where specific strings of characters are replaced with date and time data from a calendar when formatting or used to generate data for a calendar when parsing. […]</p> <p>Characters may be used multiple times. For example, if <tt class="docutils literal">y</tt> is used for the year, <tt class="docutils literal">yy</tt> might produce "99", whereas <tt class="docutils literal">yyyy</tt> produces "1999". For most numerical fields, the number of characters specifies the field width. For example, if <tt class="docutils literal">h</tt> is the hour, <tt class="docutils literal">h</tt> might produce "5", but <tt class="docutils literal">hh</tt> produces "05". For some characters, the count specifies whether an abbreviated or full form should be used […]</p> <p>Two single quotes represent a literal single quote, either inside or outside single quotes. Text within single quotes is not interpreted in any way (except for two adjacent single quotes).</p> </blockquote> <p>For example:</p> <div class="system-message"> <p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">doc/dates.txt</tt>, line 82)</p> <p>Unknown directive type "code-block".</p> <pre class="literal-block"> .. code-block:: pycon >>> d = date(2007, 4, 1) >>> format_date(d, "EEE, MMM d, ''yy", locale='en') u"Sun, Apr 1, '07" >>> format_date(d, "EEEE, d.M.yyyy", locale='de') u'Sonntag, 1.4.2007' >>> t = time(15, 30) >>> format_time(t, "hh 'o''clock' a", locale='en') u"03 o'clock PM" >>> format_time(t, 'H:mm a', locale='de') u'15:30 nachm.' >>> dt = datetime(2007, 4, 1, 15, 30) >>> format_datetime(dt, "yyyyy.MMMM.dd GGG hh:mm a", locale='en') u'02007.April.01 AD 03:30 PM' </pre> </div> <p>The syntax for custom datetime format patterns is described in detail in the the <a class="reference external" href="http://unicode.org/reports/tr35/#Date_Format_Patterns">Locale Data Markup Language specification</a>. The following table is just a relatively brief overview.</p> <blockquote> </blockquote> <div class="section" id="date-fields"> <h2>1.1 Date Fields</h2> <blockquote> <table border="1" class="docutils"> <colgroup> <col width="14%"> <col width="11%"> <col width="76%"> </colgroup> <thead valign="bottom"> <tr><th class="head">Field</th> <th class="head">Symbol</th> <th class="head">Description</th> </tr> </thead> <tbody valign="top"> <tr><td>Era</td> <td><tt class="docutils literal">G</tt></td> <td>Replaced with the era string for the current date. One to three letters for the abbreviated form, four lettersfor the long form, five for the narrow form</td> </tr> <tr><td rowspan="3">Year</td> <td><tt class="docutils literal">y</tt></td> <td>Replaced by the year. Normally the length specifies the padding, but for two letters it also specifies the maximum length.</td> </tr> <tr><td><tt class="docutils literal">Y</tt></td> <td>Same as <tt class="docutils literal">y</tt> but uses the ISO year-week calendar.</td> </tr> <tr><td><tt class="docutils literal">u</tt></td> <td>??</td> </tr> <tr><td rowspan="2">Quarter</td> <td><tt class="docutils literal">Q</tt></td> <td>Use one or two for the numerical quarter, three for the abbreviation, or four for the full name.</td> </tr> <tr><td><tt class="docutils literal">q</tt></td> <td>Use one or two for the numerical quarter, three for the abbreviation, or four for the full name.</td> </tr> <tr><td rowspan="2">Month</td> <td><tt class="docutils literal">M</tt></td> <td>Use one or two for the numerical month, three for the abbreviation, or four for the full name, or five for the narrow name.</td> </tr> <tr><td><tt class="docutils literal">L</tt></td> <td>Use one or two for the numerical month, three for the abbreviation, or four for the full name, or 5 for the narrow name.</td> </tr> <tr><td rowspan="2">Week</td> <td><tt class="docutils literal">w</tt></td> <td>Week of year.</td> </tr> <tr><td><tt class="docutils literal">W</tt></td> <td>Week of month.</td> </tr> <tr><td rowspan="4">Day</td> <td><tt class="docutils literal">d</tt></td> <td>Day of month.</td> </tr> <tr><td><tt class="docutils literal">D</tt></td> <td>Day of year.</td> </tr> <tr><td><tt class="docutils literal">F</tt></td> <td>Day of week in month.</td> </tr> <tr><td><tt class="docutils literal">g</tt></td> <td>??</td> </tr> <tr><td rowspan="3">Week day</td> <td><tt class="docutils literal">E</tt></td> <td>Day of week. Use one through three letters for the short day, or four for the full name, or five for the narrow name.</td> </tr> <tr><td><tt class="docutils literal">e</tt></td> <td>Local day of week. Same as E except adds a numeric value that will depend on the local starting day of the week, using one or two letters.</td> </tr> <tr><td><tt class="docutils literal">c</tt></td> <td>??</td> </tr> </tbody> </table> </blockquote> </div> <div class="section" id="time-fields"> <h2>1.2 Time Fields</h2> <blockquote> <table border="1" class="docutils"> <colgroup> <col width="14%"> <col width="11%"> <col width="76%"> </colgroup> <thead valign="bottom"> <tr><th class="head">Field</th> <th class="head">Symbol</th> <th class="head">Description</th> </tr> </thead> <tbody valign="top"> <tr><td>Period</td> <td><tt class="docutils literal">a</tt></td> <td>AM or PM</td> </tr> <tr><td rowspan="4">Hour</td> <td><tt class="docutils literal">h</tt></td> <td>Hour [1-12].</td> </tr> <tr><td><tt class="docutils literal">H</tt></td> <td>Hour [0-23].</td> </tr> <tr><td><tt class="docutils literal">K</tt></td> <td>Hour [0-11].</td> </tr> <tr><td><tt class="docutils literal">k</tt></td> <td>Hour [1-24].</td> </tr> <tr><td>Minute</td> <td><tt class="docutils literal">m</tt></td> <td>Use one or two for zero places padding.</td> </tr> <tr><td rowspan="3">Second</td> <td><tt class="docutils literal">s</tt></td> <td>Use one or two for zero places padding.</td> </tr> <tr><td><tt class="docutils literal">S</tt></td> <td>Fractional second, rounds to the count of letters.</td> </tr> <tr><td><tt class="docutils literal">A</tt></td> <td>Milliseconds in day.</td> </tr> <tr><td rowspan="4">Timezone</td> <td><tt class="docutils literal">z</tt></td> <td>Use one to three letters for the short timezone or four for the full name.</td> </tr> <tr><td><tt class="docutils literal">Z</tt></td> <td>Use one to three letters for RFC 822, four letters for GMT format.</td> </tr> <tr><td><tt class="docutils literal">v</tt></td> <td>Use one letter for short wall (generic) time, four for long wall time.</td> </tr> <tr><td><tt class="docutils literal">V</tt></td> <td>Same as <tt class="docutils literal">z</tt>, except that timezone abbreviations should be used regardless of whether they are in common use by the locale.</td> </tr> </tbody> </table> </blockquote> </div> </div> <div class="section" id="time-zone-support"> <h1>2 Time-zone Support</h1> <p>Many of the verbose time formats include the time-zone, but time-zone information is not by default available for the Python <tt class="docutils literal">datetime</tt> and <tt class="docutils literal">time</tt> objects. The standard library includes only the abstract <tt class="docutils literal">tzinfo</tt> class, which you need appropriate implementations for to actually use in your application. Babel includes a <tt class="docutils literal">tzinfo</tt> implementation for UTC (Universal Time).</p> <p>For real time-zone support, it is strongly recommended that you use the third-party package <a class="reference external" href="http://pytz.sourceforge.net/">pytz</a>, which includes the definitions of practically all of the time-zones used on the world, as well as important functions for reliably converting from UTC to local time, and vice versa:</p> <div class="system-message"> <p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">doc/dates.txt</tt>, line 215)</p> <p>Unknown directive type "code-block".</p> <pre class="literal-block"> .. code-block:: pycon >>> from datetime import time >>> from pytz import timezone, utc >>> dt = datetime(2007, 04, 01, 15, 30, tzinfo=utc) >>> eastern = timezone('US/Eastern') >>> format_datetime(dt, 'H:mm Z', tzinfo=eastern, locale='en_US') u'11:30 -0400' </pre> </div> <p>The recommended approach to deal with different time-zones in a Python application is to always use UTC internally, and only convert from/to the users time-zone when accepting user input and displaying date/time data, respectively. You can use Babel together with <tt class="docutils literal">pytz</tt> to apply a time-zone to any <tt class="docutils literal">datetime</tt> or <tt class="docutils literal">time</tt> object for display, leaving the original information unchanged:</p> <div class="system-message"> <p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">doc/dates.txt</tt>, line 231)</p> <p>Unknown directive type "code-block".</p> <pre class="literal-block"> .. code-block:: pycon >>> british = timezone('Europe/London') >>> format_datetime(dt, 'H:mm zzzz', tzinfo=british, locale='en_US') u'16:30 British Summer Time' </pre> </div> <p>Here, the given UTC time is adjusted to the "Europe/London" time-zone, and daylight savings time is taken into account. Daylight savings time is also applied to <tt class="docutils literal">format_time</tt>, but because the actual date is unknown in that case, the current day is assumed to determine whether DST or standard time should be used.</p> <blockquote> </blockquote> <div class="section" id="localized-time-zone-names"> <h2>2.1 Localized Time-zone Names</h2> <p>While the <tt class="docutils literal">Locale</tt> class provides access to various locale display names related to time-zones, the process of building a localized name of a time-zone is actually quite complicated. Babel implements it in separately usable functions in the <tt class="docutils literal">babel.dates</tt> module, most importantly the <tt class="docutils literal">get_timezone_name</tt> function:</p> <div class="system-message"> <p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">doc/dates.txt</tt>, line 255)</p> <p>Unknown directive type "code-block".</p> <pre class="literal-block"> .. code-block:: pycon >>> from pytz import timezone >>> from babel import Locale >>> from babel.dates import get_timezone_name >>> tz = timezone('Europe/Berlin') >>> get_timezone_name(tz, locale=Locale.parse('pt_PT')) u'Hor\xe1rio Alemanha' </pre> </div> <p>You can pass the function either a <tt class="docutils literal">datetime.tzinfo</tt> object, or a <tt class="docutils literal">datetime.date</tt> or <tt class="docutils literal">datetime.datetime</tt> object. If you pass an actual date, the function will be able to take daylight savings time into account. If you pass just the time-zone, Babel does not know whether daylight savings time is in effect, so it uses a generic representation, which is useful for example to display a list of time-zones to the user.</p> <div class="system-message"> <p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">doc/dates.txt</tt>, line 272)</p> <p>Unknown directive type "code-block".</p> <pre class="literal-block"> .. code-block:: pycon >>> from datetime import datetime >>> dt = tz.localize(datetime(2007, 8, 15)) >>> get_timezone_name(dt, locale=Locale.parse('de_DE')) u'Mitteleurop\xe4ische Sommerzeit' >>> get_timezone_name(tz, locale=Locale.parse('de_DE')) u'Deutschland' </pre> </div> </div> </div> <div class="section" id="parsing-dates"> <h1>3 Parsing Dates</h1> <p>Babel can also parse date and time information in a locale-sensitive manner:</p> <div class="system-message"> <p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">doc/dates.txt</tt>, line 288)</p> <p>Unknown directive type "code-block".</p> <pre class="literal-block"> .. code-block:: pycon >>> from babel.dates import parse_date, parse_datetime, parse_time </pre> </div> <div class="note"> <p class="first admonition-title">Note</p> <p class="last">Date/time parsing is not properly implemented yet</p> </div> </div> <div id="footer"> Visit the Babel open source project at <a href="http://babel.edgewall.org/">http://babel.edgewall.org/</a> </div> </div> </body> </html>
Upload File
Create Folder
