Usually I can count on Python and Python libraries being consistent out of the box :), but instead pytz
has opted to provide a "normalize" function, that we as developers need to be aware of when doing time zone conversions. The problem in that the problem is inconsistent and it forces us (the developers) to make the decision on how to handle all the craziness ourselves, cause the library author cannot decide for us.
http://pytz.sourceforge.net/#localized-times-and-date-arithmetic seems like a MUST READ.
Note that this library differs from the documented Python API for tzinfo implementations; if you want to create local wallclock times you need to use the localize() method documented in this document. In addition, if you perform date arithmetic on local times that cross DST boundaries, the result may be in an incorrect timezone (ie. subtract 1 minute from 2002-10-27 1:00 EST and you get 2002-10-27 0:59 EST instead of the correct 2002-10-27 1:59 EDT). A normalize() method is provided to correct this. Unfortunately these issues cannot be resolved without modifying the Python datetime implementation.
This is very unpythonic in that there is more then one way to do things that work. ie. For UTC normalize
and localize
are not necessary, and we can observe things working until we actually cross DST - STD boundaries when working with other time zones, but in this case I'm not sure the alternative would have been any better (breaking code that uses the standard datetime API). I certainly would have preferred a stacktrace instead of a silently bad astimezone conversion.
I really put the fault on the datetime
documentation:
http://docs.python.org/2/library/datetime.html#datetime.datetime.astimezone
Which mentions pytz and that this is where to get some tzinfo objects, but doesn't mention that you better read their documentation for caveats.