Add additional examples about TypeIs

[mikeshardmind]

This is a followup from discussion on discourse, and specifically this example which was constructed with the help of many going back and forth to determine a situation that could have a parallel in real world code, and which was possibly unsound. To not overly deter users from using this when it is appropriate, counter examples of "tolerably safe" narrowing functions that operate on generic types are included.

[mikeshardmind]

I'm not sure why the typing council decision label was added to this, this is purely an extended example of existing behavior to help better document the sharp edges that already exist on a typing feature and not a specification change, which does not appear to need one.

Quoting: https://github.com/python/typing-council/blob/main/README.md

The Council makes decisions in response to issues opened on this repo. Such decisions include:

• Substantive changes to the specification for the type system
• Recommendations on PEPs that relate to typing

If there's anything I need to do to have this proceed, please let me know.

[JelleZijlstra]

This PR is to the spec, but I'm not sure why this text needs to be in the spec; it doesn't seem to specify any additional behavior. It might be a better fit for the guide on type narrowing that I added recently.

[erictraut]

Reviewing the proposed addition, I don't think this belongs in the typing spec. The typing spec is intended to specify how the type system works and how type checkers must behave. The proposed addition doesn't serve this purpose. It is instead directed at users of TypeIs. It therefore belongs in the typing guide, not the typing spec.

[mikeshardmind]

Hmm. I thought placing it next to the existing example of behavior around TypeIs would make more sense, but I can retool the PR to move it to the guide, thanks for the feedback.

[JelleZijlstra]

This fits better under "Safety and soundness" below, probably as a new subheader.

The example could be made more convincing; I think it's not going to be clear to most readers why it's unsafe.

I think something like this would demonstrate it:

def takes_any_a(a: A[int | str]):
    if possible_problem(a):
        assert_type(a, A[int])  # OK because A[int] is a subtype of A[int | str]
        if isinstance(a, B):
            assert_type(a, B[int])  # A[int] & B -> B[int]
            print(b.j + 1)  # boom
takes_any_a(B(i=1, j="x"))

[JelleZijlstra]

This also fits better as a new subparagraph instead of as part of the header

[JelleZijlstra]

Note this has other tradeoffs, e.g. potentially higher memory usage. For example, range(1000) is a Sequence, turning it into the equivalent tuple takes a lot more memory.