Coverage for src/griffe_typingdoc/_docstrings.py: 64.71%

1"""Helpers to build docstring sections.""" 

2 

3from __future__ import annotations 

4 

5from typing import TYPE_CHECKING, Any 

6 

7from griffe import ( 

8 DocstringParameter, 

9 DocstringRaise, 

10 DocstringReceive, 

11 DocstringReturn, 

12 DocstringSectionAdmonition, 

13 DocstringSectionOtherParameters, 

14 DocstringSectionParameters, 

15 DocstringSectionRaises, 

16 DocstringSectionReceives, 

17 DocstringSectionReturns, 

18 DocstringSectionWarns, 

19 DocstringSectionYields, 

20 DocstringWarn, 

21 DocstringYield, 

22) 

23 

24if TYPE_CHECKING: 

25 from collections.abc import Iterable 

26 

27 from griffe import Function, Parameter 

28 

29 

30def _no_self_params(func: Function) -> list[Parameter]: 

31 if func.parent and func.parent.is_class and func.parameters and func.parameters[0].name in {"self", "cls"}: 

32 return list(func.parameters)[1:] 

33 return list(func.parameters) 

34 

35 

36def _to_parameters_section(params_dict: dict[str, dict[str, Any]], func: Function) -> DocstringSectionParameters: 

37 return DocstringSectionParameters( 

38 [ 

39 DocstringParameter( 

40 name=param_name, 

41 description=param_doc["description"], 

42 annotation=param_doc["annotation"], 

43 value=func.parameters[param_name].default, # type: ignore[arg-type] 

44 ) 

45 for param_name, param_doc in params_dict.items() 

46 ], 

47 ) 

48 

49 

50def _to_other_parameters_section(params_dict: dict[str, dict[str, Any]]) -> DocstringSectionOtherParameters: 

51 return DocstringSectionOtherParameters( 

52 [ 

53 DocstringParameter( 

54 name=param_name, 

55 description=param_doc["description"], 

56 annotation=param_doc["annotation"], 

57 ) 

58 for param_name, param_doc in params_dict.items() 

59 ], 

60 ) 

61 

62 

63def _to_yields_section(yield_data: Iterable[dict[str, Any]]) -> DocstringSectionYields: 

64 return DocstringSectionYields( 

65 [ 

66 DocstringYield( 

67 name=yield_dict.get("name", ""), 

68 description=yield_dict.get("doc", ""), 

69 annotation=yield_dict["annotation"], 

70 ) 

71 for yield_dict in yield_data 

72 ], 

73 ) 

74 

75 

76def _to_receives_section(receive_data: Iterable[dict[str, Any]]) -> DocstringSectionReceives: 

77 return DocstringSectionReceives( 

78 [ 

79 DocstringReceive( 

80 name=receive_dict.get("name", ""), 

81 description=receive_dict.get("doc", ""), 

82 annotation=receive_dict["annotation"], 

83 ) 

84 for receive_dict in receive_data 

85 ], 

86 ) 

87 

88 

89def _to_returns_section(return_data: Iterable[dict[str, Any]]) -> DocstringSectionReturns: 

90 return DocstringSectionReturns( 

91 [ 

92 DocstringReturn( 

93 name=return_dict.get("name", ""), 

94 description=return_dict.get("doc", ""), 

95 annotation=return_dict["annotation"], 

96 ) 

97 for return_dict in return_data 

98 ], 

99 ) 

100 

101 

102def _to_warns_section(warn_data: Iterable[dict[str, Any]]) -> DocstringSectionWarns: 

103 return DocstringSectionWarns( 

104 [ 

105 DocstringWarn( 

106 annotation=warn_dict["annotation"], 

107 description=warn_dict.get("description", ""), 

108 ) 

109 for warn_dict in warn_data 

110 ], 

111 ) 

112 

113 

114def _to_raises_section(raise_data: Iterable[dict[str, Any]]) -> DocstringSectionRaises: 

115 return DocstringSectionRaises( 

116 [ 

117 DocstringRaise( 

118 annotation=raise_dict["annotation"], 

119 description=raise_dict.get("description", ""), 

120 ) 

121 for raise_dict in raise_data 

122 ], 

123 ) 

124 

125 

126def _to_deprecated_section(deprecation_data: dict[str, Any]) -> DocstringSectionAdmonition: 

127 description = deprecation_data["description"] 

128 description_lines = deprecation_data["description"].split("\n") 

129 if len(description_lines) > 1: 

130 title = description_lines[0].strip() 

131 description = "\n".join(description_lines[1:]).strip() 

132 else: 

133 title = description 

134 description = "" 

135 return DocstringSectionAdmonition(kind="danger", title=title, text=description)