cpython: 1d4b02d8fa8a (original) (raw)

--- a/Doc/library/datetime.rst +++ b/Doc/library/datetime.rst @@ -593,15 +593,17 @@ Instance methods: .. 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:: @@ -793,7 +795,8 @@ Other constructors, all class methods: format. This is equivalent to datetime(*(time.strptime(date_string,[](#l1.26) 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.

@@ -1160,14 +1163,16 @@ Instance methods: .. 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: @@ -1399,15 +1404,17 @@ Instance methods: .. 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() @@ -1773,22 +1780,6 @@ For :class:date objects, the format co 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. @@ -1798,116 +1789,119 @@ version) requires, and these work on all 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)

• 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).

• 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)

• 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.

• 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 @@ -1917,14 +1911,48 @@ Notes: 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). +

(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.

• 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[](#l1.357)

•  +HHMM or -HHMM, where HH is a 2-digit string giving the number of UTC[](#l1.358)

•  offset hours, and MM is a 2-digit string giving the number of UTC offset[](#l1.359)

•  minutes.  For example, if :meth:`utcoffset` returns[](#l1.360)

•  ``timedelta(hours=-3, minutes=-30)``, ``%z`` is replaced with the string[](#l1.361)

•  ``'-0330'``.[](#l1.362)

+

• %Z

•  If :meth:`tzname` returns ``None``, ``%Z`` is replaced by an empty[](#l1.365)

•  string.  Otherwise ``%Z`` is replaced by the returned value, which must[](#l1.366)

•  be a string.[](#l1.367)

+

• .. versionchanged:: 3.2

•  When the ``%z`` directive is provided to the :meth:`strptime` method, an[](#l1.370)

•  aware :class:`.datetime` object will be produced.  The ``tzinfo`` of the[](#l1.371)

•  result will be set to a :class:`timezone` instance.[](#l1.372)

+ +(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

--- a/Misc/NEWS +++ b/Misc/NEWS @@ -298,6 +298,8 @@ Tests Documentation ------------- +- Issue #17701: Improving strftime documentation. +

• Issue #18440: Clarify that hash() can truncate the value returned from an object's custom __hash__() method.