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 

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

47 str | __.types.ModuleType | ModuleNamespaceDictionary, 

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

49] 

50ReclassifyModulesRecursiveArgument: __.typx.TypeAlias = __.typx.Annotated[ 

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

52] 

53 

54 

55class Module( _classes.Object, __.types.ModuleType ): 

56 ''' Module class. ''' 

57 

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

59 

60 

61def reclassify_modules( 

62 module: ReclassifyModulesModuleArgument, /, *, 

63 recursive: ReclassifyModulesRecursiveArgument = False, 

64) -> None: 

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

66 

67 Can operate on individual modules or entire package hierarchies. 

68 

69 Only converts modules within the same package to prevent unintended 

70 modifications to external modules. 

71 

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

73 values if they belong to the same package. 

74 

75 Has no effect on already-reclassified modules. 

76 ''' 

77 __.ccstd.reclassify_modules( 

78 module, 

79 attributes_namer = __.calculate_attrname, 

80 replacement_class = Module )