pytoolbox.datetime module

pytoolbox.datetime.str_to_time(value, defaults_to_zero=False, as_delta=False)

Return the string of format ‘hh:mm:ss’ into an instance of time.

Example usage

>>> str_to_time('08:23:57')
datetime.time(8, 23, 57)
>>> str_to_time('00:03:02.12')
datetime.time(0, 3, 2, 120)
>>> str_to_time(None)
>>> str_to_time(None, defaults_to_zero=True)
datetime.time(0, 0)
>>> result = str_to_time('08:23:57', as_delta=True)
>>> type(result)
<class 'datetime.timedelta'>
>>> str(result)
'8:23:57'
>>> result = str_to_time('00:03:02.12', as_delta=True)
>>> type(result)
<class 'datetime.timedelta'>
>>> str(result)
'0:03:02.120000'
>>> str_to_time(None, as_delta=True) is None
True
>>> str_to_time(None, defaults_to_zero=True, as_delta=True)
datetime.timedelta(0)

pytoolbox.datetime.datetime_to_epoch(date_time, utc=True, factor=1)

Return the datetime.datetime/datetime.date converted into an Unix epoch. Default factor means that the result is in seconds.

Example usage

>>> datetime_to_epoch(datetime.datetime(1970, 1, 1), factor=1)
0
>>> datetime_to_epoch(datetime.datetime(2010, 6, 10))
1276128000
>>> datetime_to_epoch(datetime.datetime(2010, 6, 10), factor=1000)
1276128000000
>>> datetime_to_epoch(datetime.date(2010, 6, 10), factor=1000)
1276128000000
>>> datetime_to_epoch(datetime.date(1987, 6, 10), factor=1000)
550281600000

In Switzerland:

>> datetime_to_epoch(datetime.datetime(1970, 1, 1), utc=False, factor=1)
-3600
>> datetime_to_epoch(datetime.date(1970, 1, 1), utc=False, factor=1)
-3600

pytoolbox.datetime.multiply_time(value, factor, as_delta=False)

Return an instance of datetime.time/datetime.timedelta corresponding to value multiplied by a factor.

Example usage

>>> multiply_time('00:10:00', 0.5)
datetime.time(0, 5)
>>> multiply_time(datetime.timedelta(seconds=60), 3)
datetime.time(0, 3)
>>> multiply_time(120, 0.1)
datetime.time(0, 0, 12)
>>> res = multiply_time(datetime.timedelta(seconds=152, microseconds=500000), 1, as_delta=True)
>>> type(res)
<class 'datetime.timedelta'>
>>> print(res)
0:02:32.500000

pytoolbox.datetime.secs_to_time(value, defaults_to_zero=False, as_delta=False)

Return an instance of datetime.time/datetime.timedelta, taking value as the number of seconds + microseconds (e.g. 10.3 = 10s 3000us).

Example usage

>>> secs_to_time(83707.0035)
datetime.time(23, 15, 7, 3500)
>>> secs_to_time(None)
>>> secs_to_time(None, defaults_to_zero=True)
datetime.time(0, 0)
>>> result = secs_to_time(83707.0035, as_delta=True)
>>> type(result)
<class 'datetime.timedelta'>
>>> print(result)
23:15:07.003500
>>> secs_to_time(None, as_delta=True) is None
True
>>> secs_to_time(None, defaults_to_zero=True, as_delta=True)
datetime.timedelta(0)

pytoolbox.datetime.epoch_to_datetime(unix_epoch, tz=<UTC>, factor=1)

Return the Unix epoch converted to a datetime.datetime. Default factor means that the unix_epoch is in seconds.

Example usage

>>> epoch_to_datetime(0, factor=1)
datetime.datetime(1970, 1, 1, 0, 0, tzinfo=<UTC>)
>>> epoch_to_datetime(1276128000, factor=1)
datetime.datetime(2010, 6, 10, 0, 0, tzinfo=<UTC>)
>>> epoch_to_datetime(1276128000, tz=pytz.timezone('Europe/Zurich'), factor=1)
datetime.datetime(2010, 6, 10, 2, 0, tzinfo=<DstTzInfo 'Europe/Zurich' CEST+2:00:00 DST>)
>>> epoch_to_datetime(1276128000000, factor=1000)
datetime.datetime(2010, 6, 10, 0, 0, tzinfo=<UTC>)
>>> today = datetime.datetime(1985, 6, 1, 5, 2, 0, tzinfo=pytz.utc)
>>> epoch_to_datetime(datetime_to_epoch(today, factor=1000), factor=1000) == today
True

