Coverage for sources/frigid/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''' Immutable modules. 

22 

23 Provides a module type that enforces complete attribute immutability. 

24 This helps ensure that module-level constants remain constant and that 

25 module interfaces remain stable during runtime. 

26 

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

28 adds immutability. This makes it particularly useful for: 

29 

30 * Ensuring constants remain constant 

31 * Preventing modification of module interfaces 

32 

33 Also provides a convenience function: 

34 

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

36''' 

37 

38 

39from . import __ 

40from . import classes as _classes 

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( _classes.Object, __.types.ModuleType ): 

78 ''' Immutable module. ''' 

79 

80 _dynadoc_fragments_ = ( 'module', 'module conceal', 'module protect' ) 

81 

82 

83def finalize_module( # noqa: PLR0913 

84 module: ModuleArgument, /, 

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

86 attributes_namer: __.AttributesNamer = __.calculate_attrname, 

87 dynadoc_introspection: DynadocIntrospectionArgument = __.absent, 

88 dynadoc_table: FinalizeModuleDynadocTableArgument = __.absent, 

89 recursive: RecursiveArgument = False, 

90 replacement_class: ReplacementClassArgument = Module, 

91) -> None: 

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

93 

94 Applies module docstring generation via Dynadoc introspection, 

95 then reclassifies modules for immutability and concealment. 

96 

97 When recursive is False, automatically excludes module targets from 

98 dynadoc introspection to document only the provided module. When 

99 recursive is True, automatically includes module targets so Dynadoc 

100 can recursively document all modules. 

101 ''' 

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

103 attributes_namer = attributes_namer, 

104 recursive = recursive, 

105 replacement_class = replacement_class ) 

106 if not __.is_absent( dynadoc_introspection ): 

107 nomargs[ 'dynadoc_introspection' ] = dynadoc_introspection 

108 if not __.is_absent( dynadoc_table ): 

109 nomargs[ 'dynadoc_table' ] = dynadoc_table 

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

111 

112 

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

114def reclassify_modules( 

115 module: ModuleNamespaceArgument, /, *, 

116 recursive: RecursiveArgument = False, 

117) -> None: 

118 ''' Reclassifies modules to have attributes concealment and immutability. 

119 

120 Can operate on individual modules or entire package hierarchies. 

121 

122 Only converts modules within the same package to prevent unintended 

123 modifications to external modules. 

124 

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

126 values if they belong to the same package. 

127 

128 Has no effect on already-reclassified modules. 

129 ''' 

130 __.ccstd.reclassify_modules( 

131 module, 

132 attributes_namer = __.calculate_attrname, 

133 recursive = recursive, 

134 replacement_class = Module )