Type annotating `Context.open_stream()` (probably with `msgspec.Struct` subtype(s)) :sunglasses:

[goodboy]

After having seen this style in anyio's latest release:

https://github.com/agronholm/anyio/pull/599/files#diff-1fb03ea452beca16c76e364dc7f8ffe3dfcbb20be7e732cc5a552cba32fd771aR104

which it turns out, trio also already supports this :boom: (well via trio_typing), https://github.com/python-trio/trio/blob/348713a7ae73c1afaef79969c90c57e12f4f098b/trio/_channel.py#L93

ANNDDD apparently since it's being proposed more generally for typing functions! https://peps.python.org/pep-0718/

I think doing the same (at least) for our MsgStreams would be super nice (and) as it pertains to eventual plans for static msg typing in #36 and #196 :surfer:!

---

proto API

typed msging API would probably be something like:

# theoretical API exposing `msgspec.Struct` subtype B)
from tractor.msg import Msg


# only this msg is allowed to be sent from `Context.started()`
class StartupMsg(Msg):  # a `msgspec.Struct` subtype
    allowed_startup_attr: str


# only this msg is allowed to be sent from `Context.send()`
class StreamMsg(Msg):  # a `msgspec.Struct` subtype
    key: str
    value: float


@tractor.context[StartupMsg]  # is this useful?
async def stream_ctx_er_sumthin(

    ctx: tractor.Context[StartupMsg],  # which is better (see above)?

) -> None:
    await ctx.started(StartupMsg(allowed_startup_attr='yeye'))

    async with ctx.open_stream[StreamMsg]() as stream:
        await stream.send(StreamMsg(key='yo', value=69))

        # should error immediately here or on rx end?
        await stream.send(dict(key='yo', value=69))

---

research on latest py typing feats

typed_ipc_msgs = [
  'https://github.com/goodboy/tractor/issues/365',
    'https://peps.python.org/pep-0718/',  # subscriptable fns
    #|_ for the future

  # main type-spec-page
  'https://typing.readthedocs.io/en/latest/spec/',

  # relevant py docs
  'https://docs.python.org/3/reference/compound_stmts.html#type-params',
    # |_ def max[T](args: list[T]) -> T:

    'https://docs.python.org/3/library/typing.html#typing.ParamSpec',
    #|_specialized `TypeVar` which are,
    # > used to forward the parameter types of one callable to
    # > another callable – a pattern commonly found in higher order
    # > functions and decorators.
      'https://peps.python.org/pep-0612/',
      #|_ intro pep
        'https://github.com/python/mypy/issues/8645',
        #|_ orig mypy tracking issue
      'https://docs.python.org/3/library/typing.html#typing.ParamSpecKwargs',
      #|_ XXX! for rt introspection, LIKELY WHAT WE NEED! XXX
      'https://typing.readthedocs.io/en/latest/spec/generics.html#paramspec',
      'https://typing.python.org/en/latest/spec/callables.html#signatures-with-paramspecs',
      #|_ type-spec-page docs on the same..

    'https://docs.python.org/3/library/typing.html#typing.Concatenate',
    #|_to annot higher-order-fns, use with `Callable/ParamSpec`

    'https://docs.python.org/3/library/typing.html#typing.Annotated',
    #|_ XXX to store meta-data in annotations!

    # XXX related general callable annotation examples XXX
    'https://docs.python.org/3/library/typing.html#annotating-callable-objects',
    'https://docs.python.org/3/library/typing.html#annotating-generators-and-coroutines',
    'https://docs.python.org/3/library/typing.html#generics',
    #|_legacy mypy-GH ishes on typing callables
      'https://github.com/python/typing/issues/424',
      'https://github.com/python/mypy/issues/3028',
      'https://github.com/python/cpython/pull/92104/files',  # async fns
]