pytoolbox.datetime.datetime_to_str(date_time, format='%Y-%m-%d %H:%M:%S', append_utc=False)

pytoolbox.datetime.str_to_datetime(date, format='%Y-%m-%d %H:%M:%S', fail=True)

Return the date string converted into an instance of datetime.datetime. Handle 24h+ hour format like 2015:06:28 24:05:00 equal to the 28th June 2015 at midnight and 5 minutes.

Example usage

>>> str_to_datetime('1985-01-06 05:02:00')
datetime.datetime(1985, 1, 6, 5, 2)
>>> str_to_datetime('this is not a date')
Traceback (most recent call last):
    ...
ValueError: time data 'this is not a date' does not match format '%Y-%m-%d %H:%M:%S'

pytoolbox.datetime.total_seconds(time)

Return the time converted in seconds.

Example usage

>>> total_seconds('00:10:00')
600.0
>>> total_seconds('01:54:17')
6857.0
>>> round(total_seconds('16.40'), 3)
16.4
>>> total_seconds(143.2)
143.2
>>> total_seconds(datetime.timedelta(seconds=152, microseconds=500000))
152.5
>>> total_seconds(datetime.datetime(2010, 6, 10, 0, 1, 30))
90.0
>>> total_seconds(datetime.datetime(2010, 6, 10, 14, 15, 23))
51323.0
>>> total_seconds(datetime.datetime(2010, 6, 10, 23, 59, 59))
86399.0

pytoolbox.datetime.parts_to_time(hours, minutes, seconds, microseconds, as_delta=False)

Return an instance of datetime.time/datetime.timedelta out of the parts.

Example usage

>>> parts_to_time(23, 15, 7, 3500)
datetime.time(23, 15, 7, 3500)
>>> result = parts_to_time(23, 15, 7, 3500, as_delta=True)
>>> type(result)
<class 'datetime.timedelta'>
>>> print(result)
23:15:07.003500

pytoolbox.datetime.datetime_now(format='%Y-%m-%d %H:%M:%S', append_utc=False, offset=None, tz=<UTC>)

Return the current (timezone aware) date and time as UTC, local (tz=None) or related to a timezone. If format is not None, the date will be returned in a formatted string.

Parameters:

• format (str) – Output date string formatting

• append_utc (bool) – Append ‘ UTC’ to date string

• offset (datetime.timedelta) – Offset to add to current time

• tz (tz) – The timezone (e.g. pytz.timezone('EST'))

Example usage

Add an offset:

>>> now = datetime_now(format=None)
>>> future = datetime_now(offset=datetime.timedelta(hours=2, minutes=10), format=None)
>>> result = (future - now)
>>> type(result)
<class 'datetime.timedelta'>
>>> print(result)
2:10:00.00...

Append UTC to output date string:

>>> type(datetime_now())
<class 'str'>
>>> assert ' UTC' not in datetime_now(tz=pytz.utc, append_utc=False)
>>> assert ' UTC' not in datetime_now(tz=None, append_utc=True)
>>> assert ' UTC' not in datetime_now(tz=pytz.timezone('EST'), append_utc=True)
>>> assert ' UTC' in datetime_now(tz=pytz.utc, append_utc=True)

Play with timezones:

>> datetime_now(tz=pytz.timezone('Europe/Zurich'))
'2013-10-17 09:54:08'
>> datetime_now(tz=pytz.timezone('US/Eastern'))
'2013-10-17 03:54:08'

pytoolbox.datetime.time_ratio(numerator, denominator, zero_div_result=1.0)

Return the ratio between two times.

Example usage

>>> from pytoolbox.unittest import asserts
>>> time_ratio('0:30:00', '01:30:00')
0.33...
>>> time_ratio('0:00:05', '00:00:00')
1.0
>>> with asserts.raises(ValueError):
...     time_ratio('01:42:34', 'N/A')