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 

23Provides a module type that enforces attribute immutability after assignment. 

24This helps ensure that module-level constants remain constant and that module 

25interfaces remain stable during runtime. 

26 

27The module implementation is derived from :py:class:`types.ModuleType` and adds 

28accretive behavior. This makes it particularly useful for: 

29 

30* Ensuring constants remain constant 

31* Preventing accidental modification of module interfaces 

32* Creating plugin modules with stable APIs 

33 

34Also provides a convenience function: 

35 

36* ``reclassify_modules``: Converts existing modules to accretive modules. 

37''' 

38 

39 

40from . import __ 

41 

42 

43class Module( __.Module ): # type: ignore[misc] 

44 ''' Accretive modules. ''' 

45 

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

47 from .exceptions import AttributeImmutabilityError 

48 raise AttributeImmutabilityError( name ) 

49 

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

51 from .exceptions import AttributeImmutabilityError 

52 if hasattr( self, name ): 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: __.cabc.Mapping[ str, __.a.Any ], 

61 to_class: type[ Module ] = Module 

62) -> None: 

63 ''' Reclassifies modules in dictionary with custom module type. ''' 

64 from inspect import ismodule 

65 for attribute in attributes.values( ): 

66 if not ismodule( attribute ): continue 

67 if isinstance( attribute, to_class ): continue 

68 attribute.__class__ = to_class