tools/src/nas,5.n2.os.2/lib/python/html/python/lib/datetime-tzinfo.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="lib.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index' />
<link rel="first" href="lib.html" title='Python Library Reference' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="node257.html" />
<link rel="prev" href="datetime-time.html" />
<link rel="parent" href="module-datetime.html" />
<link rel="next" href="node257.html" />
<meta name='aesop' content='information' />
<title>6.10.6 tzinfo Objects </title>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="6.10.5 time Objects"
  href="datetime-time.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="6.10 datetime  "
  href="module-datetime.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="6.10.7 strftime() Behavior"
  href="node257.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="datetime-time.html">6.10.5 time Objects</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-datetime.html">6.10 datetime  </A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="node257.html">6.10.7 strftime() Behavior</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H2><A NAME="SECTION0081060000000000000000"></A><A NAME="datetime-tzinfo"></A>
<BR>
6.10.6 <tt class="class">tzinfo</tt> Objects
</H2>

<P>
<tt class="class">tzinfo</tt> is an abstract base clase, meaning that this class
should not be instantiated directly.  You need to derive a concrete
subclass, and (at least) supply implementations of the standard
<tt class="class">tzinfo</tt> methods needed by the <tt class="class">datetime</tt> methods you
use.  The <tt class="module">datetime</tt> module does not supply any concrete
subclasses of <tt class="class">tzinfo</tt>.

<P>
An instance of (a concrete subclass of) <tt class="class">tzinfo</tt> can be passed
to the constructors for <tt class="class">datetime</tt> and <tt class="class">time</tt> objects.
The latter objects view their members as being in local time, and the
<tt class="class">tzinfo</tt> object supports methods revealing offset of local time
from UTC, the name of the time zone, and DST offset, all relative to a
date or time object passed to them.

<P>
Special requirement for pickling:  A <tt class="class">tzinfo</tt> subclass must have an
<tt class="method">__init__</tt> method that can be called with no arguments, else it
can be pickled but possibly not unpickled again.  This is a technical
requirement that may be relaxed in the future.

<P>
A concrete subclass of <tt class="class">tzinfo</tt> may need to implement the
following methods.  Exactly which methods are needed depends on the
uses made of aware <tt class="module">datetime</tt> objects.  If in doubt, simply
implement all of them.

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1940' xml:id='l2h-1940' class="method">utcoffset</tt></b>(</nobr></td>
  <td><var>self, dt</var>)</td></tr></table></dt>
<dd>
  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 total offset from UTC; for example, if a
  <tt class="class">tzinfo</tt> object represents both time zone and DST adjustments,
  <tt class="method">utcoffset()</tt> should return their sum.  If the UTC offset
  isn't known, return <code>None</code>.  Else the value returned must be
  a <tt class="class">timedelta</tt> object specifying a whole number of minutes in the
  range -1439 to 1439 inclusive (1440 = 24*60; the magnitude of the offset
  must be less than one day).  Most implementations of
  <tt class="method">utcoffset()</tt> will probably look like one of these two:

<P>
<div class="verbatim"><pre>
    return CONSTANT                 # fixed-offset class
    return CONSTANT + self.dst(dt)  # daylight-aware class
</pre></div>

<P>
If <tt class="method">utcoffset()</tt> does not return <code>None</code>,
    <tt class="method">dst()</tt> should not return <code>None</code> either.

<P>
The default implementation of <tt class="method">utcoffset()</tt> raises
    <tt class="exception">NotImplementedError</tt>.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1941' xml:id='l2h-1941' class="method">dst</tt></b>(</nobr></td>
  <td><var>self, dt</var>)</td></tr></table></dt>
<dd>
  Return the daylight saving time (DST) adjustment, in minutes east of
  UTC, or <code>None</code> if DST information isn't known.  Return
  <code>timedelta(0)</code> if DST is not in effect.
  If DST is in effect, return the offset as a
  <tt class="class">timedelta</tt> object (see <tt class="method">utcoffset()</tt> for details).
  Note that DST offset, if applicable, has
  already been added to the UTC offset returned by
  <tt class="method">utcoffset()</tt>, so there's no need to consult <tt class="method">dst()</tt>
  unless you're interested in obtaining DST info separately.  For
  example, <tt class="method">datetime.timetuple()</tt> calls its <tt class="member">tzinfo</tt>
  member's <tt class="method">dst()</tt> method to determine how the
  <tt class="member">tm_isdst</tt> flag should be set, and
  <tt class="method">tzinfo.fromutc()</tt> calls <tt class="method">dst()</tt> to account for
  DST changes when crossing time zones.

