babel/old/mirror: doc/dates.txt annotate

annotate doc/dates.txt @ 126:b12c6a776c44

Split docs on date and number formatting.

author	cmlenz
date	Mon, 18 Jun 2007 15:15:31 +0000
parents	doc/formatting.txt@3eaa652b1216
children	d0cd235ede46

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

Mercurial > babel > old > mirror

annotate doc/dates.txt @ 126:b12c6a776c44