diff -r 4feb10457c13 -r 574aeece098f 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 16:22:06 2012 +1000 @@ -1005,25 +1005,51 @@ .. 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. + + The offset is positive for timezones east from UTC, negative for timezones + west from UTC. + + If :attr:`tzinfo` is ``None``, return ``None``. Otherwise, call + ``self.tzinfo.utcoffset(self)`` and return the result if it is valid. + + Valid offset values are :class:`timedelta` values (if not, raise + :class:`TypeError`) of a whole number of minutes with a magnitude no 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. + + The offset is positive for timezones east from UTC, negative for timezones + west from UTC. + + If :attr:`tzinfo` is ``None``, return ``None``. Otherwise, call + ``self.tzinfo.dst(self)`` and return the result if it is valid. + + Valid offset values are :class:`timedelta` values (if not, raise + :class:`TypeError`) of a whole number of minutes with a magnitude no larger + than 24 hours (if not, raise :class:`ValueError`). + + This is purely informational; the DST offset is already 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`. + + Note that the name is 100% informational – there's no requirement that it + mean anything in particular. For example, ``"GMT"``, ``"UTC"``, ``"-500"``, + ``"-5:00"``, ``"EDT"``, ``"US/Eastern"``, ``"America/New York"`` are all + valid replies. .. method:: datetime.timetuple() @@ -1902,3 +1928,4 @@ .. rubric:: Footnotes .. [#] If, that is, we ignore the effects of Relativity + diff -r 4feb10457c13 -r 574aeece098f Lib/datetime.py --- a/Lib/datetime.py Sun Aug 19 17:45:40 2012 -0400 +++ b/Lib/datetime.py Mon Aug 20 16:22:06 2012 +1000 @@ -928,15 +928,11 @@ 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. - - Return 0 if DST not in effect. utcoffset() must include the DST - offset. - """ + "datetime -> DST offset from UTC, as a ``timedelta`` value." raise NotImplementedError("tzinfo subclass must override dst()") def fromutc(self, dt): @@ -1207,8 +1203,7 @@ # Timezone functions def utcoffset(self): - """Return the timezone offset in minutes east of UTC (negative west of - UTC).""" + """Return the timezone's offset from UTC, as a ``timedelta`` value.""" if self._tzinfo is None: return None offset = self._tzinfo.utcoffset(None) @@ -1229,13 +1224,8 @@ 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. - - 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. + """ + Return the timezone's DST offset from UTC, as a ``timedelta`` value. """ if self._tzinfo is None: return None @@ -1615,9 +1605,6 @@ def tzname(self): """Return the timezone name. - Note that the name is 100% informational -- there's no requirement that - it mean anything in particular. For example, "GMT", "UTC", "-500", - "-5:00", "EDT", "US/Eastern", "America/New York" are all valid replies. """ name = _call_tzinfo_method(self._tzinfo, "tzname", self) _check_tzname(name) @@ -1626,11 +1613,6 @@ def dst(self): """Return 0 if DST is not in effect, or the DST offset (in minutes eastward) if DST is 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 - need to consult dst() unless you're interested in displaying the DST - info. """ if self._tzinfo is None: return None @@ -1881,12 +1863,14 @@ return self.tzname(None) def utcoffset(self, dt): + """datetime -> timezone's offset from UTC, as a ``timedelta`` value.""" if isinstance(dt, datetime) or dt is None: return self._offset raise TypeError("utcoffset() argument must be a datetime instance" " or None") def tzname(self, dt): + """datetime -> timezone name.""" if isinstance(dt, datetime) or dt is None: if self._name is None: return self._name_from_offset(self._offset) @@ -1895,12 +1879,16 @@ " or None") def dst(self, dt): + """ + datetime -> timezone's DST offset from UTC, as a ``timedelta`` value. + """ if isinstance(dt, datetime) or dt is None: return None raise TypeError("dst() argument must be a datetime instance" " or None") def fromutc(self, dt): + """datetime in UTC -> datetime in local time.""" if isinstance(dt, datetime): if dt.tzinfo is not self: raise ValueError("fromutc: dt.tzinfo " diff -r 4feb10457c13 -r 574aeece098f Modules/_datetimemodule.c --- a/Modules/_datetimemodule.c Sun Aug 19 17:45:40 2012 -0400 +++ b/Modules/_datetimemodule.c Mon Aug 20 16:22:06 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) @@ -3126,11 +3117,12 @@ 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( + "datetime -> timezone offset from UTC, as a timedelta value.")}, {"dst", (PyCFunction)tzinfo_dst, METH_O, - PyDoc_STR("datetime -> DST offset in minutes east of UTC.")}, + PyDoc_STR( + "datetime -> timezone DST offset from UTC, as a timedelta value.")}, {"fromutc", (PyCFunction)tzinfo_fromutc, METH_O, PyDoc_STR("datetime in UTC -> datetime in local time.")},