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

annotate doc/dates.txt @ 163:f2c78a271159

Added preliminary catalog updating/merging functionality.

author	cmlenz
date	Fri, 22 Jun 2007 00:33:22 +0000
parents	bf1bcdf19111
children	bc22f5aef216

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. \|
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	193 +----------+--------+--------------------------------------------------------+
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	194
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	195
31 b6ff3e4b43e5 Raise error on unsupported locales. Closes #5. cmlenz parents: 29 diff changeset	196 Time-Zone Support
124 bf1bcdf19111 Split docs on date and number formatting. cmlenz parents: 98 diff changeset	197 =================
29 da1c9610e751 More work on timezones. cmlenz parents: 20 diff changeset	198
31 b6ff3e4b43e5 Raise error on unsupported locales. Closes #5. cmlenz parents: 29 diff changeset	199 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	200 information is not by default available for the Python ``datetime`` and
b6ff3e4b43e5 Raise error on unsupported locales. Closes #5. cmlenz parents: 29 diff changeset	201 ``time`` objects. The standard library includes only the abstract ``tzinfo``
b6ff3e4b43e5 Raise error on unsupported locales. Closes #5. cmlenz parents: 29 diff changeset	202 class, which you need appropriate implementations for to actually use in your
29 da1c9610e751 More work on timezones. cmlenz parents: 20 diff changeset	203 application. Babel includes a ``tzinfo`` implementation for UTC (Universal
31 b6ff3e4b43e5 Raise error on unsupported locales. Closes #5. cmlenz parents: 29 diff changeset	204 Time).
b6ff3e4b43e5 Raise error on unsupported locales. Closes #5. cmlenz parents: 29 diff changeset	205
b6ff3e4b43e5 Raise error on unsupported locales. Closes #5. cmlenz parents: 29 diff changeset	206 For real time-zone support, it is strongly recommended that you use the
29 da1c9610e751 More work on timezones. cmlenz parents: 20 diff changeset	207 third-party package `pytz`_, which includes the definitions of practically all
da1c9610e751 More work on timezones. cmlenz parents: 20 diff changeset	208 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	209 reliably converting from UTC to local time, and vice versa:
4525549aa6cc Syntax highlighting for the docs. cmlenz parents: 35 diff changeset	210
4525549aa6cc Syntax highlighting for the docs. cmlenz parents: 35 diff changeset	211 .. code-block:: pycon
29 da1c9610e751 More work on timezones. cmlenz parents: 20 diff changeset	212
da1c9610e751 More work on timezones. cmlenz parents: 20 diff changeset	213 >>> from datetime import time
34 3666f3d3df15 Extended time-zone support. cmlenz parents: 32 diff changeset	214 >>> from pytz import timezone, utc
3666f3d3df15 Extended time-zone support. cmlenz parents: 32 diff changeset	215 >>> dt = datetime(2007, 04, 01, 15, 30, tzinfo=utc)
3666f3d3df15 Extended time-zone support. cmlenz parents: 32 diff changeset	216 >>> eastern = timezone('US/Eastern')
3666f3d3df15 Extended time-zone support. cmlenz parents: 32 diff changeset	217 >>> format_datetime(dt, 'H:mm Z', tzinfo=eastern, locale='en_US')
3666f3d3df15 Extended time-zone support. cmlenz parents: 32 diff changeset	218 u'11:30 -0400'
29 da1c9610e751 More work on timezones. cmlenz parents: 20 diff changeset	219
da1c9610e751 More work on timezones. cmlenz parents: 20 diff changeset	220 The recommended approach to deal with different time-zones in a Python
da1c9610e751 More work on timezones. cmlenz parents: 20 diff changeset	221 application is to always use UTC internally, and only convert from/to the users
da1c9610e751 More work on timezones. cmlenz parents: 20 diff changeset	222 time-zone when accepting user input and displaying date/time data, respectively.
34 3666f3d3df15 Extended time-zone support. cmlenz parents: 32 diff changeset	223 You can use Babel together with ``pytz`` to apply a time-zone to any
3666f3d3df15 Extended time-zone support. cmlenz parents: 32 diff changeset	224 ``datetime`` or ``time`` object for display, leaving the original information
40 4525549aa6cc Syntax highlighting for the docs. cmlenz parents: 35 diff changeset	225 unchanged:
4525549aa6cc Syntax highlighting for the docs. cmlenz parents: 35 diff changeset	226
4525549aa6cc Syntax highlighting for the docs. cmlenz parents: 35 diff changeset	227 .. code-block:: pycon
34 3666f3d3df15 Extended time-zone support. cmlenz parents: 32 diff changeset	228
3666f3d3df15 Extended time-zone support. cmlenz parents: 32 diff changeset	229 >>> british = timezone('Europe/London')
3666f3d3df15 Extended time-zone support. cmlenz parents: 32 diff changeset	230 >>> format_datetime(dt, 'H:mm zzzz', tzinfo=british, locale='en_US')
3666f3d3df15 Extended time-zone support. cmlenz parents: 32 diff changeset	231 u'16:30 British Summer Time'
29 da1c9610e751 More work on timezones. cmlenz parents: 20 diff changeset	232
35 b6c51490cc95 Add note on daylight savings time. cmlenz parents: 34 diff changeset	233 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	234 daylight savings time is taken into account. Daylight savings time is also
b6c51490cc95 Add note on daylight savings time. cmlenz parents: 34 diff changeset	235 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	236 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	237 should be used.
b6c51490cc95 Add note on daylight savings time. cmlenz parents: 34 diff changeset	238
29 da1c9610e751 More work on timezones. cmlenz parents: 20 diff changeset	239 .. _`pytz`: http://pytz.sourceforge.net/
da1c9610e751 More work on timezones. cmlenz parents: 20 diff changeset	240
da1c9610e751 More work on timezones. cmlenz parents: 20 diff changeset	241
18 77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	242 Parsing Dates
124 bf1bcdf19111 Split docs on date and number formatting. cmlenz parents: 98 diff changeset	243 =============
18 77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	244
40 4525549aa6cc Syntax highlighting for the docs. cmlenz parents: 35 diff changeset	245 Babel can also parse date and time information in a locale-sensitive manner:
4525549aa6cc Syntax highlighting for the docs. cmlenz parents: 35 diff changeset	246
4525549aa6cc Syntax highlighting for the docs. cmlenz parents: 35 diff changeset	247 .. code-block:: pycon
18 77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	248
77a68f88f6bc Started documentation for date formatting, plus some code tweaks in that area. cmlenz parents: 2 diff changeset	249 >>> from babel.dates import parse_date, parse_datetime, parse_time

Mercurial > babel > old > babel-test

annotate doc/dates.txt @ 163:f2c78a271159