Add timeout to publisher_coverage.py

[MaxDall]

This adds a new timeout wrapper to publisher coverage enabling Fundus to use Sitemaps for coverage as well.

[dobbersc]

I don't think the overload type hints work as intended. Example:

def test(a: int) -> int:
    return a + 1
    
reveal_type(timeout(test, time=20))  # Revealed type is "def (a: builtins.int) -> builtins.int"
reveal_type(timeout(test, time=20, silent=True))  # Revealed type is "def (a: builtins.int) -> builtins.int"
reveal_type(timeout(test, time=20, silent=False))  # Revealed type is "def (a: builtins.int) -> builtins.int"

I would expect the second variant to yield Optional[int] as return type.

Suggested change

	@overload
	def timeout(func: Callable[P, T], time: int, silent: bool = False) -> Callable[P, T]:
	...
	@overload
	def timeout(func: Callable[P, T], time: int, silent: bool = True) -> Callable[P, Optional[T]]:
	...
	def timeout(func: Callable[P, T], time: int, silent: bool = False) -> Callable[P, Optional[T]]:
	@overload
	def timeout(func: Callable[P, T], time: int, silent: Literal[False] = ...) -> Callable[P, T]:
	...
	@overload
	def timeout(func: Callable[P, T], time: int, silent: Literal[True]) -> Callable[P, Optional[T]]:
	...
	def timeout(func: Callable[P, T], time: int, silent: bool = False) -> Callable[P, Optional[T]]:

The overloaded types of silent directly match the literal type of the parameter while the ellipsis signifies the optional presence of the parameter. (This is also explained here in the mypy documentation.)

Now we get:

main.py:52: note: Revealed type is "def (a: builtins.int) -> builtins.int"
main.py:53: note: Revealed type is "def (a: builtins.int) -> Union[builtins.int, None]"
main.py:54: note: Revealed type is "def (a: builtins.int) -> builtins.int"

[MaxDall]

Really nice!!

[MaxDall]

But why the Literal? Shouldn't silent: bool = True/False be correct? According to the documentation? What am I missing here because it obviously isn't 😅

[dobbersc]

In my opinion, the mypy documentation does not touch on this (or I missed it). As I understand it, mypy only checks the type itself and the absence or presence:

The default values of a function’s arguments don’t affect its signature – only the absence or presence of a default value does.

So to tell mypy that we return Callable[P, T] for slient=False we need to restrict the type itself to only False via Literal[False], as bool would still allow for both values True and False. When using silent: bool = True/False mypy would not accept the variant where the caller does not provide a silent parameter, and the default is used. This case is covered by the ellipsis, which is then annotated with Literal[True] since the default value is True.

Example with ellipsis:

# Applies when "flag" is omitted or set to True.
@overload
def func(a: int, flag: Literal[True] = ...) -> int: ...


# Applies when "flag" is set to False.
@overload
def func(a: int, flag: Literal[False]) -> str: ...


def func(a: int, flag: bool = True) -> Union[int, str]:
    return a if flag else str(a)

Example without the ellipsis that is equivalent to the previous example:

# Applies when "flag" is omitted.
@overload
def func(a: int) -> int: ...

# Applies when "flag" is set to True.
@overload
def func(a: int, flag: Literal[True]) -> int: ...

# Applies when "flag" set to False.
@overload
def func(a: int, flag: Literal[False]) -> str: ...

def func(a: int, flag: bool = True) -> Union[int, str]:
    return a if flag else str(a)

But is is also just speculation. There is also an issue about this overloads behavior here.

[MaxDall]

Thank you for the detailed explanation 👍