[python-win32] how to best use datetime objects in pywin32?

[Mark Hammond]

Hi all,
  As we've discussed before, the pywintypes Time object is fairly
fundamentally broken.  While the next pywin32 build for Python 2.x will
still use the old time objects, I think it makes sense for the py3k build to
make that switch unconditional from the very first release (its getting much
closer now!).  I hope to offer a transition plan for 2.x, but not in the
next release.

I've had some discussions with Jason Coombs, the author of the win32timezone
module, about some of this and particularly how win32timezone can help, but
we think it worth throwing out here for further discussion:

SYSTEMTIME, FILETIME and timezones
----------------------------------

* Windows documents a SYSTEMTIME as explicitly being UTC.  It therefore
makes sense to me that whenever the win32 API is providing a SYSTEMTIME
directly, we will create a datetime object with an explicit UTC timezone.

* FILETIMEs are a little less clear; Windows documents that FILETIMEs are
sometimes *stored* as UTC and sometimes stored as local time - but
experimentation shows that assuming the time was converted to a SYSTEMTIME
via FileTimeToSystemTime(), it will always some back as UTC.  This is true
for NTFS and FAT32 in my experiments, but anyone with direct experience here
is urged to speak now!  If things were indeed ambiguous, then we may be
forced to return a timezone naïve object here, but that would suck somewhat.

For some reason I can't articulate, it makes sense to me that when the API
provides a FILETIME object, we return the time with the *local* timezone
specified (eg, someone printing a FILETIME may expect to see localtime
rather than UTC).  On the other hand, I can't see a good reason to *not*
simply convert to a SYSTEMTIME and return UTC in all cases, as printing the
objects directly isn't really that common.  Thoughts?

Timezone naïve objects
----------------------

As described above, pywin32 will always return a "timezone aware" time when
we started with a FILETIME or SYSTEMTIME structure.  However, we still need
to support creating such objects from "time module" compatible integers.
When given this "time_t", pywin32 will create a timezone naïve object.
Further, "casual" use of the datetime module almost encourages timezone
naïve objects - datetime.now() and datetime.nowutc() both return timezone
naïve objects.

So, my question is: Assuming we want to set a time object into a SYSTEMTIME
or FILETIME structure, what should pywin32 do when faced with a timezone
naïve object?  I see only 2 options:

* Given the SYSTEMTIME assumes UTC and the object is timezone naïve, the
code could fail, refusing the temptation to guess.

* Assume that the user knows that they are doing, and just copy the time
elements to the structures.  In effect, this would be assuming a timezone
naïve object is already in UTC (FILETIMES again may be more complex - if the
target was a FILETIME I think we would want to assume whatever timezone we
*return* FILETIME objects in - which may be another argument for returning
FILETIMEs in UTC)

The first seems more attractive (ie, the user may *not* know what they are
doing, so forcing them to be explicit actually helps them), but may make
life painful (and already is painful for the test suite).  Eg, the below
would work:

>>> t1, t2, t3 = win32api.GetFileTimes("foo") # t1, t2, and t3 all 'tz
aware'
>>> win32api.SetFileTimes("foo", t1, t2, t2) # works.

But this would fail:
>>> now = datetime.datetime.now()
>>> win32api.SetFileTimes("foo", now, now, now) # fail - now is tz naïve.

instead we would be forcing the user to do something like:

>>> import win32timezone
>>> now = datetime.datetime.now(tzinfo=win32timezone.GetLocalTimeZone()) #
now tz aware...
>>> win32api.SetFileTimes("foo", now, now, now) # should work

I think the above is more than enough to kick start a discussion, so I'd
welcome all thoughts on the above.  FYI, I expect to mark the next pywin32
release as experimental/unstable/scary - particularly py3k support - and
part of that will be reserving the right to make changes to the datetime
support delivered in that first build, which should give us some time to
experiment without fully committing to the details.

Cheers,

Mark