Release v0.0.8 (What’s new?).
Welcome to the rolex
Documentation¶
A elegant datetime library.
- 100% Pure Python implementation.
- Faster datetime/date parser than
dateutil.parser.parse
. - Powerful parser convert other type to datetime/date.
- Easy to use high performance time series/random datetime, date generator.
- Relative time calculation (add seconds, hour, week, month, year …).
Contents
Install¶
rolex
is released on PyPI, so all you need is:
$ pip install rolex
To upgrade to latest version:
$ pip install --upgrade rolex
Usage¶
First, let’s import:
import rolex
from datetime import datetime, date
Parser¶
Parse anything to datetime
:
# parse string
>>> rolex.parse_datetime("2014-01-15T17:58:31Z-0400")
datetime.datetime(2014, 1, 15, 17, 58, 31, tzinfo=datetime.timezone(datetime.timedelta(-1, 72000)))
# parse numbers by mean of timestamps from epoch
>>> rolex.parse_datetime(1234567890)
datetime.datetime(2009, 2, 13, 23, 31, 30)
# convert date to datetime
>>> rolex.parse_datetime(date(2015, 12, 24))
datetime.datetime(2015, 12, 24, 0, 0)
# remains datetime
>>> rolex.parse_datetime(datetime(2015, 11, 24, 20, 30))
datetime.datetime(2015, 11, 24, 20, 30)
Also works fine with date
:
# parse string
>>> rolex.parse_date("Saturday, September 20, 2014")
datetime.date(2014, 9, 20)
# parse numbers by mean of days from ordinary 0000-01-01
>>> rolex.parse_date(720000)
datetime.date(1972, 4, 17)
...
If rolex meets a unknown time format, automatically, it will start using dateutil. So if rolex CAN NOT parse the string, then dateutil can’t either. But rolex’s built in method is 4x times faster than dateutil
for known format. If rolex
failed to parse your string, please submit it to https://github.com/MacHu-GWU/rolex-project/issues.
Timestamp¶
Python2 doesn’t implement datetime.timestamp()
. And in Python3, it assume that it’s a local time by default, for example:
>>> datetime(1970, 1, 1).timestamp() # In Python3
18000 # New York Time Zone, it should be zero
That’s not good!
rolex
provide more flexibility:
to_utctimestamp()
: assume it’s utc time if it is a naive datetimefrom_utctimestamp()
: return a local time represent of a utc timestamp
See also: to_ordinal()
, from_ordinal()
.
Random Generator¶
# random date from 1970-01-01 to today >>> rolex.rnd_date() datetime.date(1994, 10, 13)
# random datetime from 1970-01-01 00:00:00 to now >>> rolex.rnd_datetime() datetime.datetime(2011,
# random date / datetime between: >>> rolex.rnd_date(“2015-01-01”, “2015-12-31”) # or rnd_datetime datetime.date(2015, 5, 14)
rnd_date_array()
, rnd_datetime_array()
# gives you length-6 date list >>> rolex.rnd_date_array(6, “2015-01-01”, “2015-12-31”) # or rnd_datetime_array
# gives you 2 x 3 date matrix >>> rolex.rnd_date_array((2, 3), “2015-01-01”, “2015-12-31”) # or rnd_datetime_array
Time Series¶
Generate a time series is simple:
>>> start = "2014-01-01 03:00:00"
>>> end = "2014-01-01 03:10:00"
>>> rolex.time_series(start=start, end=end, freq="5min")
[datetime.datetime(2014, 1, 1, 3, 0),
datetime.datetime(2014, 1, 1, 3, 5),
datetime.datetime(2014, 1, 1, 3, 10)]
If you want it repeat specified times from start point, do this:
>>> start = "2014-01-01 03:00:00"
>>> rolex.time_series(start=start, periods=3, freq="5min")
[datetime.datetime(2014, 1, 1, 3, 0),
datetime.datetime(2014, 1, 1, 3, 5),
datetime.datetime(2014, 1, 1, 3, 10)]
And it has more options
available.
weekday_series()
helps you create a time series only on specifid weekday:
>>> start = "2014-01-01 06:30:25"
>>> end = "2014-02-01 06:30:25"
>>> rolex.weekday_series(start, end, weekday=2) # all tuesday
[datetime.datetime(2014, 1, 7, 6, 30, 25),
datetime.datetime(2014, 1, 14, 6, 30, 25),
datetime.datetime(2014, 1, 21, 6, 30, 25),
datetime.datetime(2014, 1, 28, 6, 30, 25)]
Time Delta¶
The method name described itself.
Example:
>>> rolex.add_seconds("2015-01-01", 3600 * 24)
datetime.datetime(2015, 1, 2, 0, 0, 0)
Timezone¶
to_utc(a_datetime)()
: Convert a time awared datetime to utc datetime.utc_to_tz()
: Convert a UTC datetime to a time awared local timeutc_to_local()
: Convert a UTC datetime to current machine local timezone datetime.
Playing with SQL¶
You man have this demands while playing with SQL database. select data within one day, one month, or one year. Basically you gonna do:
select * from table_name where datetime_column between '2014-01-01 00:00:00' to '2014-01-01 23:59:59'
rolex
can help:
>>> rolex.day_interval(2014, 1, 1)
(datetime.datetime(2014, 1, 1, 0, 0),
datetime.datetime(2014, 1, 1, 23, 59, 59))
>>> rolex.month_interval(2014, 6)
(datetime.datetime(2014, 6, 1, 0, 0),
datetime.datetime(2014, 6, 30, 23, 59, 59))
>>> rolex.year_interval(2014)
(datetime.datetime(2014, 1, 1, 0, 0),
datetime.datetime(2014, 12, 31, 23, 59, 59))
If you got an idea, or have request for more utility method, tell me at here https://github.com/MacHu-GWU/rolex-project/issues
About the Author¶
(\ (\
( -.-)o I am a lovely Rabbit!
o_(")(")
Sanhe Hu is a very active Python Developer Since 2010. Research area includes Machine Learning, Big Data Infrastructure, Block Chain, Business Intelligent, AWS, Distributive System. Love photography, outdoor, arts, game, and also the best Python.
- My Github: https://github.com/MacHu-GWU
- My HomePage: http://www.sanhehu.org/
- My Linkedin: https://www.linkedin.com/in/sanhehu/