Overload hash generation functions to make return types more specific (…

…#2047)

Before this change, the return type for these functions was always
`bytes| str`. However, the type can be narrowed based on the value
passed to `raw_output`.

This change adds overload annotations for the two allowable values to
allow type checkers to narrow the type and correctly infer the exact
return type.

Resolves #2046

Co-authored-by: Flavio Curella <[email protected]>

faker/providers/misc/__init__.py

@@ -60,6 +60,14 @@ def binary(self, length: int = (1 * 1024 * 1024)) -> bytes:
         # Generator is unseeded anyway, just use urandom
         return os.urandom(length)
 
+    @overload
+    def md5(self, raw_output: Literal[True]) -> bytes:
+        ...
+
+    @overload
+    def md5(self, raw_output: Literal[False]) -> str:
+        ...
+
     def md5(self, raw_output: bool = False) -> Union[bytes, str]:
         """Generate a random MD5 hash.
 
@@ -74,6 +82,14 @@ def md5(self, raw_output: bool = False) -> Union[bytes, str]:
             return res.digest()
         return res.hexdigest()
 
+    @overload
+    def sha1(self, raw_output: Literal[True]) -> bytes:
+        ...
+
+    @overload
+    def sha1(self, raw_output: Literal[False]) -> str:
+        ...
+
     def sha1(self, raw_output: bool = False) -> Union[bytes, str]:
         """Generate a random SHA-1 hash.
 
@@ -88,6 +104,14 @@ def sha1(self, raw_output: bool = False) -> Union[bytes, str]:
             return res.digest()
         return res.hexdigest()
 
+    @overload
+    def sha256(self, raw_output: Literal[True]) -> bytes:
+        ...
+
+    @overload
+    def sha256(self, raw_output: Literal[False]) -> str:
+        ...
+
     def sha256(self, raw_output: bool = False) -> Union[bytes, str]:
         """Generate a random SHA-256 hash.
 

faker/proxy.pyi

@@ -2202,7 +2202,20 @@ class Faker:
         """
         ...
 
-    def md5(self, raw_output: bool = ...) -> Union[bytes, str]:
+    @overload
+    def md5(self, raw_output: Literal[True]) -> bytes:
+        """
+        Generate a random MD5 hash.
+
+        If ``raw_output`` is ``False`` (default), a hexadecimal string representation of the MD5 hash
+        will be returned. If ``True``, a ``bytes`` object representation will be returned instead.
+
+        :sample: raw_output=False
+        :sample: raw_output=True
+        """
+        ...
+    @overload
+    def md5(self, raw_output: Literal[False]) -> str:
         """
         Generate a random MD5 hash.
 
@@ -2263,7 +2276,8 @@ class Faker:
         """
         ...
 
-    def sha1(self, raw_output: bool = ...) -> Union[bytes, str]:
+    @overload
+    def sha1(self, raw_output: Literal[True]) -> bytes:
         """
         Generate a random SHA-1 hash.
 
@@ -2275,7 +2289,33 @@ class Faker:
         """
         ...
 
-    def sha256(self, raw_output: bool = ...) -> Union[bytes, str]:
+    @overload
+    def sha1(self, raw_output: Literal[False]) -> str:
+        """
+        Generate a random SHA-1 hash.
+
+        If ``raw_output`` is ``False`` (default), a hexadecimal string representation of the SHA-1 hash
+        will be returned. If ``True``, a ``bytes`` object representation will be returned instead.
+
+        :sample: raw_output=False
+        :sample: raw_output=True
+        """
+        ...
+
+    @overload
+    def sha256(self, raw_output: Literal[True]) -> bytes:
+        """
+        Generate a random SHA-256 hash.
+
+        If ``raw_output`` is ``False`` (default), a hexadecimal string representation of the SHA-256 hash
+        will be returned. If ``True``, a ``bytes`` object representation will be returned instead.
+
+        :sample: raw_output=False
+        :sample: raw_output=True
+        """
+        ...
+    @overload
+    def sha256(self, raw_output: Literal[False]) -> str:
         """
         Generate a random SHA-256 hash.