
Maya – Datetime for Humans - ra7
https://github.com/kennethreitz/maya
======
niftich
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...](https://github.com/kennethreitz/maya/commit/ecd0166ba215c1a5caa778c0a4f7ce51820a5615)
[2]
[https://pendulum.eustace.io/docs/#instantiation](https://pendulum.eustace.io/docs/#instantiation)
[3]
[http://delorean.readthedocs.io/en/latest/quickstart.html#nat...](http://delorean.readthedocs.io/en/latest/quickstart.html#natural-
language) [4] [http://crsmithdev.com/arrow/#replace-
shift](http://crsmithdev.com/arrow/#replace-shift) [5]
[https://news.ycombinator.com/item?id=12364805](https://news.ycombinator.com/item?id=12364805)

