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 __ 

40 

41 

42class Module( __.types.ModuleType ): 

43 ''' Accretive modules. ''' 

44 

45 def __delattr__( self, name: str ) -> None: 

46 from .exceptions import AttributeImmutabilityError 

47 raise AttributeImmutabilityError( name ) 

48 

49 def __setattr__( self, name: str, value: __.typx.Any ) -> None: 

50 if hasattr( self, name ): 

51 from .exceptions import AttributeImmutabilityError 

52 raise AttributeImmutabilityError( name ) 

53 super( ).__setattr__( name, value ) 

54 

55Module.__doc__ = __.generate_docstring( 

56 Module, 'description of module', 'module attributes accretion' ) 

57 

58 

59def reclassify_modules( 

60 attributes: __.typx.Annotated[ 

61 __.cabc.Mapping[ str, __.typx.Any ] | __.types.ModuleType | str, 

62 __.typx.Doc( 

63 'Module, module name, or dictionary of object attributes.' ), 

64 ], 

65 recursive: __.typx.Annotated[ 

66 bool, __.typx.Doc( 'Recursively reclassify package modules?' ), 

67 ] = False, 

68) -> None: 

69 ''' Reclassifies modules to be accretive. 

70 

71 Can operate on individual modules or entire package hierarchies. 

72 

73 Notes 

74 ----- 

75 * Only converts modules within the same package to prevent unintended 

76 modifications to external modules. 

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

78 values if they belong to the same package. 

79 * Has no effect on already-accretive modules. 

80 ''' 

81 from inspect import ismodule 

82 from sys import modules 

83 if isinstance( attributes, str ): 

84 attributes = modules[ attributes ] 

85 if isinstance( attributes, __.types.ModuleType ): 

86 module = attributes 

87 attributes = attributes.__dict__ 

88 else: module = None 

89 package_name = ( 

90 attributes.get( '__package__' ) or attributes.get( '__name__' ) ) 

91 if not package_name: return 

92 for value in attributes.values( ): 

93 if not ismodule( value ): continue 

94 if not value.__name__.startswith( f"{package_name}." ): continue 

95 if recursive: reclassify_modules( value, recursive = True ) 

96 if isinstance( value, Module ): continue 

97 value.__class__ = Module 

98 if module and not isinstance( module, Module ): 

99 module.__class__ = Module