Coverage for src/_griffe/agents/nodes/docstrings.py: 100.00%

1# This module contains utilities for extracting docstrings from nodes. 

2 

3from __future__ import annotations 

4 

5import ast 

6 

7 

8def get_docstring( 

9 node: ast.AST, 

10 *, 

11 strict: bool = False, 

12) -> tuple[str | None, int | None, int | None]: 

13 """Extract a docstring. 

14 

15 Parameters: 

16 node: The node to extract the docstring from. 

17 strict: Whether to skip searching the body (functions). 

18 

19 Returns: 

20 A tuple with the value and line numbers of the docstring. 

21 """ 

22 # TODO: possible optimization using a type map 

23 if isinstance(node, ast.Expr): 

24 doc = node.value 

25 elif not strict and node.body and isinstance(node.body, list) and isinstance(node.body[0], ast.Expr): # type: ignore[attr-defined] 

26 doc = node.body[0].value # type: ignore[attr-defined] 

27 else: 

28 return None, None, None 

29 if isinstance(doc, ast.Constant) and isinstance(doc.value, str): 

30 return doc.value, doc.lineno, doc.end_lineno 

31 return None, None, None