Skip to content

Commit 945880a

Browse files
pawamoypawamoy
committed
refactor: Provide typed dicts for docstring options
Issue-370: #370
1 parent f1ad8df commit 945880a

12 files changed

Lines changed: 139 additions & 59 deletions

File tree

‎docs/reference/api/docstrings/parsers.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,16 @@
1414

1515
::: griffe.DocstringStyle
1616

17+
## **Parser options**
18+
19+
::: griffe.DocstringOptions
20+
21+
::: griffe.GoogleOptions
22+
23+
::: griffe.NumpyOptions
24+
25+
::: griffe.SphinxOptions
26+
1727
## **Advanced API**
1828

1929
::: griffe.Parser

‎src/griffe/__init__.py‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -203,7 +203,7 @@
203203
ReturnChangedTypeBreakage,
204204
find_breaking_changes,
205205
)
206-
from griffe._internal.docstrings.google import parse_google
206+
from griffe._internal.docstrings.google import GoogleOptions, parse_google
207207
from griffe._internal.docstrings.models import (
208208
DocstringAdmonition,
209209
DocstringAttribute,
@@ -240,16 +240,17 @@
240240
DocstringWarn,
241241
DocstringYield,
242242
)
243-
from griffe._internal.docstrings.numpy import parse_numpy
243+
from griffe._internal.docstrings.numpy import NumpyOptions, parse_numpy
244244
from griffe._internal.docstrings.parsers import (
245245
DocstringDetectionMethod,
246+
DocstringOptions,
246247
DocstringStyle,
247248
infer_docstring_style,
248249
parse,
249250
parse_auto,
250251
parsers,
251252
)
252-
from griffe._internal.docstrings.sphinx import parse_sphinx
253+
from griffe._internal.docstrings.sphinx import SphinxOptions, parse_sphinx
253254
from griffe._internal.docstrings.utils import docstring_warning, parse_docstring_annotation
254255
from griffe._internal.encoders import JSONEncoder, json_decoder
255256
from griffe._internal.enumerations import (
@@ -400,6 +401,7 @@
400401
"DocstringFunction",
401402
"DocstringModule",
402403
"DocstringNamedElement",
404+
"DocstringOptions",
403405
"DocstringParameter",
404406
"DocstringRaise",
405407
"DocstringReceive",
@@ -470,6 +472,7 @@
470472
"Function",
471473
"GetMembersMixin",
472474
"GitError",
475+
"GoogleOptions",
473476
"GriffeError",
474477
"GriffeLoader",
475478
"Inspector",
@@ -488,6 +491,7 @@
488491
"NamePartsType",
489492
"NameResolutionError",
490493
"NamespacePackage",
494+
"NumpyOptions",
491495
"Object",
492496
"ObjectAliasMixin",
493497
"ObjectChangedKindBreakage",
@@ -510,6 +514,7 @@
510514
"RootNodeError",
511515
"SerializationMixin",
512516
"SetMembersMixin",
517+
"SphinxOptions",
513518
"Stats",
514519
"TmpPackage",
515520
"TypeAlias",

‎src/griffe/_internal/agents/inspector.py‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@
3838
from collections.abc import Sequence
3939
from pathlib import Path
4040

41-
from griffe._internal.docstrings.parsers import DocstringStyle
41+
from griffe._internal.docstrings.parsers import DocstringOptions, DocstringStyle
4242
from griffe._internal.enumerations import Parser
4343

4444
_TYPING_MODULES: tuple[types.ModuleType, ...]
@@ -60,7 +60,7 @@ def inspect(
6060
extensions: Extensions | None = None,
6161
parent: Module | None = None,
6262
docstring_parser: DocstringStyle | Parser | None = None,
63-
docstring_options: dict[str, Any] | None = None,
63+
docstring_options: DocstringOptions | None = None,
6464
lines_collection: LinesCollection | None = None,
6565
modules_collection: ModulesCollection | None = None,
6666
) -> Module:
@@ -95,7 +95,7 @@ def inspect(
9595
extensions: The extensions to use when inspecting the module.
9696
parent: The optional parent of this module.
9797
docstring_parser: The docstring parser to use. By default, no parsing is done.
98-
docstring_options: Additional docstring parsing options.
98+
docstring_options: Docstring parsing options.
9999
lines_collection: A collection of source code lines.
100100
modules_collection: A collection of modules.
101101
@@ -127,7 +127,7 @@ def __init__(
127127
extensions: Extensions,
128128
parent: Module | None = None,
129129
docstring_parser: DocstringStyle | Parser | None = None,
130-
docstring_options: dict[str, Any] | None = None,
130+
docstring_options: DocstringOptions | None = None,
131131
lines_collection: LinesCollection | None = None,
132132
modules_collection: ModulesCollection | None = None,
133133
) -> None:
@@ -139,7 +139,7 @@ def __init__(
139139
extensions: Extensions to use when inspecting.
140140
parent: The module parent.
141141
docstring_parser: The docstring parser to use.
142-
docstring_options: The docstring parsing options.
142+
docstring_options: Docstring parsing options.
143143
lines_collection: A collection of source code lines.
144144
modules_collection: A collection of modules.
145145
"""
@@ -163,7 +163,7 @@ def __init__(
163163
self.docstring_parser: DocstringStyle | Parser | None = docstring_parser
164164
"""The docstring parser to use."""
165165

166-
self.docstring_options: dict[str, Any] = docstring_options or {}
166+
self.docstring_options: DocstringOptions = docstring_options or {}
167167
"""The docstring parsing options."""
168168

169169
self.lines_collection: LinesCollection = lines_collection or LinesCollection()

‎src/griffe/_internal/agents/visitor.py‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
import ast
77
import sys
88
from contextlib import suppress
9-
from typing import TYPE_CHECKING, Any, Final
9+
from typing import TYPE_CHECKING, Final
1010

1111
from griffe._internal.agents.nodes.assignments import get_instance_names, get_names
1212
from griffe._internal.agents.nodes.ast import (
@@ -48,7 +48,7 @@
4848
if TYPE_CHECKING:
4949
from pathlib import Path
5050

51-
from griffe._internal.docstrings.parsers import DocstringStyle
51+
from griffe._internal.docstrings.parsers import DocstringOptions, DocstringStyle
5252
from griffe._internal.enumerations import Parser
5353

5454

@@ -84,7 +84,7 @@ def visit(
8484
extensions: Extensions | None = None,
8585
parent: Module | None = None,
8686
docstring_parser: DocstringStyle | Parser | None = None,
87-
docstring_options: dict[str, Any] | None = None,
87+
docstring_options: DocstringOptions | None = None,
8888
lines_collection: LinesCollection | None = None,
8989
modules_collection: ModulesCollection | None = None,
9090
) -> Module:
@@ -107,7 +107,7 @@ def visit(
107107
extensions: The extensions to use when visiting the AST.
108108
parent: The optional parent of this module.
109109
docstring_parser: The docstring parser to use. By default, no parsing is done.
110-
docstring_options: Additional docstring parsing options.
110+
docstring_options: Docstring parsing options.
111111
lines_collection: A collection of source code lines.
112112
modules_collection: A collection of modules.
113113
@@ -141,7 +141,7 @@ def __init__(
141141
extensions: Extensions,
142142
parent: Module | None = None,
143143
docstring_parser: DocstringStyle | Parser | None = None,
144-
docstring_options: dict[str, Any] | None = None,
144+
docstring_options: DocstringOptions | None = None,
145145
lines_collection: LinesCollection | None = None,
146146
modules_collection: ModulesCollection | None = None,
147147
) -> None:
@@ -154,7 +154,7 @@ def __init__(
154154
extensions: The extensions to use when visiting.
155155
parent: An optional parent for the final module object.
156156
docstring_parser: The docstring parser to use.
157-
docstring_options: The docstring parsing options.
157+
docstring_options: Docstring parsing options.
158158
lines_collection: A collection of source code lines.
159159
modules_collection: A collection of modules.
160160
"""
@@ -181,7 +181,7 @@ def __init__(
181181
self.docstring_parser: DocstringStyle | Parser | None = docstring_parser
182182
"""The docstring parser to use."""
183183

184-
self.docstring_options: dict[str, Any] = docstring_options or {}
184+
self.docstring_options: DocstringOptions = docstring_options or {}
185185
"""The docstring parsing options."""
186186

187187
self.lines_collection: LinesCollection = lines_collection or LinesCollection()

‎src/griffe/_internal/cli.py‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@
3636
if TYPE_CHECKING:
3737
from collections.abc import Sequence
3838

39+
from griffe._internal.docstrings.parsers import DocstringOptions, DocstringStyle
3940
from griffe._internal.extensions.base import Extension, Extensions
4041

4142

@@ -70,8 +71,8 @@ def _load_packages(
7071
*,
7172
extensions: Extensions | None = None,
7273
search_paths: Sequence[str | Path] | None = None,
73-
docstring_parser: Parser | None = None,
74-
docstring_options: dict[str, Any] | None = None,
74+
docstring_parser: DocstringStyle | Parser | None = None,
75+
docstring_options: DocstringOptions | None = None,
7576
resolve_aliases: bool = True,
7677
resolve_implicit: bool = False,
7778
resolve_external: bool | None = None,
@@ -332,8 +333,8 @@ def dump(
332333
*,
333334
output: str | IO | None = None,
334335
full: bool = False,
335-
docstring_parser: Parser | None = None,
336-
docstring_options: dict[str, Any] | None = None,
336+
docstring_parser: DocstringStyle | Parser | None = None,
337+
docstring_options: DocstringOptions | None = None,
337338
extensions: Sequence[str | dict[str, Any] | Extension | type[Extension]] | None = None,
338339
resolve_aliases: bool = False,
339340
resolve_implicit: bool = False,
@@ -352,7 +353,7 @@ def dump(
352353
output: Where to output the JSON-serialized data.
353354
full: Whether to output full or minimal data.
354355
docstring_parser: The docstring parser to use. By default, no parsing is done.
355-
docstring_options: Additional docstring parsing options.
356+
docstring_options: Docstring parsing options.
356357
resolve_aliases: Whether to resolve aliases (indirect objects references).
357358
resolve_implicit: Whether to resolve every alias or only the explicitly exported ones.
358359
resolve_external: Whether to load additional, unspecified modules to resolve aliases.

‎src/griffe/_internal/docstrings/google.py‎

Lines changed: 32 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,8 @@
44

55
import re
66
from contextlib import suppress
7-
from typing import TYPE_CHECKING
7+
from typing import TYPE_CHECKING, TypedDict
8+
from warnings import warn
89

910
from griffe._internal.docstrings.models import (
1011
DocstringAttribute,
@@ -851,7 +852,30 @@ def _is_empty_line(line: str) -> bool:
851852
DocstringSectionKind.receives: _read_receives_section,
852853
}
853854

854-
_sentinel = object()
855+
856+
class GoogleOptions(TypedDict, total=False):
857+
"""Options for parsing Google-style docstrings."""
858+
859+
ignore_init_summary: bool
860+
"""Whether to ignore the summary in `__init__` methods' docstrings."""
861+
trim_doctest_flags: bool
862+
"""Whether to remove doctest flags from Python example blocks."""
863+
returns_multiple_items: bool
864+
"""Whether to parse multiple items in `Yields` and `Returns` sections."""
865+
returns_named_value: bool
866+
"""Whether to parse `Yields` and `Returns` section items as name and description, rather than type and description."""
867+
returns_type_in_property_summary: bool
868+
"""Whether to parse the return type of properties at the beginning of their summary."""
869+
receives_multiple_items: bool
870+
"""Whether to parse multiple items in `Receives` sections."""
871+
receives_named_value: bool
872+
"""Whether to parse `Receives` section items as name and description, rather than type and description."""
873+
warn_unknown_params: bool
874+
"""Whether to warn about unknown parameters."""
875+
warn_missing_types: bool
876+
"""Whether to warn about missing types/annotations for parameters, return values, etc."""
877+
warnings: bool
878+
"""Whether to issue warnings for parsing issues."""
855879

856880

857881
def parse_google(
@@ -867,6 +891,7 @@ def parse_google(
867891
warn_unknown_params: bool = True,
868892
warn_missing_types: bool = True,
869893
warnings: bool = True,
894+
# YORE: Bump 2: Remove line.
870895
**options: Any,
871896
) -> list[DocstringSection]:
872897
"""Parse a Google-style docstring.
@@ -895,7 +920,7 @@ def parse_google(
895920
warn_unknown_params: Warn about documented parameters not appearing in the signature.
896921
warn_missing_types: Warn about missing types/annotations for parameters, return values, etc.
897922
warnings: Whether to log warnings at all.
898-
**options: Additional parsing options.
923+
**options: Swallowing keyword arguments for backward-compatibility.
899924
900925
Returns:
901926
A list of docstring sections.
@@ -906,6 +931,10 @@ def parse_google(
906931
in_code_block = False
907932
lines = docstring.lines
908933

934+
# YORE: Bump 2: Remove block.
935+
if options:
936+
warn("Passing additional options is deprecated, these options are ignored.", DeprecationWarning, stacklevel=2)
937+
909938
options = {
910939
"ignore_init_summary": ignore_init_summary,
911940
"trim_doctest_flags": trim_doctest_flags,
@@ -917,7 +946,6 @@ def parse_google(
917946
"warn_unknown_params": warn_unknown_params,
918947
"warn_missing_types": warn_missing_types,
919948
"warnings": warnings,
920-
**options,
921949
}
922950

923951
ignore_summary = (

‎src/griffe/_internal/docstrings/numpy.py‎

Lines changed: 23 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,8 @@
2222
import re
2323
from contextlib import suppress
2424
from textwrap import dedent
25-
from typing import TYPE_CHECKING
25+
from typing import TYPE_CHECKING, TypedDict
26+
from warnings import warn
2627

2728
from griffe._internal.docstrings.models import (
2829
DocstringAttribute,
@@ -892,6 +893,21 @@ def _append_section(sections: list, current: list[str], admonition_title: str) -
892893
}
893894

894895

896+
class NumpyOptions(TypedDict, total=False):
897+
"""Options for parsing Numpydoc-style docstrings."""
898+
899+
ignore_init_summary: bool
900+
"""Whether to ignore the summary in `__init__` methods' docstrings."""
901+
trim_doctest_flags: bool
902+
"""Whether to remove doctest flags from Python example blocks."""
903+
warn_unknown_params: bool
904+
"""Whether to warn about unknown parameters."""
905+
warn_missing_types: bool
906+
"""Whether to warn about missing types/annotations for parameters, return values, etc."""
907+
warnings: bool
908+
"""Whether to issue warnings for parsing issues."""
909+
910+
895911
def parse_numpy(
896912
docstring: Docstring,
897913
*,
@@ -900,6 +916,7 @@ def parse_numpy(
900916
warn_unknown_params: bool = True,
901917
warn_missing_types: bool = True,
902918
warnings: bool = True,
919+
# YORE: Bump 2: Remove line.
903920
**options: Any,
904921
) -> list[DocstringSection]:
905922
"""Parse a Numpydoc-style docstring.
@@ -914,7 +931,7 @@ def parse_numpy(
914931
warn_unknown_params: Warn about documented parameters not appearing in the signature.
915932
warn_missing_types: Warn about missing types/annotations for parameters, return values, etc.
916933
warnings: Whether to log warnings at all.
917-
**options: Additional parsing options.
934+
**options: Swallowing keyword arguments for backward-compatibility.
918935
919936
Returns:
920937
A list of docstring sections.
@@ -926,13 +943,16 @@ def parse_numpy(
926943
in_code_block = False
927944
lines = docstring.lines
928945

946+
# YORE: Bump 2: Remove block.
947+
if options:
948+
warn("Passing additional options is deprecated, these options are ignored.", DeprecationWarning, stacklevel=2)
949+
929950
options = {
930951
"trim_doctest_flags": trim_doctest_flags,
931952
"ignore_init_summary": ignore_init_summary,
932953
"warn_unknown_params": warn_unknown_params,
933954
"warn_missing_types": warn_missing_types,
934955
"warnings": warnings,
935-
**options,
936956
}
937957

938958
ignore_summary = (

0 commit comments

Comments
 (0)