Coverage for sources/classcore/nomina.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''' Catalog of common type aliases. ''' 

22 

23 

24from . import __ 

25 

26 

27AttributesNamer: __.typx.TypeAlias = __.typx.Annotated[ 

28 __.cabc.Callable[ [ str, str ], str ], 

29 __.ddoc.Doc( 

30 ''' Names attribute from level and core arguments. 

31 

32 Level will be one of 'class', 'instances', or 'instance'. 

33 Core will be the core of the name as supplied this package. 

34 

35 Can be used by downstream packages to determine names of 

36 bookkeeping attributes assigned by this package. 

37 ''' ), 

38] 

39 

40Decorator: __.typx.TypeAlias = __.typx.Annotated[ 

41 __.cabc.Callable[ [ type[ __.U ] ], type[ __.U ] ], 

42 __.ddoc.Doc( 

43 ''' Class decorator. 

44 

45 Takes class argument and returns class. 

46 ''' ), 

47] 

48Decorators: __.typx.TypeAlias = __.typx.Annotated[ 

49 __.cabc.Sequence[ Decorator[ __.U ] ], 

50 __.ddoc.Doc( 

51 ''' Sequence of class decorators. 

52 

53 Each element takes a class argument and returns a class. 

54 ''' ), 

55] 

56DecoratorsMutable: __.typx.TypeAlias = __.typx.Annotated[ 

57 __.cabc.MutableSequence[ Decorator[ __.U ] ], 

58 __.ddoc.Doc( 

59 ''' Sequence of class decorators. 

60 

61 Each element takes a class argument and returns a class. 

62 

63 Decorators may be inserted or removed from sequence. 

64 ''' ), 

65] 

66 

67DecorationPreparer: __.typx.TypeAlias = __.typx.Annotated[ 

68 __.cabc.Callable[ [ type[ __.U ], DecoratorsMutable[ __.U ] ], None ], 

69 __.ddoc.Doc( 

70 ''' Class decoration preparer. 

71 

72 Takes class and mutable sequence of decorators as arguments. 

73 Can alter the sequence. 

74 ''' ), 

75] 

76DecorationPreparers: __.typx.TypeAlias = __.typx.Annotated[ 

77 __.cabc.Sequence[ DecorationPreparer[ __.U ] ], 

78 __.ddoc.Doc( 

79 ''' Sequence of class decoration preparers. 

80 

81 Each element takes class and mutable sequence of decorators as 

82 arguments. And, each element can alter the sequence. 

83 ''' ), 

84] 

85 

86ClassConstructorLigation: __.typx.TypeAlias = __.typx.Annotated[ 

87 __.cabc.Callable[ ..., type ], 

88 __.ddoc.Doc( 

89 ''' Bound class constructor function. 

90 

91 Usually from ``super( ).__new__`` or a partial function. 

92 ''' ), 

93] 

94InitializerLigation: __.typx.TypeAlias = __.typx.Annotated[ 

95 __.cabc.Callable[ ..., None ], 

96 __.ddoc.Doc( 

97 ''' Bound initializer function. 

98 

99 Usually from ``super( ).__init__`` or a partial function. 

100 ''' ), 

101] 

102AssignerLigation: __.typx.TypeAlias = __.typx.Annotated[ 

103 __.cabc.Callable[ [ str, __.typx.Any ], None ], 

104 __.ddoc.Doc( 

105 ''' Bound attributes assigner function. 

106 

107 Usually from ``super( ).__setattr__`` or a partial function. 

108 ''' ), 

109] 

110DeleterLigation: __.typx.TypeAlias = __.typx.Annotated[ 

111 __.cabc.Callable[ [ str ], None ], 

112 __.ddoc.Doc( 

113 ''' Bound attributes deleter function. 

114 

115 Usually from ``super( ).__delattr__`` or a partial function. 

116 ''' ), 

117] 

118SurveyorLigation: __.typx.TypeAlias = __.typx.Annotated[ 

119 __.cabc.Callable[ [ ], __.cabc.Iterable[ str ] ], 

120 __.ddoc.Doc( 

121 ''' Bound attributes surveyor function. 

122 

123 Usually from ``super( ).__dir__`` or a partial function. 

124 ''' ), 

125] 

126 

127 

128ClassConstructionPreprocessor: __.typx.TypeAlias = __.typx.Annotated[ 

129 __.cabc.Callable[ 

130 [ 

131 type[ type ], # metaclass 

132 str, # class name 

133 list[ type ], # bases (mutable) 

134 dict[ str, __.typx.Any ], # namespace (mutable) 

135 dict[ str, __.typx.Any ], # arguments (mutable) 

136 DecoratorsMutable[ __.U ], # decorators (mutable) 

137 ], 

138 None 

139 ], 

140 __.ddoc.Doc( 

141 ''' Processes class data before construction. 

142 

143 For use cases, such as argument conversion. 

144 ''' ), 

145] 

146ClassConstructionPreprocessors: __.typx.TypeAlias = __.typx.Annotated[ 

147 __.cabc.Sequence[ ClassConstructionPreprocessor[ __.U ] ], 

148 __.ddoc.Doc( ''' Processors to apply before construction of class. ''' ), 

149] 

150ClassConstructionPostprocessor: __.typx.TypeAlias = __.typx.Annotated[ 

151 __.cabc.Callable[ [ type, DecoratorsMutable[ __.U ] ], None ], 

152 __.ddoc.Doc( 

153 ''' Processes class before decoration. 

154 

155 For use cases, such as decorator list manipulation. 

156 ''' ), 

157] 

158ClassConstructionPostprocessors: __.typx.TypeAlias = __.typx.Annotated[ 

159 __.cabc.Sequence[ ClassConstructionPostprocessor[ __.U ] ], 

160 __.ddoc.Doc( 

161 ''' Processors to apply before decoration of class. ''' ), 

162] 

163# TODO: ClassInitializationPreparer (arguments mutation) 

164ClassInitializationCompleter: __.typx.TypeAlias = __.typx.Annotated[ 

165 __.cabc.Callable[ [ type ], None ], 

166 __.ddoc.Doc( 

167 ''' Completes initialization of class. 

168 

169 For use cases, such as enabling immutability once all other 

170 initialization has occurred. 

171 ''' ), 

172] 

173ClassInitializationCompleters: __.typx.TypeAlias = __.typx.Annotated[ 

174 __.cabc.Sequence[ ClassInitializationCompleter ], 

175 __.ddoc.Doc( 

176 ''' Processors to apply at final stage of class initialization. ''' ), 

177] 

178 

179 

180ClassConstructor: __.typx.TypeAlias = __.typx.Annotated[ 

181 __.cabc.Callable[ 

182 [ 

183 type, 

184 ClassConstructorLigation, 

185 str, 

186 tuple[ type, ... ], 

187 dict[ str, __.typx.Any ], 

188 __.NominativeArguments, 

189 Decorators[ __.U ], 

190 ], 

191 type 

192 ], 

193 __.ddoc.Doc( ''' Constructor to use with metaclass. ''' ), 

194] 

195ClassInitializer: __.typx.TypeAlias = __.typx.Annotated[ 

196 __.cabc.Callable[ 

197 [ 

198 type, 

199 InitializerLigation, 

200 __.PositionalArguments, 

201 __.NominativeArguments, 

202 ], 

203 None 

204 ], 

205 __.ddoc.Doc( ''' Initializer to use with metaclass. ''' ), 

206]