Release v0.0.8 (What’s new?).

Documentation Status https://travis-ci.org/MacHu-GWU/rolex-project.svg?branch=master https://codecov.io/gh/MacHu-GWU/rolex-project/branch/master/graph/badge.svg https://img.shields.io/pypi/v/rolex.svg https://img.shields.io/pypi/l/rolex.svg https://img.shields.io/pypi/pyversions/rolex.svg https://img.shields.io/badge/STAR_Me_on_GitHub!--None.svg?style=social
https://img.shields.io/badge/Link-Document-blue.svg https://img.shields.io/badge/Link-API-blue.svg https://img.shields.io/badge/Link-Source_Code-blue.svg https://img.shields.io/badge/Link-Install-blue.svg https://img.shields.io/badge/Link-GitHub-blue.svg https://img.shields.io/badge/Link-Submit_Issue-blue.svg https://img.shields.io/badge/Link-Request_Feature-blue.svg https://img.shields.io/badge/Link-Download-blue.svg

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 …).

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:

See also: to_ordinal(), from_ordinal().

Random Generator

rnd_date(), rnd_datetime():

# 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 time
  • utc_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.