Como especificar o tipo de retorno "anulável" com dicas de tipo

Suponha que eu tenha uma função:

def get_some_date(some_argument: int=None) -> %datetime_or_None%:
    if some_argument is not None and some_argument == 1:
        return datetime.utcnow()
    else:
        return None

Como especifico o tipo de retorno para algo que pode ser None?

Você está procurando Optional.

Como seu tipo de retorno pode ser datetime(como retornado datetime.utcnow()) ou Nonevocê deve usar Optional[datetime]:

from typing import Optional

def get_some_date(some_argument: int=None) -> Optional[datetime]:
    # as defined

A partir da documentação sobre digitação, Optionalé uma abreviação de:

Optional[X]é equivalente a Union[X, None].

onde Union[X, Y]significa um valor do tipo Xou Y.

Se você quiser ser explícito devido a preocupações de que outras pessoas possam tropeçar Optionale não perceber o significado, sempre use Union:

from typing import Union

def get_some_date(some_argument: int=None) -> Union[datetime, None]:

Mas duvido que seja uma boa ideia, Optionalseja um nome indicativo e economize algumas teclas.

_{Como apontado nos comentários de @ Michael0x2a, Union[T, None]é transformado para Union[T, type(None)]que não seja necessário usar typeaqui.}

Visualmente, eles podem diferir, mas programaticamente, em ambos os casos, o resultado é exatamente o mesmo ; Union[datetime.datetime, NoneType]será o tipo armazenado em get_some_date.__annotations__^* :

>>> from typing import get_type_hints
>>> print(get_type_hints(get_some_date))
{'return': typing.Union[datetime.datetime, NoneType],
 'some_argument': typing.Union[int, NoneType]}

^* Use typing.get_type_hintspara pegar o __annotations__atributo dos objetos em vez de acessá-lo diretamente.