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 

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

90FlavorsRegistry: __.typx.TypeAlias = ( 

91 __.ImmutableDictionary[ Flavor, FlavorConfiguration ] ) 

92FlavorsRegistryLiberal: __.typx.TypeAlias = ( 

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

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

95FormatterFactory: __.typx.TypeAlias = ( 

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

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

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

99 

100 

101class ModuleConfiguration( metaclass = __.ImmutableCompleteDataclass ): 

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

103 

104 flavors: __.typx.Annotated[ 

105 FlavorsRegistry, 

106 __.typx.Doc( 

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

108 ] = __.dcls.field( default_factory = FlavorsRegistry ) 

109 formatter_factory: __.typx.Annotated[ 

110 __.typx.Optional[ FormatterFactory ], 

111 __.typx.Doc( 

112 ''' Factory which produces formatter callable. 

113 

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

115 Returns formatter to convert an argument to a string. 

116 

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

118 ''' ), 

119 ] = None 

120 include_context: __.typx.Annotated[ 

121 __.typx.Optional[ bool ], 

122 __.typx.Doc( 

123 ''' Include stack frame with output? 

124 

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

126 ''' ), 

127 ] = None 

128 prefix_emitter: __.typx.Annotated[ 

129 __.typx.Optional[ PrefixEmitterUnion ], 

130 __.typx.Doc( 

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

132 

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

134 arguments. Returns prefix string. 

135 

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

137 ''' ), 

138 ] = None 

139 

140 

141class VehicleConfiguration( metaclass = __.ImmutableCompleteDataclass ): 

142 ''' Per-vehicle configuration. ''' 

143 

144 flavors: __.typx.Annotated[ 

145 FlavorsRegistry, 

146 __.typx.Doc( 

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

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

149 formatter_factory: __.typx.Annotated[ 

150 FormatterFactory, 

151 __.typx.Doc( 

152 ''' Factory which produces formatter callable. 

153 

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

155 Returns formatter to convert an argument to a string. 

156 ''' ), 

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

158 include_context: __.typx.Annotated[ 

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

160 ] = False 

161 prefix_emitter: __.typx.Annotated[ 

162 PrefixEmitterUnion, 

163 __.typx.Doc( 

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

165 

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

167 arguments. Returns prefix string. 

168 ''' ), 

169 ] = _icecream.DEFAULT_PREFIX