Calling an `ABIReturnSubroutine` instance returns the type `abi.ReturnedValue | Expr`

[jasonpaulos]

Problem

When calling a subroutine decorated with ABIReturnSubroutine, the Python type annotation of the returned value is abi.ReturnedValue | Expr. Take a look at the definition of ABIReturnSubroutine.__call__:

pyteal/pyteal/ast/subroutine.py

Lines 663 to 665 in 4c716b4

	def __call__(
	self, *args: Expr | ScratchVar | abi.BaseType, **kwargs
	) -> abi.ReturnedValue | Expr:

The rational behind this behavior is that if an ABIReturnSubroutine returns a value, calling it will return an abi.ReturnedValue; but if the subroutine does not return a valid (has void return type), then it returns a simple Expr.

This union type is problematic for calling code, since abi.ReturnedValue and Expr behave completely differently. As of right now, calling must must cast the value to one of abi.ReturnedValue or Expr for it to pass type checking.

Solution

At the moment I can't think of a good solution for this. ABIReturnSubroutine instances really do return either abi.ReturnedValue or Expr, and I'm not aware of any tricks we can use in the Python type system to make it aware of this.