Proposal: Add coerced type narrowing similar to 'cast'

[NoamNol]

My suggestion is to add a way to coerce type narrowing without any runtime change,
by adding new type_assert and/or ensure_type.

def function(arg: Any):
    type_assert isinstance(arg, int)
    reveal_type(arg)  # Revealed type: "builtins.int"

def function(arg: Any):
    ensure_type(arg, int)
    reveal_type(arg)  # Revealed type: "builtins.int"

These functions do nothing at runtime! they only help with the types.

Why not cast(int, arg)?

1. cast completely replaces the type and we need to write a full new type.
   With type narrowing it's only necessary to limit the options of the existing type.

   def function(arg: Union[int, str, list]):
       arg = cast(Union[str, list], arg)
       reveal_type(arg)  # Revealed type: "str | list"

   def function(arg: Union[int, str, list]):
       type_assert not isinstance(arg, int)  # only need to remove 'int'
       reveal_type(arg)  # Revealed type: "str | list"

2. cast is more dangerous because we ignore the previous type. with narrowing we just limit the options of the previous type.

   def function(arg: Union[int, str, list]):
       arg1 = cast(dict, arg)
       reveal_type(arg1)  # Revealed type: "dict"

   def function(arg: Union[int, str, list]):
       type_assert not isinstance(arg, dict)  # Error: Subclass of "int" and "dict[Any, Any]" cannot exist

   def function(arg: Union[int, str, list]):
       type_assert not isinstance(arg, int)
       type_assert not isinstance(arg, str)
       type_assert not isinstance(arg, list)
       reveal_type(arg)  # Error: Statement is unreachable

3. cast can't do Intersection (yet). explained below.

Why type_assert and not a normal assert?

1. assert makes it slower at runtime, and sometimes we care
2. assert can break things when improving types of an old code base

The downsides:

1. Without assert or if-else conditions at runtime, the coerced narrowing ignores the real type and is dangerous, almost like cast.

With Intersection type

Until we have Intersection type, this kind of things are problematic:

class Animal:
    def say_my_name(self) -> None:
        print("My name is Animal")

@runtime_checkable
class CanFlyProtocol(Protocol):
    def fly(self) -> None: ...

class Bird(Animal, CanFlyProtocol):
    def fly(self) -> None:
        print("Fly")

def let_it_fly(animal: Animal):  # we can't restrict the argument type to be Animal AND CanFlyProtocol
    animal.say_my_name()
    animal.fly()  # Error: "Animal" has no attribute "fly"

Even cast can't help us, but we can narrow the type!

def let_it_fly(animal: Animal):
    assert isinstance(animal, CanFlyProtocol)
    animal.say_my_name()
    animal.fly()
    reveal_type(animal)  # Revealed type: "<subclass of "Animal" and "CanFlyProtocol">"

Type checkers can understand Intersection when we narrow the type, great!

But what if we don't want to change runtime behavior? for this we can
replace assert with the suggested type_assert or ensure_type!

def let_it_fly(animal: Animal):
    type_assert isinstance(animal, CanFlyProtocol)
    animal.say_my_name()
    animal.fly()
    reveal_type(animal)  # Revealed type: "<subclass of "Animal" and "CanFlyProtocol">"

A side note: with type_assert we probably can stop adding @runtime_checkable to Protocols, if we only added it for this kind of type-hint only issues that assert isinstance(animal, CanFlyProtocol) solved.
Performing isinstance with Protocol is very slow so this benefit is not small.

ensure_type with Not

See:

def function(arg: Union[int, str, list]):
    type_assert not isinstance(arg, int)
    reveal_type(arg)  # Revealed type: "str | list"

How to do not isinstance with ensure_type? we have two options:

1. Add a similar ensure_not_type

   def function(arg: Union[int, str, list]):
       ensure_not_type(arg, int)
       reveal_type(arg)  # Revealed type: "str | list"

2. Wait for the Not[] type

   def function(arg: Union[int, str, list]):
       ensure_type(arg, Not[int])
       reveal_type(arg)  # Revealed type: "str | list"

[NoamNol]

I found we already have a typing.assert_type that does something else, so the suggested name type_assert will confuse people.

We can stay with the ensure_type option or combine the two options:

ensure_type isinstance(animal, CanFlyProtocol)