[Python-checkins] cpython (merge 3.3 -> default): Merge issue #17701: Improving strftime documentation.
david.wolever
python-checkins at python.org
Mon Aug 12 23:15:54 CEST 2013
http://hg.python.org/cpython/rev/ab550dac6209
changeset: 85142:ab550dac6209
parent: 85140:c27ec198d3d1
parent: 85141:1d4b02d8fa8a
user: David Wolever <david at wolever.net>
date: Mon Aug 12 17:15:36 2013 -0400
summary:
Merge issue #17701: Improving strftime documentation.
files:
Doc/library/datetime.rst | 314 ++++++++++++++------------
Misc/NEWS | 2 +
2 files changed, 173 insertions(+), 143 deletions(-)
diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst
--- a/Doc/library/datetime.rst
+++ b/Doc/library/datetime.rst
@@ -595,15 +595,17 @@
.. method:: date.strftime(format)
Return a string representing the date, controlled by an explicit format string.
- Format codes referring to hours, minutes or seconds will see 0 values. See
- section :ref:`strftime-strptime-behavior`.
+ Format codes referring to hours, minutes or seconds will see 0 values. For a
+ complete list of formatting directives, see
+ :ref:`strftime-strptime-behavior`.
.. method:: date.__format__(format)
Same as :meth:`.date.strftime`. This makes it possible to specify format
- string for a :class:`.date` object when using :meth:`str.format`.
- See section :ref:`strftime-strptime-behavior`.
+ string for a :class:`.date` object when using :meth:`str.format`. For a
+ complete list of formatting directives, see
+ :ref:`strftime-strptime-behavior`.
Example of counting days to an event::
@@ -795,7 +797,8 @@
*format*. This is equivalent to ``datetime(*(time.strptime(date_string,
format)[0:6]))``. :exc:`ValueError` is raised if the date_string and format
can't be parsed by :func:`time.strptime` or if it returns a value which isn't a
- time tuple. See section :ref:`strftime-strptime-behavior`.
+ time tuple. For a complete list of formatting directives, see
+ :ref:`strftime-strptime-behavior`.
@@ -1162,14 +1165,16 @@
.. method:: datetime.strftime(format)
Return a string representing the date and time, controlled by an explicit format
- string. See section :ref:`strftime-strptime-behavior`.
+ string. For a complete list of formatting directives, see
+ :ref:`strftime-strptime-behavior`.
.. method:: datetime.__format__(format)
Same as :meth:`.datetime.strftime`. This makes it possible to specify format
- string for a :class:`.datetime` object when using :meth:`str.format`.
- See section :ref:`strftime-strptime-behavior`.
+ string for a :class:`.datetime` object when using :meth:`str.format`. For a
+ complete list of formatting directives, see
+ :ref:`strftime-strptime-behavior`.
Examples of working with datetime objects:
@@ -1401,15 +1406,17 @@
.. method:: time.strftime(format)
- Return a string representing the time, controlled by an explicit format string.
- See section :ref:`strftime-strptime-behavior`.
+ Return a string representing the time, controlled by an explicit format
+ string. For a complete list of formatting directives, see
+ :ref:`strftime-strptime-behavior`.
.. method:: time.__format__(format)
Same as :meth:`.time.strftime`. This makes it possible to specify format string
- for a :class:`.time` object when using :meth:`str.format`.
- See section :ref:`strftime-strptime-behavior`.
+ for a :class:`.time` object when using :meth:`str.format`. For a
+ complete list of formatting directives, see
+ :ref:`strftime-strptime-behavior`.
.. method:: time.utcoffset()
@@ -1775,22 +1782,6 @@
microseconds should not be used, as :class:`date` objects have no such
values. If they're used anyway, ``0`` is substituted for them.
-For a naive object, the ``%z`` and ``%Z`` format codes are replaced by empty
-strings.
-
-For an aware object:
-
-``%z``
- :meth:`utcoffset` is transformed into a 5-character string of the form +HHMM or
- -HHMM, where HH is a 2-digit string giving the number of UTC offset hours, and
- MM is a 2-digit string giving the number of UTC offset minutes. For example, if
- :meth:`utcoffset` returns ``timedelta(hours=-3, minutes=-30)``, ``%z`` is
- replaced with the string ``'-0330'``.
-
-``%Z``
- If :meth:`tzname` returns ``None``, ``%Z`` is replaced by an empty string.
- Otherwise ``%Z`` is replaced by the returned value, which must be a string.
-
The full set of format codes supported varies across platforms, because Python
calls the platform C library's :func:`strftime` function, and platform
variations are common.
@@ -1800,133 +1791,170 @@
implementation. Note that the 1999 version of the C standard added additional
format codes.
-+-----------+--------------------------------+-------+
-| Directive | Meaning | Notes |
-+===========+================================+=======+
-| ``%a`` | Locale's abbreviated weekday | |
-| | name. | |
-+-----------+--------------------------------+-------+
-| ``%A`` | Locale's full weekday name. | |
-+-----------+--------------------------------+-------+
-| ``%b`` | Locale's abbreviated month | |
-| | name. | |
-+-----------+--------------------------------+-------+
-| ``%B`` | Locale's full month name. | |
-+-----------+--------------------------------+-------+
-| ``%c`` | Locale's appropriate date and | |
-| | time representation. | |
-+-----------+--------------------------------+-------+
-| ``%d`` | Day of the month as a decimal | |
-| | number [01,31]. | |
-+-----------+--------------------------------+-------+
-| ``%f`` | Microsecond as a decimal | \(1) |
-| | number [0,999999], zero-padded | |
-| | on the left | |
-+-----------+--------------------------------+-------+
-| ``%H`` | Hour (24-hour clock) as a | |
-| | decimal number [00,23]. | |
-+-----------+--------------------------------+-------+
-| ``%I`` | Hour (12-hour clock) as a | |
-| | decimal number [01,12]. | |
-+-----------+--------------------------------+-------+
-| ``%j`` | Day of the year as a decimal | |
-| | number [001,366]. | |
-+-----------+--------------------------------+-------+
-| ``%m`` | Month as a decimal number | |
-| | [01,12]. | |
-+-----------+--------------------------------+-------+
-| ``%M`` | Minute as a decimal number | |
-| | [00,59]. | |
-+-----------+--------------------------------+-------+
-| ``%p`` | Locale's equivalent of either | \(2) |
-| | AM or PM. | |
-+-----------+--------------------------------+-------+
-| ``%S`` | Second as a decimal number | \(3) |
-| | [00,59]. | |
-+-----------+--------------------------------+-------+
-| ``%U`` | Week number of the year | \(4) |
-| | (Sunday as the first day of | |
-| | the week) as a decimal number | |
-| | [00,53]. All days in a new | |
-| | year preceding the first | |
-| | Sunday are considered to be in | |
-| | week 0. | |
-+-----------+--------------------------------+-------+
-| ``%w`` | Weekday as a decimal number | |
-| | [0(Sunday),6]. | |
-+-----------+--------------------------------+-------+
-| ``%W`` | Week number of the year | \(4) |
-| | (Monday as the first day of | |
-| | the week) as a decimal number | |
-| | [00,53]. All days in a new | |
-| | year preceding the first | |
-| | Monday are considered to be in | |
-| | week 0. | |
-+-----------+--------------------------------+-------+
-| ``%x`` | Locale's appropriate date | |
-| | representation. | |
-+-----------+--------------------------------+-------+
-| ``%X`` | Locale's appropriate time | |
-| | representation. | |
-+-----------+--------------------------------+-------+
-| ``%y`` | Year without century as a | |
-| | decimal number [00,99]. | |
-+-----------+--------------------------------+-------+
-| ``%Y`` | Year with century as a decimal | \(5) |
-| | number [0001,9999]. | |
-+-----------+--------------------------------+-------+
-| ``%z`` | UTC offset in the form +HHMM | \(6) |
-| | or -HHMM (empty string if the | |
-| | the object is naive). | |
-+-----------+--------------------------------+-------+
-| ``%Z`` | Time zone name (empty string | |
-| | if the object is naive). | |
-+-----------+--------------------------------+-------+
-| ``%%`` | A literal ``'%'`` character. | |
-+-----------+--------------------------------+-------+
++-----------+--------------------------------+------------------------+-------+
+| Directive | Meaning | Example | Notes |
++===========+================================+========================+=======+
+| ``%a`` | Weekday as locale's || Sun, Mon, ..., Sat | \(1) |
+| | abbreviated name. | (en_US); | |
+| | || So, Mo, ..., Sa | |
+| | | (de_DE) | |
++-----------+--------------------------------+------------------------+-------+
+| ``%A`` | Weekday as locale's full name. || Sunday, Monday, ..., | \(1) |
+| | | Saturday (en_US); | |
+| | || Sonntag, Montag, ..., | |
+| | | Samstag (de_DE) | |
++-----------+--------------------------------+------------------------+-------+
+| ``%w`` | Weekday as a decimal number, | 0, 1, ..., 6 | |
+| | where 0 is Sunday and 6 is | | |
+| | Saturday. | | |
++-----------+--------------------------------+------------------------+-------+
+| ``%d`` | Day of the month as a | 01, 02, ..., 31 | |
+| | zero-padded decimal number. | | |
++-----------+--------------------------------+------------------------+-------+
+| ``%b`` | Month as locale's abbreviated || Jan, Feb, ..., Dec | \(1) |
+| | name. | (en_US); | |
+| | || Jan, Feb, ..., Dez | |
+| | | (de_DE) | |
++-----------+--------------------------------+------------------------+-------+
+| ``%B`` | Month as locale's full name. || January, February, | \(1) |
+| | | ..., December (en_US);| |
+| | || Januar, Februar, ..., | |
+| | | Dezember (de_DE) | |
++-----------+--------------------------------+------------------------+-------+
+| ``%m`` | Month as a zero-padded | 01, 02, ..., 12 | |
+| | decimal number. | | |
++-----------+--------------------------------+------------------------+-------+
+| ``%y`` | Year without century as a | 00, 01, ..., 99 | |
+| | zero-padded decimal number. | | |
++-----------+--------------------------------+------------------------+-------+
+| ``%Y`` | Year with century as a decimal | 0001, 0002, ..., 2013, | \(2) |
+| | number. | 2014, ...., 9998, 9999 | |
++-----------+--------------------------------+------------------------+-------+
+| ``%H`` | Hour (24-hour clock) as a | 00, 01, ..., 23 | |
+| | zero-padded decimal number. | | |
++-----------+--------------------------------+------------------------+-------+
+| ``%I`` | Hour (12-hour clock) as a | 01, 02, ..., 12 | |
+| | zero-padded decimal number. | | |
++-----------+--------------------------------+------------------------+-------+
+| ``%p`` | Locale's equivalent of either || AM, PM (en_US); | \(1), |
+| | AM or PM. || am, pm (de_DE) | \(3) |
++-----------+--------------------------------+------------------------+-------+
+| ``%M`` | Minute as a zero-padded | 00, 01, ..., 59 | |
+| | decimal number. | | |
++-----------+--------------------------------+------------------------+-------+
+| ``%S`` | Second as a zero-padded | 00, 01, ..., 59 | \(4) |
+| | decimal number. | | |
++-----------+--------------------------------+------------------------+-------+
+| ``%f`` | Microsecond as a decimal | 000000, 000001, ..., | \(5) |
+| | number, zero-padded on the | 999999 | |
+| | left. | | |
++-----------+--------------------------------+------------------------+-------+
+| ``%z`` | UTC offset in the form +HHMM | (empty), +0000, -0400, | \(6) |
+| | or -HHMM (empty string if the | +1030 | |
+| | the object is naive). | | |
++-----------+--------------------------------+------------------------+-------+
+| ``%Z`` | Time zone name (empty string | (empty), UTC, EST, CST | |
+| | if the object is naive). | | |
++-----------+--------------------------------+------------------------+-------+
+| ``%j`` | Day of the year as a | 001, 002, ..., 366 | |
+| | zero-padded decimal number. | | |
++-----------+--------------------------------+------------------------+-------+
+| ``%U`` | Week number of the year | 00, 01, ..., 53 | \(7) |
+| | (Sunday as the first day of | | |
+| | the week) as a zero padded | | |
+| | decimal number. All days in a | | |
+| | new year preceding the first | | |
+| | Sunday are considered to be in | | |
+| | week 0. | | |
++-----------+--------------------------------+------------------------+-------+
+| ``%W`` | Week number of the year | 00, 01, ..., 53 | \(7) |
+| | (Monday as the first day of | | |
+| | the week) as a decimal number. | | |
+| | All days in a new year | | |
+| | preceding the first Monday | | |
+| | are considered to be in | | |
+| | week 0. | | |
++-----------+--------------------------------+------------------------+-------+
+| ``%c`` | Locale's appropriate date and || Tue Aug 16 21:30:00 | \(1) |
+| | time representation. | 1988 (en_US); | |
+| | || Di 16 Aug 21:30:00 | |
+| | | 1988 (de_DE) | |
++-----------+--------------------------------+------------------------+-------+
+| ``%x`` | Locale's appropriate date || 08/16/88 (None); | \(1) |
+| | representation. || 08/16/1988 (en_US); | |
+| | || 16.08.1988 (de_DE) | |
++-----------+--------------------------------+------------------------+-------+
+| ``%X`` | Locale's appropriate time || 21:30:00 (en_US); | \(1) |
+| | representation. || 21:30:00 (de_DE) | |
++-----------+--------------------------------+------------------------+-------+
+| ``%%`` | A literal ``'%'`` character. | % | |
++-----------+--------------------------------+------------------------+-------+
Notes:
(1)
+ Because the format depends on the current locale, care should be taken when
+ making assumptions about the output value. Field orderings will vary (for
+ example, "month/day/year" versus "day/month/year"), and the output may
+ contain Unicode characters encoded using the locale's default encoding (for
+ example, if the current locale is ``js_JP``, the default encoding could be
+ any one of ``eucJP``, ``SJIS``, or ``utf-8``; use :meth:`locale.getlocale`
+ to determine the current locale's encoding).
+
+(2)
+ The :meth:`strptime` method can parse years in the full [1, 9999] range, but
+ years < 1000 must be zero-filled to 4-digit width.
+
+ .. versionchanged:: 3.2
+ In previous versions, :meth:`strftime` method was restricted to
+ years >= 1900.
+
+ .. versionchanged:: 3.3
+ In version 3.2, :meth:`strftime` method was restricted to
+ years >= 1000.
+
+(3)
+ When used with the :meth:`strptime` method, the ``%p`` directive only affects
+ the output hour field if the ``%I`` directive is used to parse the hour.
+
+(4)
+ Unlike the :mod:`time` module, the :mod:`datetime` module does not support
+ leap seconds.
+
+(5)
When used with the :meth:`strptime` method, the ``%f`` directive
accepts from one to six digits and zero pads on the right. ``%f`` is
an extension to the set of format characters in the C standard (but
implemented separately in datetime objects, and therefore always
available).
-(2)
- When used with the :meth:`strptime` method, the ``%p`` directive only affects
- the output hour field if the ``%I`` directive is used to parse the hour.
-
-(3)
- Unlike :mod:`time` module, :mod:`datetime` module does not support
- leap seconds.
-
-(4)
- When used with the :meth:`strptime` method, ``%U`` and ``%W`` are only used in
- calculations when the day of the week and the year are specified.
-
-(5)
- The :meth:`strptime` method can
- parse years in the full [1, 9999] range, but years < 1000 must be
- zero-filled to 4-digit width.
+(6)
+ For a naive object, the ``%z`` and ``%Z`` format codes are replaced by empty
+ strings.
+
+ For an aware object:
+
+ ``%z``
+ :meth:`utcoffset` is transformed into a 5-character string of the form
+ +HHMM or -HHMM, where HH is a 2-digit string giving the number of UTC
+ offset hours, and MM is a 2-digit string giving the number of UTC offset
+ minutes. For example, if :meth:`utcoffset` returns
+ ``timedelta(hours=-3, minutes=-30)``, ``%z`` is replaced with the string
+ ``'-0330'``.
+
+ ``%Z``
+ If :meth:`tzname` returns ``None``, ``%Z`` is replaced by an empty
+ string. Otherwise ``%Z`` is replaced by the returned value, which must
+ be a string.
.. versionchanged:: 3.2
- In previous versions, :meth:`strftime` method was restricted to
- years >= 1900.
-
- .. versionchanged:: 3.3
- In version 3.2, :meth:`strftime` method was restricted to
- years >= 1000.
-
-(6)
- For example, if :meth:`utcoffset` returns ``timedelta(hours=-3, minutes=-30)``,
- ``%z`` is replaced with the string ``'-0330'``.
-
-.. versionchanged:: 3.2
- When the ``%z`` directive is provided to the :meth:`strptime` method, an
- aware :class:`.datetime` object will be produced. The ``tzinfo`` of the
- result will be set to a :class:`timezone` instance.
+ When the ``%z`` directive is provided to the :meth:`strptime` method, an
+ aware :class:`.datetime` object will be produced. The ``tzinfo`` of the
+ result will be set to a :class:`timezone` instance.
+
+(7)
+ When used with the :meth:`strptime` method, ``%U`` and ``%W`` are only used
+ in calculations when the day of the week and the year are specified.
.. rubric:: Footnotes
diff --git a/Misc/NEWS b/Misc/NEWS
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -750,6 +750,8 @@
Documentation
-------------
+- Issue #17701: Improving strftime documentation.
+
- Issue #18440: Clarify that `hash()` can truncate the value returned from an
object's custom `__hash__()` method.
--
Repository URL: http://hg.python.org/cpython
More information about the Python-checkins
mailing list