Skip to content

Commit 7f39373

Browse files
committed
perf: Make Google, Numpy and Sphinx docstring parsers faster
1 parent ad58ad5 commit 7f39373

3 files changed

Lines changed: 146 additions & 71 deletions

File tree

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

Lines changed: 59 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -105,8 +105,14 @@
105105
_RE_DOCTEST_FLAGS: Pattern = re.compile(r"(\s*#\s*doctest:.+)$")
106106

107107

108-
def _read_block_items(docstring: Docstring, *, offset: int, warnings: bool = True, **options: Any) -> _ItemsBlock: # noqa: ARG001
109-
lines = docstring.lines
108+
def _read_block_items(
109+
lines: list[str],
110+
docstring: Docstring,
111+
*,
112+
offset: int,
113+
warnings: bool = True,
114+
**options: Any, # noqa: ARG001
115+
) -> _ItemsBlock:
110116
if offset >= len(lines):
111117
return [], offset
112118

@@ -169,8 +175,12 @@ def _read_block_items(docstring: Docstring, *, offset: int, warnings: bool = Tru
169175
return items, new_offset - 1
170176

171177

172-
def _read_block(docstring: Docstring, *, offset: int, **options: Any) -> tuple[str, int]: # noqa: ARG001
173-
lines = docstring.lines
178+
def _read_block(
179+
lines: list[str],
180+
*,
181+
offset: int,
182+
**options: Any, # noqa: ARG001
183+
) -> tuple[str, int]:
174184
if offset >= len(lines):
175185
return "", offset - 1
176186

@@ -201,6 +211,7 @@ def _read_block(docstring: Docstring, *, offset: int, **options: Any) -> tuple[s
201211

202212

203213
def _read_parameters(
214+
lines: list[str],
204215
docstring: Docstring,
205216
*,
206217
offset: int,
@@ -212,7 +223,7 @@ def _read_parameters(
212223
parameters = []
213224
annotation: str | Expr | None
214225

215-
block, new_offset = _read_block_items(docstring, offset=offset, warnings=warnings, **options)
226+
block, new_offset = _read_block_items(lines, docstring, offset=offset, warnings=warnings, **options)
216227

217228
# TODO: Use `get_name_annotation_description` here too?
218229
for line_number, param_lines in block:
@@ -270,27 +281,30 @@ def _read_parameters(
270281

271282

272283
def _read_parameters_section(
284+
lines: list[str],
273285
docstring: Docstring,
274286
*,
275287
offset: int,
276288
**options: Any,
277289
) -> tuple[DocstringSectionParameters | None, int]:
278-
parameters, new_offset = _read_parameters(docstring, offset=offset, **options)
290+
parameters, new_offset = _read_parameters(lines, docstring, offset=offset, **options)
279291
return DocstringSectionParameters(parameters), new_offset
280292

281293

282294
def _read_other_parameters_section(
295+
lines: list[str],
283296
docstring: Docstring,
284297
*,
285298
offset: int,
286299
warn_unknown_params: bool = True, # noqa: ARG001
287300
**options: Any,
288301
) -> tuple[DocstringSectionOtherParameters | None, int]:
289-
parameters, new_offset = _read_parameters(docstring, offset=offset, warn_unknown_params=False, **options)
302+
parameters, new_offset = _read_parameters(lines, docstring, offset=offset, warn_unknown_params=False, **options)
290303
return DocstringSectionOtherParameters(parameters), new_offset
291304

292305

293306
def _read_type_parameters_section(
307+
lines: list[str],
294308
docstring: Docstring,
295309
*,
296310
offset: int,
@@ -300,7 +314,7 @@ def _read_type_parameters_section(
300314
type_parameters = []
301315
bound: str | Expr | None
302316

303-
block, new_offset = _read_block_items(docstring, offset=offset, **options)
317+
block, new_offset = _read_block_items(lines, docstring, offset=offset, **options)
304318

305319
for line_number, type_param_lines in block:
306320
# check the presence of a name and description, separated by a colon
@@ -360,14 +374,15 @@ def _read_type_parameters_section(
360374

361375

362376
def _read_attributes_section(
377+
lines: list[str],
363378
docstring: Docstring,
364379
*,
365380
offset: int,
366381
warnings: bool = True,
367382
**options: Any,
368383
) -> tuple[DocstringSectionAttributes | None, int]:
369384
attributes = []
370-
block, new_offset = _read_block_items(docstring, offset=offset, warnings=warnings, **options)
385+
block, new_offset = _read_block_items(lines, docstring, offset=offset, warnings=warnings, **options)
371386

372387
annotation: str | Expr | None = None
373388
for line_number, attr_lines in block:
@@ -402,14 +417,15 @@ def _read_attributes_section(
402417

403418

404419
def _read_functions_section(
420+
lines: list[str],
405421
docstring: Docstring,
406422
*,
407423
offset: int,
408424
warnings: bool = True,
409425
**options: Any,
410426
) -> tuple[DocstringSectionFunctions | None, int]:
411427
functions = []
412-
block, new_offset = _read_block_items(docstring, offset=offset, warnings=warnings, **options)
428+
block, new_offset = _read_block_items(lines, docstring, offset=offset, warnings=warnings, **options)
413429

414430
signature: str | Expr | None = None
415431
for line_number, func_lines in block:
@@ -439,14 +455,15 @@ def _read_functions_section(
439455

440456

441457
def _read_classes_section(
458+
lines: list[str],
442459
docstring: Docstring,
443460
*,
444461
offset: int,
445462
warnings: bool = True,
446463
**options: Any,
447464
) -> tuple[DocstringSectionClasses | None, int]:
448465
classes = []
449-
block, new_offset = _read_block_items(docstring, offset=offset, warnings=warnings, **options)
466+
block, new_offset = _read_block_items(lines, docstring, offset=offset, warnings=warnings, **options)
450467

451468
signature: str | Expr | None = None
452469
for line_number, class_lines in block:
@@ -476,13 +493,14 @@ def _read_classes_section(
476493

477494

478495
def _read_type_aliases_section(
496+
lines: list[str],
479497
docstring: Docstring,
480498
*,
481499
offset: int,
482500
**options: Any,
483501
) -> tuple[DocstringSectionTypeAliases | None, int]:
484502
type_aliases = []
485-
block, new_offset = _read_block_items(docstring, offset=offset, **options)
503+
block, new_offset = _read_block_items(lines, docstring, offset=offset, **options)
486504

487505
for line_number, type_alias_lines in block:
488506
try:
@@ -501,14 +519,15 @@ def _read_type_aliases_section(
501519

502520

503521
def _read_modules_section(
522+
lines: list[str],
504523
docstring: Docstring,
505524
*,
506525
offset: int,
507526
warnings: bool = True,
508527
**options: Any,
509528
) -> tuple[DocstringSectionModules | None, int]:
510529
modules = []
511-
block, new_offset = _read_block_items(docstring, offset=offset, warnings=warnings, **options)
530+
block, new_offset = _read_block_items(lines, docstring, offset=offset, warnings=warnings, **options)
512531

513532
for line_number, module_lines in block:
514533
try:
@@ -529,14 +548,15 @@ def _read_modules_section(
529548

530549

531550
def _read_raises_section(
551+
lines: list[str],
532552
docstring: Docstring,
533553
*,
534554
offset: int,
535555
warnings: bool = True,
536556
**options: Any,
537557
) -> tuple[DocstringSectionRaises | None, int]:
538558
exceptions = []
539-
block, new_offset = _read_block_items(docstring, offset=offset, warnings=warnings, **options)
559+
block, new_offset = _read_block_items(lines, docstring, offset=offset, warnings=warnings, **options)
540560

541561
annotation: str | Expr
542562
for line_number, exception_lines in block:
@@ -560,14 +580,15 @@ def _read_raises_section(
560580

561581

562582
def _read_warns_section(
583+
lines: list[str],
563584
docstring: Docstring,
564585
*,
565586
offset: int,
566587
warnings: bool = True,
567588
**options: Any,
568589
) -> tuple[DocstringSectionWarns | None, int]:
569590
warns = []
570-
block, new_offset = _read_block_items(docstring, offset=offset, warnings=warnings, **options)
591+
block, new_offset = _read_block_items(lines, docstring, offset=offset, warnings=warnings, **options)
571592

572593
for line_number, warning_lines in block:
573594
try:
@@ -588,15 +609,16 @@ def _read_warns_section(
588609

589610

590611
def _read_block_items_maybe(
612+
lines: list[str],
591613
docstring: Docstring,
592614
*,
593615
offset: int,
594616
multiple: bool = True,
595617
**options: Any,
596618
) -> _ItemsBlock:
597619
if multiple:
598-
return _read_block_items(docstring, offset=offset, **options)
599-
one_block, new_offset = _read_block(docstring, offset=offset, **options)
620+
return _read_block_items(lines, docstring, offset=offset, **options)
621+
one_block, new_offset = _read_block(lines, offset=offset, **options)
600622
return [(new_offset, one_block.splitlines())], new_offset
601623

602624

@@ -651,6 +673,7 @@ def _annotation_from_parent(
651673

652674

653675
def _read_returns_section(
676+
lines: list[str],
654677
docstring: Docstring,
655678
*,
656679
offset: int,
@@ -663,6 +686,7 @@ def _read_returns_section(
663686
returns = []
664687

665688
block, new_offset = _read_block_items_maybe(
689+
lines,
666690
docstring,
667691
offset=offset,
668692
multiple=returns_multiple_items,
@@ -697,6 +721,7 @@ def _read_returns_section(
697721

698722

699723
def _read_yields_section(
724+
lines: list[str],
700725
docstring: Docstring,
701726
*,
702727
offset: int,
@@ -709,6 +734,7 @@ def _read_yields_section(
709734
yields = []
710735

711736
block, new_offset = _read_block_items_maybe(
737+
lines,
712738
docstring,
713739
offset=offset,
714740
multiple=returns_multiple_items,
@@ -743,6 +769,7 @@ def _read_yields_section(
743769

744770

745771
def _read_receives_section(
772+
lines: list[str],
746773
docstring: Docstring,
747774
*,
748775
offset: int,
@@ -755,6 +782,7 @@ def _read_receives_section(
755782
receives = []
756783

757784
block, new_offset = _read_block_items_maybe(
785+
lines,
758786
docstring,
759787
offset=offset,
760788
multiple=receives_multiple_items,
@@ -789,13 +817,14 @@ def _read_receives_section(
789817

790818

791819
def _read_examples_section(
792-
docstring: Docstring,
820+
lines: list[str],
821+
docstring: Docstring, # noqa: ARG001
793822
*,
794823
offset: int,
795824
trim_doctest_flags: bool = True,
796825
**options: Any,
797826
) -> tuple[DocstringSectionExamples | None, int]:
798-
text, new_offset = _read_block(docstring, offset=offset, **options)
827+
text, new_offset = _read_block(lines, offset=offset, **options)
799828

800829
sub_sections: list[tuple[Literal[DocstringSectionKind.text, DocstringSectionKind.examples], str]] = []
801830
in_code_example = False
@@ -848,7 +877,7 @@ def _read_examples_section(
848877

849878

850879
def _is_empty_line(line: str) -> bool:
851-
return not line.strip()
880+
return not line or line.isspace()
852881

853882

854883
_section_reader = {
@@ -969,18 +998,19 @@ def parse_google(
969998
offset = 2 if ignore_summary else 0
970999

9711000
while offset < len(lines):
972-
line_lower = lines[offset].lower()
1001+
line = lines[offset]
1002+
is_code_fence = line.lstrip(" ").startswith("```")
9731003

9741004
if in_code_block:
975-
if line_lower.lstrip(" ").startswith("```"):
1005+
if is_code_fence:
9761006
in_code_block = False
977-
current_section.append(lines[offset])
1007+
current_section.append(line)
9781008

979-
elif line_lower.lstrip(" ").startswith("```"):
1009+
elif is_code_fence:
9801010
in_code_block = True
981-
current_section.append(lines[offset])
1011+
current_section.append(line)
9821012

983-
elif match := _RE_ADMONITION.match(lines[offset]):
1013+
elif ":" in line and (match := _RE_ADMONITION.match(line)):
9841014
groups = match.groupdict()
9851015
title = groups["title"]
9861016
admonition_type = groups["type"]
@@ -1025,13 +1055,13 @@ def parse_google(
10251055
sections.append(DocstringSectionText("\n".join(current_section).rstrip("\n")))
10261056
current_section = []
10271057
reader = _section_reader[_section_kind[admonition_type.lower()]]
1028-
section, offset = reader(docstring, offset=offset + 1, **options)
1058+
section, offset = reader(lines, docstring, offset=offset + 1, **options)
10291059
if section:
10301060
section.title = title
10311061
sections.append(section)
10321062

10331063
else:
1034-
contents, offset = _read_block(docstring, offset=offset + 1)
1064+
contents, offset = _read_block(lines, offset=offset + 1)
10351065
if contents:
10361066
if current_section:
10371067
if any(current_section):
@@ -1045,7 +1075,7 @@ def parse_google(
10451075
with suppress(IndexError):
10461076
current_section.append(lines[offset])
10471077
else:
1048-
current_section.append(lines[offset])
1078+
current_section.append(line)
10491079

10501080
offset += 1
10511081

0 commit comments

Comments
 (0)