<P>
An instance <var>tz</var> of a <tt class="class">tzinfo</tt> subclass that models both
  standard and daylight times must be consistent in this sense:

<P>
<code><var>tz</var>.utcoffset(<var>dt</var>) - <var>tz</var>.dst(<var>dt</var>)</code>

<P>
must return the same result for every <tt class="class">datetime</tt> <var>dt</var>
  with <code><var>dt</var>.tzinfo == <var>tz</var></code>  For sane <tt class="class">tzinfo</tt>
  subclasses, this expression yields the time zone's "standard offset",
  which should not depend on the date or the time, but only on geographic
  location.  The implementation of <tt class="method">datetime.astimezone()</tt> relies
  on this, but cannot detect violations; it's the programmer's
  responsibility to ensure it.  If a <tt class="class">tzinfo</tt> subclass cannot
  guarantee this, it may be able to override the default implementation
  of <tt class="method">tzinfo.fromutc()</tt> to work correctly with <tt class="method">astimezone()</tt>
  regardless.

<P>
Most implementations of <tt class="method">dst()</tt> will probably look like one
  of these two:

<P>
<div class="verbatim"><pre>
    def dst(self):
        # a fixed-offset class:  doesn't account for DST
        return timedelta(0)
</pre></div>

<P>
or

<P>
<div class="verbatim"><pre>
    def dst(self):
        # Code to set dston and dstoff to the time zone's DST
        # transition times based on the input dt.year, and expressed
        # in standard local time.  Then

        if dston &lt;= dt.replace(tzinfo=None) &lt; dstoff:
            return timedelta(hours=1)
        else:
            return timedelta(0)
</pre></div>

<P>
The default implementation of <tt class="method">dst()</tt> raises
  <tt class="exception">NotImplementedError</tt>.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1942' xml:id='l2h-1942' class="method">tzname</tt></b>(</nobr></td>
  <td><var>self, dt</var>)</td></tr></table></dt>
<dd>
  Return the time zone name corresponding to the <tt class="class">datetime</tt>
  object <var>dt</var>, as a string.
  Nothing about string names is defined by the
  <tt class="module">datetime</tt> module, and 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.  Return
  <code>None</code> if a string name isn't known.  Note that this is a method
  rather than a fixed string primarily because some <tt class="class">tzinfo</tt>
  subclasses will wish to return different names depending on the specific
  value of <var>dt</var> passed, especially if the <tt class="class">tzinfo</tt> class is
  accounting for daylight time.

<P>
The default implementation of <tt class="method">tzname()</tt> raises
  <tt class="exception">NotImplementedError</tt>.
</dl>

<P>
These methods are called by a <tt class="class">datetime</tt> or <tt class="class">time</tt> object,
in response to their methods of the same names.  A <tt class="class">datetime</tt>
object passes itself as the argument, and a <tt class="class">time</tt> object passes
<code>None</code> as the argument.  A <tt class="class">tzinfo</tt> subclass's methods should
therefore be prepared to accept a <var>dt</var> argument of <code>None</code>, or of
class <tt class="class">datetime</tt>.

<P>
When <code>None</code> is passed, it's up to the class designer to decide the
best response.  For example, returning <code>None</code> is appropriate if the
class wishes to say that time objects don't participate in the
<tt class="class">tzinfo</tt> protocols.  It may be more useful for <code>utcoffset(None)</code>
to return the standard UTC offset, as there is no other convention for
discovering the standard offset.

<P>
When a <tt class="class">datetime</tt> object is passed in response to a
<tt class="class">datetime</tt> method, <code>dt.tzinfo</code> is the same object as
<var>self</var>.  <tt class="class">tzinfo</tt> methods can rely on this, unless
user code calls <tt class="class">tzinfo</tt> methods directly.  The intent is that
the <tt class="class">tzinfo</tt> methods interpret <var>dt</var> as being in local time,
and not need worry about objects in other timezones.

<P>
There is one more <tt class="class">tzinfo</tt> method that a subclass may wish to
override:

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1943' xml:id='l2h-1943' class="method">fromutc</tt></b>(</nobr></td>
  <td><var>self, dt</var>)</td></tr></table></dt>
