diff -r 4feb10457c13 -r b53be3cc1a8d Doc/library/datetime.rst --- a/Doc/library/datetime.rst Sun Aug 19 17:45:40 2012 -0400 +++ b/Doc/library/datetime.rst Mon Aug 20 13:12:45 2012 +1000 @@ -1005,25 +1005,38 @@ .. method:: datetime.utcoffset() - If :attr:`tzinfo` is ``None``, returns ``None``, else returns - ``self.tzinfo.utcoffset(self)``, and raises an exception if the latter doesn't - return ``None``, or a :class:`timedelta` object representing a whole number of - minutes with magnitude less than one day. + Get the offset from UTC as a :class:`timedelta` object. + + If :attr:`tzinfo` is ``None``, return ``None``. Otherwise, call + ``self.tzinfo.utcoffset(self)`` and return the result if it is valid. Valid + values are :class:`timedelta` values (if not, raise :class:`TypeError`) with + a magnitude of a whole number of minutes and larger than 24 hours (if not, + raise :class:`ValueError`). .. method:: datetime.dst() - If :attr:`tzinfo` is ``None``, returns ``None``, else returns - ``self.tzinfo.dst(self)``, and raises an exception if the latter doesn't return - ``None``, or a :class:`timedelta` object representing a whole number of minutes - with magnitude less than one day. + Get the DST offset from UTC as a :class:`timedelta` object, or + ``timedelta(0)`` if DST is not in effect. + + If :attr:`tzinfo` is ``None``, return ``None``. Otherwise, call + ``self.tzinfo.utcoffset(self)`` and return the result if it is valid. Valid + values are :class:`timedelta` values (if not, raise :class:`TypeError`) with + a magnitude of a whole number of minutes and larger than 24 hours (if not, + raise :class:`ValueError`). + + 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 info. .. method:: datetime.tzname() - If :attr:`tzinfo` is ``None``, returns ``None``, else returns - ``self.tzinfo.tzname(self)``, raises an exception if the latter doesn't return - ``None`` or a string object, + Get the time zone name. + + If :attr:`tzinfo` is ``None``, return ``None``. Otherwise, call + ``self.tzinfo.tzname(self)``; if the result is ``None`` or a string, return + the result, otherwise raise :class:`TypeError`. .. method:: datetime.timetuple() diff -r 4feb10457c13 -r b53be3cc1a8d Lib/datetime.py --- a/Lib/datetime.py Sun Aug 19 17:45:40 2012 -0400 +++ b/Lib/datetime.py Mon Aug 20 13:12:45 2012 +1000 @@ -928,14 +928,14 @@ raise NotImplementedError("tzinfo subclass must override tzname()") def utcoffset(self, dt): - "datetime -> minutes east of UTC (negative for west of UTC)" + "datetime -> offset from UTC, as a timedelta value." raise NotImplementedError("tzinfo subclass must override utcoffset()") def dst(self, dt): - """datetime -> DST offset in minutes east of UTC. + """datetime -> DST offset from UTC, as a timedelta value. - Return 0 if DST not in effect. utcoffset() must include the DST - offset. + Return timedelta(0) if DST not in effect. utcoffset() must include the + DST offset, so this offset is purely informational. """ raise NotImplementedError("tzinfo subclass must override dst()") diff -r 4feb10457c13 -r b53be3cc1a8d Modules/_datetimemodule.c --- a/Modules/_datetimemodule.c Sun Aug 19 17:45:40 2012 -0400 +++ b/Modules/_datetimemodule.c Mon Aug 20 13:12:45 2012 +1000 @@ -861,12 +861,13 @@ return tzinfo; } -/* Call getattr(tzinfo, name)(tzinfoarg), and check the result. tzinfo must - * be an instance of the tzinfo class. If the method returns None, this - * returns None. If the method doesn't return None or timedelta, TypeError is - * raised and this returns NULL. If it returns a timedelta and the value is - * out of range or isn't a whole number of minutes, ValueError is raised and - * this returns NULL. Else result is returned. +/* Call getattr(tzinfo, name)(tzinfoarg), and check the result. tzinfo must be + * an instance of the tzinfo class, or None. If tzinfo is None, or the method + * returns None, this returns None. If the method doesn't return None or a + * timedelta, TypeError is raised and this returns NULL. If the method returns + * a timedelta but the value is larger than 24 hours or isn't a whole number of + * minutes, ValueError is raised and this returns NULL. Else the timedelta + * value is returned. */ static PyObject * call_tzinfo_method(PyObject *tzinfo, char *name, PyObject *tzinfoarg) @@ -910,13 +911,8 @@ return offset; } -/* Call tzinfo.utcoffset(tzinfoarg), and extract an integer from the - * result. tzinfo must be an instance of the tzinfo class. If utcoffset() - * returns None, call_utcoffset returns 0 and sets *none to 1. If uctoffset() - * 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). +/* Call tzinfo.utcoffset(tzinfoarg) and return the result. tzinfo must be an + * instance of the tzinfo class, or None. If tzinfo is None, return None. */ static PyObject * call_utcoffset(PyObject *tzinfo, PyObject *tzinfoarg) @@ -924,13 +920,8 @@ return call_tzinfo_method(tzinfo, "utcoffset", tzinfoarg); } -/* Call tzinfo.dst(tzinfoarg), and extract an integer from the - * result. tzinfo must be an instance of the tzinfo class. If dst() - * returns None, call_dst returns 0 and sets *none to 1. If dst() - & 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). +/* Call tzinfo.dst(tzinfoarg) and return the result. tzinfo must be an instance + * of the tzinfo class, or None. If tzinfo is None, return None. */ static PyObject * call_dst(PyObject *tzinfo, PyObject *tzinfoarg)