Agreed (though it should still work with tooling like Sphinx and would definitely work in a REPL, notebook, or debugger). That touches on a slightly bigger iss

Agreed (though it should still work with tooling like Sphinx and would definitely work in a REPL, notebook, or debugger). That touches on a slightly bigger issue too. IDEs only approximate the language and usually fail miserably if you, e.g., do anything nontrivial with PEP-263. They'll whine when new language features like async or assignment expressions come out, they have the damnedest time inferring the type of inner functions, and so on. An IDE typically offers support for a (hopefully useful) subset of your favorite language.