Coverage for src/griffe_typingdoc/_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._docstrings import _to_parameters_section 

8 

9if TYPE_CHECKING: 

10 from griffe import Attribute, Function, ObjectNode 

11 from griffe.docstrings.dataclasses import ( 

12 DocstringSectionAdmonition, 

13 DocstringSectionOtherParameters, 

14 DocstringSectionParameters, 

15 DocstringSectionRaises, 

16 DocstringSectionReceives, 

17 DocstringSectionReturns, 

18 DocstringSectionWarns, 

19 DocstringSectionYields, 

20 ) 

21 

22 

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

24 try: 

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

26 except TypeError: 

27 if node.parent: 

28 return _hints(node.parent) 

29 return {} 

30 

31 

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

33 try: 

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

35 except (AttributeError, KeyError): 

36 return None 

37 

38 

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

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

41 

42 

43def _parameters_docs( 

44 func: Function, 

45 *, 

46 node: ObjectNode, 

47 **kwargs: Any, # noqa: ARG001 

48) -> DocstringSectionParameters | None: 

49 hints = _hints(node) 

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

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

52 } 

53 if params_doc: 

54 return _to_parameters_section(params_doc, func) 

55 return None 

56 

57 

58# FIXME: Implement this function. 

59def _other_parameters_docs( 

60 func: Function, # noqa: ARG001 

61 *, 

62 node: ObjectNode, # noqa: ARG001 

63 **kwargs: Any, # noqa: ARG001 

64) -> DocstringSectionOtherParameters | None: 

65 return None 

66 

67 

68# FIXME: Implement this function. 

69def _deprecated_docs( 

70 attr_or_func: Attribute | Function, # noqa: ARG001 

71 *, 

72 node: ObjectNode, # noqa: ARG001 

73 **kwargs: Any, # noqa: ARG001 

74) -> DocstringSectionAdmonition | None: 

75 return None 

76 

77 

78# FIXME: Implement this function. 

79def _raises_docs( 

80 attr_or_func: Attribute | Function, # noqa: ARG001 

81 *, 

82 node: ObjectNode, # noqa: ARG001 

83 **kwargs: Any, # noqa: ARG001 

84) -> DocstringSectionRaises | None: 

85 return None 

86 

87 

88# FIXME: Implement this function. 

89def _warns_docs( 

90 attr_or_func: Attribute | Function, # noqa: ARG001 

91 *, 

92 node: ObjectNode, # noqa: ARG001 

93 **kwargs: Any, # noqa: ARG001 

94) -> DocstringSectionWarns | None: 

95 return None 

96 

97 

98# FIXME: Implement this function. 

99def _yields_docs( 

100 func: Function, # noqa: ARG001 

101 *, 

102 node: ObjectNode, # noqa: ARG001 

103 **kwargs: Any, # noqa: ARG001 

104) -> DocstringSectionYields | None: 

105 return None 

106 

107 

108# FIXME: Implement this function. 

109def _receives_docs( 

110 func: Function, # noqa: ARG001 

111 *, 

112 node: ObjectNode, # noqa: ARG001 

113 **kwargs: Any, # noqa: ARG001 

114) -> DocstringSectionReceives | None: 

115 return None 

116 

117 

118# FIXME: Implement this function. 

119def _returns_docs( 

120 func: Function, # noqa: ARG001 

121 *, 

122 node: ObjectNode, # noqa: ARG001 

123 **kwargs: Any, # noqa: ARG001 

124) -> DocstringSectionReturns | None: 

125 return None