Add NaiveDateTime and AwareDateTime

[lafrech]

Closes #1234.

[sloria]

Is NaiveDateTime necessary? What's the use case?

[lafrech]

In Python, naive and aware datetimes are different objects with different properties and some operations only work on either naive or aware datetimes. I was caught by this already (https://github.com/lepture/flask-oauthlib/issues/294). Being able to enforce the type is therefore a must have IMHO. Otherwise, the user needs to do it manually.

Whether it is done by a specific class or a flag is an implementation choice. I think different classes is better, more explicit. Generally we have a class for a type and the flags are just parameters.

[sloria]

It makes sense to have validation that an input datetime includes timezone info, but I'm more curious about cases when you want to enforce naiveness. Or is it more about having symmetry?

[lafrech]

Symmetry would be good enough a reason for me, since it is relatively easy to achieve.

This issue is an example of a lib that expects a naive datetime and will fail if fed an aware datetime. I don't use it anymore, but by the time, I had to enforce naiveness myself manually.

This issue can be extended to every use case involving date comparisons.

If the API stores datetimes, it most likely wants to enforce the type, if only to allow the user to sort objects by datetime. Perhaps most of the time, the DB driver will uniformize the format, by making a silent choice to force aware or naive, but I think this should be the role of the deserialization layer.

Maybe I'm missing something because once I fell into this, I figured it was something marshmallow absolutely needed to address, but since then, I heard no one complain, so maybe it is not such an issue in practice.

(In any case, I'd still consider this PR relevant, as it comes with a nice cleanup, hopefully no regression, and a code easier to maintain and with better test coverage.)

[sloria]

Sure, I'm fine with that reasoning and with going forward with this. Will take a closer look hopefully over the next few days.

[deckar01]

I heard no one complain

I suspect loading datetimes is just not a very common behavior of most apps. Not until I made a webcam timelapse scheduler recently did I ever have to accept a datetime from the user.

[sloria]

I'm basically good with this. My comments are nits. Once this is polished up, should be good to merge. 🎉

[lafrech]

Rebased and documented.

Feedback welcome.

I'm open to changes, especially about the new parameter names. And the docs.

[sloria]

Looking awesome. Nice job with the tests. Just nits left.

[lafrech]

Rebased. Remarks addressed.

[sloria]

Very nice. Can you update the changelog then merge?

🚢 🇮🇹