add %f format to datetime - issue 1158
diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst
index 3477250..32813b9 100644
--- a/Doc/library/datetime.rst
+++ b/Doc/library/datetime.rst
@@ -1489,9 +1489,31 @@
be used, as time objects have no such values. If they're used anyway, ``1900``
is substituted for the year, and ``0`` for the month and day.
-For :class:`date` objects, the format codes for hours, minutes, and seconds
-should not be used, as :class:`date` objects have no such values. If they're
-used anyway, ``0`` is substituted for them.
+For :class:`date` objects, the format codes for hours, minutes, seconds, and
+microseconds should not be used, as :class:`date` objects have no such
+values. If they're used anyway, ``0`` is substituted for them.
+
+:class:`time` and :class:`datetime` objects support a ``%f`` format code
+which expands to the number of microseconds in the object, zero-padded on
+the left to six places.
+
+.. versionadded:: 2.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.
The full set of format codes supported varies across platforms, because Python
calls the platform C library's :func:`strftime` function, and platform
@@ -1524,6 +1546,10 @@
| ``%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]. | |
+-----------+--------------------------------+-------+
@@ -1539,13 +1565,13 @@
| ``%M`` | Minute as a decimal number | |
| | [00,59]. | |
+-----------+--------------------------------+-------+
-| ``%p`` | Locale's equivalent of either | \(1) |
+| ``%p`` | Locale's equivalent of either | \(2) |
| | AM or PM. | |
+-----------+--------------------------------+-------+
-| ``%S`` | Second as a decimal number | \(2) |
+| ``%S`` | Second as a decimal number | \(3) |
| | [00,61]. | |
+-----------+--------------------------------+-------+
-| ``%U`` | Week number of the year | \(3) |
+| ``%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 | |
@@ -1556,7 +1582,7 @@
| ``%w`` | Weekday as a decimal number | |
| | [0(Sunday),6]. | |
+-----------+--------------------------------+-------+
-| ``%W`` | Week number of the year | \(3) |
+| ``%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 | |
@@ -1576,7 +1602,7 @@
| ``%Y`` | Year with century as a decimal | |
| | number. | |
+-----------+--------------------------------+-------+
-| ``%z`` | UTC offset in the form +HHMM | \(4) |
+| ``%z`` | UTC offset in the form +HHMM | \(5) |
| | or -HHMM (empty string if the | |
| | the object is naive). | |
+-----------+--------------------------------+-------+
@@ -1589,17 +1615,22 @@
Notes:
(1)
+ When used with the :func:`strptime` function, 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.
+
+(2)
When used with the :func:`strptime` function, the ``%p`` directive only affects
the output hour field if the ``%I`` directive is used to parse the hour.
-(2)
+(3)
The range really is ``0`` to ``61``; this accounts for leap seconds and the
(very rare) double leap seconds.
-(3)
+(4)
When used with the :func:`strptime` function, ``%U`` and ``%W`` are only used in
calculations when the day of the week and the year are specified.
-(4)
+(5)
For example, if :meth:`utcoffset` returns ``timedelta(hours=-3, minutes=-30)``,
``%z`` is replaced with the string ``'-0330'``.