python · slateny · Mar 5, 2022 · Mar 5, 2022 · Apr 3, 2022 · Apr 3, 2022
@@ -1954,8 +1954,8 @@ Examples of working with a :class:`.time` object::

 .. method:: tzinfo.utcoffset(dt)

-   Return offset of local time from UTC, as a :class:`timedelta` object that is
-   positive east of UTC. If local time is west of UTC, this should be negative.
+   Return the difference between local time and UTC as a :class:`timedelta` object.
+   One must add this offset to UTC to arrive at local time.

   This represents the *total* offset from UTC; for example, if a
   :class:`tzinfo` object represents both time zone and DST adjustments,

@@ -1123,11 +1123,11 @@ def tzname(self, dt):
        raise NotImplementedError("tzinfo subclass must override tzname()")

    def utcoffset(self, dt):
-        "datetime -> timedelta, positive for east of UTC, negative for west of UTC"
+        "Return the difference between local time and UTC as a timedelta object."
        raise NotImplementedError("tzinfo subclass must override utcoffset()")

    def dst(self, dt):
-        """datetime -> DST offset as timedelta, positive for east of UTC.
+        """Return the DST offset as a timedelta object.

        Return 0 if DST not in effect.  utcoffset() must include the DST
        offset.
@@ -1466,8 +1466,7 @@ def __format__(self, fmt):
    # Timezone functions

    def utcoffset(self):
-        """Return the timezone offset as timedelta, positive east of UTC
-         (negative west of UTC)."""
+        """Return the difference between local time and UTC as a timedelta object."""
        if self._tzinfo is None:
            return None
        offset = self._tzinfo.utcoffset(None)
@@ -1488,8 +1487,8 @@ def tzname(self):
        return name

    def dst(self):
-        """Return 0 if DST is not in effect, or the DST offset (as timedelta
-        positive eastward) if DST is in effect.
+        """Return the DST offset as a timedelta object, or timedelta(0) if
+        DST is not in effect.

        This is purely informational; the DST offset has already been added to
        the UTC offset returned by utcoffset() if applicable, so there's no
@@ -1951,8 +1950,7 @@ def strptime(cls, date_string, format):
        return _strptime._strptime_datetime(cls, date_string, format)

    def utcoffset(self):
-        """Return the timezone offset as timedelta positive east of UTC (negative west of
-        UTC)."""
+        """Return the difference between local time and UTC as a timedelta object."""
        if self._tzinfo is None:
            return None
        offset = self._tzinfo.utcoffset(self)
@@ -1973,8 +1971,8 @@ def tzname(self):
        return name

    def dst(self):
-        """Return 0 if DST is not in effect, or the DST offset (as timedelta
-        positive eastward) if DST is in effect.
+        """Return the DST offset as a timedelta object, or timedelta(0) if
+        DST is not in effect.

        This is purely informational; the DST offset has already been added to
        the UTC offset returned by utcoffset() if applicable, so there's no

@@ -1199,7 +1199,7 @@ call_tzinfo_method(PyObject *tzinfo, const char *name, PyObject *tzinfoarg)
 * doesn't return None or timedelta, TypeError is raised and this returns -1.
 * If utcoffset() returns an out of range timedelta,
 * ValueError is raised and this returns -1.  Else *none is
- * set to 0 and the offset is returned (as timedelta, positive east of UTC).
+ * set to 0 and the offset from UTC is returned as an int number of minutes.
 */
 static PyObject *
 call_utcoffset(PyObject *tzinfo, PyObject *tzinfoarg)
@@ -1213,7 +1213,7 @@ call_utcoffset(PyObject *tzinfo, PyObject *tzinfoarg)
 * doesn't return None or timedelta, TypeError is raised and this
 * returns -1.  If dst() returns an invalid timedelta for a UTC offset,
 * ValueError is raised and this returns -1.  Else *none is set to 0 and
- * the offset is returned (as timedelta, positive east of UTC).
+ * the offset from local time is returned as an int number of minutes.
 */
 static PyObject *
 call_dst(PyObject *tzinfo, PyObject *tzinfoarg)
@@ -3790,11 +3790,11 @@ static PyMethodDef tzinfo_methods[] = {
     PyDoc_STR("datetime -> string name of time zone.")},

    {"utcoffset",       (PyCFunction)tzinfo_utcoffset,          METH_O,
-     PyDoc_STR("datetime -> timedelta showing offset from UTC, negative "
-           "values indicating West of UTC")},
+     PyDoc_STR("Return the difference between local time and UTC as a timedelta "
+        "object.")},

    {"dst",             (PyCFunction)tzinfo_dst,                METH_O,
-     PyDoc_STR("datetime -> DST offset as timedelta positive east of UTC.")},
+     PyDoc_STR("Return the DST offset as a timedelta object.")},

    {"fromutc",         (PyCFunction)tzinfo_fromutc,            METH_O,
     PyDoc_STR("datetime in UTC -> datetime in local time.")},