<dd>
  This is called from the default <tt class="class">datetime.astimezone()</tt>
  implementation.  When called from that, <code><var>dt</var>.tzinfo</code> is
  <var>self</var>, and <var>dt</var>'s date and time members are to be viewed as
  expressing a UTC time.  The purpose of <tt class="method">fromutc()</tt> is to
  adjust the date and time members, returning an equivalent datetime in
  <var>self</var>'s local time.

<P>
Most <tt class="class">tzinfo</tt> subclasses should be able to inherit the default
  <tt class="method">fromutc()</tt> implementation without problems.  It's strong enough
  to handle fixed-offset time zones, and time zones accounting for both
  standard and daylight time, and the latter even if the DST transition
  times differ in different years.  An example of a time zone the default
  <tt class="method">fromutc()</tt> implementation may not handle correctly in all cases
  is one where the standard offset (from UTC) depends on the specific date
  and time passed, which can happen for political reasons.
  The default implementations of <tt class="method">astimezone()</tt> and
  <tt class="method">fromutc()</tt> may not produce the result you want if the result is
  one of the hours straddling the moment the standard offset changes.

<P>
Skipping code for error cases, the default <tt class="method">fromutc()</tt>
  implementation acts like:

<P>
<div class="verbatim"><pre>
  def fromutc(self, dt):
      # raise ValueError error if dt.tzinfo is not self
      dtoff = dt.utcoffset()
      dtdst = dt.dst()
      # raise ValueError if dtoff is None or dtdst is None
      delta = dtoff - dtdst  # this is self's standard offset
      if delta:
          dt += delta   # convert to standard local time
          dtdst = dt.dst()
          # raise ValueError if dtdst is None
      if dtdst:
          return dt + dtdst
      else:
          return dt
</pre></div>
</dl>

<P>
Example <tt class="class">tzinfo</tt> classes:

<P>
<div class="verbatim">
<pre>from datetime import tzinfo, timedelta, datetime

ZERO = timedelta(0)
HOUR = timedelta(hours=1)

# A UTC class.

class UTC(tzinfo):
    """UTC"""

    def utcoffset(self, dt):
        return ZERO

    def tzname(self, dt):
        return "UTC"

    def dst(self, dt):
        return ZERO

utc = UTC()

# A class building tzinfo objects for fixed-offset time zones.
# Note that FixedOffset(0, "UTC") is a different way to build a
# UTC tzinfo object.

class FixedOffset(tzinfo):
    """Fixed offset in minutes east from UTC."""

    def __init__(self, offset, name):
        self.__offset = timedelta(minutes = offset)
        self.__name = name

    def utcoffset(self, dt):
        return self.__offset

    def tzname(self, dt):
        return self.__name

    def dst(self, dt):
        return ZERO

# A class capturing the platform's idea of local time.

import time as _time

STDOFFSET = timedelta(seconds = -_time.timezone)
if _time.daylight:
    DSTOFFSET = timedelta(seconds = -_time.altzone)
else:
    DSTOFFSET = STDOFFSET

DSTDIFF = DSTOFFSET - STDOFFSET

class LocalTimezone(tzinfo):

    def utcoffset(self, dt):
        if self._isdst(dt):
            return DSTOFFSET
        else:
            return STDOFFSET

    def dst(self, dt):
        if self._isdst(dt):
            return DSTDIFF
        else:
            return ZERO

    def tzname(self, dt):
        return _time.tzname[self._isdst(dt)]

    def _isdst(self, dt):
        tt = (dt.year, dt.month, dt.day,
              dt.hour, dt.minute, dt.second,
              dt.weekday(), 0, -1)
        stamp = _time.mktime(tt)
        tt = _time.localtime(stamp)
        return tt.tm_isdst &gt; 0

Local = LocalTimezone()

# A complete implementation of current DST rules for major US time zones.

def first_sunday_on_or_after(dt):
    days_to_go = 6 - dt.weekday()
    if days_to_go:
        dt += timedelta(days_to_go)
    return dt

# In the US, DST starts at 2am (standard time) on the first Sunday in April.
DSTSTART = datetime(1, 4, 1, 2)
# and ends at 2am (DST time; 1am standard time) on the last Sunday of Oct.
# which is the first Sunday on or after Oct 25.
DSTEND = datetime(1, 10, 25, 1)

