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 __future__ import annotations 

25 

26from . import __ 

27from . import behaviors as _behaviors 

28from . import classes as _classes 

29from . import nomina as _nomina 

30 

31 

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

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

34 

35 

36def reclassify_modules( 

37 attributes: __.typx.Annotated[ 

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

39 __.typx.Doc( 

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

41 ], /, *, 

42 attributes_namer: __.typx.Annotated[ 

43 _nomina.AttributesNamer, 

44 __.typx.Doc( 

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

46 ] = __.calculate_attrname, 

47 recursive: __.typx.Annotated[ 

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

49 ] = False, 

50) -> None: 

51 # TODO? Ensure correct operation with namespace packages. 

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

53 

54 Can operate on individual modules or entire package hierarchies. 

55 

56 Notes 

57 ----- 

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

59 modifications to external modules. 

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

61 values if they belong to the same package. 

62 * Has no effect on already-reclassified modules. 

63 ''' 

64 if isinstance( attributes, str ): 

65 attributes = __.sys.modules[ attributes ] 

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

67 module = attributes 

68 attributes = attributes.__dict__ 

69 else: module = None 

70 package_name = ( 

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

72 if not package_name: return 

73 for value in attributes.values( ): 

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

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

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

77 if isinstance( value, Module ): continue 

78 _seal_module( value, attributes_namer ) 

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

80 _seal_module( module, attributes_namer ) 

81 

82 

83def _seal_module( 

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

85) -> None: 

86 behaviors = { _behaviors.concealment_label, _behaviors.immutability_label } 

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

88 setattr( module, behaviors_name, behaviors ) 

89 module.__class__ = Module