kwutil.util_time module

exception kwutil.util_time.TimeValueError

Bases: ValueError

exception kwutil.util_time.TimeTypeError

Bases: TypeError

class kwutil.util_time.datetime

Bases: datetime

An enriched datetime class

Example

>>> import kwutil
>>> self = kwutil.util_time.datetime.random()
>>> print(f'self = {self!s}')
>>> print(f'self = {self!r}')

isoformat(pathsafe=False)

classmethod coerce(data, **kwargs)

Parameters:

• data – passed to func:coerce_datetime

• **kwargs – passed to func:coerce_datetime

Example

data = ‘1970-01-01’ cls = datetime

classmethod random(start=None, end=None, rng=None)

Example

datetime.random(start=’2010-01-01’, end=’2020-01-01’) data = ‘1970-01-01’ cls = datetime rng = 0 start = None end = None

class kwutil.util_time.timedelta

Bases: timedelta

An enriched timedelta class

Example

>>> import kwutil
>>> self = kwutil.util_time.timedelta.random()
>>> print(f'self={self}')

classmethod random(rng=None)

classmethod coerce(data)

Example

>>> from kwutil.util_time import *  # NOQA
>>> data = '3.141592653589793 years'
>>> cls = timedelta
>>> self = cls.coerce(data)
>>> print('self = {}'.format(ub.urepr(self, nl=1)))

kwutil.util_time.isoformat(dt, sep='T', timespec='seconds', pathsafe=True)

A path-safe version of datetime_cls.isotime() that returns a path-friendlier version of a ISO 8601 timestamp.

Parameters:

• dt (datetime_cls) – datetime to format

• pathsafe (bool)

References

https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes

SeeAlso:

ubelt.timestamp

Example

>>> from kwutil.util_time import *  # NOQA
>>> items = []
>>> dt = datetime_cls.now()
>>> dt = ensure_timezone(dt, datetime_mod.timezone(datetime_mod.timedelta(hours=+5)))
>>> items.append(dt)
>>> dt = datetime_cls.utcnow()
>>> items.append(dt)
>>> dt = dt.replace(tzinfo=datetime_mod.timezone.utc)
>>> items.append(dt)
>>> dt = ensure_timezone(datetime_cls.now(), datetime_mod.timezone(datetime_mod.timedelta(hours=-5)))
>>> items.append(dt)
>>> dt = ensure_timezone(datetime_cls.now(), datetime_mod.timezone(datetime_mod.timedelta(hours=+5)))
>>> items.append(dt)
>>> print('items = {!r}'.format(items))
>>> for dt in items:
>>>     print('----')
>>>     print('dt = {!r}'.format(dt))
>>>     # ISO format is cool, but it doesnt give much control
>>>     print(dt.isoformat())
>>>     # Need a better version
>>>     print(isoformat(dt))
>>>     print(isoformat(dt, pathsafe=False))

kwutil.util_time._format_offset(off)

Taken from CPython:

https://github.com/python/cpython/blob/main/Lib/datetime_mod.py

kwutil.util_time.coerce_datetime(data, default_timezone='utc', nan_policy='return-None', none_policy='return-None')

Parses a timestamp and always returns a timestamp with a timezone. If only a date is specified, the time is defaulted to 00:00:00 If one is not discoverable a specified default is used. A nan or None input depends on nan_policy and none_policy.

Parameters:

• data (None | str | datetime_mod.datetime | datetime_mod.date)

• default_timezone (str) – defaults to utc.

• none_policy (str) – Can be: ‘return-None’, ‘return-nan’, or ‘raise’. See _handle_null_policy() for details.

• nan_policy (str) – Can be: ‘return-None’, ‘return-nan’, or ‘raise’. See _handle_null_policy() for details.

Returns:

datetime_mod.datetime | None

Example

>>> from kwutil.util_time import *  # NOQA
>>> assert coerce_datetime(None) is None
>>> assert coerce_datetime(float('nan')) is None
>>> assert coerce_datetime('2020-01-01') == datetime_cls(2020, 1, 1, 0, 0, tzinfo=datetime_mod.timezone.utc)
>>> assert coerce_datetime(datetime_cls(2020, 1, 1, 0, 0)) == datetime_cls(2020, 1, 1, 0, 0, tzinfo=datetime_mod.timezone.utc)
>>> assert coerce_datetime(datetime_cls(2020, 1, 1, 0, 0).date()) == datetime_cls(2020, 1, 1, 0, 0, tzinfo=datetime_mod.timezone.utc)
>>> dt = coerce_datetime('2020-01-01')
>>> stamp = dt.timestamp()
>>> assert stamp == 1577836800.0
>>> assert coerce_datetime(stamp) == dt
>>> assert dt.isoformat() == '2020-01-01T00:00:00+00:00'

kwutil.util_time._handle_null_policy(policy, ex_type=<class 'TypeError'>, ex_msg='cannot accept null input')

For handling a nan or None policy.

Parameters:

• policy (str) –

  How null inputs are handled. Can be:

  ‘return-None’: returns None ‘return-nan’: returns nan ‘raise’: raises an error

• ex_type (type) – Exception type to raise if policy is raise

• ex_msg (msg) – Exception arguments

