Skip to content

Commit fb196c6

Browse files
StanFromIrelandStanFromIreland
authored
gh-140715: Update datetime.*.str*time format code tables (GH-140716)
1 parent 172135c commit fb196c6

File tree

1 file changed

+104
-67
lines changed

1 file changed

+104
-67
lines changed

‎Doc/library/datetime.rst‎

Lines changed: 104 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -2495,140 +2495,174 @@ These methods accept format codes that can be used to parse and format dates::
24952495
>>> _.strftime('%a %d %b %Y, %I:%M%p')
24962496
'Mon 31 Jan 2022, 11:59PM'
24972497

2498-
The following is a list of all the format codes that the 1989 C standard
2499-
requires, and these work on all platforms with a standard C implementation.
2498+
The following is a list of all the format codes that the 2011 C standard
2499+
requires, and these work on all supported platforms.
25002500

25012501
+-----------+--------------------------------+------------------------+-------+
2502-
| Directive | Meaning | Example | Notes |
2502+
| Directive | Meaning | Example | Notes |
2503+
| | | | |
25032504
+===========+================================+========================+=======+
2504-
| ``%a`` | Weekday as locale's || Sun, Mon, ..., Sat | \(1) |
2505+
| ``%a`` | Weekday as locale's || Sun, Mon, ..., Sat | \(1) |
25052506
| | abbreviated name. | (en_US); | |
25062507
| | || So, Mo, ..., Sa | |
25072508
| | | (de_DE) | |
25082509
+-----------+--------------------------------+------------------------+-------+
2509-
| ``%A`` | Weekday as locale's full name. || Sunday, Monday, ..., | \(1) |
2510+
| ``%A`` | Weekday as locale's full name. || Sunday, Monday, ..., | \(1) |
25102511
| | | Saturday (en_US); | |
25112512
| | || Sonntag, Montag, ..., | |
25122513
| | | Samstag (de_DE) | |
25132514
+-----------+--------------------------------+------------------------+-------+
2514-
| ``%w`` | Weekday as a decimal number, | 0, 1, ..., 6 | |
2515-
| | where 0 is Sunday and 6 is | | |
2516-
| | Saturday. | | |
2517-
+-----------+--------------------------------+------------------------+-------+
2518-
| ``%d`` | Day of the month as a | 01, 02, ..., 31 | \(9) |
2519-
| | zero-padded decimal number. | | |
2520-
+-----------+--------------------------------+------------------------+-------+
2521-
| ``%b`` | Month as locale's abbreviated || Jan, Feb, ..., Dec | \(1) |
2515+
| ``%b`` | Month as locale's abbreviated || Jan, Feb, ..., Dec | \(1) |
25222516
| | name. | (en_US); | |
25232517
| | || Jan, Feb, ..., Dez | |
25242518
| | | (de_DE) | |
25252519
+-----------+--------------------------------+------------------------+-------+
2526-
| ``%B`` | Month as locale's full name. || January, February, | \(1) |
2520+
| ``%B`` | Month as locale's full name. || January, February, | \(1) |
25272521
| | | ..., December (en_US);| |
25282522
| | || Januar, Februar, ..., | |
25292523
| | | Dezember (de_DE) | |
25302524
+-----------+--------------------------------+------------------------+-------+
2531-
| ``%m`` | Month as a zero-padded | 01, 02, ..., 12 | \(9) |
2532-
| | decimal number. | | |
2525+
| ``%c`` | Locale's appropriate date and || Tue Aug 16 21:30:00 | \(1) |
2526+
| | time representation. | 1988 (en_US); | |
2527+
| | || Di 16 Aug 21:30:00 | |
2528+
| | | 1988 (de_DE) | |
25332529
+-----------+--------------------------------+------------------------+-------+
2534-
| ``%y`` | Year without century as a | 00, 01, ..., 99 | \(9) |
2530+
| ``%C`` | The year divided by 100 and | 01, 02, ..., 99 | \(0) |
2531+
| | truncated to an integer as a | | |
25352532
| | zero-padded decimal number. | | |
25362533
+-----------+--------------------------------+------------------------+-------+
2537-
| ``%Y`` | Year with century as a decimal | 0001, 0002, ..., 2013, | \(2) |
2538-
| | number. | 2014, ..., 9998, 9999 | |
2534+
| ``%d`` | Day of the month as a | 01, 02, ..., 31 | \(9) |
2535+
| | zero-padded decimal number. | | |
2536+
+-----------+--------------------------------+------------------------+-------+
2537+
| ``%D`` | Equivalent to ``%m/%d/%y``. | 11/10/2025 | \(9), |
2538+
| | | | \(0) |
2539+
+-----------+--------------------------------+------------------------+-------+
2540+
| ``%e`` | The day of the month as a | ␣1, ␣2, ..., 31 | |
2541+
| | space-padded decimal number. | | |
2542+
+-----------+--------------------------------+------------------------+-------+
2543+
| ``%F`` | Equivalent to ``%Y-%m-%d``, | 2025-10-11, | \(0) |
2544+
| | the ISO 8601 format. | 1001-12-30 | |
2545+
+-----------+--------------------------------+------------------------+-------+
2546+
| ``%g`` | Last 2 digits of ISO 8601 year | 00, 01, ..., 99 | \(0) |
2547+
| | representing the year that | | |
2548+
| | contains the greater part of | | |
2549+
| | the ISO week (``%V``). | | |
25392550
+-----------+--------------------------------+------------------------+-------+
2540-
| ``%H`` | Hour (24-hour clock) as a | 00, 01, ..., 23 | \(9) |
2551+
| ``%G`` | ISO 8601 year with century | 0001, 0002, ..., 2013, | \(8) |
2552+
| | representing the year that | 2014, ..., 9998, 9999 | |
2553+
| | contains the greater part of | | |
2554+
| | the ISO week (``%V``). | | |
2555+
+-----------+--------------------------------+------------------------+-------+
2556+
| ``%h`` | Equivalent to ``%b``. | See ``%b``. | \(0) |
2557+
+-----------+--------------------------------+------------------------+-------+
2558+
| ``%H`` | Hour (24-hour clock) as a | 00, 01, ..., 23 | \(9) |
25412559
| | zero-padded decimal number. | | |
25422560
+-----------+--------------------------------+------------------------+-------+
2543-
| ``%I`` | Hour (12-hour clock) as a | 01, 02, ..., 12 | \(9) |
2561+
| ``%I`` | Hour (12-hour clock) as a | 01, 02, ..., 12 | \(9) |
25442562
| | zero-padded decimal number. | | |
25452563
+-----------+--------------------------------+------------------------+-------+
2546-
| ``%p`` | Locale's equivalent of either || AM, PM (en_US); | \(1), |
2547-
| | AM or PM. || am, pm (de_DE) | \(3) |
2564+
| ``%j`` | Day of the year as a | 001, 002, ..., 366 | \(9) |
2565+
| | zero-padded decimal number. | | |
25482566
+-----------+--------------------------------+------------------------+-------+
2549-
| ``%M`` | Minute as a zero-padded | 00, 01, ..., 59 | \(9) |
2567+
| ``%m`` | Month as a zero-padded | 01, 02, ..., 12 | \(9) |
25502568
| | decimal number. | | |
25512569
+-----------+--------------------------------+------------------------+-------+
2552-
| ``%S`` | Second as a zero-padded | 00, 01, ..., 59 | \(4), |
2553-
| | decimal number. | | \(9) |
2570+
| ``%M`` | Minute as a zero-padded | 00, 01, ..., 59 | \(9) |
2571+
| | decimal number. | | |
25542572
+-----------+--------------------------------+------------------------+-------+
2555-
| ``%f`` | Microsecond as a decimal | 000000, 000001, ..., | \(5) |
2556-
| | number, zero-padded to 6 | 999999 | |
2557-
| | digits. | | |
2573+
| ``%n`` | The newline character | ``\n`` | \(0) |
2574+
| | (``'\n'``). | | |
25582575
+-----------+--------------------------------+------------------------+-------+
2559-
| ``%z`` | UTC offset in the form | (empty), +0000, | \(6) |
2560-
| | ``±HHMM[SS[.ffffff]]`` (empty | -0400, +1030, | |
2561-
| | string if the object is | +063415, | |
2562-
| | naive). | -030712.345216 | |
2576+
| ``%p`` | Locale's equivalent of either || AM, PM (en_US); | \(1), |
2577+
| | AM or PM. || am, pm (de_DE) | \(3) |
25632578
+-----------+--------------------------------+------------------------+-------+
2564-
| ``%Z`` | Time zone name (empty string | (empty), UTC, GMT | \(6) |
2565-
| | if the object is naive). | | |
2579+
| ``%r`` | Locale's 12-hour clock time. | 12:00:00 AM | \(1), |
2580+
| | | | \(0) |
25662581
+-----------+--------------------------------+------------------------+-------+
2567-
| ``%j`` | Day of the year as a | 001, 002, ..., 366 | \(9) |
2568-
| | zero-padded decimal number. | | |
2582+
| ``%R`` | Equivalent to ``%H:%M``. | 10:01 | |
2583+
+-----------+--------------------------------+------------------------+-------+
2584+
| ``%S`` | Second as a zero-padded | 00, 01, ..., 59 | \(4), |
2585+
| | decimal number. | | \(9) |
2586+
+-----------+--------------------------------+------------------------+-------+
2587+
| ``%t`` | The tab character | ``\t`` | \(0) |
2588+
| | (``'\t'``). | | |
2589+
+-----------+--------------------------------+------------------------+-------+
2590+
| ``%T`` | ISO 8601 time format, | 10:01:59 | |
2591+
| | equivalent to ``%H:%M:%S``. | | |
2592+
+-----------+--------------------------------+------------------------+-------+
2593+
| ``%u`` | ISO 8601 weekday as a decimal | 1, 2, ..., 7 | |
2594+
| | number where 1 is Monday. | | |
25692595
+-----------+--------------------------------+------------------------+-------+
2570-
| ``%U`` | Week number of the year | 00, 01, ..., 53 | \(7), |
2596+
| ``%U`` | Week number of the year | 00, 01, ..., 53 | \(7), |
25712597
| | (Sunday as the first day of | | \(9) |
25722598
| | the week) as a zero-padded | | |
25732599
| | decimal number. All days in a | | |
25742600
| | new year preceding the first | | |
25752601
| | Sunday are considered to be in | | |
25762602
| | week 0. | | |
25772603
+-----------+--------------------------------+------------------------+-------+
2578-
| ``%W`` | Week number of the year | 00, 01, ..., 53 | \(7), |
2604+
| ``%V`` | ISO 8601 week as a decimal | 01, 02, ..., 53 | \(8), |
2605+
| | number with Monday as | | \(9) |
2606+
| | the first day of the week. | | |
2607+
| | Week 01 is the week containing | | |
2608+
| | Jan 4. | | |
2609+
+-----------+--------------------------------+------------------------+-------+
2610+
| ``%w`` | Weekday as a decimal number, | 0, 1, ..., 6 | |
2611+
| | where 0 is Sunday and 6 is | | |
2612+
| | Saturday. | | |
2613+
+-----------+--------------------------------+------------------------+-------+
2614+
| ``%W`` | Week number of the year | 00, 01, ..., 53 | \(7), |
25792615
| | (Monday as the first day of | | \(9) |
25802616
| | the week) as a zero-padded | | |
25812617
| | decimal number. All days in a | | |
25822618
| | new year preceding the first | | |
25832619
| | Monday are considered to be in | | |
25842620
| | week 0. | | |
25852621
+-----------+--------------------------------+------------------------+-------+
2586-
| ``%c`` | Locale's appropriate date and || Tue Aug 16 21:30:00 | \(1) |
2587-
| | time representation. | 1988 (en_US); | |
2588-
| | || Di 16 Aug 21:30:00 | |
2589-
| | | 1988 (de_DE) | |
2590-
+-----------+--------------------------------+------------------------+-------+
2591-
| ``%x`` | Locale's appropriate date || 08/16/88 (None); | \(1) |
2622+
| ``%x`` | Locale's appropriate date || 08/16/88 (None); | \(1) |
25922623
| | representation. || 08/16/1988 (en_US); | |
25932624
| | || 16.08.1988 (de_DE) | |
25942625
+-----------+--------------------------------+------------------------+-------+
2595-
| ``%X`` | Locale's appropriate time || 21:30:00 (en_US); | \(1) |
2626+
| ``%X`` | Locale's appropriate time || 21:30:00 (en_US); | \(1) |
25962627
| | representation. || 21:30:00 (de_DE) | |
25972628
+-----------+--------------------------------+------------------------+-------+
2598-
| ``%%`` | A literal ``'%'`` character. | % | |
2629+
| ``%y`` | Year without century as a | 00, 01, ..., 99 | \(9) |
2630+
| | zero-padded decimal number. | | |
2631+
+-----------+--------------------------------+------------------------+-------+
2632+
| ``%Y`` | Year with century as a decimal | 0001, 0002, ..., 2013, | \(2) |
2633+
| | number. | 2014, ..., 9998, 9999 | |
2634+
+-----------+--------------------------------+------------------------+-------+
2635+
| ``%z`` | UTC offset in the form | (empty), +0000, | \(6) |
2636+
| | ``±HHMM[SS[.ffffff]]`` (empty | -0400, +1030, | |
2637+
| | string if the object is | +063415, | |
2638+
| | naive). | -030712.345216 | |
2639+
+-----------+--------------------------------+------------------------+-------+
2640+
| ``%Z`` | Time zone name (empty string | (empty), UTC, GMT | \(6) |
2641+
| | if the object is naive). | | |
2642+
+-----------+--------------------------------+------------------------+-------+
2643+
| ``%%`` | A literal ``'%'`` character. | % | |
25992644
+-----------+--------------------------------+------------------------+-------+
26002645

