search

microsoft / yardl

Tooling for streaming instrument data
https://microsoft.github.io/yardl/
MIT License
29 stars 5 forks source link

time zone handling in documentation #66

Open KrisThielemans opened 10 months ago

KrisThielemans commented 10 months ago

https://microsoft.github.io/yardl/reference/binary.html#dates-times-and-datetimes isn't clear on time zone handling. DateTimes is clear enough, (although a reference to what "since epoch" means would be good) but the doc on Dates and Times should say this is in UTC presumably. That might be undesirable/confusing though, so maybe it's better to support time zones spec.

Also, I'm assuming the types are actually singular, e.g. DateTime. I think a different font needs to be used for the actual type name (like you use for float etc).

johnstairs commented 10 months ago

That's good feedback. One of the challenges is that Numpy's datetime64 type does not store time zone offset information. So I think we either state that datetimes are "naive" and have no knowledge of time zones, or we say that they are assumed/required to be UTC. The other option is creating another data type that can be used in NumPy arrays that has time zone information. But that will bring other challenges and perhaps complicate adoption.

KrisThielemans commented 10 months ago

I don't care too much if numpy is limited. yardl shouldn't be 😄 .

If you say that DateTime is secs (or whatever) since the epoch, it is time zone dependent. The epoch is a specific time in UTC.

I have no idea how "seconds since epoch" is computed (i.e. taking leap years/seconds etc into account or not). There's probably an RFC or other standard on that somewhere, which you could/should refer to.

An apparently frequently referenced/debated set of suggestions is https://apiux.com/2013/03/20/5-laws-api-dates-and-times/

By the way, I think that using "nanosecs since epoch" is probably asking for trouble, given possible uncertainty on leap secs and all that. This goes well beyond what I know about time conventions though.

We do need a "TimeZone" type I believe. We definitely want to be able to store this.