Suggestion: Add option to expand Literals

[phil65]

The old python handler "expanded" Literals and was showing every single value (for method parameter types for example), in this new one it only shows the name of the Literal. Would be great to have that option for the now handler, too.

[pawamoy]

I'm not sure to understand. Could you show some code snippets that illustrate your suggestion?

[phil65]

Let´s say we have this:

PossibleOptions = Literal["option_1", "option_2", "option_3"]

def some_fn(param_1: PossibleOptions):
   ...

With old handler, docs would show every single Literal in the generated "Parameters" box.
With new handler, it only shows "PossibleOptions" as parameter type.

[pawamoy]

I'm not in favor of bringing this change in the new handler. Most of the time we do not want to expand types. A fully expanded type quickly becomes very long. Even if we provide an option to expand or not, we don't have a way (yet) to configure it in a fine-grain manner: it would affect the whole tree of the injected object. It would also be impossible to guess whether to expand or not, without configuration options.

What I suggest instead is that, since you define a PossibleOptions type, you should document this type by adding a docstring below it:

PossibleOptions = Literal[...]  # etc
"""The possible options."""

With this, you can now include the type into your API docs, and whenever a function parameter is annotated with it, the rendered HTML will link to it, showing users the possible literal values.

WDYT?

[phil65]

A quick search shows me that my project contains almost 600 Literals, so manually docstringing them wouldnt be my favorite. 😄
For my use case, alyways expanding would work very well, but I can understand your reservations.
Perhaps something like a "show-expanded-values-on-mouseover" would be possible?

[pawamoy]

And how many types do you define to logically group literals? Note that I do not recommend documenting each literal, but rather each type like PossibleOptions.

Or you could not document them at all but still render them in the docs (show_if_no_docstring: true) to enjoy cross-references in function signatures.
Attributes have their value displayed so users would see the literals.

In your code base you only have type annotations made of literals? Don't you have other type annotations which are assigned unions of types or similar constructs? Always expanding would expand them as well. Would you be OK with that?

Another question: should the expansion be recursive? Griffe is not prepared for recursive expansion yet, as it simply unparses attribute values' AST into strings.

[phil65]

For me, non-recursive would work already very well. I use Literals almost exclusively for that PossibleOptions use-case, most of the time they contain 3-20 strings. And I need a lot of them since I am basically wrapping large parts of the Qt framework to make it more python friendly, so my scenario might be a bit special.
Apart from that, I am also using Unions of course. And yes, I would be fine with also expanding them. There might be few cases where this leads to long lists, but in 99 % of cases it would work very well.

[pawamoy]

OK, thanks for you answers :)