Coverage for pyTooling/Exceptions/__init__.py: 62%

1# ==================================================================================================================== # 

2# # 

3# _____ _ _ _____ _ _ # 

4# _ __ _ |_ _|__ ___ | (_)_ __ __ _ | ____|_ _____ ___ _ __ | |_(_) ___ _ __ ___ # 

5# | '_ \| | | || |/ _ \ / _ \| | | '_ \ / _` | | _| \ \/ / __/ _ \ '_ \| __| |/ _ \| '_ \/ __| # 

6# | |_) | |_| || | (_) | (_) | | | | | | (_| |_| |___ > < (_| __/ |_) | |_| | (_) | | | \__ \ # 

7# | .__/ \__, ||_|\___/ \___/|_|_|_| |_|\__, (_)_____/_/\_\___\___| .__/ \__|_|\___/|_| |_|___/ # 

8# |_| |___/ |___/ |_| # 

9# ==================================================================================================================== # 

10# Authors: # 

11# Patrick Lehmann # 

12# # 

13# License: # 

14# ==================================================================================================================== # 

15# Copyright 2017-2026 Patrick Lehmann - Bötzingen, Germany # 

16# # 

17# Licensed under the Apache License, Version 2.0 (the "License"); # 

18# you may not use this file except in compliance with the License. # 

19# You may obtain a copy of the License at # 

20# # 

21# http://www.apache.org/licenses/LICENSE-2.0 # 

22# # 

23# Unless required by applicable law or agreed to in writing, software # 

24# distributed under the License is distributed on an "AS IS" BASIS, # 

25# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 

26# See the License for the specific language governing permissions and # 

27# limitations under the License. # 

28# # 

29# SPDX-License-Identifier: Apache-2.0 # 

30# ==================================================================================================================== # 

31# 

32""" 

33A common set of missing exceptions in Python. 

34 

35.. hint:: 

36 

37 See :ref:`high-level help <EXECPTION>` for explanations and usage examples. 

38""" 

39from typing import Tuple, Iterable, Any 

40 

41from pyTooling.Decorators import export, readonly 

42 

43 

44@export 

45def addNoteWithItemList( 

46 ex: BaseException, 

47 message: str, 

48 items: Iterable[Any], 

49 *, 

50 indent: str = " ", 

51 separator: str = ", ", 

52 maxWidth: int = 100 

53) -> None: 

54 """ 

55 Add a message as a note to the exception. The iterables items are added as a coma separated list. If the list gets too 

56 long, remaining items will be continued in addition notes. 

57 

58 :param ex: Exception to attach the note to. 

59 :param message: The message of the note. 

60 :param items: An iterable of items to add to the note. 

61 :param indent: The indentation of the additional notes. 

62 :param separator: Separator between items. 

63 :param maxWidth: The maximum width of the attached notes. 

64 """ 

65 note = message 

66 sep = "" 

67 

68 for item in items: 

69 if len(note) + len(newItem := f"{sep}{item}") <= maxWidth: 

70 note += newItem 

71 sep = separator 

72 else: 

73 ex.add_note(note) 

74 

75 note = f"{indent}{item}" 

76 sep = separator 

77 

78 ex.add_note(note) 

79 

80 

81@export 

82class OverloadResolutionError(Exception): 

83 """ 

84 The exception is raised, when no matching overloaded method was found. 

85 

86 .. seealso:: 

87 

88 :deco:`~pyTooling.MetaClasses.overloadable` 

89 |rarr| Mark a method as *overloadable*. 

90 """ 

91 

92 @readonly 

93 def HasNotes(self) -> bool: 

94 """ 

95 Read-only property to return if the warning has attached notes. 

96 

97 :returns: True, if the warning has attached notes. 

98 """ 

99 return hasattr(self, "__notes__") and self.__notes__ is not None and len(self.__notes__) > 0 

100 

101 @readonly 

102 def Notes(self) -> Tuple[str, ...]: 

103 """ 

104 Read-only property to return warning's attached notes. 

105 

106 :returns: Attached notes. 

107 """ 

108 return tuple(self.__notes__) if hasattr(self, "__notes__") else tuple() 

109 

110 

111@export 

112class ExceptionBase(Exception): 

113 """Base exception derived from :exc:`Exception <python:Exception>` for all custom exceptions.""" 

114 

115 def __init__(self, message: str = "") -> None: 

116 """ 

117 ExceptionBase initializer. 

118 

119 :param message: The exception message. 

120 """ 

121 super().__init__() 

122 self.message = message 

123 

124 @readonly 

125 def HasNotes(self) -> bool: 

126 """ 

127 Read-only property to return if the warning has attached notes. 

128 

129 :returns: True, if the warning has attached notes. 

130 """ 

131 return hasattr(self, "__notes__") and self.__notes__ is not None and len(self.__notes__) > 0 

132 

133 @readonly 

134 def Notes(self) -> Tuple[str, ...]: 

135 """ 

136 Read-only property to return warning's attached notes. 

137 

138 :returns: Attached notes. 

139 """ 

140 return tuple(self.__notes__) if hasattr(self, "__notes__") else tuple() 

141 

142 def __str__(self) -> str: 

143 """Returns the exception's message text.""" 

144 return self.message 

145 

146 # @DocumentMemberAttribute(False) 

147 # @MethodAlias(pyExceptions.with_traceback) 

148 # def with_traceback(self): pass 

149 

150 

151@export 

152class EnvironmentException(ExceptionBase): 

153 """The exception is raised when an expected environment variable is missing.""" 

154 

155 

156# ConfigurationException 

157# 

158 

159@export 

160class PlatformNotSupportedException(ExceptionBase): 

161 """The exception is raise if the platform is not supported.""" 

162 

163 

164@export 

165class NotConfiguredException(ExceptionBase): 

166 """The exception is raise if the requested setting is not configured.""" 

167 

168 

169# FIXME: Why not derived from ExceptionBase? 

170@export 

171class ToolingException(Exception): 

172 """The exception is raised by pyTooling internal features.""" 

173 

174 @readonly 

175 def HasNotes(self) -> bool: 

176 """ 

177 Read-only property to return if the warning has attached notes. 

178 

179 :returns: True, if the warning has attached notes. 

180 """ 

181 return hasattr(self, "__notes__") and self.__notes__ is not None and len(self.__notes__) > 0 

182 

183 @readonly 

184 def Notes(self) -> Tuple[str, ...]: 

185 """ 

186 Read-only property to return warning's attached notes. 

187 

188 :returns: Attached notes. 

189 """ 

190 return tuple(self.__notes__) if hasattr(self, "__notes__") else tuple()