Coverage for /var/devmt/py/utils4_1.5.0rc1/utils4/timedelta.py: 100%
23 statements
« prev ^ index » next coverage.py v7.6.1, created at 2024-08-12 15:38 +0100
« prev ^ index » next coverage.py v7.6.1, created at 2024-08-12 15:38 +0100
1# -*- coding: utf-8 -*-
2r"""
3:Purpose: This module handles the time delta calculations.
5 Essentially, this module is a soft wrapper around the
6 :func:`pandas.DateOffset` class, which handles the time delta
7 calculations.
9:Platform: Linux/Windows | Python 3.6+
10:Developer: J Berendt
11:Email: support@s3dev.uk
13:Comments: n/a
15:Example:
17 Calculate five months into the future::
19 >>> from datetime import datetime as dt # Imported for demonstration only
20 >>> from utils4.timedelta import timedelta
22 >>> origin = dt.now()
23 >>> result = timedelta(origin=origin, unit='m', value=5)
25 >>> print(f'Origin: {origin}', f'Result: {result}', sep='\n')
26 Origin: 2022-03-23 14:45:58.974822
27 Result: 2022-08-23 14:45:58.974822
30 Calculate 55 minutes into the past::
32 >>> from datetime import datetime as dt # Imported for demonstration only
33 >>> from utils4.timedelta import timedelta
35 >>> origin = dt.now()
36 >>> result = timedelta(origin=origin, unit='M', value=-55)
38 >>> print(f'Origin: {origin}', f'Result: {result}', sep='\n')
39 Origin: 2022-03-23 14:48:43.566826
40 Result: 2022-03-23 13:53:43.566826
43 Calculate 15 months into the past::
45 >>> from datetime import datetime as dt # Imported for demonstration only
46 >>> from utils4.timedelta import timedelta
48 >>> origin = dt.now()
49 >>> result = timedelta(origin=origin, unit='m', value=-15)
51 >>> print(f'Origin: {origin}', f'Result: {result}', sep='\n')
52 Origin: 2022-03-23 14:48:59.531170
53 Result: 2020-12-23 14:48:59.531170
55"""
57import pandas as pd
58try:
59 from .reporterror import reporterror
60except ImportError:
61 from utils4.reporterror import reporterror
64def timedelta(origin, unit, value):
65 """Calculate the time delta, of a given unit, from the original value.
67 Args:
68 origin (datetime.datetime): Original datetime on which the
69 time delta is to be calculated.
70 unit (str): Time unit to be used. Valid options are:
72 - ``'S'``: seconds
73 - ``'M'``: minutes
74 - ``'H'``: hours
75 - ``'d'``: days
76 - ``'w'``: weeks
77 - ``'m'``: months
78 - ``'y'``: years
80 value (int): Value of the delta. Can be either a positive or negative
81 integer.
83 Raises:
84 ValueError: If the unit provided is invalid.
86 Returns:
87 datetime.datetime: A ``datetime.datetime`` object of the calculated
88 result.
90 """
91 units = ['S', 'M', 'H', 'd', 'w', 'm', 'y']
92 if not unit in units:
93 raise ValueError(f'Invalid unit. Valid units are: {", ".join(units)}\n'
94 'Seconds through years, respectively.')
95 try:
96 if unit == 'S':
97 new = origin + pd.DateOffset(seconds=value)
98 elif unit == 'M':
99 new = origin + pd.DateOffset(minutes=value)
100 elif unit == 'H':
101 new = origin + pd.DateOffset(hours=value)
102 elif unit == 'd':
103 new = origin + pd.DateOffset(days=value)
104 elif unit == 'w':
105 new = origin + pd.DateOffset(weeks=value)
106 elif unit == 'm':
107 new = origin + pd.DateOffset(months=value)
108 elif unit == 'y':
109 new = origin + pd.DateOffset(years=value)
110 except Exception as err:
111 reporterror(err)
112 return new