Add Python type annotation transformation options

[jbms]

No description provided.

[jbms]

I'm not sure what makes sense as far as defaults for all of these options.

[2bndy5]

Now that we're using sphinx-jinja, we could probably throw in some docs about domain-specific parameter object types from

sphinx-immaterial/sphinx_immaterial/apidoc_formatting.py

Line 231 in 7cb4682

DEFAULT_OBJECT_DESCRIPTION_OPTIONS: List[Tuple[str, dict]] = [

[2bndy5]

I'm not sure what makes sense as far as defaults for all of these options.

The booleans make sense. In a perfect world, I think that python_type_aliases would use the actual imported symbol, but using strings makes sense implementation wise.

I can't think of any objections to any of this. Let me give it a spin on my CirPy_nRF24 project...

[2bndy5]

I forgot that I have avoided using typing in my CirPy_nRF24 lib because CircuitPython doesn't have the a ported variant of CPython's typing module (due to limited memory resources). The good news is that nothing is broken.

[jbms]

What do you think about the concise_literals change? Since that is not valid Python syntax, should we still apply that transformation by default?

[2bndy5]

I actually like that change. I think there was a recent PEP that now prefers the | syntax. Primary reason that I didn't take to type hinting in python is because I tend to abuse the dynamic typing of python and the rendered type hints in docs tend to be "wordy" (which makes me think it would only add confusion to the reader's experience).

I guess some square brackets would help differentiate from other data in the signature (like default values). Since python uses the or instead of |, we're not really at risk of ambitiousness between concise literals vs default values

[jbms]

An example where concise literals are ambiguous is the following:

class Foo:
  pass

def foo(t: Literal[Foo]):
  pass

foo(Foo)

With the concise literals transform, this would be documented as:

foo(t: Foo)

which is incorrect.

[mhostetter]

Is there a case when a Literal with only one option is used? Wouldn't the argument be superfluous at that point? I suspect this case wouldn't come up much in practice.

Really like these additions, by the way!! 🔥

[jbms]

Probably the 1-argument Literal would only be used as part of a larger type, e.g. Union[int, Literal[False]] or something like that.

There is still an ambiguity:

class Foo: pass
class Bar: pass

def foo(t: Literal[Foo, Bar]): pass

Here foo would be incorrectly documented as:

foo(t: Foo | Bar)

[jbms]

I added an additional restriction to only use the concise syntax for constants. That avoids the ambiguity.