fix(mypy): properly describe link between parameter and return types

This gives mypy all information that it needs to determine what the
return type of a function call is *iff* it knows the argument's type.

As a result it can now stop complaining about passing None to str.join()
in exc.py.

git/compat.py

@@ -18,7 +18,16 @@
 
 # typing --------------------------------------------------------------------
 
-from typing import IO, Any, AnyStr, Dict, Optional, Type, Union
+from typing import (
+    Any,
+    AnyStr,
+    Dict,
+    IO,
+    Optional,
+    Type,
+    Union,
+    overload,
+)
 from git.types import TBD
 
 # ---------------------------------------------------------------------------
@@ -30,6 +39,12 @@
 defenc = sys.getfilesystemencoding()
 
 
+@overload
+def safe_decode(s: None) -> None: ...
+
+@overload
+def safe_decode(s: Union[IO[str], AnyStr]) -> str: ...
+
 def safe_decode(s: Union[IO[str], AnyStr, None]) -> Optional[str]:
     """Safely decodes a binary string to unicode"""
     if isinstance(s, str):
@@ -42,6 +57,12 @@ def safe_decode(s: Union[IO[str], AnyStr, None]) -> Optional[str]:
         raise TypeError('Expected bytes or text, but got %r' % (s,))
 
 
+@overload
+def safe_encode(s: None) -> None: ...
+
+@overload
+def safe_encode(s: AnyStr) -> bytes: ...
+
 def safe_encode(s: Optional[AnyStr]) -> Optional[bytes]:
     """Safely encodes a binary string to unicode"""
     if isinstance(s, str):
@@ -54,6 +75,12 @@ def safe_encode(s: Optional[AnyStr]) -> Optional[bytes]:
         raise TypeError('Expected bytes or text, but got %r' % (s,))
 
 
+@overload
+def win_encode(s: None) -> None: ...
+
+@overload
+def win_encode(s: AnyStr) -> bytes: ...
+
 def win_encode(s: Optional[AnyStr]) -> Optional[bytes]:
     """Encode unicodes for process arguments on Windows."""
     if isinstance(s, str):
@@ -65,7 +92,6 @@ def win_encode(s: Optional[AnyStr]) -> Optional[bytes]:
     return None
 
 
-
 def with_metaclass(meta: Type[Any], *bases: Any) -> 'metaclass': # type: ignore ## mypy cannot understand dynamic class creation
     """copied from https://github.com/Byron/bcore/blob/master/src/python/butility/future.py#L15"""