[Feature Request] New `beartype.math` API for performing type hint arithmetic

Discussed in https://github.com/beartype/beartype/discussions/132

<div type='discussions-op-text'>

^{Originally posted by tlambert03 May 31, 2022} First, thanks for this amazing library. The scope and detail are beary impressive. 🐻

Apologies if I’ve missed an obvious answer (or previous discussion) of this question: I’ve been digging through the readme and source code for a couple days but still haven’t hit on it, and I’m not sure if this is just fundamentally out of the primary goal here of isinstance(some_object, some_typehint).

I’m looking for something that would tell me whether type hint B is “compatible” with type hint A (something akin to pytypes is_subtype function):

from typing import Sequence, List, Union, Optional, Any

def is_subtype(hintA, hintB) -> bool:
    ...  # ?

assert is_subtype(list, list) is True
assert is_subtype(list, Sequence) is True
assert is_subtype(Sequence, list) is False

assert is_subtype(List[int], Sequence[Any]) is True
assert is_subtype(List[int], Sequence[int]) is True
assert is_subtype(List[int], Sequence[str]) is False

assert is_subtype(list, Union[list, str]) is True
assert is_subtype(Union[int, str], Union[int, str, list]) is True
assert is_subtype(Union[list, str], list) is False
assert is_subtype(list, Union[int, str]) is False
assert is_subtype(Union[int, tuple], Union[int, str, list]) is False

assert is_subtype(Optional[int], int) is False
assert is_subtype(int, Optional[int]) is True

is this something that could be achieved with beartype? digging through the source, i see lots of stuff that seems very useful towards this goal, but not sure I see anything in the public API (since we’re not really trying to determine whether some object is an instance of a hint).

my goal here would be to detect if an API breakage has occurred between two versions:

# version 1
def func() -> list:
   ...

# version 2
def func() -> Sequence:  # potential API breakage
   ...

… and this seems like something you’d have an opinion on 😃 thanks for your work!

</div>

[tlambert03]

you’re too generous @leycec 😂 it was your pattern too! it was a pleasure working with you, thanks for the help!

[tlambert03]

awesome, thanks as always! Didn’t see this before I started on #136, but will have a look at the diff and incorporate changes this weekend. The pattern seems to be working nicely! 👍