timedelta - Date and time delta calculator

Purpose:

This module handles the time delta calculations.

Essentially, this module is a soft wrapper around the pandas.DateOffset() class, which handles the time delta calculations.

Platform:

Linux/Windows | Python 3.6+

Developer:

J Berendt

Email:

support@s3dev.uk

Comments:

n/a

Example:

Calculate five months into the future:

>>> from datetime import datetime as dt  # Imported for demonstration only
>>> from utils4.timedelta import timedelta

>>> origin = dt.now()
>>> result = timedelta(origin=origin, unit='m', value=5)

>>> print(f'Origin: {origin}', f'Result: {result}', sep='\n')
Origin: 2022-03-23 14:45:58.974822
Result: 2022-08-23 14:45:58.974822

Calculate 55 minutes into the past:

>>> from datetime import datetime as dt  # Imported for demonstration only
>>> from utils4.timedelta import timedelta

>>> origin = dt.now()
>>> result = timedelta(origin=origin, unit='M', value=-55)

>>> print(f'Origin: {origin}', f'Result: {result}', sep='\n')
Origin: 2022-03-23 14:48:43.566826
Result: 2022-03-23 13:53:43.566826

Calculate 15 months into the past:

>>> from datetime import datetime as dt  # Imported for demonstration only
>>> from utils4.timedelta import timedelta

>>> origin = dt.now()
>>> result = timedelta(origin=origin, unit='m', value=-15)

>>> print(f'Origin: {origin}', f'Result: {result}', sep='\n')
Origin: 2022-03-23 14:48:59.531170
Result: 2020-12-23 14:48:59.531170
timedelta.timedelta(origin, unit, value)[source]

Calculate the time delta, of a given unit, from the original value.

Parameters:
  • origin (datetime.datetime) – Original datetime on which the time delta is to be calculated.

  • unit (str) –

    Time unit to be used. Valid options are:

    • 'S': seconds

    • 'M': minutes

    • 'H': hours

    • 'd': days

    • 'w': weeks

    • 'm': months

    • 'y': years

  • value (int) – Value of the delta. Can be either a positive or negative integer.

Raises:

ValueError – If the unit provided is invalid.

Returns:

A datetime.datetime object of the calculated result.

Return type:

datetime.datetime