Best Practices: Add note about object/Any

[srittau]

Part of #851

[hauntsaninja]

I'm not sure I'd recommend using from __future__ import annotations for new syntax without at least having a note mentioning that doing so breaks runtime uses of annotations (and e.g. type aliases won't work).

The note doesn't need to be lengthy or scary, e.g. it could just link to https://mypy.readthedocs.io/en/stable/runtime_troubles.html or something, but I do think we should acknowledge sharp edges.

[srittau]

I'm not sure I'd recommend using from future import annotations for new syntax without at least having a note mentioning that doing so breaks runtime uses of annotations (and e.g. type aliases won't work).

I'm not sure I follow. What runtime uses break that work without the future import. The mypy docs link doesn't mention anything either.

Edit: Or even better yet, propose a wording.

[JelleZijlstra]

I personally would not recommend using from __future__ import annotations:

• As Shantanu says, it can break some runtime use cases. See e.g. David Foster's message in https://discuss.python.org/t/finding-edge-cases-for-peps-484-563-and-649-type-annotations/14314 .
• It's still unclear whether the __future__ import will ever become the default, so people using it may have to migrate later to another subtly different version.

[hauntsaninja]

It's not just the edge cases, since we're currently recommending from __future__ import annotations specifically as a way to backport new syntax (not just the usual forward references stuff). So typing.get_type_hints and friends will break.

Suggested wording (based on mypy docs):

Some code may evaluate annotations at runtime, for instance, through use of typing.get_type_hints or eval. If your annotation would raise an error when evaluated (say by using new-style unions on Python 3.9 and older), you may need to be careful. See here for more discussion on sharp edges.

Of course, if we don't want to recommend future annotations at all because of the edge cases and co_annotations stuff, this is moot.

[srittau]

I have removed the future import section for now.

[srittau]

Bumpity bump.