diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst index f447b7bc9491e4d..02c68382a6eede6 100644 --- a/Doc/library/datetime.rst +++ b/Doc/library/datetime.rst @@ -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, diff --git a/Lib/datetime.py b/Lib/datetime.py index 6bf37ccfab7ac86..ce527ab72bd7349 100644 --- a/Lib/datetime.py +++ b/Lib/datetime.py @@ -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 diff --git a/Modules/_datetimemodule.c b/Modules/_datetimemodule.c index ae97190bccbde09..96033f32b3b024d 100644 --- a/Modules/_datetimemodule.c +++ b/Modules/_datetimemodule.c @@ -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.")},