Coverage for src/griffe_typingdoc/_internal/dynamic.py: 34.15%

1# Helpers to get documentation metadata dynamically. 

2 

3from __future__ import annotations 

4 

5from typing import TYPE_CHECKING, Any, get_type_hints 

6 

7from griffe_typingdoc._internal.docstrings import _to_parameters_section 

8 

9if TYPE_CHECKING: 

10 from griffe import ( 

11 Attribute, 

12 DocstringSectionAdmonition, 

13 DocstringSectionOtherParameters, 

14 DocstringSectionParameters, 

15 DocstringSectionRaises, 

16 DocstringSectionReceives, 

17 DocstringSectionReturns, 

18 DocstringSectionWarns, 

19 DocstringSectionYields, 

20 Function, 

21 ObjectNode, 

22 ) 

23 

24 

25def _hints(node: ObjectNode) -> dict[str, str]: 

26 try: 

27 return get_type_hints(node.obj, include_extras=True) 

28 except TypeError: 

29 if node.parent: 

30 return _hints(node.parent) 

31 return {} 

32 

33 

34def _doc(name: str, hints: dict[str, Any]) -> str | None: 

35 try: 

36 return hints[name].__metadata__[0].documentation 

37 except (AttributeError, KeyError): 

38 return None 

39 

40 

41def _attribute_docs(attr: Attribute, *, node: ObjectNode, **kwargs: Any) -> str: # noqa: ARG001 

42 return _doc(attr.name, _hints(node)) or "" 

43 

44 

45def _parameters_docs( 

46 func: Function, 

47 *, 

48 node: ObjectNode, 

49 **kwargs: Any, # noqa: ARG001 

50) -> DocstringSectionParameters | None: 

51 hints = _hints(node) 

52 params_doc: dict[str, dict[str, Any]] = { 

53 name: {"description": _doc(name, hints)} for name in hints if name != "return" 

54 } 

55 if params_doc: 

56 return _to_parameters_section(params_doc, func) 

57 return None 

58 

59 

60# FIXME: Implement this function. 

61def _other_parameters_docs( 

62 func: Function, # noqa: ARG001 

63 *, 

64 node: ObjectNode, # noqa: ARG001 

65 **kwargs: Any, # noqa: ARG001 

66) -> DocstringSectionOtherParameters | None: 

67 return None 

68 

69 

70# FIXME: Implement this function. 

71def _deprecated_docs( 

72 attr_or_func: Attribute | Function, # noqa: ARG001 

73 *, 

74 node: ObjectNode, # noqa: ARG001 

75 **kwargs: Any, # noqa: ARG001 

76) -> DocstringSectionAdmonition | None: 

77 return None 

78 

79 

80# FIXME: Implement this function. 

81def _raises_docs( 

82 attr_or_func: Attribute | Function, # noqa: ARG001 

83 *, 

84 node: ObjectNode, # noqa: ARG001 

85 **kwargs: Any, # noqa: ARG001 

86) -> DocstringSectionRaises | None: 

87 return None 

88 

89 

90# FIXME: Implement this function. 

91def _warns_docs( 

92 attr_or_func: Attribute | Function, # noqa: ARG001 

93 *, 

94 node: ObjectNode, # noqa: ARG001 

95 **kwargs: Any, # noqa: ARG001 

96) -> DocstringSectionWarns | None: 

97 return None 

98 

99 

100# FIXME: Implement this function. 

101def _yields_docs( 

102 func: Function, # noqa: ARG001 

103 *, 

104 node: ObjectNode, # noqa: ARG001 

105 **kwargs: Any, # noqa: ARG001 

106) -> DocstringSectionYields | None: 

107 return None 

108 

109 

110# FIXME: Implement this function. 

111def _receives_docs( 

112 func: Function, # noqa: ARG001 

113 *, 

114 node: ObjectNode, # noqa: ARG001 

115 **kwargs: Any, # noqa: ARG001 

116) -> DocstringSectionReceives | None: 

117 return None 

118 

119 

120# FIXME: Implement this function. 

121def _returns_docs( 

122 func: Function, # noqa: ARG001 

123 *, 

124 node: ObjectNode, # noqa: ARG001 

125 **kwargs: Any, # noqa: ARG001 

126) -> DocstringSectionReturns | None: 

127 return None