Index: Doc/library/datetime.rst =================================================================== --- Doc/library/datetime.rst (revision 86565) +++ Doc/library/datetime.rst (working copy) @@ -1370,8 +1370,8 @@ .. method:: tzinfo.utcoffset(dt) - Return offset of local time from UTC, in minutes east of UTC. If local time is - west of UTC, this should be negative. Note that this is intended to be the + Returns offset of local time from UTC as a :class:`timedelta` object. One must + add this offset to UTC to arrive at local time. Note that this is intended to be the total offset from UTC; for example, if a :class:`tzinfo` object represents both time zone and DST adjustments, :meth:`utcoffset` should return their sum. If the UTC offset isn't known, return ``None``. Else the value returned must be a @@ -1392,12 +1392,13 @@ .. method:: tzinfo.dst(dt) - Return the daylight saving time (DST) adjustment, in minutes east of UTC, or - ``None`` if DST information isn't known. Return ``timedelta(0)`` if DST is not - in effect. If DST is in effect, return the offset as a :class:`timedelta` object - (see :meth:`utcoffset` for details). Note that DST offset, if applicable, has - already been added to the UTC offset returned by :meth:`utcoffset`, so there's - no need to consult :meth:`dst` unless you're interested in obtaining DST info + Returns the daylight saving time (DST) adjustment as a :class:`timedelta` object. + This represents the offset in minutes that must be added to the local time zone to + follow DST rules. If DST information is unknown, returns ``None``. Returns + ``timedelta(0)`` if DST is not in effect. If DST is in effect, returns the offset as a + :class:`timedelta` object (see :meth:`utcoffset` for details). Note that DST offset, + if applicable, has already been added to the UTC offset returned by :meth:`utcoffset`, + so there's no need to consult :meth:`dst` unless you're interested in obtaining DST info separately. For example, :meth:`datetime.timetuple` calls its :attr:`tzinfo` member's :meth:`dst` method to determine how the :attr:`tm_isdst` flag should be set, and :meth:`tzinfo.fromutc` calls :meth:`dst` to account for DST changes Index: Doc/includes/tzinfo-examples.py =================================================================== --- Doc/includes/tzinfo-examples.py (revision 86565) +++ Doc/includes/tzinfo-examples.py (working copy) @@ -24,7 +24,7 @@ # UTC tzinfo object. class FixedOffset(tzinfo): - """Fixed offset in minutes east from UTC.""" + """Fixed offset in minutes from UTC.""" def __init__(self, offset, name): self.__offset = timedelta(minutes = offset) Index: Lib/datetime.py =================================================================== --- Lib/datetime.py (revision 86565) +++ Lib/datetime.py (working copy) @@ -928,11 +928,11 @@ raise NotImplementedError("tzinfo subclass must override tzname()") def utcoffset(self, dt): - "datetime -> minutes east of UTC (negative for west of UTC)" + "Returns offset of local time from UTC as a timedelta object." raise NotImplementedError("tzinfo subclass must override utcoffset()") def dst(self, dt): - """datetime -> DST offset in minutes east of UTC. + """Returns the daylight saving time (DST) adjustment as a timedelta object. Return 0 if DST not in effect. utcoffset() must include the DST offset. @@ -1204,8 +1204,7 @@ # Timezone functions def utcoffset(self): - """Return the timezone offset in minutes east of UTC (negative west of - UTC).""" + """Returns offset of local time from UTC as a timedelta object.""" if self._tzinfo is None: return None offset = self._tzinfo.utcoffset(None) @@ -1226,9 +1225,10 @@ return name def dst(self): - """Return 0 if DST is not in effect, or the DST offset (in minutes - eastward) if DST is in effect. + """Returns the daylight saving time (DST) adjustment as a timedelta object. + Returns timedelta(0) if DST is not in effect, or the offset in minutes. + This is purely informational; the DST offset has already been added to the UTC offset returned by utcoffset() if applicable, so there's no need to consult dst() unless you're interested in displaying the DST @@ -1568,8 +1568,7 @@ return _strptime._strptime_datetime(cls, date_string, format) def utcoffset(self): - """Return the timezone offset in minutes east of UTC (negative west of - UTC).""" + """Returns offset of local time from UTC as a timedelta object.""" if self._tzinfo is None: return None offset = self._tzinfo.utcoffset(self) @@ -1588,9 +1587,10 @@ return name def dst(self): - """Return 0 if DST is not in effect, or the DST offset (in minutes - eastward) if DST is in effect. + """Returns the daylight saving time (DST) adjustment as a timedelta object. + Returns timedelta(0) if DST is not in effect, or the offset in minutes. + This is purely informational; the DST offset has already been added to the UTC offset returned by utcoffset() if applicable, so there's no need to consult dst() unless you're interested in displaying the DST Index: Modules/_datetimemodule.c =================================================================== --- Modules/_datetimemodule.c (revision 86565) +++ Modules/_datetimemodule.c (working copy) @@ -915,7 +915,7 @@ * doesn't return None or timedelta, TypeError is raised and this returns -1. * If utcoffset() returns an invalid timedelta (out of range, or not a whole * # of minutes), ValueError is raised and this returns -1. Else *none is - * set to 0 and the offset is returned (as int # of minutes east of UTC). + * set to 0 and the offset from UTC is returned as int # of minutes. */ static PyObject * call_utcoffset(PyObject *tzinfo, PyObject *tzinfoarg) @@ -929,7 +929,7 @@ & 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 an int # of minutes east of UTC). + * the offset from local time zone is returned as an int # of minutes. */ static PyObject * call_dst(PyObject *tzinfo, PyObject *tzinfoarg) @@ -3152,11 +3152,11 @@ 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("Returns offset of local time from UTC as a timedelta object.")}, {"dst", (PyCFunction)tzinfo_dst, METH_O, - PyDoc_STR("datetime -> DST offset in minutes east of UTC.")}, + PyDoc_STR("Returns the daylight saving time (DST) adjustment as a " + "timedelta object.")}, {"fromutc", (PyCFunction)tzinfo_fromutc, METH_O, PyDoc_STR("datetime in UTC -> datetime in local time.")},