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
« 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 -*-
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#============================================================================#
21''' Catalog of common type aliases. '''
24from . import __
27AttributesNamer: __.typx.TypeAlias = __.typx.Annotated[
28 __.cabc.Callable[ [ str, str ], str ],
29 __.ddoc.Doc(
30 ''' Names attribute from level and core arguments.
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).
38 Can be used by downstream packages to determine names of
39 bookkeeping attributes assigned by this package.
40 ''' ),
41]
43Decorator: __.typx.TypeAlias = __.typx.Annotated[
44 __.cabc.Callable[ [ type[ __.U ] ], type[ __.U ] ],
45 __.ddoc.Doc(
46 ''' Class decorator.
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.
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.
64 Each element takes a class argument and returns a class.
66 Decorators may be inserted or removed from sequence.
67 ''' ),
68]
70ClassDecorator: __.typx.TypeAlias = __.typx.Annotated[
71 __.cabc.Callable[ [ type[ __.U ] ], type[ __.U ] ],
72 __.ddoc.Doc(
73 ''' Class decorator.
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.
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.
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.
99 Takes a mapping of attribute names to values and applies
100 reclassification (e.g., immutability and concealment).
101 ''' ),
102]
104DecorationPreparer: __.typx.TypeAlias = __.typx.Annotated[
105 __.cabc.Callable[ [ type[ __.U ], DecoratorsMutable[ __.U ] ], None ],
106 __.ddoc.Doc(
107 ''' Class decoration preparer.
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.
118 Each element takes class and mutable sequence of decorators as
119 arguments. And, each element can alter the sequence.
120 ''' ),
121]
123ClassConstructorLigation: __.typx.TypeAlias = __.typx.Annotated[
124 __.cabc.Callable[ ..., type ],
125 __.ddoc.Doc(
126 ''' Bound class constructor function.
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.
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.
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.
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.
160 Usually from ``super( ).__dir__`` or a partial function.
161 ''' ),
162]
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.
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.
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.
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]
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.
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.
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.
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).
264 Invoked only at the most-derived metaclass of a class.
265 ''' ),
266]
269def is_public_identifier( name: str ) -> bool:
270 ''' Is Python identifier public? '''
271 return not name.startswith( '_' )