-
-
Notifications
You must be signed in to change notification settings - Fork 32
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Suggestion: Add option to expand Literals #73
Comments
I'm not sure to understand. Could you show some code snippets that illustrate your suggestion? |
Let´s say we have this:
With old handler, docs would show every single Literal in the generated "Parameters" box. |
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 = 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? |
A quick search shows me that my project contains almost 600 Literals, so manually docstringing them wouldnt be my favorite. 😄 |
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 Or you could not document them at all but still render them in the docs ( 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. |
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. |
OK, thanks for you answers :) |
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.
The text was updated successfully, but these errors were encountered: