Feature: Implement Overloaded[*Callables]

[AliiiBenn]

Description

Implement the Overloaded[*Callables] type as specified in PEP 827.

From the PEP:

Overloaded[*Callables] - An overloaded function type, with the underlying types in order.

This allows representing overloaded functions where multiple callable signatures are provided.

Implementation Notes

Current State

The Overloaded class is already defined in typing.py:

class Overloaded[*Callables]:
    pass

However, there is no evaluator registered for it.

Approach

The evaluator would need to:

1. Take variadic callable types as arguments
2. Create a runtime object that represents an overloaded function
3. Return a type that indicates multiple call signatures

@type_eval.register_evaluator(Overloaded)
def _eval_Overloaded(*callables, ctx):
    """Evaluate an Overloaded function type.
    
    Args:
        *callables: Variable number of Callable types
        
    Returns:
        A type representing an overloaded function
    """
    evaluated = [_eval_types(c, ctx) for c in callables]
    
    # Create an overload marker type
    # This could use typing.overload at runtime
    return _OverloadedType(tuple(evaluated))

Runtime Considerations

Python's typing module has @typing.overload decorator, but it's designed for function definitions, not as a type expression. We may need to create a custom type to represent this.

Use Cases

# Example from PEP context
type ProcessFunc = Overloaded[
    Callable[[int], str],
    Callable[[float], int],
]

This would indicate a function that can either:

• Take an int and return a str
• Take a float and return an int

Test Cases

• Basic Overloaded with two Callable types
• Overloaded with more than two callables
• Using with Param types for detailed signatures

Status

• Analyze existing Overloaded implementation
• Implement evaluator in _eval_operators.py
• Add tests
• Update documentation

---

Related PEP 827 Section: Overloaded function types (lines 752-753)