Coverage for sources/accretive/modules.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''' Accretive modules. 

22 

23 Provides a module type that enforces attribute immutability after 

24 assignment. This helps ensure that module-level constants remain constant 

25 and that module interfaces remain stable during runtime. 

26 

27 The module implementation is derived from :py:class:`types.ModuleType` and 

28 adds accretive behavior. This makes it particularly useful for: 

29 

30 * Ensuring constants remain constant 

31 * Preventing accidental modification of module interfaces 

32 

33 Also provides a convenience function: 

34 

35 * ``reclassify_modules``: Converts existing modules to accretive modules. 

36''' 

37 

38 

39from . import __ 

40from . import iclasses as _iclasses 

41 

42 

43ModuleNamespaceDictionary: __.typx.TypeAlias = ( 

44 __.cabc.Mapping[ str, __.typx.Any ] ) 

45 

46DynadocIntrospectionArgument: __.typx.TypeAlias = __.typx.Annotated[ 

47 __.Absential[ __.ddoc.IntrospectionControl ], 

48 __.ddoc.Doc( 

49 ''' Dynadoc introspection control. 

50 

51 Which kinds of object to recursively introspect? 

52 Scan unnannotated attributes? 

53 Consider base classes? 

54 Etc... 

55 ''' ), 

56] 

57FinalizeModuleDynadocTableArgument: __.typx.TypeAlias = __.typx.Annotated[ 

58 __.Absential[ __.cabc.Mapping[ str, str ] ], 

59 __.ddoc.Doc( ''' Table of documentation fragments. ''' ), 

60] 

61ModuleArgument: __.typx.TypeAlias = __.typx.Annotated[ 

62 str | __.types.ModuleType, __.ddoc.Doc( ''' Module or module name. ''' ), 

63] 

64ModuleNamespaceArgument: __.typx.TypeAlias = __.typx.Annotated[ 

65 str | __.types.ModuleType | ModuleNamespaceDictionary, 

66 __.ddoc.Doc( ''' Module, module name, or module namespace. ''' ), 

67] 

68RecursiveArgument: __.typx.TypeAlias = __.typx.Annotated[ 

69 bool, __.ddoc.Doc( ''' Recursively reclassify package modules? ''' ) 

70] 

71ReplacementClassArgument: __.typx.TypeAlias = __.typx.Annotated[ 

72 type[ __.types.ModuleType ], 

73 __.ddoc.Doc( ''' New class for module. ''' ), 

74] 

75 

76 

77class Module( 

78 __.types.ModuleType, 

79 metaclass = _iclasses.Class, 

80 instances_assigner_core = _iclasses.assign_attribute_if_absent_mutable, 

81): 

82 ''' Accretive module. ''' 

83 

84 _dynadoc_fragments_ = ( 'module', 'module conceal', 'module accrete' ) 

85 

86 

87def finalize_module( # noqa: PLR0913 

88 module: ModuleArgument, /, 

89 *fragments: __.ddoc.interfaces.Fragment, 

90 attributes_namer: __.AttributesNamer = __.calculate_attrname, 

91 dynadoc_introspection: DynadocIntrospectionArgument = __.absent, 

92 dynadoc_table: FinalizeModuleDynadocTableArgument = __.absent, 

93 recursive: RecursiveArgument = False, 

94 replacement_class: ReplacementClassArgument = Module, 

95) -> None: 

96 ''' Combines Dynadoc docstring assignment and module reclassification. 

97 

98 Applies module docstring generation via Dynadoc introspection, 

99 then reclassifies modules for accretion and concealment. 

100 

101 When recursive is False, automatically excludes module targets from 

102 dynadoc introspection to document only the provided module. When 

103 recursive is True, automatically includes module targets so Dynadoc 

104 can recursively document all modules. 

105 ''' 

106 nomargs: dict[ str, __.typx.Any ] = dict( 

107 attributes_namer = attributes_namer, 

108 recursive = recursive, 

109 replacement_class = replacement_class ) 

110 if not __.is_absent( dynadoc_introspection ): 

111 nomargs[ 'dynadoc_introspection' ] = dynadoc_introspection 

112 if not __.is_absent( dynadoc_table ): 

113 nomargs[ 'dynadoc_table' ] = dynadoc_table 

114 __.ccstd.finalize_module( module, *fragments, **nomargs ) 

115 

116 

117@__.typx.deprecated( "Use 'finalize_module' function instead." ) 

118def reclassify_modules( 

119 module: ModuleNamespaceArgument, /, *, 

120 recursive: RecursiveArgument = False, 

121) -> None: 

122 ''' Reclassifies modules to be accretive. 

123 

124 Can operate on individual modules or entire package hierarchies. 

125 

126 Only converts modules within the same package to prevent unintended 

127 modifications to external modules. 

128 

129 When used with a dictionary, converts any module objects found as 

130 values if they belong to the same package. 

131 

132 Has no effect on already-accretive modules. 

133 ''' 

134 __.ccstd.reclassify_modules( 

135 module, 

136 attributes_namer = __.calculate_attrname, 

137 recursive = recursive, 

138 replacement_class = Module )