Coverage for sources/ictruck/configuration.py: 100%

1# vim: set filetype=python fileencoding=utf-8: 

2# -*- coding: utf-8 -*- 

3 

4#============================================================================# 

5# # 

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

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

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

9# # 

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

11# # 

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

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

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

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

16# limitations under the License. # 

17# # 

18#============================================================================# 

19 

20 

21''' Portions of configuration hierarchy. ''' 

22 

23 

24from __future__ import annotations 

25 

26import icecream as _icecream 

27 

28from . import __ 

29 

30 

31def produce_default_flavors( ) -> __.ImmutableDictionary[ 

32 Flavor, FlavorConfiguration 

33]: 

34 ''' Produces flavors for trace depths 0 through 9. ''' 

35 return __.ImmutableDictionary( { 

36 i: FlavorConfiguration( 

37 prefix_emitter = f"TRACE{i}| " ) for i in range( 10 ) } ) 

38 

39 

40class FormatterControl( metaclass = __.ImmutableCompleteDataclass ): 

41 ''' Contextual data for formatter and prefix factories. ''' 

42 

43 columns_count_effective: __.typx.Annotated[ 

44 __.typx.Optional[ int ], 

45 __.typx.Doc( 

46 ''' Available line length after accounting for embellishments. 

47 

48 May be ``None`` if not determinable. 

49 ''' 

50 ), 

51 ] = None 

52 

53 

54class FlavorConfiguration( metaclass = __.ImmutableCompleteDataclass ): 

55 ''' Per-flavor configuration. ''' 

56 

57 formatter_factory: __.typx.Annotated[ 

58 __.typx.Optional[ FormatterFactory ], 

59 __.typx.Doc( 

60 ''' Factory which produces formatter callable. 

61 

62 Takes formatter control, module name, and flavor as arguments. 

63 Returns formatter to convert an argument to a string. 

64 

65 Default ``None`` inherits from cumulative configuration. 

66 ''' ), 

67 ] = None 

68 include_context: __.typx.Annotated[ 

69 __.typx.Optional[ bool ], 

70 __.typx.Doc( 

71 ''' Include stack frame with output? 

72 

73 Default ``None`` inherits from cumulative configuration. 

74 ''' ), 

75 ] = None 

76 prefix_emitter: __.typx.Annotated[ 

77 __.typx.Optional[ PrefixEmitterUnion ], 

78 __.typx.Doc( 

79 ''' String or factory which produces output prefix string. 

80 

81 Factory takes formatter control, module name, and flavor as 

82 arguments. Returns prefix string. 

83 

84 Default ``None`` inherits from cumulative configuration. 

85 ''' ), 

86 ] = None 

87 

88 

89class ModuleConfiguration( metaclass = __.ImmutableCompleteDataclass ): 

90 ''' Per-module or per-package configuration. ''' 

91 

92 # pylint: disable=invalid-field-call 

93 flavors: __.typx.Annotated[ 

94 FlavorsRegistry, 

95 __.typx.Doc( 

96 ''' Registry of flavor identifiers to configurations. ''' ), 

97 ] = __.dcls.field( default_factory = __.ImmutableDictionary ) # pyright: ignore 

98 formatter_factory: __.typx.Annotated[ 

99 __.typx.Optional[ FormatterFactory ], 

100 __.typx.Doc( 

101 ''' Factory which produces formatter callable. 

102 

103 Takes formatter control, module name, and flavor as arguments. 

104 Returns formatter to convert an argument to a string. 

105 

106 Default ``None`` inherits from cumulative configuration. 

107 ''' ), 

108 ] = None 

109 include_context: __.typx.Annotated[ 

110 __.typx.Optional[ bool ], 

111 __.typx.Doc( 

112 ''' Include stack frame with output? 

113 

114 Default ``None`` inherits from cumulative configuration. 

115 ''' ), 

116 ] = None 

117 prefix_emitter: __.typx.Annotated[ 

118 __.typx.Optional[ PrefixEmitterUnion ], 

119 __.typx.Doc( 

120 ''' String or factory which produces output prefix string. 

121 

122 Factory takes formatter control, module name, and flavor as 

123 arguments. Returns prefix string. 

124 

125 Default ``None`` inherits from cumulative configuration. 

126 ''' ), 

127 ] = None 

128 # pylint: enable=invalid-field-call 

129 

130 

131class VehicleConfiguration( metaclass = __.ImmutableCompleteDataclass ): 

132 ''' Per-vehicle configuration. ''' 

133 

134 # pylint: disable=invalid-field-call 

135 flavors: __.typx.Annotated[ 

136 FlavorsRegistry, 

137 __.typx.Doc( 

138 ''' Registry of flavor identifiers to configurations. ''' ), 

139 ] = __.dcls.field( default_factory = produce_default_flavors ) 

140 formatter_factory: __.typx.Annotated[ 

141 FormatterFactory, 

142 __.typx.Doc( 

143 ''' Factory which produces formatter callable. 

144 

145 Takes formatter control, module name, and flavor as arguments. 

146 Returns formatter to convert an argument to a string. 

147 ''' ), 

148 ] = lambda ctrl, mname, flavor: _icecream.DEFAULT_ARG_TO_STRING_FUNCTION 

149 include_context: __.typx.Annotated[ 

150 bool, __.typx.Doc( ''' Include stack frame with output? ''' ) 

151 ] = False 

152 prefix_emitter: __.typx.Annotated[ 

153 PrefixEmitterUnion, 

154 __.typx.Doc( 

155 ''' String or factory which produces output prefix string. 

156 

157 Factory takes formatter control, module name, and flavor as 

158 arguments. Returns prefix string. 

159 ''' ), 

160 ] = _icecream.DEFAULT_PREFIX 

161 # pylint: enable=invalid-field-call 

162 

163 

164Flavor: __.typx.TypeAlias = int | str 

165FlavorsRegistry: __.typx.TypeAlias = ( 

166 __.ImmutableDictionary[ Flavor, FlavorConfiguration ] ) 

167FlavorsRegistryLiberal: __.typx.TypeAlias = ( 

168 __.cabc.Mapping[ Flavor, FlavorConfiguration ] ) 

169Formatter: __.typx.TypeAlias = __.typx.Callable[ [ __.typx.Any ], str ] 

170FormatterFactory: __.typx.TypeAlias = ( 

171 __.typx.Callable[ [ FormatterControl, str, Flavor ], Formatter ] ) 

172PrefixEmitter: __.typx.TypeAlias = __.typx.Callable[ [ str, Flavor ], str ] 

173PrefixEmitterUnion: __.typx.TypeAlias = str | PrefixEmitter