babel/old/babel-test: doc/dates.txt annotate

annotate doc/dates.txt @ 507:b29ff192b610 stable-0.9.x

Python 2.3 compatibility: backporting r456 and r457 to 0.9 branch (see #233)

author	fschwarz
date	Fri, 04 Mar 2011 13:14:03 +0000
parents	00b83943f79e
children	0f7f4226f765

rev	line source
2 b2492365f186 Forgot to check in the doc directory. cmlenz parents: diff changeset	1 .. -- mode: rst; encoding: utf-8 --
b2492365f186 Forgot to check in the doc directory. cmlenz parents: diff changeset	2
124 bf1bcdf19111 Split docs on date and number formatting. cmlenz parents: 98 diff changeset	3 ===============
bf1bcdf19111 Split docs on date and number formatting. cmlenz parents: 98 diff changeset	4 Date Formatting
bf1bcdf19111 Split docs on date and number formatting. cmlenz parents: 98 diff changeset	5 ===============
2 b2492365f186 Forgot to check in the doc directory. cmlenz parents: diff changeset	6
b2492365f186 Forgot to check in the doc directory. cmlenz parents: diff changeset	7
b2492365f186 Forgot to check in the doc directory. cmlenz parents: diff changeset	8 .. contents:: Contents
b2492365f186 Forgot to check in the doc directory. cmlenz parents: diff changeset	9 :depth: 2
b2492365f186 Forgot to check in the doc directory. cmlenz parents: diff changeset	10 .. sectnum::
b2492365f186 Forgot to check in the doc directory. cmlenz parents: diff changeset	11
b2492365f186 Forgot to check in the doc directory. cmlenz parents: diff changeset	12
18 77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	13 When working with date and time information in Python, you commonly use the
98 a696e249467a Add `--without-apidocs` switch to `build_doc` command for quicker doc-edit/review cycles. cmlenz parents: 40 diff changeset	14 classes ``date``, ``datetime`` and/or ``time`` from the `datetime`_ package.
18 77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	15 Babel provides functions for locale-specific formatting of those objects in its
40 4525549aa6cc Syntax highlighting for the docs. cmlenz parents: 35 diff changeset	16 ``dates`` module:
4525549aa6cc Syntax highlighting for the docs. cmlenz parents: 35 diff changeset	17
98 a696e249467a 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
a696e249467a Add `--without-apidocs` switch to `build_doc` command for quicker doc-edit/review cycles. cmlenz parents: 40 diff changeset	19
40 4525549aa6cc Syntax highlighting for the docs. cmlenz parents: 35 diff changeset	20 .. code-block:: pycon
18 77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	21
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	22 >>> from datetime import date, datetime, time
77a68f88f6bc 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
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	24
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	25 >>> d = date(2007, 4, 1)
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	26 >>> format_date(d, locale='en')
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	27 u'Apr 1, 2007'
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	28 >>> format_date(d, locale='de_DE')
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	29 u'01.04.2007'
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	30
77a68f88f6bc 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
77a68f88f6bc 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.
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	33
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	34 The ``format_*()`` functions also accept an optional ``format`` argument, which
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	35 allows you to choose between one of four format variations:
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	36
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	37 * ``short``,
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	38 * ``medium`` (the default),
20 2fdc2b500347 Fix typo in doc. cmlenz parents: 18 diff changeset	39 * ``long``, and
2fdc2b500347 Fix typo in doc. cmlenz parents: 18 diff changeset	40 * ``full``.
18 77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	41
40 4525549aa6cc Syntax highlighting for the docs. cmlenz parents: 35 diff changeset	42 For example:
4525549aa6cc Syntax highlighting for the docs. cmlenz parents: 35 diff changeset	43
4525549aa6cc Syntax highlighting for the docs. cmlenz parents: 35 diff changeset	44 .. code-block:: pycon
18 77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	45
77a68f88f6bc 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')
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	47 u'4/1/07'
77a68f88f6bc 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')
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	49 u'April 1, 2007'
77a68f88f6bc 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')
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	51 u'Sunday, April 1, 2007'
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	52
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	53
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	54 Pattern Syntax
124 bf1bcdf19111 Split docs on date and number formatting. cmlenz parents: 98 diff changeset	55 ==============
18 77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	56
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	57 While Babel makes it simple to use the appropriate date/time format for a given
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	58 locale, you can also force it to use custom patterns. Note that Babel uses
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	59 different patterns for specifying number and date formats compared to the
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	60 Python equivalents (such as ``time.strftime()``), which have mostly been
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	61 inherited from C and POSIX. The patterns used in Babel are based on the
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	62 `Locale Data Markup Language specification`_ (LDML), which defines them as
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	63 follows:
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	64
77a68f88f6bc 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
77a68f88f6bc 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
77a68f88f6bc 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. […]
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	68
77a68f88f6bc 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
77a68f88f6bc 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
77a68f88f6bc 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
77a68f88f6bc 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
77a68f88f6bc 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
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	74 form should be used […]
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	75
77a68f88f6bc 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
77a68f88f6bc 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
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	78 for two adjacent single quotes).
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	79
40 4525549aa6cc Syntax highlighting for the docs. cmlenz parents: 35 diff changeset	80 For example:
4525549aa6cc Syntax highlighting for the docs. cmlenz parents: 35 diff changeset	81
4525549aa6cc Syntax highlighting for the docs. cmlenz parents: 35 diff changeset	82 .. code-block:: pycon
18 77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	83
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	84 >>> d = date(2007, 4, 1)
77a68f88f6bc 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')
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	86 u"Sun, Apr 1, '07"
77a68f88f6bc 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')
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	88 u'Sonntag, 1.4.2007'
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	89
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	90 >>> t = time(15, 30)
77a68f88f6bc 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')
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	92 u"03 o'clock PM"
77a68f88f6bc 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')
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	94 u'15:30 nachm.'
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	95
77a68f88f6bc 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)
77a68f88f6bc 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')
77a68f88f6bc 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'
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	99
77a68f88f6bc 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
77a68f88f6bc 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
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	102 relatively brief overview.
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	103
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	104 .. _`Locale Data Markup Language specification`: http://unicode.org/reports/tr35/#Date_Format_Patterns
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	105
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	106 Date Fields
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	107 -----------
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	108
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	109 +----------+--------+--------------------------------------------------------+
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	110 \| Field \| Symbol \| Description \|
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	111 +==========+========+========================================================+
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	112 \| Era \| ``G`` \| Replaced with the era string for the current date. One \|
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	113 \| \| \| to three letters for the abbreviated form, four \|
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	114 \| \| \| lettersfor the long form, five for the narrow form \|
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	115 +----------+--------+--------------------------------------------------------+
77a68f88f6bc 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 \|
77a68f88f6bc 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 \|
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	118 \| \| \| maximum length. \|
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	119 \| +--------+--------------------------------------------------------+
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	120 \| \| ``Y`` \| Same as ``y`` but uses the ISO year-week calendar. \|
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	121 \| +--------+--------------------------------------------------------+
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	122 \| \| ``u`` \| ?? \|
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	123 +----------+--------+--------------------------------------------------------+
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	124 \| Quarter \| ``Q`` \| Use one or two for the numerical quarter, three for \|
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	125 \| \| \| the abbreviation, or four for the full name. \|
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	126 \| +--------+--------------------------------------------------------+
77a68f88f6bc 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 \|
77a68f88f6bc 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. \|
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	129 +----------+--------+--------------------------------------------------------+
77a68f88f6bc 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 \|
77a68f88f6bc 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 \|
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	132 \| \| \| the narrow name. \|
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	133 \| +--------+--------------------------------------------------------+
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	134 \| \| ``L`` \| Use one or two for the numerical month, three for the \|
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	135 \| \| \| abbreviation, or four for the full name, or 5 for the \|
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	136 \| \| \| narrow name. \|
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	137 +----------+--------+--------------------------------------------------------+
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	138 \| Week \| ``w`` \| Week of year. \|
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	139 \| +--------+--------------------------------------------------------+
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	140 \| \| ``W`` \| Week of month. \|
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	141 +----------+--------+--------------------------------------------------------+
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	142 \| Day \| ``d`` \| Day of month. \|
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	143 \| +--------+--------------------------------------------------------+
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	144 \| \| ``D`` \| Day of year. \|
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	145 \| +--------+--------------------------------------------------------+
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	146 \| \| ``F`` \| Day of week in month. \|
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	147 \| +--------+--------------------------------------------------------+
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	148 \| \| ``g`` \| ?? \|
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	149 +----------+--------+--------------------------------------------------------+
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	150 \| Week day \| ``E`` \| Day of week. Use one through three letters for the \|
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	151 \| \| \| short day, or four for the full name, or five for the \|
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	152 \| \| \| narrow name. \|
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	153 \| +--------+--------------------------------------------------------+
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	154 \| \| ``e`` \| Local day of week. Same as E except adds a numeric \|
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	155 \| \| \| value that will depend on the local starting day of \|
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	156 \| \| \| the week, using one or two letters. \|
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	157 \| +--------+--------------------------------------------------------+
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	158 \| \| ``c`` \| ?? \|
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	159 +----------+--------+--------------------------------------------------------+
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	160
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	161 Time Fields
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	162 -----------
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	163
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	164 +----------+--------+--------------------------------------------------------+
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	165 \| Field \| Symbol \| Description \|
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	166 +==========+========+========================================================+
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	167 \| Period \| ``a`` \| AM or PM \|
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	168 +----------+--------+--------------------------------------------------------+
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	169 \| Hour \| ``h`` \| Hour [1-12]. \|
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	170 \| +--------+--------------------------------------------------------+
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	171 \| \| ``H`` \| Hour [0-23]. \|
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	172 \| +--------+--------------------------------------------------------+
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	173 \| \| ``K`` \| Hour [0-11]. \|
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	174 \| +--------+--------------------------------------------------------+
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	175 \| \| ``k`` \| Hour [1-24]. \|
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	176 +----------+--------+--------------------------------------------------------+
77a68f88f6bc 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. \|
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	178 +----------+--------+--------------------------------------------------------+
77a68f88f6bc 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. \|
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	180 \| +--------+--------------------------------------------------------+
77a68f88f6bc 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. \|
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	182 \| +--------+--------------------------------------------------------+
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	183 \| \| ``A`` \| Milliseconds in day. \|
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	184 +----------+--------+--------------------------------------------------------+
77a68f88f6bc 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 \|
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	186 \| \| \| four for the full name. \|
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	187 \| +--------+--------------------------------------------------------+
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	188 \| \| ``Z`` \| Use one to three letters for RFC 822, four letters for \|
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	189 \| \| \| GMT format. \|
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	190 \| +--------+--------------------------------------------------------+
77a68f88f6bc 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 \|
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	192 \| \| \| long wall time. \|
233 bc22f5aef216 Upgraded to CLDR 1.5 and improved timezone formatting. cmlenz parents: 124 diff changeset	193 \| +--------+--------------------------------------------------------+
bc22f5aef216 Upgraded to CLDR 1.5 and improved timezone formatting. cmlenz parents: 124 diff changeset	194 \| \| ``V`` \| Same as ``z``, except that timezone abbreviations \|
bc22f5aef216 Upgraded to CLDR 1.5 and improved timezone formatting. cmlenz parents: 124 diff changeset	195 \| \| \| should be used regardless of whether they are in \|
bc22f5aef216 Upgraded to CLDR 1.5 and improved timezone formatting. cmlenz parents: 124 diff changeset	196 \| \| \| common use by the locale. \|
18 77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	197 +----------+--------+--------------------------------------------------------+
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	198
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	199
255 00b83943f79e Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	200 Time-zone Support
124 bf1bcdf19111 Split docs on date and number formatting. cmlenz parents: 98 diff changeset	201 =================
29 da1c9610e751 More work on timezones. cmlenz parents: 20 diff changeset	202
31 b6ff3e4b43e5 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
b6ff3e4b43e5 Raise error on unsupported locales. Closes #5. cmlenz parents: 29 diff changeset	204 information is not by default available for the Python ``datetime`` and
b6ff3e4b43e5 Raise error on unsupported locales. Closes #5. cmlenz parents: 29 diff changeset	205 ``time`` objects. The standard library includes only the abstract ``tzinfo``
b6ff3e4b43e5 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 da1c9610e751 More work on timezones. cmlenz parents: 20 diff changeset	207 application. Babel includes a ``tzinfo`` implementation for UTC (Universal
31 b6ff3e4b43e5 Raise error on unsupported locales. Closes #5. cmlenz parents: 29 diff changeset	208 Time).
b6ff3e4b43e5 Raise error on unsupported locales. Closes #5. cmlenz parents: 29 diff changeset	209
b6ff3e4b43e5 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 da1c9610e751 More work on timezones. cmlenz parents: 20 diff changeset	211 third-party package `pytz`_, which includes the definitions of practically all
da1c9610e751 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 4525549aa6cc Syntax highlighting for the docs. cmlenz parents: 35 diff changeset	213 reliably converting from UTC to local time, and vice versa:
4525549aa6cc Syntax highlighting for the docs. cmlenz parents: 35 diff changeset	214
4525549aa6cc Syntax highlighting for the docs. cmlenz parents: 35 diff changeset	215 .. code-block:: pycon
29 da1c9610e751 More work on timezones. cmlenz parents: 20 diff changeset	216
da1c9610e751 More work on timezones. cmlenz parents: 20 diff changeset	217 >>> from datetime import time
34 3666f3d3df15 Extended time-zone support. cmlenz parents: 32 diff changeset	218 >>> from pytz import timezone, utc
3666f3d3df15 Extended time-zone support. cmlenz parents: 32 diff changeset	219 >>> dt = datetime(2007, 04, 01, 15, 30, tzinfo=utc)
3666f3d3df15 Extended time-zone support. cmlenz parents: 32 diff changeset	220 >>> eastern = timezone('US/Eastern')
3666f3d3df15 Extended time-zone support. cmlenz parents: 32 diff changeset	221 >>> format_datetime(dt, 'H:mm Z', tzinfo=eastern, locale='en_US')
3666f3d3df15 Extended time-zone support. cmlenz parents: 32 diff changeset	222 u'11:30 -0400'
29 da1c9610e751 More work on timezones. cmlenz parents: 20 diff changeset	223
da1c9610e751 More work on timezones. cmlenz parents: 20 diff changeset	224 The recommended approach to deal with different time-zones in a Python
da1c9610e751 More work on timezones. cmlenz parents: 20 diff changeset	225 application is to always use UTC internally, and only convert from/to the users
da1c9610e751 More work on timezones. cmlenz parents: 20 diff changeset	226 time-zone when accepting user input and displaying date/time data, respectively.
34 3666f3d3df15 Extended time-zone support. cmlenz parents: 32 diff changeset	227 You can use Babel together with ``pytz`` to apply a time-zone to any
3666f3d3df15 Extended time-zone support. cmlenz parents: 32 diff changeset	228 ``datetime`` or ``time`` object for display, leaving the original information
40 4525549aa6cc Syntax highlighting for the docs. cmlenz parents: 35 diff changeset	229 unchanged:
4525549aa6cc Syntax highlighting for the docs. cmlenz parents: 35 diff changeset	230
4525549aa6cc Syntax highlighting for the docs. cmlenz parents: 35 diff changeset	231 .. code-block:: pycon
34 3666f3d3df15 Extended time-zone support. cmlenz parents: 32 diff changeset	232
3666f3d3df15 Extended time-zone support. cmlenz parents: 32 diff changeset	233 >>> british = timezone('Europe/London')
3666f3d3df15 Extended time-zone support. cmlenz parents: 32 diff changeset	234 >>> format_datetime(dt, 'H:mm zzzz', tzinfo=british, locale='en_US')
3666f3d3df15 Extended time-zone support. cmlenz parents: 32 diff changeset	235 u'16:30 British Summer Time'
29 da1c9610e751 More work on timezones. cmlenz parents: 20 diff changeset	236
35 b6c51490cc95 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
b6c51490cc95 Add note on daylight savings time. cmlenz parents: 34 diff changeset	238 daylight savings time is taken into account. Daylight savings time is also
b6c51490cc95 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
b6c51490cc95 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
b6c51490cc95 Add note on daylight savings time. cmlenz parents: 34 diff changeset	241 should be used.
b6c51490cc95 Add note on daylight savings time. cmlenz parents: 34 diff changeset	242
29 da1c9610e751 More work on timezones. cmlenz parents: 20 diff changeset	243 .. _`pytz`: http://pytz.sourceforge.net/
da1c9610e751 More work on timezones. cmlenz parents: 20 diff changeset	244
da1c9610e751 More work on timezones. cmlenz parents: 20 diff changeset	245
255 00b83943f79e Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	246 Localized Time-zone Names
00b83943f79e Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	247 -------------------------
00b83943f79e Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	248
00b83943f79e 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
00b83943f79e 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
00b83943f79e 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
00b83943f79e Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	252 functions in the ``babel.dates`` module, most importantly the
00b83943f79e Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	253 ``get_timezone_name`` function:
00b83943f79e Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	254
00b83943f79e Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	255 .. code-block:: pycon
00b83943f79e Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	256
00b83943f79e Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	257 >>> from pytz import timezone
00b83943f79e Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	258 >>> from babel import Locale
00b83943f79e Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	259 >>> from babel.dates import get_timezone_name
00b83943f79e Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	260
00b83943f79e Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	261 >>> tz = timezone('Europe/Berlin')
00b83943f79e Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	262 >>> get_timezone_name(tz, locale=Locale.parse('pt_PT'))
00b83943f79e Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	263 u'Hor\xe1rio Alemanha'
00b83943f79e Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	264
00b83943f79e 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
00b83943f79e 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,
00b83943f79e 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
00b83943f79e 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
00b83943f79e 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
00b83943f79e Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	270 display a list of time-zones to the user.
00b83943f79e Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	271
00b83943f79e Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	272 .. code-block:: pycon
00b83943f79e Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	273
00b83943f79e Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	274 >>> from datetime import datetime
00b83943f79e Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	275
00b83943f79e Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	276 >>> dt = tz.localize(datetime(2007, 8, 15))
00b83943f79e Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	277 >>> get_timezone_name(dt, locale=Locale.parse('de_DE'))
00b83943f79e Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	278 u'Mitteleurop\xe4ische Sommerzeit'
00b83943f79e Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	279 >>> get_timezone_name(tz, locale=Locale.parse('de_DE'))
00b83943f79e Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	280 u'Deutschland'
00b83943f79e Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	281
00b83943f79e Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	282
18 77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	283 Parsing Dates
124 bf1bcdf19111 Split docs on date and number formatting. cmlenz parents: 98 diff changeset	284 =============
18 77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	285
40 4525549aa6cc Syntax highlighting for the docs. cmlenz parents: 35 diff changeset	286 Babel can also parse date and time information in a locale-sensitive manner:
4525549aa6cc Syntax highlighting for the docs. cmlenz parents: 35 diff changeset	287
4525549aa6cc Syntax highlighting for the docs. cmlenz parents: 35 diff changeset	288 .. code-block:: pycon
18 77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	289
77a68f88f6bc 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 00b83943f79e Added examples for using `get_timezone_name` to documentation. cmlenz parents: 233 diff changeset	291
00b83943f79e 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 > old > babel-test

annotate doc/dates.txt @ 507:b29ff192b610 stable-0.9.x