Coverage for sources/classcore/standard/__.py: 100%

24 statements  

« prev     ^ index     » next       coverage.py v7.16.2, created at 2026-10-15 02:08 +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 constants, imports, and utilities. ''' 

22 

23# ruff: noqa: F403, F405 

24 

25 

26from ..__ import * 

27from ..nomina import is_public_identifier 

28 

29 

30def provide_error_class( name: str ) -> type[ Exception ]: 

31 ''' Produces error class for this package. ''' 

32 match name: 

33 case 'AttributeImmutability': 

34 from ..exceptions import AttributeImmutability as error 

35 case _: 

36 from ..exceptions import ErrorProvideFailure 

37 raise ErrorProvideFailure( name, reason = 'Does not exist.' ) 

38 return error 

39 

40 

41mutables_default = ( ) 

42visibles_default = ( is_public_identifier, ) 

43 

44# Standard library ABC machinery attribute names which the class-level 

45# immutability behavior permits. The C _abc implementation writes these 

46# cache attributes through direct dict access, so they must remain 

47# assignable on standard classes. Also used to mark such names as 

48# internal in attribute explanations. 

49abc_class_mutables = ( 

50 '_abc_cache', 

51 '_abc_negative_cache', 

52 '_abc_negative_cache_version', 

53 '_abc_registry', 

54) 

55# Standard library typing machinery attribute names which the 

56# class-level immutability behavior permits on protocol classes. 

57# 'typing' sets these protocol bookkeeping attributes during class 

58# decoration: '_is_runtime_protocol' and '__non_callable_proto_members__' 

59# in the 'runtime_checkable' decorator, and 

60# '__typing_is_deprecated_inherited_runtime_protocol__' (CPython 3.15+) 

61# during class decoration and in 'runtime_checkable'. Without this 

62# exemption, decorating a runtime protocol which inherits runtime 

63# checkability fails. Also used to mark such names as internal in 

64# attribute explanations. 

65typing_class_mutables = ( 

66 '_is_runtime_protocol', 

67 '__non_callable_proto_members__', 

68 '__typing_is_deprecated_inherited_runtime_protocol__', # Python 3.15+ 

69) 

70 

71 

72def is_same_detector( 

73 detector: cabc.Callable[ [ str ], bool ], 

74 other: cabc.Callable[ [ str ], bool ], /, 

75) -> bool: 

76 ''' Returns whether two detector references are the same detector. 

77 

78 Bound methods are the same detector only when both the 

79 underlying function and the bound instance are identical, so 

80 distinct namer instances with distinct configured behavior keep 

81 separate contributions. Plain callables compare by identity. 

82 ''' 

83 if detector is other: return True 

84 function = getattr( detector, '__func__', None ) 

85 other_function = getattr( other, '__func__', None ) 

86 if function is None or other_function is None: return False 

87 return ( 

88 function is other_function 

89 and getattr( detector, '__self__', None ) 

90 is getattr( other, '__self__', None ) ) 

91 

92 

93def augment_internal_names( 

94 cls: type, /, detector: cabc.Callable[ [ str ], bool ] 

95) -> None: 

96 ''' Adds an internal-name detector to existing contributions. 

97 

98 Private wiring point for machinery mixins: the abstract-base 

99 metaclass adds the stdlib machinery set after factory 

100 decoration, without expanding public factory arguments. 

101 ''' 

102 detectors = getattr( cls, calculate_contribution_name( ), ( ) ) 

103 if any( is_same_detector( detector, d ) for d in detectors ): return 

104 setattr( 

105 cls, calculate_contribution_name( ), 

106 ( *detectors, detector ) )