Coverage for packages / griffelib / src / griffe / _internal / docstrings / parsers.py: 100.00%

1# This module imports all the defined parsers 

2# and provides a generic function to parse docstrings. 

3 

4from __future__ import annotations 

5 

6from typing import TYPE_CHECKING, Any, Literal 

7 

8from griffe._internal.docstrings.auto import AutoOptions, parse_auto 

9from griffe._internal.docstrings.google import GoogleOptions, parse_google 

10from griffe._internal.docstrings.models import DocstringSection, DocstringSectionText 

11from griffe._internal.docstrings.numpy import NumpyOptions, parse_numpy 

12from griffe._internal.docstrings.sphinx import SphinxOptions, parse_sphinx 

13from griffe._internal.enumerations import Parser 

14 

15if TYPE_CHECKING: 

16 from collections.abc import Callable 

17 

18 from griffe._internal.models import Docstring 

19 

20 

21DocstringStyle = Literal["google", "numpy", "sphinx", "auto"] 

22"""The supported docstring styles (literal values of the Parser enumeration).""" 

23DocstringOptions = GoogleOptions | NumpyOptions | SphinxOptions | AutoOptions 

24"""The options for each docstring style.""" 

25 

26 

27parsers: dict[Parser, Callable[[Docstring], list[DocstringSection]]] = { 

28 Parser.auto: parse_auto, 

29 Parser.google: parse_google, 

30 Parser.sphinx: parse_sphinx, 

31 Parser.numpy: parse_numpy, 

32} 

33 

34 

35def parse( 

36 docstring: Docstring, 

37 parser: DocstringStyle | Parser | None, 

38 **options: Any, 

39) -> list[DocstringSection]: 

40 """Parse the docstring. 

41 

42 Parameters: 

43 docstring: The docstring to parse. 

44 parser: The docstring parser to use. If None, return a single text section. 

45 **options: The options accepted by the parser. 

46 

47 Returns: 

48 A list of docstring sections. 

49 """ 

50 if parser: 

51 if not isinstance(parser, Parser): 

52 parser = Parser(parser) 

53 return parsers[parser](docstring, **options) 

54 return [DocstringSectionText(docstring.value)] if docstring.value else []