Why is typeshed information not integrated into the official python docs?

[topherbuckley]

I was just introduced to typeshed, and from a brief look, it looks like it is to be used by other tools like PyCharm, mypy, etc, but I'm not seeing anything compiled to a general reference like the online python docs. Is this not a thing; a general reference for types on built-ins? I feel like the info in typeshed should somehow be merged/integrated with the docs. It feels off that there is documentation about type hints not in the official docs.

More info on this SO Question

[srittau]

There isn't a definitive answer for this, but there are a few factors:

• typeshed is incomplete, not all stdlib definitions are typed.
• typeshed isn't part of Python's core development. Only one of the active maintainers is a Python Core Developer (and that is a rather recent development).
• typeshed annotations aren't really meant as documentation, they are a technical description meant for consumption by type checkers. Therefore, sometimes type annotation can be hard to understand. The thoughts on this are changing a bit and there have been some thoughts to possibly include more information for human readers, but there is nothing concrete so far.

[topherbuckley]

@srittau yeah, I was a bit surprised to see that the typeshed stubs and python sphinx files all looks to be manually assembled (correct me if I'm wrong) rather than everything being pulled from some central place. I agree that adding a 3rd place of development wouldn't be ideal, so I was trying to find a way to automate the injection of the typeshed type hints into the python documentation either via the sphinx build system or some awk|sed|python text manipulation. Then the final versions (pdf/html/epub/etc) from sphinx could be built with github actions or the like and simply be made from existing sources rather than maintaining a separate one.

@AlexWaygood you see any easy way to do what I mention above via sphinx (text injection) or will this require some awk magic?

[Gobot1234]

To inject the type hints into python code you might be able to use https://github.com/google/pytype/tree/main/pytype/tools/merge_pyi

[AlexWaygood]

@AlexWaygood you see any easy way to do what I mention above via sphinx (text injection) or will this require some awk magic?

No point tagging me, I don't know anything about sphinx :) I just tagged a friendly sphinx expert who might be able to help, if he has the time!

[topherbuckley]

@Gobot1234 thanks for the hint. I'll check it out.

@AlexWaygood, sorry just a slip of the autocomplete. I intended to tag @AA-Turner. Understood on that. Happy to receive help, but happy to tinker away until then when time is available.

[adam-grant-hendry]

This is perhaps also related to my question.