Coverage for sources/classcore/standard/dynadoc.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''' Dynadoc integration. ''' 

22 

23 

24from .. import utilities as _utilities 

25from . import __ 

26from . import nomina as _nomina 

27 

28 

29dynadoc_context = __.ddoc.produce_context( ) 

30dynadoc_class_introspection_control = ( 

31 __.ddoc.ClassIntrospectionControl( 

32 inheritance = True, 

33 introspectors = ( 

34 __.ddoc.introspection.introspect_special_classes, ) ) ) 

35dynadoc_module_introspection_control = ( 

36 __.ddoc.ModuleIntrospectionControl( ) ) 

37 

38 

39def dynadoc_avoid_immutables( 

40 objct: object, 

41 introspection: __.ddoc.IntrospectionControl, 

42 attributes_namer: _nomina.AttributesNamer, 

43) -> __.ddoc.IntrospectionControl: 

44 ''' Disables introspection of immutable objects. ''' 

45 if __.inspect.isclass( objct ): 

46 behaviors_name = attributes_namer( 'class', 'behaviors' ) 

47 behaviors = _utilities.getattr0( objct, behaviors_name, frozenset( ) ) 

48 if _nomina.immutability_label in behaviors: 

49 return introspection.with_limit( 

50 __.ddoc.IntrospectionLimit( disable = True ) ) 

51 return introspection 

52 

53 

54def produce_dynadoc_introspection_limiter( 

55 attributes_namer: _nomina.AttributesNamer = __.calculate_attrname, 

56) -> __.ddoc.IntrospectionLimiter: 

57 ''' Produces introspection limiter which avoids immutable objects. ''' 

58 return __.funct.partial( 

59 dynadoc_avoid_immutables, attributes_namer = attributes_namer ) 

60 

61dynadoc_introspection_limiter = produce_dynadoc_introspection_limiter( ) 

62 

63 

64def produce_dynadoc_introspection_control( 

65 enable: bool = True, 

66 class_control: __.ddoc.ClassIntrospectionControl = ( 

67 dynadoc_class_introspection_control ), 

68 module_control: __.ddoc.ModuleIntrospectionControl = ( 

69 dynadoc_module_introspection_control ), 

70 limiters: __.ddoc.IntrospectionLimiters = ( 

71 dynadoc_introspection_limiter, ), 

72 targets: __.ddoc.IntrospectionTargets = ( 

73 __.ddoc.IntrospectionTargetsSansModule ), 

74) -> __.ddoc.IntrospectionControl: 

75 ''' Produces compatible Dynadoc introspection control. ''' 

76 return __.ddoc.IntrospectionControl( 

77 enable = enable, 

78 class_control = class_control, 

79 module_control = module_control, 

80 limiters = limiters, 

81 targets = targets ) 

82 

83dynadoc_introspection_on_class = produce_dynadoc_introspection_control( ) 

84dynadoc_introspection_on_package = ( 

85 produce_dynadoc_introspection_control( 

86 targets = __.ddoc.IntrospectionTargetsOmni ) ) 

87 

88 

89def assign_module_docstring( # noqa: PLR0913 

90 module: str | __.types.ModuleType, /, 

91 *fragments: __.ddoc.interfaces.Fragment, 

92 context: _nomina.DynadocContextArgument = dynadoc_context, 

93 introspection: _nomina.DynadocIntrospectionArgument = ( 

94 dynadoc_introspection_on_package ), 

95 preserve: _nomina.DynadocPreserveArgument = True, 

96 renderer: __.ddoc.xtnsapi.Renderer = ( 

97 __.ddoc.assembly.renderer_default ), 

98 table: _nomina.DynadocTableArgument = __.dictproxy_empty, 

99) -> None: 

100 ''' Updates module docstring based on introspection. 

101 

102 By default, recursively updates docstrings of all module members 

103 which have docstrings. 

104 

105 By default, ignores previously-decorated immutable classes. 

106 ''' 

107 __.ddoc.assign_module_docstring( 

108 module, 

109 *fragments, 

110 context = context, 

111 introspection = introspection, 

112 preserve = preserve, 

113 renderer = renderer, 

114 table = table ) 

115 

116 

117def produce_dynadoc_configuration( 

118 context: _nomina.DynadocContextArgument = dynadoc_context, 

119 introspection: _nomina.DynadocIntrospectionArgument = ( 

120 dynadoc_introspection_on_class ), 

121 preserve: _nomina.DynadocPreserveArgument = True, 

122 table: _nomina.DynadocTableArgument = __.dictproxy_empty, 

123) -> _nomina.ProduceDynadocConfigurationReturn: 

124 ''' Produces compatible Dynadoc configuration. ''' 

125 return __.types.MappingProxyType( dict( 

126 context = context, 

127 introspection = introspection, 

128 preserve = preserve, 

129 table = table ) )