How to define a recursive Iterable type? - type-hinting

Question

I am trying to define a recursive Iterable type Iterable_of_TOIs:
# from __future__ import annotations
from typing import overload, Optional, Iterable, Union
class ToI:
"""
ToI = Token or Iterable of ToIs
"""
Iterable_of_ToIs = Iterable[Union[ToI, 'Iterable_of_ToIs']]
#overload
def __init__(self, *, token: str) -> None:
...
#overload
def __init__(self, *, iterable: Iterable_of_ToIs) -> None:
...
# actual implementation
def __init__(
self,
token: Optional[str] = None,
iterable: Optional[Iterable_of_ToIs] = None
) -> None:
self.token: Optional[str] = token
self.iterable: Optional[Iterable_of_ToIs] = iterable
But mypy complains
with error: Name 'Iterable_of_ToIs' is not defined or
with error: Cannot resolve name "Iterable_of_ToIs" (possible cyclic definition)
if I move the definition of Iterable_of_ToIs out of the class scope.
What am I doing wrong?

Answer 1

Apparently, I am doing wrong not that much.
Regarding error: Name 'Iterable_of_ToIs' is not defined:
in the section Motivation of PEP 613 (Status Accepted) I found:
Type aliases are declared as top level variable assignments.
Yikes! Couldn't find this rule for Python 3.9 or prior in any other doc, especially not in PEP 484.
But anyway... it explains the error. So, ok, let's move the line to the top level.
Regarding error: Cannot resolve name "Iterable_of_ToIs" (possible cyclic definition):
seems to be not yet supported: https://github.com/python/mypy/issues/731