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

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''' Common names and type aliases. ''' 

22 

23 

24from . import imports as __ 

25 

26 

27ComparisonResult: __.typx.TypeAlias = bool | __.types.NotImplementedType 

28NominativeArguments: __.typx.TypeAlias = __.cabc.Mapping[ str, __.typx.Any ] 

29PositionalArguments: __.typx.TypeAlias = __.cabc.Sequence[ __.typx.Any ] 

30 

31 

32package_name = __name__.split( '.', maxsplit = 1 )[ 0 ] 

33 

34 

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' ) ) 

47 

48 

49class AttrnameCalculator: 

50 ''' Calculates framework attribute names from level and core. 

51 

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 ''' 

69 

70 def __init__( self, package_name: str = package_name ) -> None: 

71 self._package_name = package_name 

72 

73 @property 

74 def package_name( self ) -> str: 

75 ''' Package prefix this calculator generates and detects. ''' 

76 return self._package_name 

77 

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 

104 

105 def __call__( self, level: str, core: str ) -> str: 

106 return f"_{self.package_name}_{level}_{core}_" 

107 

108 

109calculate_attrname = AttrnameCalculator( ) 

110 

111 

112def calculate_contribution_name( ) -> str: 

113 ''' Returns metaclass attribute name holding internal-name detectors. ''' 

114 return f"_{package_name}_internal_names_"