"""Tests for the [Google-style parser][griffe.docstrings.google].""" from __future__ import annotations import inspect from typing import TYPE_CHECKING import pytest from griffe import ( Attribute, Class, Docstring, DocstringReceive, DocstringReturn, DocstringSectionKind, DocstringYield, ExprName, Function, Module, Parameter, Parameters, TypeParameter, TypeParameterKind, TypeParameters, parse_docstring_annotation, ) if TYPE_CHECKING: from tests.test_docstrings.helpers import ParserType # ============================================================================================= # Markup flow (multilines, indentation, etc.) def test_simple_docstring(parse_google: ParserType) -> None: """Parse a simple docstring. Parameters: parse_google: Fixture parser. """ sections, warnings = parse_google("A simple docstring.") assert len(sections) == 1 assert not warnings def test_multiline_docstring(parse_google: ParserType) -> None: """Parse a multi-line docstring. Parameters: parse_google: Fixture parser. """ sections, warnings = parse_google( """ A somewhat longer docstring. Blablablabla. """, ) assert len(sections) == 1 assert not warnings def test_parse_partially_indented_lines(parse_google: ParserType) -> None: """Properly handle partially indented lines. Parameters: parse_google: Fixture parser. """ docstring = """ The available formats are: - JSON The unavailable formats are: - YAML """ sections, warnings = parse_google(docstring) assert len(sections) == 2 assert sections[0].kind is DocstringSectionKind.admonition assert sections[1].kind is DocstringSectionKind.admonition assert not warnings def test_multiple_lines_in_sections_items(parse_google: ParserType) -> None: """Parse multi-line item description. Parameters: parse_google: Fixture parser. """ docstring = """ Parameters: p (int): This parameter has a description spawning on multiple lines. It even has blank lines in it. Some of these lines are indented for no reason. q (int): What if the first line is blank? """ sections, warnings = parse_google(docstring) assert len(sections) == 1 assert len(sections[0].value) == 2 assert warnings for warning in warnings: assert "should be 4 * 2 = 8 spaces, not" in warning def test_code_blocks(parse_google: ParserType) -> None: """Parse code blocks. Parameters: parse_google: Fixture parser. """ docstring = """ This docstring contains a code block! ```python print("hello") ``` """ sections, warnings = parse_google(docstring) assert len(sections) == 1 assert not warnings def test_indented_code_block(parse_google: ParserType) -> None: """Parse indented code blocks. Parameters: parse_google: Fixture parser. """ docstring = """ This docstring contains a docstring in a code block o_O! \"\"\" This docstring is contained in another docstring O_o! Parameters: s: A string. \"\"\" """ sections, warnings = parse_google(docstring) assert len(sections) == 1 assert not warnings def test_different_indentation(parse_google: ParserType) -> None: """Parse different indentations, warn on confusing indentation. Parameters: parse_google: Fixture parser. """ docstring = """ Raises: StartAt5: this section's items starts with 5 spaces of indentation. Well indented continuation line. Badly indented continuation line (will trigger a warning). Empty lines are preserved, as well as extra-indentation (this line is a code block). AnyOtherLine: ...starting with exactly 5 spaces is a new item. AnyLine: ...indented with less than 5 spaces signifies the end of the section. """ sections, warnings = parse_google(docstring) assert len(sections) == 2 assert len(sections[0].value) == 2 assert sections[0].value[0].description == ( "this section's items starts with 5 spaces of indentation.\n" "Well indented continuation line.\n" "Badly indented continuation line (will trigger a warning).\n" "\n" " Empty lines are preserved, as well as extra-indentation (this line is a code block)." ) assert sections[1].value == " AnyLine: ...indented with less than 5 spaces signifies the end of the section." assert len(warnings) == 1 assert "should be 5 * 2 = 10 spaces, not 6" in warnings[0] def test_empty_indented_lines_in_section_with_items(parse_google: ParserType) -> None: """In sections with items, don't treat lines with just indentation as items. Parameters: parse_google: Fixture parser. """ docstring = "Returns:\n only_item: Description.\n \n \n\nSomething." sections, _ = parse_google(docstring) assert len(sections) == 2 assert len(sections[0].value) == 1 @pytest.mark.parametrize( "section", [ "Attributes", "Other Parameters", "Parameters", "Type Parameters", "Raises", "Receives", "Returns", "Warns", "Type aliases", "Yields", ], ) def test_starting_item_description_on_new_line(parse_google: ParserType, section: str) -> None: """In sections with items, allow starting item descriptions on a new (indented) line. Parameters: parse_google: Fixture parser. section: A parametrized section name. """ docstring = f"\n{section}:\n only_item:\n Description." sections, _ = parse_google(docstring) assert len(sections) == 1 assert len(sections[0].value) == 1 assert sections[0].value[0].description.strip() == "Description." # ============================================================================================= # Annotations def test_parse_without_parent(parse_google: ParserType) -> None: """Parse a docstring without a parent function. Parameters: parse_google: Fixture parser. """ sections, warnings = parse_google( """ Parameters: void: SEGFAULT. niet: SEGFAULT. nada: SEGFAULT. rien: SEGFAULT. Keyword Args: keywd: SEGFAULT. Exceptions: GlobalError: when nothing works as expected. Returns: Itself. """, ) assert len(sections) == 4 assert len(warnings) == 6 # Missing annotations for parameters and return. for warning in warnings[:-1]: assert "parameter" in warning assert "return" in warnings[-1] def test_parse_without_annotations(parse_google: ParserType) -> None: """Parse a function docstring without signature annotations. Parameters: parse_google: Fixture parser. """ docstring = """ Parameters: x: X value. Keyword Args: y: Y value. Returns: Sum X + Y + Z. """ sections, warnings = parse_google( docstring, parent=Function( "func", parameters=Parameters( Parameter("x"), Parameter("y"), ), ), ) assert len(sections) == 3 assert len(warnings) == 3 for warning in warnings[:-1]: assert "parameter" in warning assert "return" in warnings[-1] def test_parse_with_annotations(parse_google: ParserType) -> None: """Parse a function docstring with signature annotations. Parameters: parse_google: Fixture parser. """ docstring = """ Parameters: x: X value. Keyword Parameters: y: Y value. Returns: Sum X + Y. """ sections, warnings = parse_google( docstring, parent=Function( "func", parameters=Parameters( Parameter("x", annotation="int"), Parameter("y", annotation="int"), ), returns="int", ), ) assert len(sections) == 3 assert not warnings # ============================================================================================= # Sections def test_parse_attributes_section(parse_google: ParserType) -> None: """Parse Attributes sections. Parameters: parse_google: Fixture parser. """ docstring = """ Attributes: hey: Hey. ho: Ho. """ sections, warnings = parse_google(docstring) assert len(sections) == 1 assert not warnings def test_parse_functions_section(parse_google: ParserType) -> None: """Parse Functions/Methods sections. Parameters: parse_google: Fixture parser. """ docstring = """ Functions: f(a, b=2): Hello. g: Hi. Methods: f(a, b=2): Hello. g: Hi. """ sections, warnings = parse_google(docstring) assert len(sections) == 2 for section in sections: assert section.kind is DocstringSectionKind.functions func_f = section.value[0] assert func_f.name == "f" assert func_f.signature == "f(a, b=2)" assert func_f.description == "Hello." func_g = section.value[1] assert func_g.name == "g" assert func_g.signature is None assert func_g.description == "Hi." assert not warnings def test_parse_classes_section(parse_google: ParserType) -> None: """Parse Classes sections. Parameters: parse_google: Fixture parser. """ docstring = """ Classes: C(a, b=2): Hello. D: Hi. """ sections, warnings = parse_google(docstring) assert len(sections) == 1 assert sections[0].kind is DocstringSectionKind.classes class_c = sections[0].value[0] assert class_c.name == "C" assert class_c.signature == "C(a, b=2)" assert class_c.description == "Hello." class_d = sections[0].value[1] assert class_d.name == "D" assert class_d.signature is None assert class_d.description == "Hi." assert not warnings def test_parse_type_aliases_section(parse_google: ParserType) -> None: """Parse Type Aliases sections. Parameters: parse_google: Fixture parser. """ docstring = """ Type Aliases: TC: Hello. TD: Hi. """ sections, warnings = parse_google(docstring) assert len(sections) == 1 assert sections[0].kind is DocstringSectionKind.type_aliases type_alias_c = sections[0].value[0] assert type_alias_c.name == "TC" assert type_alias_c.description == "Hello." type_alias_d = sections[0].value[1] assert type_alias_d.name == "TD" assert type_alias_d.description == "Hi." assert not warnings def test_parse_modules_section(parse_google: ParserType) -> None: """Parse Modules sections. Parameters: parse_google: Fixture parser. """ docstring = """ Modules: m: Hello. n: Hi. """ sections, warnings = parse_google(docstring) assert len(sections) == 1 assert sections[0].kind is DocstringSectionKind.modules module_m = sections[0].value[0] assert module_m.name == "m" assert module_m.description == "Hello." module_n = sections[0].value[1] assert module_n.name == "n" assert module_n.description == "Hi." assert not warnings def test_parse_examples_sections(parse_google: ParserType) -> None: """Parse a function docstring with examples. Parameters: parse_google: Fixture parser. """ docstring = """ Examples: Some examples that will create a unified code block: >>> 2 + 2 == 5 False >>> print("examples") "examples" This is just a random comment in the examples section. These examples will generate two different code blocks. Note the blank line. >>> print("I'm in the first code block!") "I'm in the first code block!" >>> print("I'm in other code block!") "I'm in other code block!" We also can write multiline examples: >>> x = 3 + 2 # doctest: +SKIP >>> y = x + 10 >>> y 15 This is just a typical Python code block: ```python print("examples") return 2 + 2 ``` Even if it contains doctests, the following block is still considered a normal code-block. ```pycon >>> print("examples") "examples" >>> 2 + 2 4 ``` The blank line before an example is optional. >>> x = 3 >>> y = "apple" >>> z = False >>> l = [x, y, z] >>> my_print_list_function(l) 3 "apple" False """ sections, warnings = parse_google( docstring, parent=Function( "func", parameters=Parameters( Parameter("x", annotation="int"), Parameter("y", annotation="int"), ), returns="int", ), trim_doctest_flags=False, ) assert len(sections) == 1 examples = sections[0] assert len(examples.value) == 9 assert examples.value[6][1].startswith(">>> x = 3 + 2 # doctest: +SKIP") assert not warnings def test_parse_yields_section(parse_google: ParserType) -> None: """Parse Yields section. Parameters: parse_google: Fixture parser. """ docstring = """ Yields: x: Floats. (int): Integers. y (int): Same. """ sections, warnings = parse_google(docstring) assert len(sections) == 1 annotated = sections[0].value[0] assert annotated.name == "x" assert annotated.annotation is None assert annotated.description == "Floats." annotated = sections[0].value[1] assert annotated.name == "" assert annotated.annotation == "int" assert annotated.description == "Integers." annotated = sections[0].value[2] assert annotated.name == "y" assert annotated.annotation == "int" assert annotated.description == "Same." assert len(warnings) == 1 assert "'x'" in warnings[0] def test_invalid_sections(parse_google: ParserType) -> None: """Warn on invalid sections. Parameters: parse_google: Fixture parser. """ docstring = """ Parameters: Exceptions: Exceptions: Returns: Note: Important: """ sections, warnings = parse_google(docstring) assert len(sections) == 1 assert not warnings def test_no_empty_text_section(parse_google: ParserType) -> None: """Don't create a single empty text section for an empty docstring. Parameters: parse_google: Fixture parser. """ sections, warnings = parse_google("") assert not sections assert not warnings # ============================================================================================= # Parameters sections def test_parse_args_and_kwargs(parse_google: ParserType) -> None: """Parse args and kwargs. Parameters: parse_google: Fixture parser. """ docstring = """ Parameters: a (str): a parameter. *args (str): args parameters. **kwargs (str): kwargs parameters. """ sections, warnings = parse_google(docstring) assert len(sections) == 1 expected_parameters = {"a": "a parameter.", "*args": "args parameters.", "**kwargs": "kwargs parameters."} for parameter in sections[0].value: assert parameter.name in expected_parameters assert expected_parameters[parameter.name] == parameter.description assert not warnings def test_parse_args_kwargs_keyword_only(parse_google: ParserType) -> None: """Parse args and kwargs. Parameters: parse_google: Fixture parser. """ docstring = """ Parameters: a (str): a parameter. *args (str): args parameters. Keyword Args: **kwargs (str): kwargs parameters. """ sections, warnings = parse_google(docstring) assert len(sections) == 2 expected_parameters = {"a": "a parameter.", "*args": "args parameters."} for parameter in sections[0].value: assert parameter.name in expected_parameters assert expected_parameters[parameter.name] == parameter.description expected_parameters = {"**kwargs": "kwargs parameters."} for kwarg in sections[1].value: assert kwarg.name in expected_parameters assert expected_parameters[kwarg.name] == kwarg.description assert not warnings def test_parse_types_in_docstring(parse_google: ParserType) -> None: """Parse types in docstring. Parameters: parse_google: Fixture parser. """ docstring = """ Parameters: x (int): X value. Keyword Args: y (int): Y value. Returns: s (int): Sum X + Y + Z. """ sections, warnings = parse_google( docstring, parent=Function( "func", parameters=Parameters( Parameter("x"), Parameter("y"), ), ), ) assert len(sections) == 3 assert not warnings assert sections[0].kind is DocstringSectionKind.parameters assert sections[1].kind is DocstringSectionKind.other_parameters assert sections[2].kind is DocstringSectionKind.returns (argx,) = sections[0].value (argy,) = sections[1].value (returns,) = sections[2].value assert argx.name == "x" assert argx.annotation.name == "int" assert argx.annotation.canonical_path == "int" assert argx.description == "X value." assert argx.value is None assert argy.name == "y" assert argy.annotation.name == "int" assert argy.annotation.canonical_path == "int" assert argy.description == "Y value." assert argy.value is None assert returns.annotation.name == "int" assert returns.annotation.canonical_path == "int" assert returns.description == "Sum X + Y + Z." def test_parse_optional_type_in_docstring(parse_google: ParserType) -> None: """Parse optional types in docstring. Parameters: parse_google: Fixture parser. """ docstring = """ Parameters: x (int): X value. y (int, optional): Y value. Keyword Args: z (int, optional): Z value. """ sections, warnings = parse_google( docstring, parent=Function( "func", parameters=Parameters( Parameter("x", default="1"), Parameter("y", default="None"), Parameter("z", default="None"), ), ), ) assert len(sections) == 2 assert not warnings assert sections[0].kind is DocstringSectionKind.parameters assert sections[1].kind is DocstringSectionKind.other_parameters argx, argy = sections[0].value (argz,) = sections[1].value assert argx.name == "x" assert argx.annotation.name == "int" assert argx.annotation.canonical_path == "int" assert argx.description == "X value." assert argx.value == "1" assert argy.name == "y" assert argy.annotation.name == "int" assert argy.annotation.canonical_path == "int" assert argy.description == "Y value." assert argy.value == "None" assert argz.name == "z" assert argz.annotation.name == "int" assert argz.annotation.canonical_path == "int" assert argz.description == "Z value." assert argz.value == "None" def test_prefer_docstring_types_over_annotations(parse_google: ParserType) -> None: """Prefer the docstring type over the annotation. Parameters: parse_google: Fixture parser. """ docstring = """ Parameters: x (str): X value. Keyword Args: y (str): Y value. Returns: (str): Sum X + Y + Z. """ sections, warnings = parse_google( docstring, parent=Function( "func", parameters=Parameters( Parameter("x", annotation="int"), Parameter("y", annotation="int"), ), returns="int", ), ) assert len(sections) == 3 assert not warnings assert sections[0].kind is DocstringSectionKind.parameters assert sections[1].kind is DocstringSectionKind.other_parameters assert sections[2].kind is DocstringSectionKind.returns (argx,) = sections[0].value (argy,) = sections[1].value (returns,) = sections[2].value assert argx.name == "x" assert argx.annotation.name == "str" assert argx.annotation.canonical_path == "str" assert argx.description == "X value." assert argy.name == "y" assert argy.annotation.name == "str" assert argy.annotation.canonical_path == "str" assert argy.description == "Y value." assert returns.annotation.name == "str" assert returns.annotation.canonical_path == "str" assert returns.description == "Sum X + Y + Z." def test_parameter_line_without_colon(parse_google: ParserType) -> None: """Warn when missing colon. Parameters: parse_google: Fixture parser. """ docstring = """ Parameters: x is an integer. """ sections, warnings = parse_google(docstring) assert len(sections) == 0 # Empty sections are discarded. assert len(warnings) == 1 assert "pair" in warnings[0] def test_parameter_line_without_colon_keyword_only(parse_google: ParserType) -> None: """Warn when missing colon. Parameters: parse_google: Fixture parser. """ docstring = """ Keyword Args: x is an integer. """ sections, warnings = parse_google(docstring) assert len(sections) == 0 # Empty sections are discarded. assert len(warnings) == 1 assert "pair" in warnings[0] def test_warn_about_unknown_parameters(parse_google: ParserType) -> None: """Warn about unknown parameters in "Parameters" sections. Parameters: parse_google: Fixture parser. """ docstring = """ Parameters: x (int): Integer. y (int): Integer. """ _, warnings = parse_google( docstring, parent=Function( "func", parameters=Parameters( Parameter("a"), Parameter("y"), ), ), ) assert len(warnings) == 1 assert "'x' does not appear in the function signature" in warnings[0] def test_never_warn_about_unknown_other_parameters(parse_google: ParserType) -> None: """Never warn about unknown parameters in "Other parameters" sections. Parameters: parse_google: Fixture parser. """ docstring = """ Other Parameters: x (int): Integer. z (int): Integer. """ _, warnings = parse_google( docstring, parent=Function( "func", parameters=Parameters( Parameter("a"), Parameter("y"), ), ), ) assert not warnings def test_unknown_params_scan_doesnt_crash_without_parameters(parse_google: ParserType) -> None: """Assert we don't crash when parsing parameters sections and parent object does not have parameters. Parameters: parse_google: Fixture parser. """ docstring = """ Parameters: this (str): This. that (str): That. """ _, warnings = parse_google(docstring, parent=Module("mod")) assert not warnings def test_class_uses_init_parameters(parse_google: ParserType) -> None: """Assert we use the `__init__` parameters when parsing classes' parameters sections. Parameters: parse_google: Fixture parser. """ docstring = """ Parameters: x: X value. """ parent = Class("c") parent["__init__"] = Function("__init__", parameters=Parameters(Parameter("x", annotation="int"))) sections, warnings = parse_google(docstring, parent=parent) assert not warnings argx = sections[0].value[0] assert argx.name == "x" assert argx.annotation == "int" assert argx.description == "X value." def test_parse_parameters_and_type_without_space(parse_google: ParserType) -> None: """Parse parameter name and type without space. Parameters: parse_google: Fixture parser. """ docstring = """ Parameters: x(int): X value. """ sections, warnings = parse_google(docstring) assert len(sections) == 1 assert not warnings argx = sections[0].value[0] assert argx.name == "x" assert argx.annotation == "int" assert argx.description == "X value." # TODO: possible feature # def test_missing_parameter(parse_google: ParserType) -> None: # """Warn on missing parameter in docstring. # # Parameters: # parse_google: Fixture parser. # """ # docstring = """ # Parameters: # x: Integer. # """ # assert not warnings # ============================================================================================= # Type parameters sections def test_parse_type_var_tuples_and_param_specs(parse_google: ParserType) -> None: """Parse type variable tuples and parameter specifications. Parameters: parse_google: Fixture parser. """ docstring = """ Type Parameters: T: A type parameter. C (str, (int, float)): A constrained type parameter. D complex: A bounded type parameter. """ sections, warnings = parse_google(docstring) assert len(sections) == 1 expected_type_parameters = { "T": ("A type parameter.", None), "C": ("A constrained type parameter.", "str, (int, float)"), "D": ("A bounded type parameter.", "complex"), } for type_parameter in sections[0].value: assert type_parameter.name in expected_type_parameters assert expected_type_parameters[type_parameter.name][0] == type_parameter.description assert expected_type_parameters[type_parameter.name][1] == type_parameter.annotation assert not warnings def test_prefer_docstring_bounds_over_annotations(parse_google: ParserType) -> None: """Prefer the docstring bound over the annotation. Parameters: parse_google: Fixture parser. """ docstring = """ Type Parameters: X (str): X type. Y str, int: Y type. """ sections, warnings = parse_google( docstring, parent=Function( "func", type_parameters=TypeParameters( TypeParameter("X", kind=TypeParameterKind.type_var, constraints=["complex"]), TypeParameter("Y", kind=TypeParameterKind.type_var, bound="int"), ), ), ) assert len(sections) == 1 assert not warnings assert sections[0].kind is DocstringSectionKind.type_parameters (x, y) = sections[0].value assert x.name == "X" assert str(x.bound) == "str" assert x.constraints is None assert y.name == "Y" assert y.bound is None assert [str(constraint) for constraint in y.constraints] == ["str", "int"] def test_type_parameter_line_without_colon(parse_google: ParserType) -> None: """Warn when missing colon. Parameters: parse_google: Fixture parser. """ docstring = """ Type Parameters: X is an integer type. """ sections, warnings = parse_google(docstring) assert len(sections) == 0 # empty sections are discarded assert len(warnings) == 1 assert "pair" in warnings[0] def test_warn_about_unknown_type_parameters(parse_google: ParserType) -> None: """Warn about unknown type parameters in "Type Parameters" sections. Parameters: parse_google: Fixture parser. """ docstring = """ Type Parameters: X (int): Integer. Y (int): Integer. """ _, warnings = parse_google( docstring, parent=Function( "func", type_parameters=TypeParameters( TypeParameter("A", kind=TypeParameterKind.type_var), TypeParameter("Y", kind=TypeParameterKind.type_var), ), ), ) assert len(warnings) == 1 assert "'X' does not appear in the function signature" in warnings[0] def test_unknown_type_params_scan_doesnt_crash_without_type_parameters(parse_google: ParserType) -> None: """Assert we don't crash when parsing type parameters sections and parent object does not have type parameters. Parameters: parse_google: Fixture parser. """ docstring = """ TypeParameters: This (str): This. That: That. """ _, warnings = parse_google(docstring, parent=Module("mod")) assert not warnings # ============================================================================================= # Attributes sections def test_retrieve_attributes_annotation_from_parent(parse_google: ParserType) -> None: """Retrieve the annotations of attributes from the parent object. Parameters: parse_google: Fixture parser. """ docstring = """ Summary. Attributes: a: Whatever. b: Whatever. """ parent = Class("cls") parent["a"] = Attribute("a", annotation=ExprName("int")) parent["b"] = Attribute("b", annotation=ExprName("str")) sections, _ = parse_google(docstring, parent=parent) attributes = sections[1].value assert attributes[0].name == "a" assert attributes[0].annotation.name == "int" assert attributes[1].name == "b" assert attributes[1].annotation.name == "str" # ============================================================================================= # Yields sections def test_parse_yields_section_with_return_annotation(parse_google: ParserType) -> None: """Parse Yields section with a return annotation in the parent function. Parameters: parse_google: Fixture parser. """ docstring = """ Yields: Integers. """ function = Function("func", returns="Iterator[int]") sections, warnings = parse_google(docstring, function) assert len(sections) == 1 annotated = sections[0].value[0] assert annotated.annotation == "Iterator[int]" assert annotated.description == "Integers." assert not warnings @pytest.mark.parametrize( "return_annotation", [ "Iterator[tuple[int, float]]", "Generator[tuple[int, float], ..., ...]", ], ) def test_parse_yields_tuple_in_iterator_or_generator(parse_google: ParserType, return_annotation: str) -> None: """Parse Yields annotations in Iterator or Generator types. Parameters: parse_google: Fixture parser. return_annotation: Parametrized return annotation as a string. """ docstring = """ Summary. Yields: a: Whatever. b: Whatever. """ sections, _ = parse_google( docstring, parent=Function( "func", returns=parse_docstring_annotation(return_annotation, Docstring("d", parent=Function("f"))), ), ) yields = sections[1].value assert yields[0].name == "a" assert yields[0].annotation.name == "int" assert yields[1].name == "b" assert yields[1].annotation.name == "float" @pytest.mark.parametrize( "return_annotation", [ "Iterator[int]", "Generator[int, None, None]", ], ) def test_extract_yielded_type_with_single_return_item(parse_google: ParserType, return_annotation: str) -> None: """Extract main type annotation from Iterator or Generator. Parameters: parse_google: Fixture parser. return_annotation: Parametrized return annotation as a string. """ docstring = """ Summary. Yields: A number. """ sections, _ = parse_google( docstring, parent=Function( "func", returns=parse_docstring_annotation(return_annotation, Docstring("d", parent=Function("f"))), ), ) yields = sections[1].value assert yields[0].annotation.name == "int" def test_yield_section_in_property(parse_google: ParserType) -> None: """No warnings when parsing Yields section in a property. Parameters: parse_google: Fixture parser. """ docstring = """ Summary. Yields: A number. """ sections, warnings = parse_google( docstring, parent=Attribute( "prop", annotation=parse_docstring_annotation("Iterator[int]", Docstring("d", parent=Attribute("a"))), ), ) assert not warnings yields = sections[1].value assert yields[0].annotation.name == "int" # ============================================================================================= # Receives sections def test_parse_receives_tuple_in_generator(parse_google: ParserType) -> None: """Parse Receives annotations in Generator type. Parameters: parse_google: Fixture parser. """ docstring = """ Summary. Receives: a: Whatever. b: Whatever. """ sections, _ = parse_google( docstring, parent=Function( "func", returns=parse_docstring_annotation( "Generator[..., tuple[int, float], ...]", Docstring("d", parent=Function("f")), ), ), ) receives = sections[1].value assert receives[0].name == "a" assert receives[0].annotation.name == "int" assert receives[1].name == "b" assert receives[1].annotation.name == "float" @pytest.mark.parametrize( "return_annotation", [ "Generator[int, float, None]", ], ) def test_extract_received_type_with_single_return_item(parse_google: ParserType, return_annotation: str) -> None: """Extract main type annotation from Iterator or Generator. Parameters: parse_google: Fixture parser. return_annotation: Parametrized return annotation as a string. """ docstring = """ Summary. Receives: A floating point number. """ sections, _ = parse_google( docstring, parent=Function( "func", returns=parse_docstring_annotation(return_annotation, Docstring("d", parent=Function("f"))), ), ) receives = sections[1].value assert receives[0].annotation.name == "float" # ============================================================================================= # Returns sections def test_parse_returns_tuple_in_generator(parse_google: ParserType) -> None: """Parse Returns annotations in Generator type. Parameters: parse_google: Fixture parser. """ docstring = """ Summary. Returns: a: Whatever. b: Whatever. """ sections, _ = parse_google( docstring, parent=Function( "func", returns=parse_docstring_annotation( "Generator[..., ..., tuple[int, float]]", Docstring("d", parent=Function("f")), ), ), ) returns = sections[1].value assert returns[0].name == "a" assert returns[0].annotation.name == "int" assert returns[1].name == "b" assert returns[1].annotation.name == "float" # ============================================================================================= # Parser special features def test_parse_admonitions(parse_google: ParserType) -> None: """Parse admonitions. Parameters: parse_google: Fixture parser. """ docstring = """ Important note: Hello. Note: With title. Hello again. Something: Something. """ sections, warnings = parse_google(docstring) assert len(sections) == 3 assert not warnings assert sections[0].title == "Important note" assert sections[0].value.kind == "important-note" assert sections[0].value.contents == "Hello." assert sections[1].title == "With title." assert sections[1].value.kind == "note" assert sections[1].value.contents == "Hello again." assert sections[2].title == "Something" assert sections[2].value.kind == "something" assert sections[2].value.contents == "Something." @pytest.mark.parametrize( "docstring", [ """ ****************************** This looks like an admonition: ****************************** """, """ Warning: this line also looks like an admonition. """, """ Matching but not an admonition: - Multiple empty lines above. """, """Last line:""", ], ) def test_handle_false_admonitions_correctly(parse_google: ParserType, docstring: str) -> None: """Correctly handle lines that look like admonitions. Parameters: parse_google: Fixture parser. docstring: The docstring to parse (parametrized). """ sections, warnings = parse_google(docstring) assert len(sections) == 1 assert sections[0].kind is DocstringSectionKind.text assert len(sections[0].value.splitlines()) == len(inspect.cleandoc(docstring).splitlines()) assert not warnings def test_dont_insert_admonition_before_current_section(parse_google: ParserType) -> None: """Check that admonitions are inserted at the right place. Parameters: parse_google: Fixture parser. """ docstring = """ Summary. Short description. Info: Something useful. """ sections, _ = parse_google(docstring) assert len(sections) == 2 assert sections[0].kind is DocstringSectionKind.text assert sections[1].kind is DocstringSectionKind.admonition @pytest.mark.parametrize( "docstring", [ "", "\n", "\n\n", "Summary.", "Summary.\n\n\n", "Summary.\n\nParagraph.", "Summary\non two lines.", "Summary\non two lines.\n\nParagraph.", ], ) def test_ignore_init_summary(parse_google: ParserType, docstring: str) -> None: """Correctly ignore summary in `__init__` methods' docstrings. Parameters: parse_google: Fixture parser. docstring: The docstring to parse_google (parametrized). """ sections, _ = parse_google(docstring, parent=Function("__init__", parent=Class("C")), ignore_init_summary=True) for section in sections: assert "Summary" not in section.value if docstring.strip(): sections, _ = parse_google(docstring, parent=Function("__init__", parent=Module("M")), ignore_init_summary=True) assert "Summary" in sections[0].value sections, _ = parse_google(docstring, parent=Function("f", parent=Class("C")), ignore_init_summary=True) assert "Summary" in sections[0].value sections, _ = parse_google(docstring, ignore_init_summary=True) assert "Summary" in sections[0].value @pytest.mark.parametrize( "docstring", [ """ Examples: Base case 1. We want to skip the following test. >>> 1 + 1 == 3 # doctest: +SKIP True """, r""" Examples: Base case 2. We have a blankline test. >>> print("a\n\nb") a b """, ], ) def test_trim_doctest_flags_basic_example(parse_google: ParserType, docstring: str) -> None: """Correctly parse simple example docstrings when `trim_doctest_flags` option is turned on. Parameters: parse_google: Fixture parser. docstring: The docstring to parse (parametrized). """ sections, warnings = parse_google(docstring, trim_doctest_flags=True) assert len(sections) == 1 assert len(sections[0].value) == 2 assert not warnings # Verify that doctest flags have indeed been trimmed. example_str = sections[0].value[1][1] assert "# doctest: +SKIP" not in example_str assert "" not in example_str def test_trim_doctest_flags_multi_example(parse_google: ParserType) -> None: """Correctly parse multiline example docstrings when `trim_doctest_flags` option is turned on. Parameters: parse_google: Fixture parser. """ docstring = r""" Examples: Test multiline example blocks. We want to skip the following test. >>> 1 + 1 == 3 # doctest: +SKIP True And then a few more examples here: >>> print("a\n\nb") a b >>> 1 + 1 == 2 # doctest: +SKIP >>> print(list(range(1, 100))) # doctest: +ELLIPSIS [1, 2, ..., 98, 99] """ sections, warnings = parse_google(docstring, trim_doctest_flags=True) assert len(sections) == 1 assert len(sections[0].value) == 4 assert not warnings # Verify that doctest flags have indeed been trimmed. example_str = sections[0].value[1][1] assert "# doctest: +SKIP" not in example_str example_str = sections[0].value[3][1] assert "" not in example_str assert "\n>>> print(list(range(1, 100)))\n" in example_str def test_single_line_with_trailing_whitespace(parse_google: ParserType) -> None: """Don't crash on single line docstrings with trailing whitespace. Parameters: parse_google: Fixture parser. """ docstring = "a: b\n " sections, warnings = parse_google(docstring, trim_doctest_flags=True) assert len(sections) == 1 assert sections[0].kind is DocstringSectionKind.text assert not warnings @pytest.mark.parametrize( ("returns_multiple_items", "return_annotation", "expected"), [ ( False, None, [DocstringReturn("", description="XXXXXXX\n YYYYYYY\nZZZZZZZ", annotation=None)], ), ( False, "tuple[int, int]", [DocstringReturn("", description="XXXXXXX\n YYYYYYY\nZZZZZZZ", annotation="tuple[int, int]")], ), ( True, None, [ DocstringReturn("", description="XXXXXXX\nYYYYYYY", annotation=None), DocstringReturn("", description="ZZZZZZZ", annotation=None), ], ), ( True, "tuple[int,int]", [ DocstringReturn("", description="XXXXXXX\nYYYYYYY", annotation="int"), DocstringReturn("", description="ZZZZZZZ", annotation="int"), ], ), ], ) def test_parse_returns_multiple_items( parse_google: ParserType, returns_multiple_items: bool, return_annotation: str, expected: list[DocstringReturn], ) -> None: """Parse Returns section with and without multiple items. Parameters: parse_google: Fixture parser. returns_multiple_items: Whether the `Returns` section has multiple items. return_annotation: The return annotation of the function to parse. expected: The expected value of the parsed Returns section. """ parent = ( Function("func", returns=parse_docstring_annotation(return_annotation, Docstring("d", parent=Function("f")))) if return_annotation is not None else None ) docstring = """ Returns: XXXXXXX YYYYYYY ZZZZZZZ """ sections, _ = parse_google( docstring, returns_multiple_items=returns_multiple_items, parent=parent, ) assert len(sections) == 1 assert len(sections[0].value) == len(expected) for annotated, expected_ in zip(sections[0].value, expected): assert annotated.name == expected_.name assert str(annotated.annotation) == str(expected_.annotation) assert annotated.description == expected_.description @pytest.mark.parametrize( ("returns_multiple_items", "return_annotation", "expected"), [ ( False, None, [DocstringYield("", description="XXXXXXX\n YYYYYYY\nZZZZZZZ", annotation=None)], ), ( False, "Iterator[tuple[int, int]]", [DocstringYield("", description="XXXXXXX\n YYYYYYY\nZZZZZZZ", annotation="tuple[int, int]")], ), ( True, None, [ DocstringYield("", description="XXXXXXX\nYYYYYYY", annotation=None), DocstringYield("", description="ZZZZZZZ", annotation=None), ], ), ( True, "Iterator[tuple[int,int]]", [ DocstringYield("", description="XXXXXXX\nYYYYYYY", annotation="int"), DocstringYield("", description="ZZZZZZZ", annotation="int"), ], ), ], ) def test_parse_yields_multiple_items( parse_google: ParserType, returns_multiple_items: bool, return_annotation: str, expected: list[DocstringYield], ) -> None: """Parse Returns section with and without multiple items. Parameters: parse_google: Fixture parser. returns_multiple_items: Whether the `Returns` and `Yields` sections have multiple items. return_annotation: The return annotation of the function to parse. Usually an `Iterator`. expected: The expected value of the parsed Yields section. """ parent = ( Function("func", returns=parse_docstring_annotation(return_annotation, Docstring("d", parent=Function("f")))) if return_annotation is not None else None ) docstring = """ Yields: XXXXXXX YYYYYYY ZZZZZZZ """ sections, _ = parse_google( docstring, returns_multiple_items=returns_multiple_items, parent=parent, ) assert len(sections) == 1 assert len(sections[0].value) == len(expected) for annotated, expected_ in zip(sections[0].value, expected): assert annotated.name == expected_.name assert str(annotated.annotation) == str(expected_.annotation) assert annotated.description == expected_.description @pytest.mark.parametrize( ("receives_multiple_items", "return_annotation", "expected"), [ ( False, None, [DocstringReceive("", description="XXXXXXX\n YYYYYYY\nZZZZZZZ", annotation=None)], ), ( False, "Generator[..., tuple[int, int], ...]", [DocstringReceive("", description="XXXXXXX\n YYYYYYY\nZZZZZZZ", annotation="tuple[int, int]")], ), ( True, None, [ DocstringReceive("", description="XXXXXXX\nYYYYYYY", annotation=None), DocstringReceive("", description="ZZZZZZZ", annotation=None), ], ), ( True, "Generator[..., tuple[int, int], ...]", [ DocstringReceive("", description="XXXXXXX\nYYYYYYY", annotation="int"), DocstringReceive("", description="ZZZZZZZ", annotation="int"), ], ), ], ) def test_parse_receives_multiple_items( parse_google: ParserType, receives_multiple_items: bool, return_annotation: str, expected: list[DocstringReceive], ) -> None: """Parse Returns section with and without multiple items. Parameters: parse_google: Fixture parser. receives_multiple_items: Whether the `Receives` section has multiple items. return_annotation: The return annotation of the function to parse. Usually a `Generator`. expected: The expected value of the parsed Receives section. """ parent = ( Function("func", returns=parse_docstring_annotation(return_annotation, Docstring("d", parent=Function("f")))) if return_annotation is not None else None ) docstring = """ Receives: XXXXXXX YYYYYYY ZZZZZZZ """ sections, _ = parse_google( docstring, receives_multiple_items=receives_multiple_items, parent=parent, ) assert len(sections) == 1 assert len(sections[0].value) == len(expected) for annotated, expected_ in zip(sections[0].value, expected): assert annotated.name == expected_.name assert str(annotated.annotation) == str(expected_.annotation) assert annotated.description == expected_.description def test_avoid_false_positive_sections(parse_google: ParserType) -> None: """Avoid false positive when parsing sections. Parameters: parse_google: Fixture parser. """ docstring = """ Summary. Modules: Not a modules section. No blank line before title: Not an admonition. Blank line after title: Not an admonition. Modules: Not a modules section. Modules: Not a modules section. No blank line before and blank line after: Not an admonition. Classes: - Text. """ sections, warnings = parse_google(docstring) assert len(sections) == 1 assert "Classes" in sections[0].value assert "Text" in sections[0].value assert len(warnings) == 6 assert warnings == [ "Possible section skipped, reasons: Missing blank line above section", "Possible admonition skipped, reasons: Missing blank line above admonition", "Possible admonition skipped, reasons: Extraneous blank line below admonition title", "Possible section skipped, reasons: Extraneous blank line below section title", "Possible section skipped, reasons: Missing blank line above section; Extraneous blank line below section title", "Possible admonition skipped, reasons: Missing blank line above admonition; Extraneous blank line below admonition title", ] def test_type_in_returns_without_parentheses(parse_google: ParserType) -> None: """Assert we can parse the return type without parentheses. Parameters: parse_google: Fixture parser. """ docstring = """ Summary. Returns: int: Description on several lines. """ sections, warnings = parse_google(docstring, returns_named_value=False) assert len(sections) == 2 assert not warnings retval = sections[1].value[0] assert retval.name == "" assert retval.annotation == "int" assert retval.description == "Description\non several lines." docstring = """ Summary. Returns: Description on several lines. """ sections, warnings = parse_google(docstring, returns_named_value=False) assert len(sections) == 2 assert len(warnings) == 1 retval = sections[1].value[0] assert retval.name == "" assert retval.annotation is None assert retval.description == "Description\non several lines." def test_type_in_yields_without_parentheses(parse_google: ParserType) -> None: """Assert we can parse the return type without parentheses. Parameters: parse_google: Fixture parser. """ docstring = """ Summary. Yields: int: Description on several lines. """ sections, warnings = parse_google(docstring, returns_named_value=False) assert len(sections) == 2 assert not warnings retval = sections[1].value[0] assert retval.name == "" assert retval.annotation == "int" assert retval.description == "Description\non several lines." docstring = """ Summary. Yields: Description on several lines. """ sections, warnings = parse_google(docstring, returns_named_value=False) assert len(sections) == 2 assert len(warnings) == 1 retval = sections[1].value[0] assert retval.name == "" assert retval.annotation is None assert retval.description == "Description\non several lines." def test_type_in_receives_without_parentheses(parse_google: ParserType) -> None: """Assert we can parse the return type without parentheses. Parameters: parse_google: Fixture parser. """ docstring = """ Summary. Receives: int: Description on several lines. """ sections, warnings = parse_google(docstring, receives_named_value=False) assert len(sections) == 2 assert not warnings retval = sections[1].value[0] assert retval.name == "" assert retval.annotation == "int" assert retval.description == "Description\non several lines." docstring = """ Summary. Receives: Description on several lines. """ sections, warnings = parse_google(docstring, receives_named_value=False) assert len(sections) == 2 assert len(warnings) == 1 retval = sections[1].value[0] assert retval.name == "" assert retval.annotation is None assert retval.description == "Description\non several lines." def test_reading_property_type_in_summary(parse_google: ParserType) -> None: """Assert we can parse the return type of properties in their summary. Parameters: parse_google: Fixture parser. """ docstring = "str: Description of the property." parent = Attribute("prop") parent.labels.add("property") sections, _ = parse_google(docstring, returns_type_in_property_summary=True, parent=parent) assert len(sections) == 2 assert sections[0].kind is DocstringSectionKind.text assert sections[1].kind is DocstringSectionKind.returns retval = sections[1].value[0] assert retval.name == "" assert retval.annotation.name == "str" assert retval.description == "" # ============================================================================================= # Warnings def test_disabled_warnings(parse_google: ParserType) -> None: """Assert warnings are disabled. Parameters: parse_google: Fixture parser. """ docstring = """ Parameters: x: X value. """ _, warnings = parse_google(docstring, warnings=True) assert warnings _, warnings = parse_google(docstring, warnings=False) assert not warnings