gh-69142: add %:z strftime format code (gh-95983)

datetime.isoformat generates the tzoffset with colons, but there
was no format code to make strftime output the same format.

for simplicity and consistency the %:z formatting behaves mostly
as %z, with the exception of adding colons. this includes the
dynamic behaviour of adding seconds and microseconds only when
needed (when not 0).

this fixes the still open "generate" part of this issue:

https://github.com/python/cpython/issues/69142

Co-authored-by: Kumar Aditya <59607654+kumaraditya303@users.noreply.github.com>

1 files changed, 14 insertions, 2 deletions

diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst
index 0f04237..c3a66a4 100644
--- a/Doc/library/datetime.rst
+++ b/Doc/library/datetime.rst
@@ -2443,6 +2443,11 @@ convenience. These parameters all correspond to ISO 8601 date values.
 |           | Week 01 is the week containing |                        |       |
 |           | Jan 4.                         |                        |       |
 +-----------+--------------------------------+------------------------+-------+
+| ``%:z``   | UTC offset in the form         | (empty), +00:00,       | \(6)  |
+|           | ``±HH:MM[:SS[.ffffff]]``       | -04:00, +10:30,        |       |
+|           | (empty string if the object is | +06:34:15,             |       |
+|           | naive).                        | -03:07:12.345216       |       |
++-----------+--------------------------------+------------------------+-------+
 
 These may not be available on all platforms when used with the :meth:`strftime`
 method. The ISO 8601 year and ISO 8601 week directives are not interchangeable
@@ -2458,6 +2463,9 @@ differences between platforms in handling of unsupported format specifiers.
 .. versionadded:: 3.6
    ``%G``, ``%u`` and ``%V`` were added.
 
+.. versionadded:: 3.12
+   ``%:z`` was added.
+
 Technical Detail
 ^^^^^^^^^^^^^^^^
 
@@ -2530,8 +2538,8 @@ Notes:
    available).
 
 (6)
-   For a naive object, the ``%z`` and ``%Z`` format codes are replaced by empty
-   strings.
+   For a naive object, the ``%z``, ``%:z`` and ``%Z`` format codes are replaced
+   by empty strings.
 
    For an aware object:
 
@@ -2557,6 +2565,10 @@ Notes:
       For example, ``'+01:00:00'`` will be parsed as an offset of one hour.
       In addition, providing ``'Z'`` is identical to ``'+00:00'``.
 
+   ``%:z``
+      Behaves exactly as ``%z``, but has a colon separator added between
+      hours, minutes and seconds.
+
    ``%Z``
       In :meth:`strftime`, ``%Z`` is replaced by an empty string if
       :meth:`tzname` returns ``None``; otherwise ``%Z`` is replaced by the