Maya – Datetime for Humans

This doesn't seem to be a submission by the author himself, and the project is only two hours and five commits old, so take my very early comments with a grain of salt -- they refer to the progress as of this commit [1].

I love Requests -- its API design is fantastic, and manages to distill down most of a complex problem domain to a clean, dare-I-say, elegant API.

So I can eagerly anticipate this design applied to datetimes. But the progress being shown so far is definitely not it.

>>> tomorrow = maya.when('tomorrow')

<MayaDT epoch=1481919067.23>

Why is "tomorrow" a precise-to-centisecond, infinitesimally small point on a giant cosmic timeline? I'm reasonably sure it's an abstract concept that describes the calendar day that starts after the current calendar day ends.

At least, Pendulum normalizes tomorrow() and its ilk to represent midnight on the given day [2], while Delorean's natural language methods [3] like next_day() advance the day while leaving the time-of-day unchanged, but the method name makes this fairly clear.

Even Arrow, which is heavily inspired by Moment.js to the point of conflating every single datetime idea into the same class, opts for mutators that are still more clear [4].

> Timezones fit in here somewhere...

Yeah, this needs more work.

Java 8 / Threeten, and its predecessor Joda-Time took the approach of clearly modeling each and every concept that humans actually use to describe time; even if you take issue with their API, the designers have clearly done their homework, and their data model is solid.

Formats like TOML wrestled with datetimes and realized [5] that datetimes aren't just woefully underspecified in most other specs and APIs, but that they're frequently mis-modeled, so they adopted large portions of Threeten's data model. Cases like this should merit strong consideration from anyone trying to propose new datetime APIs today.

[1] https://github.com/kennethreitz/maya/commit/ecd0166ba215c1a5... [2] https://pendulum.eustace.io/docs/#instantiation [3] http://delorean.readthedocs.io/en/latest/quickstart.html#nat... [4] http://crsmithdev.com/arrow/#replace-shift [5] https://news.ycombinator.com/item?id=12364805