Coverage for pymend\docstring_parser\parser.py: 100%
26 statements
« prev ^ index » next coverage.py v7.3.2, created at 2024-04-20 19:09 +0200
« prev ^ index » next coverage.py v7.3.2, created at 2024-04-20 19:09 +0200
1"""The main parsing routine."""
3from typing import Optional
5from pymend.docstring_parser import epydoc, google, numpydoc, rest
6from pymend.docstring_parser.common import (
7 Docstring,
8 DocstringStyle,
9 ParseError,
10 RenderingStyle,
11)
13_STYLE_MAP = {
14 DocstringStyle.REST: rest,
15 DocstringStyle.GOOGLE: google,
16 DocstringStyle.NUMPYDOC: numpydoc,
17 DocstringStyle.EPYDOC: epydoc,
18}
21def parse(
22 text: Optional[str], style: DocstringStyle = DocstringStyle.AUTO
23) -> Docstring:
24 """Parse the docstring into its components.
26 Parameters
27 ----------
28 text : Optional[str]
29 docstring text to parse
30 style : DocstringStyle
31 docstring style (Default value = DocstringStyle.AUTO)
33 Returns
34 -------
35 Docstring
36 parsed docstring representation
38 Raises
39 ------
40 ParserError
41 If none of the available module an parse the docstring
42 """
43 if style != DocstringStyle.AUTO:
44 return _STYLE_MAP[style].parse(text)
46 exc: Optional[Exception] = None
47 rets: list[Docstring] = []
48 for module in _STYLE_MAP.values():
49 try:
50 ret = module.parse(text)
51 except ParseError as ex:
52 exc = ex
53 else:
54 rets.append(ret)
56 if not rets and exc:
57 raise exc
59 return sorted(rets, key=lambda d: (len(d.examples), len(d.meta)), reverse=True)[0]
62def compose(
63 docstring: Docstring,
64 style: DocstringStyle = DocstringStyle.AUTO,
65 rendering_style: RenderingStyle = RenderingStyle.COMPACT,
66 indent: str = " ",
67) -> str:
68 """Render a parsed docstring into docstring text.
70 Parameters
71 ----------
72 docstring : Docstring
73 parsed docstring representation
74 style : DocstringStyle
75 docstring style to render (Default value = DocstringStyle.AUTO)
76 indent : str
77 the characters used as indentation in the docstring string
78 (Default value = ' ')
79 rendering_style : RenderingStyle
80 The rendering style to use. (Default value = RenderingStyle.COMPACT)
82 Returns
83 -------
84 str
85 docstring text
87 Raises
88 ------
89 ValueError
90 If no output style could be determined.
91 """
92 if style == DocstringStyle.AUTO:
93 if docstring.style is None:
94 msg = (
95 "Detected docstring.style of `None` and requested style of `AUTO`.\n"
96 "Either the docstring to compose has to have its style set"
97 " (for example by calling `parse`) or an "
98 "output style has to be provided."
99 )
100 raise ValueError(msg)
101 style = docstring.style
102 module = _STYLE_MAP[style]
103 return module.compose(docstring, rendering_style=rendering_style, indent=indent)