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 

24import icecream as _icecream 

25 

26from . import __ 

27 

28 

29class FormatterControl( __.immut.DataclassObject ): 

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

31 

32 columns_count_effective: __.typx.Annotated[ 

33 __.typx.Optional[ int ], 

34 __.typx.Doc( 

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

36 

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

38 ''' 

39 ), 

40 ] = None 

41 

42 

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

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

45FormatterFactory: __.typx.TypeAlias = ( 

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

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

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

49 

50 

51class FlavorConfiguration( __.immut.DataclassObject ): 

52 ''' Per-flavor configuration. ''' 

53 

54 formatter_factory: __.typx.Annotated[ 

55 __.typx.Optional[ FormatterFactory ], 

56 __.typx.Doc( 

57 ''' Factory which produces formatter callable. 

58 

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

60 Returns formatter to convert an argument to a string. 

61 

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

63 ''' ), 

64 ] = None 

65 include_context: __.typx.Annotated[ 

66 __.typx.Optional[ bool ], 

67 __.typx.Doc( 

68 ''' Include stack frame with output? 

69 

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

71 ''' ), 

72 ] = None 

73 prefix_emitter: __.typx.Annotated[ 

74 __.typx.Optional[ PrefixEmitterUnion ], 

75 __.typx.Doc( 

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

77 

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

79 arguments. Returns prefix string. 

80 

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

82 ''' ), 

83 ] = None 

84 

85 

86def produce_default_flavors( ) -> __.immut.Dictionary[ 

87 Flavor, FlavorConfiguration 

88]: 

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

90 return __.immut.Dictionary( { 

91 i: FlavorConfiguration( 

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

93 

94 

95FlavorsRegistry: __.typx.TypeAlias = ( 

96 __.immut.Dictionary[ Flavor, FlavorConfiguration ] ) 

97FlavorsRegistryLiberal: __.typx.TypeAlias = ( 

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

99 

100 

101class ModuleConfiguration( __.immut.DataclassObject ): 

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( __.immut.DataclassObject ): 

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