Advising returning X | Any in documentation

[Gobot1234]

In the typing docs https://typing.readthedocs.io/en/latest/source/stubs.html#types it states:

"Avoid union return types, since they require isinstance() checks. Use Any or X | Any if necessary."

I really don't think this is a good advise. In cases like this I'm inclined to use overloads, handle each case separately or separate functionality into separate methods/functions. I'm interested as to whether or not you think this should be changed?

[JelleZijlstra]

This advise mostly came out of typeshed where "separate functionality into separate methods" isn't an option (we can't change the stdlib). And overloads aren't always powerful enough either.

It would be useful though to recommend refactoring your code to avoid a Union return type if possible, or to use overloads where that makes sense.

[srittau]

See #851 for the issue about creating a best practices document that is supposed to merge the existing best practices sections.