felixnext / python-time-helper

Various functions that help handling time based functions across different projects

Time Helper

Simple helper library to handle different time related tasks in python. This ties into pandas and numpy as well as pytz.

The general idea is to have a bunch of one-stop functions that allow you to easily handle datetime related tasks.

Getting Started

pip install time-helper

Then in python code:

from time_helper import make_aware

make_aware("2022-03-10")
# > datetime.datetime(2022, 3, 10, 0, 0, tzinfo=backports.zoneinfo.ZoneInfo(key='CET'))

Library Logic

The library is build to extend around various datetime objects (such as python internal datetime, date, as well as np.datetime). It provides a bunch of helper functions that are grouped into various categories:

Convert

This gets datetimes in and out of the library. This includes a range of functions for converting strings and different datetime types into canonical py-datetime types:

import time_helper as th

# convert a unix datetime
dt = th.unix_to_datetime(1649491287)
dt = th.any_to_datetime(1649491287)

# convert string to datetime
dt = th.any_to_datetime("2022-03-19")
dt = th.any_to_datetime("2022-03-19 20:15")

# convert a date to datetime
from datetime import date
dt = th.any_to_datetime(date(2022, 3, 10))

It also allows to easily switch between aware and unaware datetime:

dt = th.any_to_datetime("2022-03-10")
aware_dt = th.make_aware(dt)
aware_dt = th.make_aware(dt, "UTC")
unaware_dt = th.make_unaware(dt)
unaware_dt = th.make_unaware(dt, "UTC")

Note that for make_unaware you can still provide a datetime. In that case the datetime is first converted into the regarding timezone before the timezone information is removed from the object. You can also explicitly convert the timezone with localize_datetime.

Operations & Ranges

The library also defines a range of operations to make working with timezones easier. These include handling modifications of a single datetime:

day = th.round_time(dt, "D")
# results in: datetime.datetime(2022, 3, 10, 0, 0)
day = th.round_time(dt, "D", max_out=True)
# results in: datetime.datetime(2022, 3, 10, 23, 59, 59, 999999)
has_tz = th.has_timezone(aware_dt)
has_tz = th.has_timezone(unaware_dt)

# compute a diff (between aware and unaware datetimes)
diff = th.time_diff(
    th.round_time(aware_dt, "M", max_out=True),
    unaware_dt
)
# results in: datetime.timedelta(seconds=3659, microseconds=999999)

It also supports a bunch of range operations:

# converts the time into a interval (float) value for the defined range
# default i
dt = datetime(2022, 3, 12, 12, 0)
pos = th.time_to_interval(dt, offset=0)
# results in: 0.0 (as it is noon)
pos = th.time_to_interval(dt, offset=0, zero_center=False)
# results in: 0.5 (as half day is gone and center is no longer zeroed)

# create interval tuples
ivs = th.create_intervals(dt, dt + timedelta(days=2), interval=1)
ivs = th.create_intervals(dt, dt + timedelta(days=2), interval=timedelta(minutes=30))

Wrapper

This library also provides a wrapper class to make all functions more accessible and first class citizens of the system.

Note: This part of the library is still under construction.

Notes

There is still a lot to improve on this library, please feel free to create PRs or contact me if you wish to contribute!

python-time-helper's Issues

Integrate better summer-time support for different Timezones

There are a bunch of special cases when it comes to summer-time (e.g. switch from CET to CEST), which can lead to problems.

Check the code, add unit tests for that and improve the support for summertime

round_time might return date-type for Weeks

When rounding to weeks, round_time might return a date object instead of datetime.

Example:

import time_helper as th
from datetime import datetime

dt = th.any_to_datetime("2022-02-10")
dt_out = th.round_time(dt, "W")

assert type(dt_out) == datetime

Improve Readme with concrete examples

any_to_datetime causes problems will milliseconds

The any_to_datetime convert function has problems when running against millisecond strings (e.g. "2022-10-15T04:53:30.315Z"). This needs to be fixed (note that the parse_time function does not have this problem!)

Implement the Wrapper Class

The wrapper class is currently non functional.

Implement it as a valid wrapper for all functions and with full compatability with datetimes