babel/mirror: doc/dates.txt annotate

annotate doc/dates.txt @ 514:9eafc564d41a stable-0.9.x

merge r565 to 0.9 branch

author	fschwarz
date	Fri, 04 Mar 2011 22:55:15 +0000
parents	f9f6f740b595
children	0ca28858045e

rev	line source
2 20896f1e91c6 Forgot to check in the doc directory. cmlenz parents: diff changeset	1 .. -- mode: rst; encoding: utf-8 --
20896f1e91c6 Forgot to check in the doc directory. cmlenz parents: diff changeset	2
124 98dcabc99308 Split docs on date and number formatting. cmlenz parents: 98 diff changeset	3 ===============
98dcabc99308 Split docs on date and number formatting. cmlenz parents: 98 diff changeset	4 Date Formatting
98dcabc99308 Split docs on date and number formatting. cmlenz parents: 98 diff changeset	5 ===============
2 20896f1e91c6 Forgot to check in the doc directory. cmlenz parents: diff changeset	6
20896f1e91c6 Forgot to check in the doc directory. cmlenz parents: diff changeset	7
20896f1e91c6 Forgot to check in the doc directory. cmlenz parents: diff changeset	8 .. contents:: Contents
20896f1e91c6 Forgot to check in the doc directory. cmlenz parents: diff changeset	9 :depth: 2
20896f1e91c6 Forgot to check in the doc directory. cmlenz parents: diff changeset	10 .. sectnum::
20896f1e91c6 Forgot to check in the doc directory. cmlenz parents: diff changeset	11
20896f1e91c6 Forgot to check in the doc directory. cmlenz parents: diff changeset	12
18 990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	13 When working with date and time information in Python, you commonly use the
98 f5cfd37ec37e Add `--without-apidocs` switch to `build_doc` command for quicker doc-edit/review cycles. cmlenz parents: 40 diff changeset	14 classes ``date``, ``datetime`` and/or ``time`` from the `datetime`_ package.
18 990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	15 Babel provides functions for locale-specific formatting of those objects in its
40 0739bc8e7210 Syntax highlighting for the docs. cmlenz parents: 35 diff changeset	16 ``dates`` module:
0739bc8e7210 Syntax highlighting for the docs. cmlenz parents: 35 diff changeset	17
98 f5cfd37ec37e Add `--without-apidocs` switch to `build_doc` command for quicker doc-edit/review cycles. cmlenz parents: 40 diff changeset	18 .. _`datetime`: http://docs.python.org/lib/module-datetime.html
f5cfd37ec37e Add `--without-apidocs` switch to `build_doc` command for quicker doc-edit/review cycles. cmlenz parents: 40 diff changeset	19
40 0739bc8e7210 Syntax highlighting for the docs. cmlenz parents: 35 diff changeset	20 .. code-block:: pycon
18 990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	21
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	22 >>> from datetime import date, datetime, time
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	23 >>> from babel.dates import format_date, format_datetime, format_time
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	24
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	25 >>> d = date(2007, 4, 1)
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	26 >>> format_date(d, locale='en')
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	27 u'Apr 1, 2007'
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	28 >>> format_date(d, locale='de_DE')
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	29 u'01.04.2007'
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	30
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	31 As this example demonstrates, Babel will automatically choose a date format
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	32 that is appropriate for the requested locale.
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	33
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	34 The ``format_*()`` functions also accept an optional ``format`` argument, which
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	35 allows you to choose between one of four format variations:
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	36
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	37 * ``short``,
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	38 * ``medium`` (the default),
20 c4fc7b88206e Fix typo in doc. cmlenz parents: 18 diff changeset	39 * ``long``, and
c4fc7b88206e Fix typo in doc. cmlenz parents: 18 diff changeset	40 * ``full``.
18 990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	41
40 0739bc8e7210 Syntax highlighting for the docs. cmlenz parents: 35 diff changeset	42 For example:
0739bc8e7210 Syntax highlighting for the docs. cmlenz parents: 35 diff changeset	43
0739bc8e7210 Syntax highlighting for the docs. cmlenz parents: 35 diff changeset	44 .. code-block:: pycon
18 990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	45
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	46 >>> format_date(d, format='short', locale='en')
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	47 u'4/1/07'
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	48 >>> format_date(d, format='long', locale='en')
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	49 u'April 1, 2007'
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	50 >>> format_date(d, format='full', locale='en')
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	51 u'Sunday, April 1, 2007'
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	52
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	53
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	54 Pattern Syntax
124 98dcabc99308 Split docs on date and number formatting. cmlenz parents: 98 diff changeset	55 ==============
18 990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	56
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	57 While Babel makes it simple to use the appropriate date/time format for a given
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	58 locale, you can also force it to use custom patterns. Note that Babel uses
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	59 different patterns for specifying number and date formats compared to the
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	60 Python equivalents (such as ``time.strftime()``), which have mostly been
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	61 inherited from C and POSIX. The patterns used in Babel are based on the
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	62 `Locale Data Markup Language specification`_ (LDML), which defines them as
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	63 follows:
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	64
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	65 A date/time pattern is a string of characters, where specific strings of
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	66 characters are replaced with date and time data from a calendar when formatting
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	67 or used to generate data for a calendar when parsing. […]
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	68
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	69 Characters may be used multiple times. For example, if ``y`` is used for the
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	70 year, ``yy`` might produce "99", whereas ``yyyy`` produces "1999". For most
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	71 numerical fields, the number of characters specifies the field width. For
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	72 example, if ``h`` is the hour, ``h`` might produce "5", but ``hh`` produces
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	73 "05". For some characters, the count specifies whether an abbreviated or full
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	74 form should be used […]
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	75
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	76 Two single quotes represent a literal single quote, either inside or outside
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	77 single quotes. Text within single quotes is not interpreted in any way (except
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	78 for two adjacent single quotes).
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	79
40 0739bc8e7210 Syntax highlighting for the docs. cmlenz parents: 35 diff changeset	80 For example:
0739bc8e7210 Syntax highlighting for the docs. cmlenz parents: 35 diff changeset	81
0739bc8e7210 Syntax highlighting for the docs. cmlenz parents: 35 diff changeset	82 .. code-block:: pycon
18 990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	83
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	84 >>> d = date(2007, 4, 1)
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	85 >>> format_date(d, "EEE, MMM d, ''yy", locale='en')
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	86 u"Sun, Apr 1, '07"
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	87 >>> format_date(d, "EEEE, d.M.yyyy", locale='de')
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	88 u'Sonntag, 1.4.2007'
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	89
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	90 >>> t = time(15, 30)
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	91 >>> format_time(t, "hh 'o''clock' a", locale='en')
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	92 u"03 o'clock PM"
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	93 >>> format_time(t, 'H:mm a', locale='de')
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	94 u'15:30 nachm.'
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	95
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	96 >>> dt = datetime(2007, 4, 1, 15, 30)
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	97 >>> format_datetime(dt, "yyyyy.MMMM.dd GGG hh:mm a", locale='en')
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	98 u'02007.April.01 AD 03:30 PM'
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	99
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	100 The syntax for custom datetime format patterns is described in detail in the
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	101 the `Locale Data Markup Language specification`_. The following table is just a
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	102 relatively brief overview.
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	103
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	104 .. _`Locale Data Markup Language specification`: http://unicode.org/reports/tr35/#Date_Format_Patterns
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	105
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	106 Date Fields
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	107 -----------
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	108
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	109 +----------+--------+--------------------------------------------------------+
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	110 \| Field \| Symbol \| Description \|
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	111 +==========+========+========================================================+
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	112 \| Era \| ``G`` \| Replaced with the era string for the current date. One \|
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	113 \| \| \| to three letters for the abbreviated form, four \|
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	114 \| \| \| lettersfor the long form, five for the narrow form \|
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	115 +----------+--------+--------------------------------------------------------+
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	116 \| Year \| ``y`` \| Replaced by the year. Normally the length specifies \|
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	117 \| \| \| the padding, but for two letters it also specifies the \|
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	118 \| \| \| maximum length. \|
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	119 \| +--------+--------------------------------------------------------+
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	120 \| \| ``Y`` \| Same as ``y`` but uses the ISO year-week calendar. \|
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	121 \| +--------+--------------------------------------------------------+
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	122 \| \| ``u`` \| ?? \|
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	123 +----------+--------+--------------------------------------------------------+
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	124 \| Quarter \| ``Q`` \| Use one or two for the numerical quarter, three for \|
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	125 \| \| \| the abbreviation, or four for the full name. \|
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	126 \| +--------+--------------------------------------------------------+
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	127 \| \| ``q`` \| Use one or two for the numerical quarter, three for \|
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	128 \| \| \| the abbreviation, or four for the full name. \|
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	129 +----------+--------+--------------------------------------------------------+
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	130 \| Month \| ``M`` \| Use one or two for the numerical month, three for the \|
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	131 \| \| \| abbreviation, or four for the full name, or five for \|
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	132 \| \| \| the narrow name. \|
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	133 \| +--------+--------------------------------------------------------+
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	134 \| \| ``L`` \| Use one or two for the numerical month, three for the \|
990909fdf98b 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 5 for the \|
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	136 \| \| \| narrow name. \|
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	137 +----------+--------+--------------------------------------------------------+
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	138 \| Week \| ``w`` \| Week of year. \|
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	139 \| +--------+--------------------------------------------------------+
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	140 \| \| ``W`` \| Week of month. \|
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	141 +----------+--------+--------------------------------------------------------+
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	142 \| Day \| ``d`` \| Day of month. \|
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	143 \| +--------+--------------------------------------------------------+
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	144 \| \| ``D`` \| Day of year. \|
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	145 \| +--------+--------------------------------------------------------+
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	146 \| \| ``F`` \| Day of week in month. \|
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	147 \| +--------+--------------------------------------------------------+
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	148 \| \| ``g`` \| ?? \|
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	149 +----------+--------+--------------------------------------------------------+
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	150 \| Week day \| ``E`` \| Day of week. Use one through three letters for the \|
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	151 \| \| \| short day, or four for the full name, or five for the \|
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	152 \| \| \| narrow name. \|
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	153 \| +--------+--------------------------------------------------------+
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	154 \| \| ``e`` \| Local day of week. Same as E except adds a numeric \|
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	155 \| \| \| value that will depend on the local starting day of \|
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	156 \| \| \| the week, using one or two letters. \|
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	157 \| +--------+--------------------------------------------------------+
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	158 \| \| ``c`` \| ?? \|
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	159 +----------+--------+--------------------------------------------------------+
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	160
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	161 Time Fields
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	162 -----------
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	163
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	164 +----------+--------+--------------------------------------------------------+
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	165 \| Field \| Symbol \| Description \|
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	166 +==========+========+========================================================+
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	167 \| Period \| ``a`` \| AM or PM \|
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	168 +----------+--------+--------------------------------------------------------+
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	169 \| Hour \| ``h`` \| Hour [1-12]. \|
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	170 \| +--------+--------------------------------------------------------+
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	171 \| \| ``H`` \| Hour [0-23]. \|
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	172 \| +--------+--------------------------------------------------------+
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	173 \| \| ``K`` \| Hour [0-11]. \|
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	174 \| +--------+--------------------------------------------------------+
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	175 \| \| ``k`` \| Hour [1-24]. \|
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	176 +----------+--------+--------------------------------------------------------+
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	177 \| Minute \| ``m`` \| Use one or two for zero places padding. \|
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	178 +----------+--------+--------------------------------------------------------+
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	179 \| Second \| ``s`` \| Use one or two for zero places padding. \|
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	180 \| +--------+--------------------------------------------------------+
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	181 \| \| ``S`` \| Fractional second, rounds to the count of letters. \|
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	182 \| +--------+--------------------------------------------------------+
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	183 \| \| ``A`` \| Milliseconds in day. \|
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	184 +----------+--------+--------------------------------------------------------+
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	185 \| Timezone \| ``z`` \| Use one to three letters for the short timezone or \|
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	186 \| \| \| four for the full name. \|
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	187 \| +--------+--------------------------------------------------------+
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	188 \| \| ``Z`` \| Use one to three letters for RFC 822, four letters for \|
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	189 \| \| \| GMT format. \|
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	190 \| +--------+--------------------------------------------------------+
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	191 \| \| ``v`` \| Use one letter for short wall (generic) time, four for \|
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	192 \| \| \| long wall time. \|
233 da97a3138239 Upgraded to CLDR 1.5 and improved timezone formatting. cmlenz parents: 124 diff changeset	193 \| +--------+--------------------------------------------------------+
da97a3138239 Upgraded to CLDR 1.5 and improved timezone formatting. cmlenz parents: 124 diff changeset	194 \| \| ``V`` \| Same as ``z``, except that timezone abbreviations \|
da97a3138239 Upgraded to CLDR 1.5 and improved timezone formatting. cmlenz parents: 124 diff changeset	195 \| \| \| should be used regardless of whether they are in \|
da97a3138239 Upgraded to CLDR 1.5 and improved timezone formatting. cmlenz parents: 124 diff changeset	196 \| \| \| common use by the locale. \|
18 990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	197 +----------+--------+--------------------------------------------------------+
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	198
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	199
255 f9f6f740b595 Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	200 Time-zone Support
124 98dcabc99308 Split docs on date and number formatting. cmlenz parents: 98 diff changeset	201 =================
29 72bf45adb926 More work on timezones. cmlenz parents: 20 diff changeset	202
31 f3049ca45daa Raise error on unsupported locales. Closes #5. cmlenz parents: 29 diff changeset	203 Many of the verbose time formats include the time-zone, but time-zone
f3049ca45daa Raise error on unsupported locales. Closes #5. cmlenz parents: 29 diff changeset	204 information is not by default available for the Python ``datetime`` and
f3049ca45daa Raise error on unsupported locales. Closes #5. cmlenz parents: 29 diff changeset	205 ``time`` objects. The standard library includes only the abstract ``tzinfo``
f3049ca45daa Raise error on unsupported locales. Closes #5. cmlenz parents: 29 diff changeset	206 class, which you need appropriate implementations for to actually use in your
29 72bf45adb926 More work on timezones. cmlenz parents: 20 diff changeset	207 application. Babel includes a ``tzinfo`` implementation for UTC (Universal
31 f3049ca45daa Raise error on unsupported locales. Closes #5. cmlenz parents: 29 diff changeset	208 Time).
f3049ca45daa Raise error on unsupported locales. Closes #5. cmlenz parents: 29 diff changeset	209
f3049ca45daa Raise error on unsupported locales. Closes #5. cmlenz parents: 29 diff changeset	210 For real time-zone support, it is strongly recommended that you use the
29 72bf45adb926 More work on timezones. cmlenz parents: 20 diff changeset	211 third-party package `pytz`_, which includes the definitions of practically all
72bf45adb926 More work on timezones. cmlenz parents: 20 diff changeset	212 of the time-zones used on the world, as well as important functions for
40 0739bc8e7210 Syntax highlighting for the docs. cmlenz parents: 35 diff changeset	213 reliably converting from UTC to local time, and vice versa:
0739bc8e7210 Syntax highlighting for the docs. cmlenz parents: 35 diff changeset	214
0739bc8e7210 Syntax highlighting for the docs. cmlenz parents: 35 diff changeset	215 .. code-block:: pycon
29 72bf45adb926 More work on timezones. cmlenz parents: 20 diff changeset	216
72bf45adb926 More work on timezones. cmlenz parents: 20 diff changeset	217 >>> from datetime import time
34 464fbcefedde Extended time-zone support. cmlenz parents: 32 diff changeset	218 >>> from pytz import timezone, utc
464fbcefedde Extended time-zone support. cmlenz parents: 32 diff changeset	219 >>> dt = datetime(2007, 04, 01, 15, 30, tzinfo=utc)
464fbcefedde Extended time-zone support. cmlenz parents: 32 diff changeset	220 >>> eastern = timezone('US/Eastern')
464fbcefedde Extended time-zone support. cmlenz parents: 32 diff changeset	221 >>> format_datetime(dt, 'H:mm Z', tzinfo=eastern, locale='en_US')
464fbcefedde Extended time-zone support. cmlenz parents: 32 diff changeset	222 u'11:30 -0400'
29 72bf45adb926 More work on timezones. cmlenz parents: 20 diff changeset	223
72bf45adb926 More work on timezones. cmlenz parents: 20 diff changeset	224 The recommended approach to deal with different time-zones in a Python
72bf45adb926 More work on timezones. cmlenz parents: 20 diff changeset	225 application is to always use UTC internally, and only convert from/to the users
72bf45adb926 More work on timezones. cmlenz parents: 20 diff changeset	226 time-zone when accepting user input and displaying date/time data, respectively.
34 464fbcefedde Extended time-zone support. cmlenz parents: 32 diff changeset	227 You can use Babel together with ``pytz`` to apply a time-zone to any
464fbcefedde Extended time-zone support. cmlenz parents: 32 diff changeset	228 ``datetime`` or ``time`` object for display, leaving the original information
40 0739bc8e7210 Syntax highlighting for the docs. cmlenz parents: 35 diff changeset	229 unchanged:
0739bc8e7210 Syntax highlighting for the docs. cmlenz parents: 35 diff changeset	230
0739bc8e7210 Syntax highlighting for the docs. cmlenz parents: 35 diff changeset	231 .. code-block:: pycon
34 464fbcefedde Extended time-zone support. cmlenz parents: 32 diff changeset	232
464fbcefedde Extended time-zone support. cmlenz parents: 32 diff changeset	233 >>> british = timezone('Europe/London')
464fbcefedde Extended time-zone support. cmlenz parents: 32 diff changeset	234 >>> format_datetime(dt, 'H:mm zzzz', tzinfo=british, locale='en_US')
464fbcefedde Extended time-zone support. cmlenz parents: 32 diff changeset	235 u'16:30 British Summer Time'
29 72bf45adb926 More work on timezones. cmlenz parents: 20 diff changeset	236
35 0df10113d5c2 Add note on daylight savings time. cmlenz parents: 34 diff changeset	237 Here, the given UTC time is adjusted to the "Europe/London" time-zone, and
0df10113d5c2 Add note on daylight savings time. cmlenz parents: 34 diff changeset	238 daylight savings time is taken into account. Daylight savings time is also
0df10113d5c2 Add note on daylight savings time. cmlenz parents: 34 diff changeset	239 applied to ``format_time``, but because the actual date is unknown in that
0df10113d5c2 Add note on daylight savings time. cmlenz parents: 34 diff changeset	240 case, the current day is assumed to determine whether DST or standard time
0df10113d5c2 Add note on daylight savings time. cmlenz parents: 34 diff changeset	241 should be used.
0df10113d5c2 Add note on daylight savings time. cmlenz parents: 34 diff changeset	242
29 72bf45adb926 More work on timezones. cmlenz parents: 20 diff changeset	243 .. _`pytz`: http://pytz.sourceforge.net/
72bf45adb926 More work on timezones. cmlenz parents: 20 diff changeset	244
72bf45adb926 More work on timezones. cmlenz parents: 20 diff changeset	245
255 f9f6f740b595 Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	246 Localized Time-zone Names
f9f6f740b595 Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	247 -------------------------
f9f6f740b595 Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	248
f9f6f740b595 Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	249 While the ``Locale`` class provides access to various locale display names
f9f6f740b595 Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	250 related to time-zones, the process of building a localized name of a time-zone
f9f6f740b595 Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	251 is actually quite complicated. Babel implements it in separately usable
f9f6f740b595 Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	252 functions in the ``babel.dates`` module, most importantly the
f9f6f740b595 Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	253 ``get_timezone_name`` function:
f9f6f740b595 Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	254
f9f6f740b595 Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	255 .. code-block:: pycon
f9f6f740b595 Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	256
f9f6f740b595 Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	257 >>> from pytz import timezone
f9f6f740b595 Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	258 >>> from babel import Locale
f9f6f740b595 Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	259 >>> from babel.dates import get_timezone_name
f9f6f740b595 Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	260
f9f6f740b595 Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	261 >>> tz = timezone('Europe/Berlin')
f9f6f740b595 Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	262 >>> get_timezone_name(tz, locale=Locale.parse('pt_PT'))
f9f6f740b595 Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	263 u'Hor\xe1rio Alemanha'
f9f6f740b595 Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	264
f9f6f740b595 Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	265 You can pass the function either a ``datetime.tzinfo`` object, or a
f9f6f740b595 Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	266 ``datetime.date`` or ``datetime.datetime`` object. If you pass an actual date,
f9f6f740b595 Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	267 the function will be able to take daylight savings time into account. If you
f9f6f740b595 Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	268 pass just the time-zone, Babel does not know whether daylight savings time is
f9f6f740b595 Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	269 in effect, so it uses a generic representation, which is useful for example to
f9f6f740b595 Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	270 display a list of time-zones to the user.
f9f6f740b595 Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	271
f9f6f740b595 Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	272 .. code-block:: pycon
f9f6f740b595 Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	273
f9f6f740b595 Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	274 >>> from datetime import datetime
f9f6f740b595 Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	275
f9f6f740b595 Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	276 >>> dt = tz.localize(datetime(2007, 8, 15))
f9f6f740b595 Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	277 >>> get_timezone_name(dt, locale=Locale.parse('de_DE'))
f9f6f740b595 Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	278 u'Mitteleurop\xe4ische Sommerzeit'
f9f6f740b595 Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	279 >>> get_timezone_name(tz, locale=Locale.parse('de_DE'))
f9f6f740b595 Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	280 u'Deutschland'
f9f6f740b595 Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	281
f9f6f740b595 Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	282
18 990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	283 Parsing Dates
124 98dcabc99308 Split docs on date and number formatting. cmlenz parents: 98 diff changeset	284 =============
18 990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	285
40 0739bc8e7210 Syntax highlighting for the docs. cmlenz parents: 35 diff changeset	286 Babel can also parse date and time information in a locale-sensitive manner:
0739bc8e7210 Syntax highlighting for the docs. cmlenz parents: 35 diff changeset	287
0739bc8e7210 Syntax highlighting for the docs. cmlenz parents: 35 diff changeset	288 .. code-block:: pycon
18 990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	289
990909fdf98b Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	290 >>> from babel.dates import parse_date, parse_datetime, parse_time
255 f9f6f740b595 Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	291
f9f6f740b595 Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	292 .. note:: Date/time parsing is not properly implemented yet

Mercurial > babel > mirror

annotate doc/dates.txt @ 514:9eafc564d41a stable-0.9.x