Any differences between datetime and phony datetimes?

[mcgibbon]

I've written a PR for Sympl (code) to start integrating netcdftime datetime-like objects into Sympl models. Since the documentation is quite sparse and a little vague, I thought I should ask if there are any differences between the built-in datetime and netcdftime's datetime-like objects that I should be aware of and warn users about? You're welcome to comment on the PR directly.

I was also confused as to why there was a DatetimeProlepticGregorian to override the built-in datetime, so I've used the built-in one instead for that calendar option. Any insight into whether this is a good idea would be appreciated.

[jswhit]

The built-in datetime only works for years > 1. The 'phony' datetime objects are needed to support other calendars besides proleptic_gregorian, and years < 1. They do not contain all the functionality of the the built-in python datetime objects.

[mcgibbon]

Ah, the years makes sense.

Is there an exhaustive (or even partial) list of what functionality the netcdftime objects do not contain from built-in python datetime objects?

[jswhit]

netcdftime.datetime only has strftime, replace, timetuple, repr, to_tuple, __richcmp__

[ckhroulev]

netcdftime.datetime only has strftime, replace, timetuple, repr, to_tuple,__richcmp__

netcdftime.datetime also implements __sub__, __add__, and __radd__ (see Unidata/netcdf4-python#593).

[mcgibbon]

I'm more curious about what netcdftime.datetime is missing, than in what it has.

Could someone answer my question in plain English, if they understand the differences in those terms? I can dir the two and compare myself, but it's a lot of work to go in through code/docstrings and grok what all of these methods are/do. Particularly because the docstrings for these things (including built-in datetime) are not very descriptive. If nobody does, I'll go in and figure it out, and write some documentation so everyone doesn't have to go through this.

One example is that built-in datetimes manage timezones, while netcdftime does not.

[jswhit]

I'm telling you what I know. You'll have to compare the methods in python datetime to the methods supplied by netcdf.datetime if you want more.

Note that netcdf.datetime will be a python datetime instance in most cases - only if the python datetime object doesn't support the requested calendar or times will a 'phony' datetime instance be returned.

It would be pretty easy to write a function to request something like a timezone from the object to determine if it's a python datetime object or not.

[mcgibbon]

Thank you for sharing what you know! I wasn't trying to passive-aggressively direct my comment at you, I am genuinely asking if there are others looking at this who can give another answer. Maybe @jhamman, @shoyer, @spencerkclark, @ckhroulev or others know more?

Like I said, I'll go through the methods (likely regardless of responses here), but there are some things that might not be revealed by doing that. I'd like to get as much feedback as I can. For example, Datetime360Day's __init__ docstring is just x.__init__(...) initializes x; see help(type(x)) for signature, and help(Datetime360Day), and help(type(dt)) shows exactly the same docstring (with no signature). I wouldn't catch that you can't pass in timezones unless I tried it manually or already knew about it.

I've written my own datetime selector as a workaround for the issue where if the current (or older) versions of netcdf4 are installed, the netcdf4 version of netcdftime will be imported. So I'll always know what type I'm returning.

[shoyer]

netcdftime.num2date will create real datetime.datetime instances when possible (though this may be ill-advised), but netcdftime.datetime is always it's own class.

I don't think there's much to be done other than looking at the methods right now. Obviously API docs would be nice to have at some point in the future.

Offhand, netcdftime does not support timezones or the alternative datetime constructors (like datetime.today()) from the datetime module

[jhamman]

@mcgibbon - is there more to discuss here?

[mcgibbon]

@jhamman the discussion leads me to think someone should open a new issue for writing complete API docs. But I'll close this one, since I got what answers were available.

[jhamman]

Thanks @mcgibbon - additional issues/help developing the documentation would be much appreciated.