2601-
Several additional directives not required by the C89 standard are included for
2602-
convenience. These parameters all correspond to ISO 8601 date values.
2646+
The ISO 8601 year and ISO 8601 week directives are not interchangeable
2647+
with the year and week number directives above. Calling :meth:`~.datetime.strptime` with
2648+
incomplete or ambiguous ISO 8601 directives will raise a :exc:`ValueError`.
2649+
2650+
Several additional directives not required by the C11 standard are included for
2651+
convenience.
26032652

26042653
+-----------+--------------------------------+------------------------+-------+
26052654
| Directive | Meaning | Example | Notes |
26062655
+===========+================================+========================+=======+
2607-
| ``%G`` | ISO 8601 year with century | 0001, 0002, ..., 2013, | \(8) |
2608-
| | representing the year that | 2014, ..., 9998, 9999 | |
2609-
| | contains the greater part of | | |
2610-
| | the ISO week (``%V``). | | |
2611-
+-----------+--------------------------------+------------------------+-------+
2612-
| ``%u`` | ISO 8601 weekday as a decimal | 1, 2, ..., 7 | |
2613-
| | number where 1 is Monday. | | |
2614-
+-----------+--------------------------------+------------------------+-------+
2615-
| ``%V`` | ISO 8601 week as a decimal | 01, 02, ..., 53 | \(8), |
2616-
| | number with Monday as | | \(9) |
2617-
| | the first day of the week. | | |
2618-
| | Week 01 is the week containing | | |
2619-
| | Jan 4. | | |
2656+
| ``%f`` | Microsecond as a decimal | 000000, 000001, ..., | \(5) |
2657+
| | number, zero-padded to 6 | 999999 | |
2658+
| | digits. | | |
26202659
+-----------+--------------------------------+------------------------+-------+
26212660
| ``%:z`` | UTC offset in the form | (empty), +00:00, | \(6) |
26222661
| | ``±HH:MM[:SS[.ffffff]]`` | -04:00, +10:30, | |
26232662
| | (empty string if the object is | +06:34:15, | |
26242663
| | naive). | -03:07:12.345216 | |
26252664
+-----------+--------------------------------+------------------------+-------+
26262665

2627-
These may not be available on all platforms when used with the :meth:`~.datetime.strftime`
2628-
method. The ISO 8601 year and ISO 8601 week directives are not interchangeable
2629-
with the year and week number directives above. Calling :meth:`~.datetime.strptime` with
2630-
incomplete or ambiguous ISO 8601 directives will raise a :exc:`ValueError`.
2631-
26322666
The full set of format codes supported varies across platforms, because Python
26332667
calls the platform C library's :c:func:`strftime` function, and platform
26342668
variations are common. To see the full set of format codes supported on your
@@ -2712,6 +2746,9 @@ an empty string instead.
27122746

27132747
Notes:
27142748

2749+
(0)
2750+
This format code is currently unsupported by :meth:`~.datetime.strptime`.
2751+
27152752
(1)
27162753
Because the format depends on the current locale, care should be taken when
27172754
making assumptions about the output value. Field orderings will vary (for

0 commit comments

Comments
 (0)