`typing.Literal` doesn't support float

[lagru]

As pointed out in #44 (comment), Python's typing.Literal doesn't support floats. While this is technically something that should flagged by type checkers and not by docstub, we should still help deal with this.

Cases like {1, -1, 2, -2, inf, -inf, ‘fro’, ‘nuc’} in numpy.linalg.matrix_norm seem sensible and there might be other cases, that use nan or 0.0. So their should be a way to keep using floats and possible other types in the docstring, but arrive at a valid type for stubs.

An idea from #43 (comment): something is both annotated inline and in a docstring, docstub currently uses the annotation in the docstring. However, we might want to reverse that. That way one could keep using {inf, -inf, ...} in the docstring but type it inline as float | Literal[...].

cc @OriolAbril

[OriolAbril]

I like being able to extend or make more concise the type hints manually for specific parameters and then have docstub generate type hints from docstrings for all parameters but those few where we already wrote type hints manually.

Another case where doing that would be great are dictionaries where only a set of keys are valid. I have used that for example with dicts whose values are kwargs and whose keys are strings that indicate where to forward those kwargs to. The valid keys are explained in detail in the docstring body, along with a cross reference to where their kwargs are forwarded to, but their docstring doesn't use literal (natural language or otherwise) as type info for the dictionaty keys. To me, adding that in the docstring type would make it unnecessarily long and hard to parse without any real added value. On the other hand, type checkers being able to flag invalid keys would be a very welcome check.

[OriolAbril]

Regarding the inf/nan special case specifically, if it is possible to manually set the correct type hint along with the current "literal with float" docstring I would not add any extra logic to docstub to parse it automatically.

[OriolAbril]

@lagru I have started using docstub in https://github.com/arviz-devs/arviz-base (small, new but no type hints and very detailed docstrings instead).

I am seeing that I would like to overwrite the docstring generated type hint in some cases. Mostly in parameters where the structure/contents of the input is much more important than the type (which is often combined with multiple types being valid). Having a detailed and accurate type description on the docstring would be super long and not very useful because you still need to read the description to know if an input will be valid, so I keep the type info somewhat generic. Having a more detailed type hint won't catch all invalid inputs but can help a bit.

Is it ok if I try and send a PR on this? Have you done some work around this already? Should I open an issue specifically on this?

[lagru]

I am seeing that I would like to overwrite the docstring generated type hint in some cases.

That's totally the right direction I think. The current default makes it harder to handle edge cases that docstub can't or can't yet easily express. I don't think I've done work on that yet but might have mentioned it already in some issues. And of course, I'd a appreciate a PR. :D

I had a quick look and the following places should be good to get started:

docstub/src/docstub/_stubs.py

Lines 585 to 588 in f11cc84

	reporter.message(
	short="Replacing existing inline return annotation",
	details=details,
	)

docstub/src/docstub/_stubs.py

Lines 783 to 785 in f11cc84

	reporter.message(
	short="Replacing existing inline annotation",
	details=details,

docstub/tests/test_stubs.py

Line 317 in f11cc84

def test_overwriting_typed_return(self, capsys):

[lagru]

Ah, found it: #43 (comment). It's linked in the issue description too.