class USTimeZone(tzinfo):

    def __init__(self, hours, reprname, stdname, dstname):
        self.stdoffset = timedelta(hours=hours)
        self.reprname = reprname
        self.stdname = stdname
        self.dstname = dstname

    def __repr__(self):
        return self.reprname

    def tzname(self, dt):
        if self.dst(dt):
            return self.dstname
        else:
            return self.stdname

    def utcoffset(self, dt):
        return self.stdoffset + self.dst(dt)

    def dst(self, dt):
        if dt is None or dt.tzinfo is None:
            # An exception may be sensible here, in one or both cases.
            # It depends on how you want to treat them.  The default
            # fromutc() implementation (called by the default astimezone()
            # implementation) passes a datetime with dt.tzinfo is self.
            return ZERO
        assert dt.tzinfo is self

        # Find first Sunday in April &amp; the last in October.
        start = first_sunday_on_or_after(DSTSTART.replace(year=dt.year))
        end = first_sunday_on_or_after(DSTEND.replace(year=dt.year))

        # Can't compare naive to aware objects, so strip the timezone from
        # dt first.
        if start &lt;= dt.replace(tzinfo=None) &lt; end:
            return HOUR
        else:
            return ZERO

Eastern  = USTimeZone(-5, "Eastern",  "EST", "EDT")
Central  = USTimeZone(-6, "Central",  "CST", "CDT")
Mountain = USTimeZone(-7, "Mountain", "MST", "MDT")
Pacific  = USTimeZone(-8, "Pacific",  "PST", "PDT")
</pre>
<div class="footer">
<a href="tzinfo-examples.txt" type="text/plain">Download as text (original file name: <span class="file">tzinfo-examples.py</span>).</a>
</div></div>

<P>
Note that there are unavoidable subtleties twice per year in a
<tt class="class">tzinfo</tt>
subclass accounting for both standard and daylight time, at the DST
transition points.  For concreteness, consider US Eastern (UTC -0500),
where EDT begins the minute after 1:59 (EST) on the first Sunday in
April, and ends the minute after 1:59 (EDT) on the last Sunday in October:

<P>
<div class="verbatim"><pre>
    UTC   3:MM  4:MM  5:MM  6:MM  7:MM  8:MM
    EST  22:MM 23:MM  0:MM  1:MM  2:MM  3:MM
    EDT  23:MM  0:MM  1:MM  2:MM  3:MM  4:MM

  start  22:MM 23:MM  0:MM  1:MM  3:MM  4:MM

    end  23:MM  0:MM  1:MM  1:MM  2:MM  3:MM
</pre></div>

<P>
When DST starts (the "start" line), the local wall clock leaps from 1:59
to 3:00.  A wall time of the form 2:MM doesn't really make sense on that
day, so <code>astimezone(Eastern)</code> won't deliver a result with
<code>hour == 2</code> on the
day DST begins.  In order for <tt class="method">astimezone()</tt> to make this
guarantee, the <tt class="method">rzinfo.dst()</tt> method must consider times
in the "missing hour" (2:MM for Eastern) to be in daylight time.

<P>
When DST ends (the "end" line), there's a potentially worse problem:
there's an hour that can't be spelled unambiguously in local wall time:
the last hour of daylight time.  In Eastern, that's times of
the form 5:MM UTC on the day daylight time ends.  The local wall clock
leaps from 1:59 (daylight time) back to 1:00 (standard time) again.
Local times of the form 1:MM are ambiguous.  <tt class="method">astimezone()</tt> mimics
the local clock's behavior by mapping two adjacent UTC hours into the
same local hour then.  In the Eastern example, UTC times of the form
5:MM and 6:MM both map to 1:MM when converted to Eastern.  In order for
<tt class="method">astimezone()</tt> to make this guarantee, the <tt class="method">tzinfo.dst()</tt>
method must consider times in the "repeated hour" to be in
standard time.  This is easily arranged, as in the example, by expressing
DST switch times in the time zone's standard local time.

<P>
Applications that can't bear such ambiguities should avoid using hybrid
<tt class="class">tzinfo</tt> subclasses; there are no ambiguities when using UTC, or
any other fixed-offset <tt class="class">tzinfo</tt> subclass (such as a class
representing only EST (fixed offset -5 hours), or only EDT (fixed offset
-4 hours)).

<P>

<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="6.10.5 time Objects"
  href="datetime-time.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="6.10 datetime  "
  href="module-datetime.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="6.10.7 strftime() Behavior"
  href="node257.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="datetime-time.html">6.10.5 time Objects</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-datetime.html">6.10 datetime  </A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="node257.html">6.10.7 strftime() Behavior</A>
</div>
</div>
<hr />
<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>