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, # metaclass 

218 ClassConstructorLigation, # next constructor in metaclass MRO 

219 str, # class name 

220 tuple[ type, ... ], # bases 

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

222 __.NominativeArguments, # metaclass arguments 

223 Decorators[ __.U ], # decorators to apply after 

224 ], 

225 type 

226 ], 

227 __.ddoc.Doc( 

228 ''' Constructs class, then applies hooks. 

229 

230 Receives the metaclass ('clscls'), the next constructor in 

231 the metaclass MRO ('superf'), the class name, bases, 

232 namespace, metaclass arguments, and decorators to apply 

233 after construction. Calls 'superf' to create the class, 

234 then applies postprocessors and decorators. 

235 

236 Invoked only at the most-derived metaclass of a class. 

237 Class factory wrappers on parent metaclasses delegate 

238 directly, so construction hooks execute exactly once per 

239 class. 

240 ''' ), 

241] 

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

243 __.cabc.Callable[ 

244 [ 

245 type, # class 

246 InitializerLigation, # next initializer in metaclass MRO 

247 __.PositionalArguments, # positional arguments 

248 __.NominativeArguments, # nominative arguments 

249 ], 

250 None 

251 ], 

252 __.ddoc.Doc( 

253 ''' Initializes class, then applies hooks. 

254 

255 Receives the class ('cls'), the next initializer in the 

256 metaclass MRO ('superf'), positional arguments, and 

257 nominative arguments. Calls 'superf' first, then applies 

258 completers, which finalize class behaviors (e.g., enable 

259 immutability once all other initialization has occurred). 

260 

261 Invoked only at the most-derived metaclass of a class. 

262 ''' ), 

263] 

264 

265 

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

267 ''' Is Python identifier public? ''' 

268 return not name.startswith( '_' )