Coverage for sources/classcore/__/nomina.py: 100%
37 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''' Common names and type aliases. '''
24from . import imports as __
27ComparisonResult: __.typx.TypeAlias = bool | __.types.NotImplementedType
28NominativeArguments: __.typx.TypeAlias = __.cabc.Mapping[ str, __.typx.Any ]
29PositionalArguments: __.typx.TypeAlias = __.cabc.Sequence[ __.typx.Any ]
32package_name = __name__.split( '.', maxsplit = 1 )[ 0 ]
35_levels = frozenset( ( 'class', 'classes', 'instance', 'instances' ) )
36_cores = frozenset( (
37 'behaviors',
38 'construction_arguments',
39 'dynadoc_configuration',
40 'in_progress',
41 'mutables_names', 'mutables_predicates', 'mutables_regexes',
42 'visibles_names', 'visibles_predicates', 'visibles_regexes',
43 'assigner_core', 'deleter_core', 'surveyor_core' ) )
44_hex_digits = frozenset( '0123456789abcdef' )
45_digest_length = 64
46_mangled_cores = frozenset( ( 'class_behaviors', 'class_in_progress' ) )
49class AttrnameCalculator:
50 ''' Calculates framework attribute names from level and core.
52 Reference implementation of the attribute namer convention:
53 call instances to produce names, and consult ``is_internal_name``
54 to detect names this framework generated. The package prefix is
55 construction-time configuration (default: this package):
56 downstream packages construct with their own prefix rather
57 than overriding either method, and it is read-only
58 thereafter: assignment raises, so a registered prefix cannot
59 drift. Detection consults the reserved
60 framework grammar (shape conformance, not proof of
61 generation); generation emits the class-level mangling stems
62 whose bare forms the detector does not accept. Downstream
63 callers writing conformance or drift tests can detect a
64 generated name without the private mangled-core vocabulary:
65 try the bare form first, then the form with 64 'a'
66 characters appended, which covers the two class-level
67 mangling stems the bare form never matches.
68 '''
70 def __init__( self, package_name: str = package_name ) -> None:
71 self._package_name = package_name
73 @property
74 def package_name( self ) -> str:
75 ''' Package prefix this calculator generates and detects. '''
76 return self._package_name
78 def is_internal_name( self, name: str ) -> bool:
79 prefix = f"_{self.package_name}_"
80 if not name.startswith( prefix ):
81 return False
82 body = name[ len( prefix ): ]
83 # Static stems: _{package}_{level}_{core}_, trailing underscore.
84 # The class-level behaviors and in_progress stems are stored
85 # mangled only, so they are excluded from static acceptance.
86 if body.endswith( '_' ):
87 level, _, core = body[ :-1 ].partition( '_' )
88 if level in _levels and core in _cores:
89 return not (
90 'class' == level
91 and f"{level}_{core}" in _mangled_cores )
92 return False
93 # Mangled forms: one of the mangled cores + 64 lowercase hex,
94 # no trailing underscore. The mangling accessors append digests
95 # to these stems only.
96 for mangled_core in _mangled_cores:
97 mangled_prefix = f"{mangled_core}_"
98 if body.startswith( mangled_prefix ):
99 suffix = body[ len( mangled_prefix ): ]
100 return (
101 _digest_length == len( suffix )
102 and all( c in _hex_digits for c in suffix ) )
103 return False
105 def __call__( self, level: str, core: str ) -> str:
106 return f"_{self.package_name}_{level}_{core}_"
109calculate_attrname = AttrnameCalculator( )
112def calculate_contribution_name( ) -> str:
113 ''' Returns metaclass attribute name holding internal-name detectors. '''
114 return f"_{package_name}_internal_names_"