Exception: 'DocstringReturn' object is not iterable

[plannigan]

Describe the bug
I attempted to use the new docstring handler for Python. The first time I tried to generate the documentation I encountered an unhanded exception.

The end of the stack trace:

...
   File "/opt/hostedtoolcache/Python/3.10.2/x64/lib/python3.10/site-packages/mkdocstrings_handlers/python/templates/material/_base/docstring.html", line 21, in top-level template code
    {% include "docstring/returns.html" with context %}
  File "/opt/hostedtoolcache/Python/3.10.2/x64/lib/python3.10/site-packages/mkdocstrings_handlers/python/templates/material/docstring/returns.html", line 1, in top-level template code
    {% extends "_base/docstring/returns.html" %}
  File "/opt/hostedtoolcache/Python/3.10.2/x64/lib/python3.10/site-packages/mkdocstrings_handlers/python/templates/material/_base/docstring/returns.html", line 3, in top-level template code
    {% set name_column = section.value|selectattr("name")|any %}
  File "/opt/hostedtoolcache/Python/3.10.2/x64/lib/python3.10/site-packages/mkdocstrings/handlers/base.py", line 57, in do_any
    return any(seq)
  File "/opt/hostedtoolcache/Python/3.10.2/x64/lib/python3.10/site-packages/jinja2/filters.py", line 1749, in select_or_reject
    for item in value:
TypeError: 'DocstringReturn' object is not iterable

To Reproduce
This failed CI step demonstrate the failure.

Expected behavior
The API documentation is generated as it did with the previous handler.

System (please complete the following information):

• mkdocstrings-python version: 0.6.2
• Python version: 3.10.2
• OS: Ubuntu 20.04.3

[pawamoy]

Hello @plannigan! Thank you for testing the new handler 🙂

Do you use the Sphinx docstring style (the one you implemented 😉)? I wonder if the docstring section is built correctly within this parser. I should definitely add some validation mechanisms for the values of sections. Or use proper class inheritance or something.

[plannigan]

Yes, it does use that docstring style. I took a quick look at the class defenitions. It doesn't look like there is something that should be iterated on (maybe as_dict()?). Another option is that the template has a copy & paste error from on of the other sections were there could be multiple values.

[pawamoy]

What I meant is that the Python handler supports multiple documented return value, with optional names, and types, and that I probably didn't update the Sphinx parser in Griffe to build sections with a list rather than a single element.

Concretely, the DocstringSection value must be a list of DocstringReturn instances, not just a single instance. Would you like to see if you can bring this modification into the Sphinx parser, in the Griffe repository?

[plannigan]

Docstring.value is annotated with type Any. However, you comment makes it sound like the value of Docstring.kind implies a more specific type. I tried List[Any] and the type checker reported errors in the other parsers.

  src/griffe/docstrings/sphinx.py:319: error: Argument 2 to "DocstringSection" has incompatible type "str"; expected "List[Any]"  [arg-type]
  src/griffe/docstrings/sphinx.py:327: error: Argument 2 to "DocstringSection" has incompatible type "DocstringReturn"; expected "List[Any]"  [arg-type]
  src/griffe/docstrings/numpy.py:278: error: Argument 2 to "DocstringSection" has incompatible type "Tuple[str, str]"; expected "List[Any]"  [arg-type]
  src/griffe/docstrings/numpy.py:511: error: Argument 2 to "DocstringSection" has incompatible type "str"; expected "List[Any]"  [arg-type]
  src/griffe/docstrings/numpy.py:529: error: Argument 2 to "DocstringSection" has incompatible type "str"; expected "List[Any]"  [arg-type]
  src/griffe/docstrings/google.py:475: error: Argument 2 to "DocstringSection" has incompatible type "Tuple[str, str]"; expected "List[Any]"  [arg-type]
  src/griffe/docstrings/google.py:561: error: Argument 2 to "DocstringSection" has incompatible type "str"; expected "List[Any]"  [arg-type]
  src/griffe/docstrings/google.py:580: error: Argument "value" to "DocstringSection" has incompatible type "DocstringAdmonition"; expected "List[Any]"  [arg-type]
  src/griffe/docstrings/google.py:593: error: Argument 2 to "DocstringSection" has incompatible type "str"; expected "List[Any]"  [arg-type]
  src/griffe/docstrings/parsers.py:52: error: Argument 2 to "DocstringSection" has incompatible type "str"; expected "List[Any]"  [arg-type]

Is there documentation on what those expected types are? It is straight forward to make the Sphinx parser provide DocstringReturn as a list. But I'd rather not play whack-a-mole with all of the other values if they are slightly incorrect.

[pawamoy]

I understand, then let me improve the typing / documentation / validation mechanisms for docstrings sections first, because it's indeed lacking. I'll report back here 🙂

[pawamoy]

OK this should be fixed now! I'll release during this week (other bugfixes I can pack in).