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 flavors: __.typx.Annotated[ 

93 FlavorsRegistry, 

94 __.typx.Doc( 

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

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

97 formatter_factory: __.typx.Annotated[ 

98 __.typx.Optional[ FormatterFactory ], 

99 __.typx.Doc( 

100 ''' Factory which produces formatter callable. 

101 

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

103 Returns formatter to convert an argument to a string. 

104 

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

106 ''' ), 

107 ] = None 

108 include_context: __.typx.Annotated[ 

109 __.typx.Optional[ bool ], 

110 __.typx.Doc( 

111 ''' Include stack frame with output? 

112 

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

114 ''' ), 

115 ] = None 

116 prefix_emitter: __.typx.Annotated[ 

117 __.typx.Optional[ PrefixEmitterUnion ], 

118 __.typx.Doc( 

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

120 

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

122 arguments. Returns prefix string. 

123 

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

125 ''' ), 

126 ] = None 

127 

128 

129class VehicleConfiguration( metaclass = __.ImmutableCompleteDataclass ): 

130 ''' Per-vehicle configuration. ''' 

131 

132 flavors: __.typx.Annotated[ 

133 FlavorsRegistry, 

134 __.typx.Doc( 

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

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

137 formatter_factory: __.typx.Annotated[ 

138 FormatterFactory, 

139 __.typx.Doc( 

140 ''' Factory which produces formatter callable. 

141 

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

143 Returns formatter to convert an argument to a string. 

144 ''' ), 

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

146 include_context: __.typx.Annotated[ 

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

148 ] = False 

149 prefix_emitter: __.typx.Annotated[ 

150 PrefixEmitterUnion, 

151 __.typx.Doc( 

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

153 

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

155 arguments. Returns prefix string. 

156 ''' ), 

157 ] = _icecream.DEFAULT_PREFIX 

158 

159 

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

161FlavorsRegistry: __.typx.TypeAlias = ( 

162 __.ImmutableDictionary[ Flavor, FlavorConfiguration ] ) 

163FlavorsRegistryLiberal: __.typx.TypeAlias = ( 

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

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

166FormatterFactory: __.typx.TypeAlias = ( 

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

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

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