Add opt-in fuller typing for callables accepting (func, *args, ...)

[gschaffner]

this follows up discussion in #491. this uses trio_typing.plugin to add opt-in fuller typing to callables accepting (func, *args, unrelated_kwarg0, ...). see versionhistory.rst for more detailed info.

all of the errors that Mypy currently produces when checking AnyIO with this PR are due to either #510 or python/mypy#14337, I believe.

even with this Mypy bug, this PR is quite useful for typed AnyIO-dependent works as-is, but the Mypy bug does limit its usefulness to (for the most part) only non-generic functions.

if there is interest in this work, I'd be happy to add some typing tests to this PR.

[gschaffner]

the pyright type completion check is failing because it sees mypy_extensions in some public signatures but does not understand that the intent is for pyright to instead use the half of the union that doesn't use mypy_extensions.

one way to fix this is by passing the --ignoreexternal flag during pyright's type completion check. this can have other effects, however. unfortunately it does not look like pyright currently supports setting --ignoreexternal with granularity to ignore only mypy_extensions.

[mattmess1221]

I don't like how this is specific to mypy. Using TypeVarTuple from PEP 646 would be a better alternative. Support for it in mypy requires additional flags, but it appears to be fully implemented in pyright and pyre.

A basic implementation would be like this.

from typing import TypeVar, Awaitable, Callable, Any
from typing_extensions import TypeVarTuple, Unpack

T_Ret = TypeVar("T_Ret")
T_Args = TypeVarTuple("T_Args")


def start(
    func: Callable[[Unpack[T_Args]], Awaitable[T_Ret]],
    *args: Unpack[T_Args],
    name: Any = None,
) -> Awaitable[T_Ret]:
    pass

[gschaffner]

yeah, i actually wrote a proper PEP 646 patch a few months ago that would supplant this Mypy-only mess. i got busy with other work and never got around to posting it though. i'll try to get it submitted this weekend :)

[agronholm]

Closing in favor of #652.

[gschaffner]

technically #652 didn't supercede this, because the trio_typing Mypy plugin plus mypy_extensions.NamedArg (as used by this PR) can provide some further typing of start and start_task's *args and task_status_value, which some type checkers' PEP 646 implementations currently cannot provide. That said, I completely agree with closing this—nonstandardized, Mypy-specific stuff doesn't sound good.

From my never-posted attempt at using PEP 646 for start, dated June 28, we'd want something like

class Startable(Protocol[Unpack[PosArgsT], T_co, T_Retval]):
    def __call__(
        self, *args: Unpack[PosArgsT], task_status: TaskStatus[T_co]
    ) -> Awaitable[T_Retval]:
        ...

async def start(
    self,
    func: abc.Startable[Unpack[PosArgsT], T_co, Any],
    *args: Unpack[PosArgsT],
    name: object = None,
) -> T_co:
    ...

def start_task(
    self,
    func: Startable[Unpack[PosArgsT], T_co, T_Retval],
    *args: Unpack[PosArgsT],
    name: object = None,
) -> tuple[Future[T_Retval], T_co]:
    ...

For Mypy, at least, this doesn't work currently and the tracking issue is python/mypy#16522.