Unknown vs Any in 3rd party library types

[Molkree]

I am using watchfiles library and strict checking in Pylance/Pyright. When importing awatch function I get a warning that its type is partially unknown:

from typing import reveal_type

from watchfiles import awatch

reveal_type(awatch)

Unknown here comes from stop_event in the signature, when navigating to the library code it looks like this:

async def awatch(  # noqa C901
    *paths: Union[Path, str],
    watch_filter: Optional[Callable[[Change, str], bool]] = DefaultFilter(),
    debounce: int = 1_600,
    step: int = 50,
    stop_event: Optional['AnyEvent'] = None,
    rust_timeout: Optional[int] = None,
    yield_on_timeout: bool = False,
    debug: bool = False,
    raise_interrupt: Optional[bool] = None,
    force_polling: Optional[bool] = None,
    poll_delay_ms: int = 300,
    recursive: bool = True,
) -> AsyncGenerator[Set[FileChange], None]:

And AnyEvent in turn looks like this:

if TYPE_CHECKING:
    import asyncio

    import trio

    AnyEvent = Union[anyio.Event, asyncio.Event, trio.Event]

The thing is, I don't have trio installed in my environment (it's not required by watchfiles) so trio.Event resolves as Unknown.

My question as a simple user is, why is it Unknown and not Any? For example, mypy resolves the type to Any:

Revealed type is "def (*paths: Union[pathlib.Path, builtins.str], *, watch_filter: Union[def (watchfiles.main.Change, builtins.str) -> builtins.bool, None] =, debounce: builtins.int =, step: builtins.int =, stop_event: Union[anyio._core._synchronization.Event, asyncio.locks.Event, Any, None] =, rust_timeout: Union[builtins.int, None] =, yield_on_timeout: builtins.bool =, debug: builtins.bool =, raise_interrupt: Union[builtins.bool, None] =, force_polling: Union[builtins.bool, None] =, poll_delay_ms: builtins.int =, recursive: builtins.bool =) -> typing.AsyncGenerator[builtins.set[Tuple[watchfiles.main.Change, builtins.str]], None]"

Another related question is why is it stop_event: Event | Unknown | None = None and not stop_event: anyio.Event | asyncio.Event | Unknown | None = None?

This is how the signature looks when trio is installed:

Do you think this should be fixed on watchfiles side and if so what would be the best fix? I see that regular sync watch is typed with AbstractEvent protocol, is it the way to go? 🤔

    class AbstractEvent(Protocol):
        def is_set(self) -> bool:
            ...

[erictraut]

My question as a simple user is, why is it Unknown and not Any?

The Unknown type is an implicit Any. Pyright uses Unknown any place where a type is unspecified, as in this example. Mypy doesn't distinguish between implicit and explicit Any. For more details about the Unknown type, refer to this documentation.

Another related question is why is it stop_event: Event | Unknown | None = None...?

This is related to this issue which will be addressed in the next release of pyright.

Do you think this should be fixed on watchfiles side and if so what would be the best fix?

I can think of a few options:

1. You could install trio into your environment for purposes of type checking.
2. You could create a dummy type stub in your project that provides an explicit Any for the trio module. To do so, create a file called ./typings/trio/__init__.pyi in your project and add the line def __getattr__(name: str) -> Any: ....
3. The watchfiles maintainers could define a global symbol called USE_TRIO or something like that. They could set it to True or False based on whether the import from trio is present. If it's False, they could define a dummy type for trio events. Since the USE_TRIO variable would be dynamically assigned, you would need to specify its (static) value in pyright using the defineConstant configuration option.

[Molkree]

Thanks for the detailed and quick answer as usual, Eric!