Maya: Datetimes for Humans™

Datetimes are very frustrating to work with in Python, especially when dealing with different locales on different systems. This library exists to make the simple things much easier, while admitting that time is an illusion (timezones doubly so).

Datetimes should be interacted with via an API written for humans.

Maya is mostly built around the headaches and use-cases around parsing datetime data from websites.

Basic Usage of Maya



In [33]:

    
import maya



In [34]:

    
maya.now()









    Out[34]:





<MayaDT epoch=1544809514.491009>



In [35]:

    
tomorrow = maya.when('tomorrow')
tomorrow









    Out[35]:





<MayaDT epoch=1544895914.872356>



In [36]:

    
tomorrow.slang_date()









    Out[36]:





'tomorrow'



In [37]:

    
tomorrow.slang_time()









    Out[37]:





'in 23 hours'



In [38]:

    
# Also: MayaDT.from_iso8601(...)
tomorrow.iso8601()









    Out[38]:





'2018-12-15T17:45:14.872356Z'



In [39]:

    
# Also: MayaDT.from_rfc2822(...)
tomorrow.rfc2822()









    Out[39]:





'Sat, 15 Dec 2018 17:45:14 GMT'



In [40]:

    
# Also: MayaDT.from_rfc3339(...)
tomorrow.rfc3339()









    Out[40]:





'2018-12-15T17:45:14.8Z'



In [41]:

    
tomorrow.datetime()









    Out[41]:





datetime.datetime(2018, 12, 15, 17, 45, 14, 872356, tzinfo=<UTC>)



In [42]:

    
# Automatically parse datetime strings and generate naive datetimes.
scraped = '2016-12-16 18:23:45.423992+00:00'
maya.parse(scraped).datetime(to_timezone='US/Eastern', naive=True)









    Out[42]:





datetime.datetime(2016, 12, 16, 13, 23, 45, 423992)



In [43]:

    
rand_day = maya.when('2011-02-07', timezone='US/Eastern')



In [44]:

    
# Maya speaks Python.
from datetime import datetime

maya.MayaDT.from_datetime(datetime.utcnow())









    Out[44]:





<MayaDT epoch=1544809518.275386>



In [45]:

    
import time

maya.MayaDT.from_struct(time.gmtime())









    Out[45]:





<MayaDT epoch=1544809518.0>



In [46]:

    
maya.MayaDT(time.time())









    Out[46]:





<MayaDT epoch=1544809520.426774>



In [47]:

    
rand_day.day









    Out[47]:





7



In [48]:

    
rand_day.add(days=10).day









    Out[48]:





17



In [49]:

    
# Always.
rand_day.timezone









    Out[49]:





'UTC'



In [50]:

    
# Range of hours in a day:
maya.intervals(start=maya.now(), end=maya.now().add(days=1), interval=60*60)









    Out[50]:





<generator object intervals at 0x10c54a308>



In [51]:

    
# snap modifiers
dt = maya.when('Mon, 21 Feb 1994 21:21:42 GMT')
dt.snap('@d+3h').rfc2822()









    Out[51]:





'Mon, 21 Feb 1994 03:00:00 GMT'

Advanced Usage of Maya

In addition to timestamps, Maya also includes a wonderfully powerful MayaInterval class, which represents a range of time (e.g. an event). With this class, you can perform a multitude of advanced calendar calculations with finesse and ease.

For example:



In [52]:

    
from maya import MayaInterval



In [53]:

    
# Create an event that is one hour long, starting now.
event_start = maya.now()
event_end = event_start.add(hours=1)



In [54]:

    
MayaInterval(start=event_start, end=event_end)









    Out[54]:





<MayaInterval start=<MayaDT epoch=1544809524.395196> end=<MayaDT epoch=1544813124.395196>>

From here, there are a number of methods available to you, which you can use to compare this event to another event.

Do your own experiments here...

Try maya youself by adding your code below and running your own experiments 👇



In [ ]:

    
import maya

# your code here
maya.