Coverage for /var/devmt/py/utils4_1.8.0/utils4/timedelta.py: 100%

1# -*- coding: utf-8 -*- 

2r""" 

3:Purpose: This module handles the time delta calculations. 

4 

5 Essentially, this module is a soft wrapper around the 

6 :func:`pandas.DateOffset` class, which handles the time delta 

7 calculations. 

8 

9:Developer: J Berendt 

10:Email: support@s3dev.uk 

11 

12:Comments: n/a 

13 

14:Example: 

15 

16 Calculate five months into the future:: 

17 

18 >>> from datetime import datetime as dt # Imported for demonstration only 

19 >>> from utils4.timedelta import timedelta 

20 

21 >>> origin = dt.now() 

22 >>> result = timedelta(origin=origin, unit='m', value=5) 

23 

24 >>> print(f'Origin: {origin}', f'Result: {result}', sep='\n') 

25 Origin: 2022-03-23 14:45:58.974822 

26 Result: 2022-08-23 14:45:58.974822 

27 

28 

29 Calculate 55 minutes into the past:: 

30 

31 >>> from datetime import datetime as dt # Imported for demonstration only 

32 >>> from utils4.timedelta import timedelta 

33 

34 >>> origin = dt.now() 

35 >>> result = timedelta(origin=origin, unit='M', value=-55) 

36 

37 >>> print(f'Origin: {origin}', f'Result: {result}', sep='\n') 

38 Origin: 2022-03-23 14:48:43.566826 

39 Result: 2022-03-23 13:53:43.566826 

40 

41 

42 Calculate 15 months into the past:: 

43 

44 >>> from datetime import datetime as dt # Imported for demonstration only 

45 >>> from utils4.timedelta import timedelta 

46 

47 >>> origin = dt.now() 

48 >>> result = timedelta(origin=origin, unit='m', value=-15) 

49 

50 >>> print(f'Origin: {origin}', f'Result: {result}', sep='\n') 

51 Origin: 2022-03-23 14:48:59.531170 

52 Result: 2020-12-23 14:48:59.531170 

53 

54""" 

55 

56import pandas as pd 

57try: 

58 from .reporterror import reporterror 

59except ImportError: 

60 from utils4.reporterror import reporterror 

61 

62 

63def timedelta(origin, unit, value): 

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

65 

66 Args: 

67 origin (datetime.datetime): Original datetime on which the 

68 time delta is to be calculated. 

69 unit (str): Time unit to be used. Valid options are: 

70 

71 - ``'S'``: seconds 

72 - ``'M'``: minutes 

73 - ``'H'``: hours 

74 - ``'d'``: days 

75 - ``'w'``: weeks 

76 - ``'m'``: months 

77 - ``'y'``: years 

78 

79 value (int): Value of the delta. Can be either a positive or negative 

80 integer. 

81 

82 Raises: 

83 ValueError: If the unit provided is invalid. 

84 

85 Returns: 

86 datetime.datetime: A ``datetime.datetime`` object of the calculated 

87 result. 

88 

89 """ 

90 units = ['S', 'M', 'H', 'd', 'w', 'm', 'y'] 

91 if not unit in units: 

92 raise ValueError(f'Invalid unit. Valid units are: {", ".join(units)}\n' 

93 'Seconds through years, respectively.') 

94 try: 

95 new = None 

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