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.request = request 

96 self.config = self.request.wutta_config 

97 self.app = self.config.get_app() 

98 self.key = key 

99 self.success_msg = success_msg 

100 self.success_url = success_url 

101 self.error_url = error_url or self.success_url 

102 self.session = get_progress_session(request, key) 

103 self.clear() 

104 

105 def __call__(self, message, maximum): 

106 self.clear() 

107 self.session['message'] = message 

108 self.session['maximum'] = maximum 

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

110 self.session['value'] = 0 

111 self.session.save() 

112 return self 

113 

114 def clear(self): 

115 """ """ 

116 self.session.clear() 

117 self.session['complete'] = False 

118 self.session['error'] = False 

119 self.session.save() 

120 

121 def update(self, value): 

122 """ """ 

123 self.session.load() 

124 self.session['value'] = value 

125 self.session.save() 

126 

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

128 """ 

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

130 block upon error. 

131 

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

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

134 learn of the error and redirect the user. 

135 

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

137 

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

139 :attr:`error_url` is used. 

140 """ 

141 self.session.load() 

142 self.session['error'] = True 

143 self.session['error_msg'] = self.app.render_error(error) 

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

145 self.session.save() 

146 

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

148 """ 

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

150 operation completes. 

151 

152 The session storage will be updated to reflect the completed 

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

154 discover it has completed, and redirect the user. 

155 

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

157 (via session flash) when the operation completes 

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

159 nothing) is used 

160 

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

162 :attr:`success_url` is used. 

163 """ 

164 self.session.load() 

165 self.session['complete'] = True 

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

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

168 self.session.save()