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

24 statements  

« prev     ^ index     » next       coverage.py v7.6.9, created at 2024-12-21 17:18 +0000

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:Platform: Linux/Windows | Python 3.7+ 

10:Developer: J Berendt 

11:Email: support@s3dev.uk 

12 

13:Comments: n/a 

14 

15:Example: 

16 

17 Calculate five months into the future:: 

18 

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

20 >>> from utils4.timedelta import timedelta 

21 

22 >>> origin = dt.now() 

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

24 

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 

28 

29 

30 Calculate 55 minutes into the past:: 

31 

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

33 >>> from utils4.timedelta import timedelta 

34 

35 >>> origin = dt.now() 

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

37 

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 

41 

42 

43 Calculate 15 months into the past:: 

44 

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

46 >>> from utils4.timedelta import timedelta 

47 

48 >>> origin = dt.now() 

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

50 

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 

54 

55""" 

56 

57import pandas as pd 

58try: 

59 from .reporterror import reporterror 

60except ImportError: 

61 from utils4.reporterror import reporterror 

62 

63 

64def timedelta(origin, unit, value): 

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

66 

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: 

71 

72 - ``'S'``: seconds 

73 - ``'M'``: minutes 

74 - ``'H'``: hours 

75 - ``'d'``: days 

76 - ``'w'``: weeks 

77 - ``'m'``: months 

78 - ``'y'``: years 

79 

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

81 integer. 

82 

83 Raises: 

84 ValueError: If the unit provided is invalid. 

85 

86 Returns: 

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

88 result. 

89 

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 new = None 

97 if unit == 'S': 

98 new = origin + pd.DateOffset(seconds=value) 

99 elif unit == 'M': 

100 new = origin + pd.DateOffset(minutes=value) 

101 elif unit == 'H': 

102 new = origin + pd.DateOffset(hours=value) 

103 elif unit == 'd': 

104 new = origin + pd.DateOffset(days=value) 

105 elif unit == 'w': 

106 new = origin + pd.DateOffset(weeks=value) 

107 elif unit == 'm': 

108 new = origin + pd.DateOffset(months=value) 

109 elif unit == 'y': 

110 new = origin + pd.DateOffset(years=value) 

111 except Exception as err: 

112 reporterror(err) 

113 return new