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

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''' Utilities for the decoration of classes, including metaclasses. ''' 

22 

23 

24from . import __ 

25from . import nomina as _nomina 

26from . import utilities as _utilities 

27 

28 

29def apply_decorators( 

30 cls: type[ __.U ], decorators: _nomina.Decorators[ __.U ] 

31) -> type: 

32 ''' Applies sequence of decorators to class. 

33 

34 If decorators replace classes (e.g., ``dataclass( slots = True )``), 

35 then any necessary repairs are performed on the replacement class with 

36 respect to the original. E.g., on CPython, the class closure cell is 

37 repaired so that ``super`` operates correctly in methods of the 

38 replacement class. 

39 ''' 

40 for decorator in decorators: 

41 cls_ = decorator( cls ) 

42 if cls is cls_: continue # Simple mutation. No replacement. 

43 _utilities.repair_class_reproduction( cls, cls_ ) 

44 cls = cls_ # Use the replacement class. 

45 return cls 

46 

47 

48def decoration_by( 

49 *decorators: _nomina.Decorator[ __.U ], 

50 preparers: _nomina.DecorationPreparers[ __.U ] = ( ), 

51) -> _nomina.Decorator[ __.U ]: 

52 ''' Class decorator which applies other class decorators. 

53 

54 Useful to apply a stack of decorators as a sequence. 

55 

56 Can optionally execute a sequence of decoration preparers before 

57 applying the decorators proper. These can be used to alter the 

58 decorators list itself, such as to inject decorators based on 

59 introspection of the class. 

60 ''' 

61 def decorate( cls: type[ __.U ] ) -> type[ __.U ]: 

62 decorators_ = list( decorators ) 

63 for preparer in preparers: preparer( cls, decorators_ ) 

64 return apply_decorators( cls, decorators_ ) 

65 

66 return decorate 

67 

68 

69def produce_class_construction_decorator( 

70 attributes_namer: _nomina.AttributesNamer, 

71 constructor: _nomina.ClassConstructor[ __.T ], 

72) -> _nomina.Decorator[ __.T ]: 

73 ''' Produces metaclass decorator to control class construction. 

74 

75 Decorator overrides ``__new__`` on metaclass. 

76 ''' 

77 def decorate( clscls: type[ __.T ] ) -> type[ __.T ]: 

78 original = __.typx.cast( 

79 _nomina.ClassConstructorLigation | None, 

80 clscls.__dict__.get( '__new__' ) ) # pyright: ignore 

81 

82 if original is None: 

83 

84 def construct_with_super( 

85 clscls_: type[ __.T ], 

86 name: str, 

87 bases: tuple[ type, ... ], 

88 namespace: dict[ str, __.typx.Any ], *, 

89 decorators: _nomina.Decorators[ __.T ] = ( ), 

90 **arguments: __.typx.Any, 

91 ) -> type[ object ]: 

92 superf = super( clscls, clscls_ ).__new__ 

93 # TODO? Short-circuit if not at start of MRO. 

94 return constructor( 

95 clscls_, superf, 

96 name, bases, namespace, arguments, decorators ) 

97 

98 setattr( clscls, '__new__', construct_with_super ) 

99 

100 else: 

101 

102 def construct_with_original( 

103 clscls_: type[ __.T ], 

104 name: str, 

105 bases: tuple[ type, ... ], 

106 namespace: dict[ str, __.typx.Any ], *, 

107 decorators: _nomina.Decorators[ __.T ] = ( ), 

108 **arguments: __.typx.Any, 

109 ) -> type[ object ]: 

110 # TODO? Short-circuit if not at start of MRO. 

111 return constructor( 

112 clscls_, original, 

113 name, bases, namespace, arguments, decorators ) 

114 

115 setattr( clscls, '__new__', construct_with_original ) 

116 

117 return clscls 

118 

119 return decorate 

120 

121 

122def produce_class_initialization_decorator( 

123 attributes_namer: _nomina.AttributesNamer, 

124 initializer: _nomina.ClassInitializer, 

125) -> _nomina.Decorator[ __.T ]: 

126 ''' Produces metaclass decorator to control class initialization. 

127 

128 Decorator overrides ``__init__`` on metaclass. 

129 ''' 

130 def decorate( clscls: type[ __.T ] ) -> type[ __.T ]: 

131 original = __.typx.cast( 

132 _nomina.InitializerLigation | None, 

133 clscls.__dict__.get( '__init__' ) ) # pyright: ignore 

134 

135 if original is None: 

136 

137 def initialize_with_super( 

138 cls: type, *posargs: __.typx.Any, **nomargs: __.typx.Any 

139 ) -> None: 

140 ligation = super( clscls, cls ).__init__ 

141 # TODO? Short-circuit if not at start of MRO. 

142 initializer( cls, ligation, posargs, nomargs ) 

143 

144 clscls.__init__ = initialize_with_super 

145 

146 else: 

147 

148 @__.funct.wraps( original ) 

149 def initialize_with_original( 

150 cls: type, *posargs: __.typx.Any, **nomargs: __.typx.Any 

151 ) -> None: 

152 ligation = __.funct.partial( original, cls ) 

153 # TODO? Short-circuit if not at start of MRO. 

154 initializer( cls, ligation, posargs, nomargs ) 

155 

156 clscls.__init__ = initialize_with_original 

157 

158 return clscls 

159 

160 return decorate