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 

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

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

69 __.ddoc.Doc( 

70 ''' Class decorator. 

71 

72 Takes class argument and returns class. 

73 ''' ), 

74] 

75ClassDecorators: __.typx.TypeAlias = __.typx.Annotated[ 

76 __.cabc.Sequence[ ClassDecorator[ __.U ] ], 

77 __.ddoc.Doc( 

78 ''' Sequence of class decorators. 

79 

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

81 ''' ), 

82] 

83ClassDecoratorFactory: __.typx.TypeAlias = __.typx.Annotated[ 

84 __.cabc.Callable[ ..., ClassDecorator[ __.U ] ], 

85 __.ddoc.Doc( 

86 ''' Factory that produces class decorators. 

87 

88 Returns a class decorator when called. 

89 ''' ), 

90] 

91ModuleReclassifier: __.typx.TypeAlias = __.typx.Annotated[ 

92 __.cabc.Callable[ [ __.cabc.Mapping[ str, __.typx.Any ] ], None ], 

93 __.ddoc.Doc( 

94 ''' Reclassifies module attributes. 

95 

96 Takes a mapping of attribute names to values and applies 

97 reclassification (e.g., immutability and concealment). 

98 ''' ), 

99] 

100 

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

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

103 __.ddoc.Doc( 

104 ''' Class decoration preparer. 

105 

106 Takes class and mutable sequence of decorators as arguments. 

107 Can alter the sequence. 

108 ''' ), 

109] 

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

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

112 __.ddoc.Doc( 

113 ''' Sequence of class decoration preparers. 

114 

115 Each element takes class and mutable sequence of decorators as 

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

117 ''' ), 

118] 

119 

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

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

122 __.ddoc.Doc( 

123 ''' Bound class constructor function. 

124 

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

126 ''' ), 

127] 

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

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

130 __.ddoc.Doc( 

131 ''' Bound initializer function. 

132 

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

134 ''' ), 

135] 

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

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

138 __.ddoc.Doc( 

139 ''' Bound attributes assigner function. 

140 

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

142 ''' ), 

143] 

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

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

146 __.ddoc.Doc( 

147 ''' Bound attributes deleter function. 

148 

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

150 ''' ), 

151] 

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

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

154 __.ddoc.Doc( 

155 ''' Bound attributes surveyor function. 

156 

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

158 ''' ), 

159] 

160 

161 

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

163 __.cabc.Callable[ 

164 [ 

165 type[ type ], # metaclass 

166 str, # class name 

167 list[ type ], # bases (mutable) 

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

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

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

171 ], 

172 None 

173 ], 

174 __.ddoc.Doc( 

175 ''' Processes class data before construction. 

176 

177 For use cases, such as argument conversion. 

178 ''' ), 

179] 

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

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

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

183] 

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

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

186 __.ddoc.Doc( 

187 ''' Processes class before decoration. 

188 

189 For use cases, such as decorator list manipulation. 

190 ''' ), 

191] 

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

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

194 __.ddoc.Doc( 

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

196] 

197# TODO: ClassInitializationPreparer (arguments mutation) 

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

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

200 __.ddoc.Doc( 

201 ''' Completes initialization of class. 

202 

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

204 initialization has occurred. 

205 ''' ), 

206] 

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

208 __.cabc.Sequence[ ClassInitializationCompleter ], 

209 __.ddoc.Doc( 

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

211] 

212 

213 

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

215 __.cabc.Callable[ 

216 [ 

217 type, 

218 ClassConstructorLigation, 

219 str, 

220 tuple[ type, ... ], 

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

222 __.NominativeArguments, 

223 Decorators[ __.U ], 

224 ], 

225 type 

226 ], 

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

228] 

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

230 __.cabc.Callable[ 

231 [ 

232 type, 

233 InitializerLigation, 

234 __.PositionalArguments, 

235 __.NominativeArguments, 

236 ], 

237 None 

238 ], 

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

240] 

241 

242 

243def is_public_identifier( name: str ) -> bool: 

244 ''' Is Python identifier public? ''' 

245 return not name.startswith( '_' )