Coverage for sources/classcore/nomina.py: 100%

26 statements  

« prev     ^ index     » next       coverage.py v7.16.2, created at 2026-10-16 06:16 +0000

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', 'classes', 'instance', or 

33 'instances'. Core will be one of the framework cores 

34 named in the attribute-namer grammar (mutables and 

35 visibles rules, assigner, deleter, and surveyor cores, 

36 and construction bookkeeping). 

37 

38 Can be used by downstream packages to determine names of 

39 bookkeeping attributes assigned by this package. 

40 ''' ), 

41] 

42 

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

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

45 __.ddoc.Doc( 

46 ''' Class decorator. 

47 

48 Takes class argument and returns class. 

49 ''' ), 

50] 

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

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

53 __.ddoc.Doc( 

54 ''' Sequence of class decorators. 

55 

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

57 ''' ), 

58] 

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

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

61 __.ddoc.Doc( 

62 ''' Sequence of class decorators. 

63 

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

65 

66 Decorators may be inserted or removed from sequence. 

67 ''' ), 

68] 

69 

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

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

72 __.ddoc.Doc( 

73 ''' Class decorator. 

74 

75 Takes class argument and returns class. 

76 ''' ), 

77] 

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

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

80 __.ddoc.Doc( 

81 ''' Sequence of class decorators. 

82 

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

84 ''' ), 

85] 

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

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

88 __.ddoc.Doc( 

89 ''' Factory that produces class decorators. 

90 

91 Returns a class decorator when called. 

92 ''' ), 

93] 

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

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

96 __.ddoc.Doc( 

97 ''' Reclassifies module attributes. 

98 

99 Takes a mapping of attribute names to values and applies 

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

101 ''' ), 

102] 

103 

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

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

106 __.ddoc.Doc( 

107 ''' Class decoration preparer. 

108 

109 Takes class and mutable sequence of decorators as arguments. 

110 Can alter the sequence. 

111 ''' ), 

112] 

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

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

115 __.ddoc.Doc( 

116 ''' Sequence of class decoration preparers. 

117 

118 Each element takes class and mutable sequence of decorators as 

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

120 ''' ), 

121] 

122 

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

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

125 __.ddoc.Doc( 

126 ''' Bound class constructor function. 

127 

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

129 ''' ), 

130] 

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

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

133 __.ddoc.Doc( 

134 ''' Bound initializer function. 

135 

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

137 ''' ), 

138] 

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

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

141 __.ddoc.Doc( 

142 ''' Bound attributes assigner function. 

143 

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

145 ''' ), 

146] 

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

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

149 __.ddoc.Doc( 

150 ''' Bound attributes deleter function. 

151 

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

153 ''' ), 

154] 

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

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

157 __.ddoc.Doc( 

158 ''' Bound attributes surveyor function. 

159 

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

161 ''' ), 

162] 

163 

164 

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

166 __.cabc.Callable[ 

167 [ 

168 type[ type ], # metaclass 

169 str, # class name 

170 list[ type ], # bases (mutable) 

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

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

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

174 ], 

175 None 

176 ], 

177 __.ddoc.Doc( 

178 ''' Processes class data before construction. 

179 

180 For use cases, such as argument conversion. 

181 ''' ), 

182] 

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

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

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

186] 

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

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

189 __.ddoc.Doc( 

190 ''' Processes class before decoration. 

191 

192 For use cases, such as decorator list manipulation. 

193 ''' ), 

194] 

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

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

197 __.ddoc.Doc( 

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

199] 

200# TODO: ClassInitializationPreparer (arguments mutation) 

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

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

203 __.ddoc.Doc( 

204 ''' Completes initialization of class. 

205 

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

207 initialization has occurred. 

208 ''' ), 

209] 

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

211 __.cabc.Sequence[ ClassInitializationCompleter ], 

212 __.ddoc.Doc( 

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

214] 

215 

216 

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

218 __.cabc.Callable[ 

219 [ 

220 type, # metaclass 

221 ClassConstructorLigation, # next constructor in metaclass MRO 

222 str, # class name 

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

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

225 __.NominativeArguments, # metaclass arguments 

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

227 ], 

228 type 

229 ], 

230 __.ddoc.Doc( 

231 ''' Constructs class, then applies hooks. 

232 

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

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

235 namespace, metaclass arguments, and decorators to apply 

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

237 then applies postprocessors and decorators. 

238 

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

240 Class factory wrappers on parent metaclasses delegate 

241 directly, so construction hooks execute exactly once per 

242 class. 

243 ''' ), 

244] 

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

246 __.cabc.Callable[ 

247 [ 

248 type, # class 

249 InitializerLigation, # next initializer in metaclass MRO 

250 __.PositionalArguments, # positional arguments 

251 __.NominativeArguments, # nominative arguments 

252 ], 

253 None 

254 ], 

255 __.ddoc.Doc( 

256 ''' Initializes class, then applies hooks. 

257 

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

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

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

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

262 immutability once all other initialization has occurred). 

263 

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

265 ''' ), 

266] 

267 

268 

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

270 ''' Is Python identifier public? ''' 

271 return not name.startswith( '_' )