Coverage for sources/classcore/standard/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''' Standard module classes and reclassifers. ''' 

22 

23 

24from .. import utilities as _utilities 

25from . import __ 

26from . import classes as _classes 

27from . import nomina as _nomina 

28 

29 

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

31 ''' Modules with attributes immutability and concealment. ''' 

32 

33 

34def reclassify_modules( 

35 attributes: __.typx.Annotated[ 

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

37 __.dynadoc.Doc( 

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

39 ], /, *, 

40 attributes_namer: __.typx.Annotated[ 

41 _nomina.AttributesNamer, 

42 __.dynadoc.Doc( 

43 ''' Attributes namer function with which to seal class. ''' ), 

44 ] = __.calculate_attrname, 

45 recursive: __.typx.Annotated[ 

46 bool, __.dynadoc.Doc( 'Recursively reclassify package modules?' ) 

47 ] = False, 

48) -> None: 

49 # TODO? Ensure correct operation with namespace packages. 

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

51 

52 Can operate on individual modules or entire package hierarchies. 

53 

54 Only converts modules within the same package to prevent unintended 

55 modifications to external modules. 

56 

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

58 values if they belong to the same package. 

59 

60 Has no effect on already-reclassified modules. 

61 ''' 

62 if isinstance( attributes, str ): 

63 attributes = __.sys.modules[ attributes ] 

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

65 module = attributes 

66 attributes = attributes.__dict__ 

67 else: module = None 

68 package_name = ( 

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

70 if not package_name: return 

71 for value in attributes.values( ): 

72 if not __.inspect.ismodule( value ): continue 

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

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

75 if isinstance( value, Module ): continue 

76 _seal_module( value, attributes_namer ) 

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

78 _seal_module( module, attributes_namer ) 

79 

80 

81def _seal_module( 

82 module: __.types.ModuleType, attributes_namer: _nomina.AttributesNamer 

83) -> None: 

84 behaviors = { _nomina.concealment_label, _nomina.immutability_label } 

85 behaviors_name = attributes_namer( 'instance', 'behaviors' ) 

86 _utilities.setattr0( module, behaviors_name, behaviors ) 

87 module.__class__ = Module