Coverage for .tox/coverage/lib/python3.11/site-packages/wuttaweb/progress.py: 100%

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

2################################################################################ 

3# 

4# wuttaweb -- Web App for Wutta Framework 

5# Copyright © 2024 Lance Edgar 

6# 

7# This file is part of Wutta Framework. 

8# 

9# Wutta Framework is free software: you can redistribute it and/or modify it 

10# under the terms of the GNU General Public License as published by the Free 

11# Software Foundation, either version 3 of the License, or (at your option) any 

12# later version. 

13# 

14# Wutta Framework is distributed in the hope that it will be useful, but 

15# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 

16# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for 

17# more details. 

18# 

19# You should have received a copy of the GNU General Public License along with 

20# Wutta Framework. If not, see <http://www.gnu.org/licenses/>. 

21# 

22################################################################################ 

23""" 

24Progress Indicators 

25""" 

26 

27from wuttjamaican.progress import ProgressBase 

28 

29from beaker.session import Session as BeakerSession 

30 

31 

32def get_basic_session(request, **kwargs): 

33 """ 

34 Create/get a "basic" Beaker session object. 

35 """ 

36 kwargs['use_cookies'] = False 

37 return BeakerSession(request, **kwargs) 

38 

39 

40def get_progress_session(request, key, **kwargs): 

41 """ 

42 Create/get a Beaker session object, to be used for progress. 

43 """ 

44 kwargs['id'] = f'{request.session.id}.progress.{key}' 

45 return get_basic_session(request, **kwargs) 

46 

47 

48class SessionProgress(ProgressBase): 

49 """ 

50 Progress indicator which uses Beaker session storage to track 

51 current status. 

52 

53 This is a subclass of 

54 :class:`wuttjamaican:wuttjamaican.progress.ProgressBase`. 

55 

56 A view callable can create one of these, and then pass it into 

57 :meth:`~wuttjamaican.app.AppHandler.progress_loop()` or similar. 

58 

59 As the loop updates progress along the way, this indicator will 

60 update the Beaker session to match. 

61 

62 Separately then, the client side can send requests for the 

63 :func:`~wuttaweb.views.progress.progress()` view, to fetch current 

64 status out of the Beaker session. 

65 

66 :param request: Current :term:`request` object. 

67 

68 :param key: Unique key for this progress indicator. Used to 

69 distinguish progress indicators in the Beaker session. 

70 

71 Note that in addition to 

72 :meth:`~wuttjamaican:wuttjamaican.progress.ProgressBase.update()` 

73 and 

74 :meth:`~wuttjamaican:wuttjamaican.progress.ProgressBase.finish()` 

75 this progres class has some extra attributes and methods: 

76 

77 .. attribute:: success_msg 

78 

79 Optional message to display to the user (via session flash) 

80 when the operation completes successfully. 

81 

82 .. attribute:: success_url 

83 

84 URL to which user should be redirected, once the operation 

85 completes. 

86 

87 .. attribute:: error_url 

88 

89 URL to which user should be redirected, if the operation 

90 encounters an error. If not specified, will fall back to 

91 :attr:`success_url`. 

92 """ 

93 

94 def __init__(self, request, key, success_msg=None, success_url=None, error_url=None): 

95 self.key = key 

96 self.success_msg = success_msg 

97 self.success_url = success_url 

98 self.error_url = error_url or self.success_url 

99 self.session = get_progress_session(request, key) 

100 self.clear() 

101 

102 def __call__(self, message, maximum): 

103 self.clear() 

104 self.session['message'] = message 

105 self.session['maximum'] = maximum 

106 self.session['maximum_display'] = f'{maximum:,d}' 

107 self.session['value'] = 0 

108 self.session.save() 

109 return self 

110 

111 def clear(self): 

112 """ """ 

113 self.session.clear() 

114 self.session['complete'] = False 

115 self.session['error'] = False 

116 self.session.save() 

117 

118 def update(self, value): 

119 """ """ 

120 self.session.load() 

121 self.session['value'] = value 

122 self.session.save() 

123 

124 def handle_error(self, error, error_url=None): 

125 """ 

126 This should be called by the view code, within a try/catch 

127 block upon error. 

128 

129 The session storage will be updated to reflect details of the 

130 error. Next time client requests the progress status it will 

131 learn of the error and redirect the user. 

132 

133 :param error: :class:`python:Exception` instance. 

134 

135 :param error_url: Optional redirect URL; if not specified 

136 :attr:`error_url` is used. 

137 """ 

138 self.session.load() 

139 self.session['error'] = True 

140 self.session['error_msg'] = str(error) 

141 self.session['error_url'] = error_url or self.error_url 

142 self.session.save() 

143 

144 def handle_success(self, success_msg=None, success_url=None): 

145 """ 

146 This should be called by the view code, when the long-running 

147 operation completes. 

148 

149 The session storage will be updated to reflect the completed 

150 status. Next time client requests the progress status it will 

151 discover it has completed, and redirect the user. 

152 

153 :param success_msg: Optional message to display to the user 

154 (via session flash) when the operation completes 

155 successfully. If not specified :attr:`success_msg` (or 

156 nothing) is used 

157 

158 :param success_url: Optional redirect URL; if not specified 

159 :attr:`success_url` is used. 

160 """ 

161 self.session.load() 

162 self.session['complete'] = True 

163 self.session['success_msg'] = success_msg or self.success_msg 

164 self.session['success_url'] = success_url or self.success_url 

165 self.session.save()