kwutil.util_time.coerce_timedelta(delta, nan_policy='raise', none_policy='raise')

Parses data that could be associated with a time delta

Parameters:

• delta (str | int | float) – If given as a string, attempt to parse out a time duration. Otherwise, interpret pure magnitudes in seconds.

• none_policy (str) – Can be: ‘return-None’, ‘return-nan’, or ‘raise’. See _handle_null_policy() for details.

• nan_policy (str) – Can be: ‘return-None’, ‘return-nan’, or ‘raise’. See _handle_null_policy() for details.

Returns:

datetime_mod.timedelta | None

Example

>>> from kwutil.util_time import *  # NOQA
>>> variants = [
>>>     ['year', 'y'],
>>>     ['month', 'm', 'mon'],
>>>     ['day', 'd', 'days'],
>>>     ['hours', 'hour', 'h'],
>>>     ['minutes', 'min', 'M'],
>>>     ['second', 'S', 's', 'secs'],
>>> ]
>>> for vs in variants:
>>>     print('vs = {!r}'.format(vs))
>>>     ds = []
>>>     for v in vs:
>>>         d = coerce_timedelta(f'1{v}')
>>>         ds.append(d)
>>>         d = coerce_timedelta(f'1 {v}')
>>>         ds.append(d)
>>>     assert ub.allsame(ds)
>>>     print('ds = {!r}'.format(ds))
>>> print(coerce_timedelta(10.3))
>>> print(coerce_timedelta('1y'))
>>> print(coerce_timedelta('1m'))
>>> print(coerce_timedelta('1d'))
>>> print(coerce_timedelta('1H'))
>>> print(coerce_timedelta('1M'))
>>> print(coerce_timedelta('1S'))
>>> print(coerce_timedelta('1year'))
>>> print(coerce_timedelta('1month'))
>>> print(coerce_timedelta('1day'))
>>> print(coerce_timedelta('1hour'))
>>> print(coerce_timedelta('1min'))
>>> print(coerce_timedelta('1sec'))
>>> print(coerce_timedelta('1microsecond'))
>>> print(coerce_timedelta('1milliseconds'))
>>> print(coerce_timedelta('1ms'))
>>> print(coerce_timedelta('1us'))

Example

>>> # xdoctest: +REQUIRES(module:numpy)
>>> from kwutil.util_time import *  # NOQA
>>> import numpy as np
>>> print(coerce_timedelta(int(30)))
>>> print(coerce_timedelta(float(30)))
>>> print(coerce_timedelta(np.int32(30)))
>>> print(coerce_timedelta(np.int64(30)))
>>> print(coerce_timedelta(np.float32(30)))
>>> print(coerce_timedelta(np.float64(30)))

References

https://docs.python.org/3.4/library/datetime_mod.html#strftime-strptime-behavior

kwutil.util_time.coerce_timezone(tz)

Converts input to a valid timezone object :Parameters: tz (str | tzinfo)

Returns:

timezone object

Return type:

tzinfo

kwutil.util_time.ensure_timezone(dt, default='utc')

Gives a datetime_mod a timezone (utc by default) if it doesnt have one

Parameters:

• dt (datetime_mod.datetime) – the datetime to fix

• default (str) – the timezone to use if it does not have one.

Returns:

datetime_mod.datetime

Example

>>> from kwutil.util_time import *  # NOQA
>>> dt = ensure_timezone(datetime_cls.now(), datetime_mod.timezone(datetime_mod.timedelta(hours=+5)))
>>> print('dt = {!r}'.format(dt))
>>> dt = ensure_timezone(datetime_cls.utcnow())
>>> print('dt = {!r}'.format(dt))
>>> ensure_timezone(datetime_cls.utcnow(), 'utc')
>>> ensure_timezone(datetime_cls.utcnow(), 'local')

kwutil.util_time._time_unit_registery()

kwutil.util_time.format_timedelta(delta, resolution=None, unit=None, precision=None)

TODO format time deltas at some resolution granularity

Parameters:

• delta (datetime_mod.timedelta) – The timedelta to format

• unit (str | None | pint.Unit) – if specified, express the time delta in terms of this unit.

• precision (int) – number of decimal places when a single unit is given

• resolution (datetime_mod.timedelta | str | None) – minimum temporal resolution. If unspecified returns an isoformat

Returns:

formatted text

Return type:

str

References

https://gist.github.com/thatalextaylor/7408395

CommandLine

xdoctest -m kwutil.util_time format_timedelta

Example

>>> from kwutil.util_time import *  # NOQA
>>> resolution = coerce_timedelta('year')
>>> resolution = 'year'
>>> delta = coerce_timedelta('13months')
>>> print(format_timedelta(delta))
>>> print(format_timedelta(delta, unit='year', precision=2))

>>> print(format_timedelta('.000003 days', unit='auto', precision=0))
>>> print(format_timedelta('.03 days', unit='auto', precision=0))
>>> print(format_timedelta('39 days', unit='auto', precision=0))
>>> print(format_timedelta('3900 days', unit='auto', precision=0))

kwutil.util_time._devcheck_portion()

Portion seems like a good library to build a TimeInterval class with. Could also check PyInterval