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 

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( 

56 __.types.ModuleType, 

57 metaclass = _iclasses.Class, 

58 instances_assigner_core = _iclasses.assign_attribute_if_absent_mutable, 

59): 

60 ''' Accretive module. ''' 

61 

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

63 

64 

65def reclassify_modules( 

66 module: ReclassifyModulesModuleArgument, /, *, 

67 recursive: ReclassifyModulesRecursiveArgument = False, 

68) -> None: 

69 ''' Reclassifies modules to be accretive. 

70 

71 Can operate on individual modules or entire package hierarchies. 

72 

73 Only converts modules within the same package to prevent unintended 

74 modifications to external modules. 

75 

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

77 values if they belong to the same package. 

78 

79 Has no effect on already-accretive modules. 

80 ''' 

81 __.ccstd.reclassify_modules( 

82 module, 

83 attributes_namer = __.calculate_attrname, 

84 replacement_class = Module )