# Callable

References:

- <https://typing.python.org/en/latest/spec/callables.html#callable>

Note that `typing.Callable` is deprecated at runtime, in favor of `collections.abc.Callable` (see:
<https://docs.python.org/3/library/typing.html#deprecated-aliases>). However, removal of
`typing.Callable` is not currently planned, and the canonical location of the stub for the symbol in
typeshed is still `typing.pyi`.

## Invalid forms

The `Callable` special form requires _exactly_ two arguments where the first argument is either a
parameter type list, parameter specification, `typing.Concatenate`, or `...` and the second argument
is the return type. Here, we explore various invalid forms.

### Empty

A bare `Callable` without any type arguments:

```py
from typing import Callable, Any
from ty_extensions import static_assert
from ty_extensions._internal import is_equivalent_to

def _(c: Callable):  # error: [missing-type-argument]
    reveal_type(c)  # revealed: (...) -> Unknown

static_assert(is_equivalent_to(Callable, Callable[..., Any]))  # error: [missing-type-argument]
```

### Invalid parameter type argument

When it's not a list:

```py
from typing import Callable

# error: [invalid-type-form] "The first argument to `Callable` must be either a list of types, ParamSpec, Concatenate, or `...`"
def _(c: Callable[int, str]):
    reveal_type(c)  # revealed: (...) -> Unknown
```

Or, when it's a literal type:

```py
# error: [invalid-type-form] "The first argument to `Callable` must be either a list of types, ParamSpec, Concatenate, or `...`"
def _(c: Callable[42, str]):
    reveal_type(c)  # revealed: (...) -> Unknown
```

Or, when one of the parameter type is invalid in the list:

```py
# error: [invalid-type-form] "Int literals are not allowed in this context in a parameter annotation"
# error: [invalid-type-form] "Boolean literals are not allowed in this context in a parameter annotation"
def _(c: Callable[[int, 42, str, False], None]):
    # revealed: (int, Unknown, str, Unknown, /) -> None
    reveal_type(c)
```

Or, when an ellipsis literal is used as a parameter type in the list (note that the valid gradual
form uses `...` as the entire first argument, not inside a list):

```py
# error: [invalid-type-form] "`[...]` is not a valid parameter list for `Callable`: Did you mean `Callable[..., int]`?"
def _(c: Callable[[...], int]):
    reveal_type(c)  # revealed: (...) -> int
```

```py
# error: [invalid-type-form] "`...` is not allowed in this context in a parameter annotation"
def _(c: Callable[[int, ...], int]):
    reveal_type(c)  # revealed: (int, Unknown, /) -> int
```

### Missing return type

Using a parameter list:

```py
from typing import Callable

# error: [invalid-type-form] "Special form `Callable` expected exactly two arguments (parameter types and return type)"
def _(c: Callable[[int, str]]):
    reveal_type(c)  # revealed: (...) -> Unknown
```

Or, an ellipsis:

```py
# error: [invalid-type-form] "Special form `Callable` expected exactly two arguments (parameter types and return type)"
def _(c: Callable[...]):
    reveal_type(c)  # revealed: (...) -> Unknown
```

Or something else that's invalid in a type expression generally:

```py
# fmt: off

def _(c: Callable[  # error: [invalid-type-form] "Special form `Callable` expected exactly two arguments (parameter types and return type)"
            {1, 2}  # error: [invalid-type-form] "The first argument to `Callable` must be either a list of types, ParamSpec, Concatenate, or `...`"
        ]
    ):
    reveal_type(c)  # revealed: (...) -> Unknown
```

### Invalid parameters and return type

```py
from typing import Callable

# fmt: off

def _(c: Callable[
            # error: [invalid-type-form] "Int literals are not allowed in this context in a parameter annotation"
            {1, 2}, 2  # error: [invalid-type-form] "The first argument to `Callable` must be either a list of types, ParamSpec, Concatenate, or `...`"
        ]
    ):
    reveal_type(c)  # revealed: (...) -> Unknown
```

### More than two arguments

We can't reliably infer the callable type if there are more then 2 arguments because we don't know
which argument corresponds to either the parameters or the return type.

```py
from typing import Callable

# error: [invalid-type-form] "Special form `Callable` expected exactly two arguments (parameter types and return type)"
def _(c: Callable[[int], str, str]):
    reveal_type(c)  # revealed: (...) -> Unknown
```

### List as the second argument

```py
from typing import Callable

# fmt: off

def _(c: Callable[
            int,  # error: [invalid-type-form] "The first argument to `Callable` must be either a list of types, ParamSpec, Concatenate, or `...`"
            [str]  # error: [invalid-type-form] "List literals are not allowed in this context in a parameter annotation"
        ]
    ):
    reveal_type(c)  # revealed: (...) -> Unknown
```

### Tuple as the second argument

```py
from typing import Callable

# fmt: off

def _(c: Callable[
            int,  # error: [invalid-type-form] "The first argument to `Callable` must be either a list of types, ParamSpec, Concatenate, or `...`"
            (str, )  # error: [invalid-type-form] "Tuple literals are not allowed in this context in a parameter annotation"
        ]
    ):
    reveal_type(c)  # revealed: (...) -> Unknown
```

### List as both arguments

```py
from typing import Callable

# error: [invalid-type-form] "List literals are not allowed in this context in a parameter annotation"
def _(c: Callable[[int], [str]]):
    reveal_type(c)  # revealed: (int, /) -> Unknown
```

### Three list arguments

```py
from typing import Callable

# fmt: off


def _(c: Callable[  # error: [invalid-type-form] "Special form `Callable` expected exactly two arguments (parameter types and return type)"
            [int],
            [str],  # error: [invalid-type-form] "List literals are not allowed in this context in a parameter annotation"
            [bytes]  # error: [invalid-type-form] "List literals are not allowed in this context in a parameter annotation"
        ]
    ):
    reveal_type(c)  # revealed: (...) -> Unknown
```

## Simple

A simple `Callable` with multiple parameters and a return type:

```py
from typing import Callable

def _(c: Callable[[int, str], int]):
    reveal_type(c)  # revealed: (int, str, /) -> int
```

## Overloaded callable assignability

An overloaded callable should be assignable to a non-overloaded callable type when the overload set
as a whole is compatible with the target callable.

```py
from typing import Callable, overload

@overload
def foo(x: int) -> str: ...
@overload
def foo(x: str) -> str: ...
def foo(x: int | str) -> str:
    return str(x)

def expects(c: Callable[[int | str], str]) -> None:
    pass

expects(foo)
```

```py
from typing import overload

@overload
def foo(x: int) -> str: ...
@overload
def foo(x: str) -> str: ...
def foo(x: int | str) -> str:
    return str(x)

def errors() -> None:
    for x in map(foo, range(1, 10)):
        print(x)
```

```py
from typing import Callable, overload

@overload
def converter(x: int) -> str: ...
@overload
def converter(x: bytes) -> bytes: ...
def converter(x: int | bytes) -> str | bytes:
    if isinstance(x, int):
        return str(x)
    return x

def expects_int_str(c: Callable[[int], str]) -> None:
    pass

expects_int_str(converter)
```

The overload set must cover the full target parameter domain.

```py
from typing import Callable, overload

@overload
def partial_converter(x: int) -> str: ...
@overload
def partial_converter(x: bytes) -> str: ...
def partial_converter(x: int | bytes) -> str:
    return str(x)

def expects_int_or_str(c: Callable[[int | str], str]) -> None:
    pass

# error: [invalid-argument-type]
expects_int_or_str(partial_converter)
```

Even when the parameter domain is covered, return compatibility must still hold.

```py
from typing import Callable, overload

@overload
def wide_return_converter(x: int) -> str: ...
@overload
def wide_return_converter(x: str) -> bytes: ...
def wide_return_converter(x: int | str) -> str | bytes:
    if isinstance(x, int):
        return str(x)
    return x.encode()

def expects_str_return(c: Callable[[int | str], str]) -> None:
    pass

# error: [invalid-argument-type]
expects_str_return(wide_return_converter)
```

## Union

```py
from typing import Callable, Union

def _(
    c: Callable[[Union[int, str]], int] | None,
    d: None | Callable[[Union[int, str]], int],
    e: None | Callable[[Union[int, str]], int] | int,
):
    reveal_type(c)  # revealed: ((int | str, /) -> int) | None
    reveal_type(d)  # revealed: None | ((int | str, /) -> int)
    reveal_type(e)  # revealed: None | ((int | str, /) -> int) | int
```

## Intersection

```py
from typing import Callable, Union
from ty_extensions import Intersection, Not

class Foo: ...

def _(
    c: Intersection[Callable[[Union[int, str]], int], int],
    d: Intersection[int, Callable[[Union[int, str]], int]],
    e: Intersection[int, Callable[[Union[int, str]], int], Foo],
    f: Intersection[Not[Callable[[int, str], Intersection[int, Foo]]]],
):
    reveal_type(c)  # revealed: ((int | str, /) -> int) & int
    reveal_type(d)  # revealed: int & ((int | str, /) -> int)
    reveal_type(e)  # revealed: int & ((int | str, /) -> int) & Foo
    reveal_type(f)  # revealed: ~((int, str, /) -> int & Foo)
```

## Nested

A nested `Callable` as one of the parameter types:

```py
from typing import Callable

def _(c: Callable[[Callable[[int], str]], int]):
    reveal_type(c)  # revealed: ((int, /) -> str, /) -> int
```

And, as the return type:

```py
def _(c: Callable[[int, str], Callable[[int], int]]):
    reveal_type(c)  # revealed: (int, str, /) -> ((int, /) -> int)
```

## Gradual form

The `Callable` special form supports the use of `...` in place of the list of parameter types. This
is a [gradual form] indicating that the type is consistent with any input signature:

```py
from typing import Callable

def gradual_form(c: Callable[..., str]):
    reveal_type(c)  # revealed: (...) -> str
```

## Using `typing.Concatenate`

Using `Concatenate` as the first argument to `Callable`:

```py
from typing_extensions import Callable, Concatenate

def _(c: Callable[Concatenate[int, str, ...], int]):
    reveal_type(c)  # revealed: (int, str, /, *args: Any, **kwargs: Any) -> int
```

Other type expressions can be nested inside `Concatenate`:

```py
def _(c: Callable[Concatenate[int | str, type[str], ...], int]):
    reveal_type(c)  # revealed: (int | str, type[str], /, *args: Any, **kwargs: Any) -> int
```

But providing fewer than 2 arguments to `Concatenate` is an error:

```py
# fmt: off

def _(
    c: Callable[Concatenate[int], int],  # error: [invalid-type-form] "`typing.Concatenate` requires at least 2 arguments when used in a type expression (got 1)"
    d: Callable[Concatenate[(int,)], int],  # error: [invalid-type-form] "`typing.Concatenate` requires at least 2 arguments when used in a type expression (got 1)"
    e: Callable[Concatenate[()], int]  # error: [invalid-type-form] "`typing.Concatenate` requires at least 2 arguments when used in a type expression (got 0)"
):
    reveal_type(c)  # revealed: (...) -> int
    reveal_type(d)  # revealed: (...) -> int
    reveal_type(e)  # revealed: (...) -> int

# fmt: on
```

## Using `typing.ParamSpec`

```toml
[environment]
python-version = "3.12"
```

Using a `ParamSpec` in a `Callable` annotation:

```py
from typing_extensions import Callable

def _[**P1](c: Callable[P1, int]):
    reveal_type(P1.args)  # revealed: P1@_.args
    reveal_type(P1.kwargs)  # revealed: P1@_.kwargs

    reveal_type(c)  # revealed: (**P1@_) -> int
```

And, using the legacy syntax:

```py
from typing_extensions import ParamSpec

P2 = ParamSpec("P2")

def _(c: Callable[P2, int]):
    reveal_type(c)  # revealed: (**P2@_) -> int
```

## Using `typing.Unpack`

Using the unpack operator (`*`):

```py
from typing_extensions import Callable, TypeVarTuple

Ts = TypeVarTuple("Ts")

def unpack_operator(c: Callable[[int, *Ts], int]):
    reveal_type(c)  # revealed: (int, /, *Ts@unpack_operator) -> int
```

And, using the legacy syntax using `Unpack`:

```py
from typing_extensions import Unpack

def unpack_special_form(c: Callable[[int, Unpack[Ts]], int]):
    reveal_type(c)  # revealed: (int, /, *Ts@unpack_special_form) -> int
```

## Member lookup

```py
from typing import Callable

def _(c: Callable[[int], int]):
    reveal_type(c.__init__)  # revealed: bound method object.__init__() -> None
    reveal_type(c.__class__)  # revealed: type
    reveal_type(c.__call__)  # revealed: (int, /) -> int
```

Unlike other type checkers, we do _not_ allow attributes to be accessed that would only be available
on function-like callables:

```py
def f_wrong(c: Callable[[], None]):
    # error: [unresolved-attribute] "Object of type `() -> None` has no attribute `__qualname__`"
    c.__qualname__

    # error: [unresolved-attribute] "Unresolved attribute `__qualname__` on type `() -> None`"
    c.__qualname__ = "my_callable"
```

We do this, because at runtime, calls to `f_wrong` with a non-function callable would raise an
`AttributeError`:

```py
class MyCallable:
    def __call__(self) -> None:
        pass

f_wrong(MyCallable())  # raises `AttributeError` at runtime
```

If users want to read/write to attributes such as `__qualname__`, they need to check the existence
of the attribute first:

```py
def f_okay(c: Callable[[], None]):
    if hasattr(c, "__qualname__"):
        reveal_type(c.__qualname__)  # revealed: object

        # TODO: should be `property`
        # (or complain that we don't know that `type(c)` has the attribute at all!)
        reveal_type(type(c).__qualname__)  # revealed: @Todo(Intersection meta-type)

        # `hasattr` only guarantees that an attribute is readable.
        #
        # error: [invalid-assignment] "Object of type `Literal["my_callable"]` is not assignable to attribute `__qualname__` on type `(() -> None) & <Protocol with members '__qualname__'>`"
        c.__qualname__ = "my_callable"

        # TODO: should we have some way for users to narrow a read-only attribute
        # into a writable attribute...? What would that look like? Something like this?
        if (
            hasattr(type(c), "__qualname__")
            and isinstance(type(c).__qualname__, property)
            and type(c).__qualname__.fset is not None
        ):
            c.__qualname__ = "my_callable"  # error: [invalid-assignment]
```

## From a class

### Subclasses should return themselves, not superclass

```py
from ty_extensions._internal import into_regular_callable

class Base:
    def __init__(self) -> None:
        pass

class A(Base):
    pass

# revealed: () -> A
reveal_type(into_regular_callable(A))
```

## Nested callable relations still reach the leaf mismatch

```py
from typing import Callable

from ty_extensions import static_assert
from ty_extensions._internal import is_assignable_to

static_assert(
    not is_assignable_to(
        Callable[[], Callable[[], int]],
        Callable[[], Callable[[], str]],
    )
)
```

## `typing.Callable` and `collections.abc.Callable` parity

`typing.Callable` is a deprecated alias for `collections.abc.Callable`. Internally we model them as
distinct `SpecialFormType` variants so that we can support usage of the latter in `match`
statements, while disallowing the former, but otherwise they should be interchangeable in type
expressions.

### Bare form

```py
from typing import Any
import typing
import collections.abc

# error: [missing-type-argument]
def _(c1: typing.Callable, c2: collections.abc.Callable):  # error: [missing-type-argument]
    reveal_type(c1)  # revealed: (...) -> Unknown
    reveal_type(c2)  # revealed: (...) -> Unknown
```

### Parameterized form

```py
import typing
import collections.abc

def _(c1: typing.Callable[[int], str], c2: collections.abc.Callable[[int], str]):
    reveal_type(c1)  # revealed: (int, /) -> str
    reveal_type(c2)  # revealed: (int, /) -> str
```

### Equivalence

```py
import typing
import collections.abc
from ty_extensions import static_assert
from ty_extensions._internal import is_equivalent_to

static_assert(is_equivalent_to(typing.Callable[[int], str], collections.abc.Callable[[int], str]))
# error: [missing-type-argument]
static_assert(is_equivalent_to(typing.Callable, collections.abc.Callable))  # error: [missing-type-argument]
```

### Inside `type[...]`

`type[Callable[...]]` is not a valid type expression (the argument to `type[...]` must be a class
object), but both modules' `Callable` should produce the same diagnostic and resolved type.

```py
import typing
import collections.abc

def _(
    # error: [invalid-type-form] "The argument to `type[]` must be a class object type"
    c1: type[typing.Callable[[int], str]],
    # error: [invalid-type-form] "The argument to `type[]` must be a class object type"
    c2: type[collections.abc.Callable[[int], str]],
):
    reveal_type(c1)  # revealed: type[Unknown]
    reveal_type(c2)  # revealed: type[Unknown]
```

[gradual form]: https://typing.python.org/en/latest/spec/glossary.html#term-gradual-form
