Hide keyboard shortcuts

Hot-keys on this page

r m x p   toggle line displays

j k   next/prev highlighted chunk

0   (zero) top of page

1   (one) first highlighted chunk

1""":mod:`wand.assertions` --- Input assertion helpers 

2~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 

3 

4This module checks user input before calling MagickWands C-API methods. 

5 

6 

7.. versionadded:: 0.5.4 

8""" 

9 

10import numbers 

11try: 

12 from collections.abc import Sequence 

13except ImportError: 

14 from collections import Sequence 

15 

16from .compat import string_type 

17 

18 

19def assert_bool(**kwargs): 

20 """Ensure all given values are boolean. 

21 

22 :raises TypeError: if value is not ``True`` or ``False. 

23 

24 .. versionadded:: 0.5.4 

25 """ 

26 for label, subject in kwargs.items(): 

27 if not isinstance(subject, bool): 

28 fmt = "{0} must be a bool, not {1}" 

29 msg = fmt.format(label, repr(subject)) 

30 raise TypeError(msg) 

31 

32 

33def assert_color(**kwargs): 

34 """Ensure all given values are instances of :class:`~wand.color.Color`. 

35 

36 :raises TypeError: if value is not :class:`~wand.color.Color`. 

37 

38 .. versionadded:: 0.5.4 

39 """ 

40 for label, subject in kwargs.items(): 

41 if not isinstance(subject, Color): 

42 fmt = "Expecting an instance of wand.color.Color for {0}, not {1}" 

43 msg = fmt.format(label, repr(subject)) 

44 raise TypeError(msg) 

45 

46 

47def assert_counting_number(**kwargs): 

48 """Ensure all given values are natural integer. 

49 

50 :raises TypeError: if value is not an integer. 

51 :raises ValueError: if value is less than ``1``. 

52 

53 .. versionadded:: 0.5.4 

54 """ 

55 assert_integer(**kwargs) 

56 for label, subject in kwargs.items(): 

57 if subject < 1: 

58 fmt = "{0}={1} must be an natural number greater than 0" 

59 msg = fmt.format(label, subject) 

60 raise ValueError(msg) 

61 

62 

63def assert_integer(**kwargs): 

64 """Ensure all given values are an integer. 

65 

66 :raises TypeError: if value is not an integer. 

67 

68 .. versionadded:: 0.5.4 

69 """ 

70 for label, subject in kwargs.items(): 

71 if not isinstance(subject, numbers.Integral): 

72 fmt = "{0} must be an integer, not {1}" 

73 msg = fmt.format(label, repr(subject)) 

74 raise TypeError(msg) 

75 

76 

77def assert_real(**kwargs): 

78 """Ensure all given values are real numbers. 

79 

80 :raises TypeError: if value is not a real number. 

81 

82 .. versionadded:: 0.5.4 

83 """ 

84 for label, subject in kwargs.items(): 

85 if not isinstance(subject, numbers.Real): 

86 fmt = "{0} must be a real number, not {1}" 

87 msg = fmt.format(label, repr(subject)) 

88 raise TypeError(msg) 

89 

90 

91def assert_unsigned_integer(**kwargs): 

92 """Ensure all given values are positive integer. 

93 

94 :raises TypeError: if value is not an integer. 

95 :raises ValueError: if value is less than ``0``. 

96 

97 .. versionadded:: 0.5.4 

98 """ 

99 assert_integer(**kwargs) 

100 for label, subject in kwargs.items(): 

101 if subject < 0: 

102 fmt = "{0}={1} must be a positive integer" 

103 msg = fmt.format(label, subject) 

104 raise ValueError(msg) 

105 

106 

107def assert_coordinate(**kwargs): 

108 """Ensure all given values are a sequence of 2 real numbers. 

109 

110 :raises TypeError: if value is not a pair of doubles. 

111 

112 .. versionadded:: 0.6.0 

113 """ 

114 for label, subject in kwargs.items(): 

115 if not isinstance(subject, Sequence): 

116 fmt = "'{0}' must be a pair of real numbers, not {1}" 

117 msg = fmt.format(label, repr(subject)) 

118 raise TypeError(msg) 

119 elif len(subject) != 2: 

120 fmt = "'{0}' must be a exactly 2 real numbers, not {1}" 

121 msg = fmt.format(label, len(subject)) 

122 raise ValueError(msg) 

123 elif not isinstance(subject[0], numbers.Real): 

124 fmt = "first entry of '{0}' must be a real number, not {1}" 

125 msg = fmt.format(label, repr(subject[0])) 

126 raise TypeError(msg) 

127 elif not isinstance(subject[1], numbers.Real): 

128 fmt = "second entry of '{0}' must be a real number, not {1}" 

129 msg = fmt.format(label, repr(subject[1])) 

130 raise TypeError(msg) 

131 

132 

133def assert_string(**kwargs): 

134 for label, subject in kwargs.items(): 

135 if not isinstance(subject, string_type): 

136 fmt = "{0} must be a string, not {1}" 

137 msg = fmt.format(label, repr(subject)) 

138 raise TypeError(msg) 

139 

140 

141def in_list(options, label, **kwargs): 

142 for subject_label, subject in kwargs.items(): 

143 if subject not in options: 

144 fmt = "{0} must be defined in {1}, not {2}" 

145 msg = fmt.format(subject_label, label, repr(subject)) 

146 raise ValueError(msg) 

147 

148 

149def string_in_list(options, label, **kwargs): 

150 assert_string(**kwargs) 

151 in_list(options, label, **kwargs) 

152 

153 

154# Lazy load recursive import 

155from .color import Color # noqa: E402