Apply Python changes and update docs

Author: StanFromIreland

Doc/library/datetime.rst

@@ -1606,7 +1606,7 @@ Instance methods:
 
    .. versionadded:: 3.6
       Added the *timespec* argument.
-   .. versionadded:: 3.11
+   .. versionadded:: next
       Added the *use_utc_designator* argument.
 
 .. method:: datetime.__str__()
@@ -2003,15 +2003,12 @@ Instance methods:
       >>> dt.isoformat(timespec='auto')
       '12:34:56'
       >>> dt = time(12, 30, 59, tzinfo=timezone.utc)
-      >>> dt.isoformat()
-      '12:30:59+00:00'
       >>> dt.isoformat(use_utc_designator=True)
       '12:30:59Z'
 
    .. versionchanged:: 3.6
       Added the *timespec* parameter.
-
-   .. versionadded:: 3.11
+   .. versionadded:: next
       Added the *use_utc_designator* argument.
 
 

Lib/_pydatetime.py

@@ -1598,7 +1598,7 @@ def __repr__(self):
             s = s[:-1] + ", fold=1)"
         return s
 
-    def isoformat(self, timespec='auto'):
+    def isoformat(self, timespec='auto', use_utc_designator=False):
         """Return the time formatted according to ISO.
 
         The full format is 'HH:MM:SS.mmmmmm+zz:zz'. By default, the fractional
@@ -1607,12 +1607,19 @@ def isoformat(self, timespec='auto'):
         The optional argument timespec specifies the number of additional
         terms of the time to include. Valid options are 'auto', 'hours',
         'minutes', 'seconds', 'milliseconds' and 'microseconds'.
+
+        The UTC offset will be replaced with 'Z' if use_utc_designator
+        is True and self.tzname() is exactly 'UTC'.
         """
         s = _format_time(self._hour, self._minute, self._second,
                           self._microsecond, timespec)
-        tz = self._tzstr()
-        if tz:
-            s += tz
+
+        if use_utc_designator and self.tzname() == 'UTC':
+            s += 'Z'
+        else:
+            tz = self._tzstr()
+            if tz:
+                s += tz
         return s
 
     __str__ = isoformat
@@ -2128,7 +2135,7 @@ def ctime(self):
             self._hour, self._minute, self._second,
             self._year)
 
-    def isoformat(self, sep='T', timespec='auto'):
+    def isoformat(self, sep='T', timespec='auto', use_utc_designator=False):
         """Return the time formatted according to ISO.
 
         The full format looks like 'YYYY-MM-DD HH:MM:SS.mmmmmm'.
@@ -2143,15 +2150,21 @@ def isoformat(self, sep='T', timespec='auto'):
         The optional argument timespec specifies the number of additional
         terms of the time to include. Valid options are 'auto', 'hours',
         'minutes', 'seconds', 'milliseconds' and 'microseconds'.
+
+        The UTC offset will be replaced with 'Z' if use_utc_designator
+        is True and self.tzname() is exactly 'UTC'.
         """
         s = ("%04d-%02d-%02d%c" % (self._year, self._month, self._day, sep) +
              _format_time(self._hour, self._minute, self._second,
                           self._microsecond, timespec))
 
         off = self.utcoffset()
-        tz = _format_offset(off)
-        if tz:
-            s += tz
+        if use_utc_designator and (self.tzinfo is timezone.utc or self.tzname() == 'UTC'):
+            s += 'Z'
+        else:
+            tz = _format_offset(off)
+            if tz:
+                s += tz
 
         return s