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 constructor_name = attributes_namer( 'classes', 'constructor' ) 

79 extant = getattr( clscls, constructor_name, None ) 

80 original = getattr( clscls, '__new__' ) 

81 if extant is original: return clscls 

82 

83 def construct( 

84 clscls_: type[ __.T ], 

85 name: str, 

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

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

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

89 **arguments: __.typx.Any, 

90 ) -> type[ object ]: 

91 return constructor( 

92 clscls_, original, 

93 name, bases, namespace, arguments, decorators ) 

94 

95 setattr( clscls, constructor_name, construct ) 

96 setattr( clscls, '__new__', construct ) 

97 return clscls 

98 

99 return decorate 

100 

101 

102def produce_class_initialization_decorator( 

103 attributes_namer: _nomina.AttributesNamer, 

104 initializer: _nomina.ClassInitializer, 

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

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

107 

108 Decorator overrides ``__init__`` on metaclass. 

109 ''' 

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

111 initializer_name = attributes_namer( 'classes', 'initializer' ) 

112 extant = getattr( clscls, initializer_name, None ) 

113 original = getattr( clscls, '__init__' ) 

114 if extant is original: return clscls 

115 

116 @__.funct.wraps( original ) 

117 def initialize( 

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

119 ) -> None: 

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

121 initializer( cls, ligation, posargs, nomargs ) 

122 

123 setattr( clscls, initializer_name, initialize ) 

124 clscls.__init__ = initialize 

125 return clscls 

126 

127 return decorate